chrome.bookmarks

الوصف

استخدِم واجهة برمجة التطبيقات chrome.bookmarks لإنشاء الإشارات المرجعية وتنظيمها ومعالجتها. راجع أيضًا تجاوز الصفحات، التي يمكنك استخدامها لإنشاء صفحة مخصصة لمدير الإشارات.

يؤدي النقر على النجمة إلى إضافة إشارة مرجعية
يؤدي النقر على النجمة إلى إضافة إشارة مرجعية.

الأذونات

bookmarks

يجب الإفصاح عن "الإشارات المرجعية" إذن في بيان الإضافة لاستخدام واجهة برمجة تطبيقات الإشارات المرجعية. على سبيل المثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "bookmarks"
  ],
  ...
}

المفاهيم والاستخدام

العناصر والخصائص

يتم تنظيم الإشارات المرجعية في شجرة، بحيث تكون كل عقدة في الشجرة إشارة مرجعية أو مجلد (يُسمّى أحيانًا مجموعة). يتم تمثيل كل جزء في الشجرة بواسطة bookmarks.BookmarkTreeNode.

يتم استخدام سمات BookmarkTreeNode في واجهة برمجة التطبيقات chrome.bookmarks. على سبيل المثال، عند ويمكنك استدعاء الدالة bookmarks.create، ويمكنك إدخال العنصر الرئيسي للعقدة الجديدة (parentId) واختياريًا السمات index وtitle وurl في العقدة. يمكنك الاطّلاع على bookmarks.BookmarkTreeNode للحصول على معلومات. حول الخصائص التي يمكن أن تحتوي عليها أي عقدة.

أمثلة

ينشئ الرمز التالي مجلدًا بعنوان "الإشارات المرجعية للإضافة". الوسيطة الأولى يحدّد create() خصائص المجلد الجديد. تحدد الوسيطة الثانية دالة سيتم وتنفيذه بعد إنشاء المجلد.

chrome.bookmarks.create(
  {'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
  function(newFolder) {
    console.log("added folder: " + newFolder.title);
  },
);

ينشئ المقتطف التالي إشارة مرجعية تشير إلى مستندات المطوّرين الخاصة بالإضافات. منذ فلن يحدث أي شيء سيئ إذا فشل إنشاء الإشارة، ولن يكلف هذا الرمز عن تحديد .

chrome.bookmarks.create({
  'parentId': extensionsFolderId,
  'title': 'Extensions doc',
  'url': 'https://developer.chrome.com/docs/extensions',
});

لتجربة واجهة برمجة التطبيقات هذه، يمكنك تثبيت مثال على واجهة برمجة التطبيقات للإشارات المرجعية من chrome-extension-samples المستودع.

الأنواع

BookmarkTreeNode

تمثّل هذه السمة عقدة (إما إشارة مرجعية أو مجلد) في شجرة الإشارات المرجعية. يتم ترتيب العُقد الفرعية داخل المجلد الأصلي.

أماكن إقامة

  • الأطفال

    BookmarkTreeNode[] اختيارية

    قائمة مرتبة من العناصر الثانوية لهذه العقدة.

  • dateAdded

    الرقم اختياري

    وقت إنشاء هذه العقدة بالمللي ثانية منذ تاريخ بدء حساب الفترة (new Date(dateAdded))

  • dateGroupModified

    الرقم اختياري

    وقت آخر تغيير لمحتوى هذا المجلد، بالمللي ثانية منذ تاريخ بدء حساب الفترة

  • dateLastUsed

    الرقم اختياري

    الإصدار 114 من Chrome أو الإصدارات الأحدث

    يشير ذلك المصطلح إلى وقت فتح هذه العقدة آخر مرة، بالملي ثانية منذ بدء حساب الفترة. لم يتم ضبطها للمجلدات.

  • id

    سلسلة

    المعرّف الفريد للعقدة. تكون المعرّفات فريدة في الملف الشخصي الحالي، وتظل صالحة حتى بعد إعادة تشغيل المتصفّح.

  • المؤشر

    الرقم اختياري

    الموضع المستند إلى 0 لهذه العقدة داخل المجلد الرئيسي.

  • parentId

    سلسلة اختيارية

    id للمجلد الرئيسي يتم حذفها للعقدة الجذر.

  • title

    سلسلة

    النص المعروض للعقدة.

  • غير قابل للتعديل

    "مُدار"
     اختياري

    تشير إلى سبب عدم إمكانية تعديل هذه العقدة. تشير قيمة managed إلى أنّ هذه العقدة قد تم ضبطها من قِبل مشرف النظام أو من قِبل مشرف المستخدم تحت الإشراف. يتم حذف هذه السمة إذا كان بإمكان المستخدم والإضافة تعديل العقدة (الإعداد التلقائي).

  • url

    سلسلة اختيارية

    عنوان URL الذي تم الانتقال إليه عندما ينقر المستخدم على الإشارة المرجعية سيتم حذفها للمجلدات.

BookmarkTreeNodeUnmodifiable

الإصدار 44 من Chrome أو الإصدارات الأحدث

تشير إلى سبب عدم إمكانية تعديل هذه العقدة. تشير قيمة managed إلى أنّ مشرف النظام هو من ضبط هذه العقدة. يتم حذف هذه السمة إذا كان بإمكان المستخدم والإضافة تعديل العقدة (الإعداد التلقائي).

القيمة

"مُدار"

CreateDetails

تم تمرير الكائن إلى الدالة create().

أماكن إقامة

  • المؤشر

    الرقم اختياري

  • parentId

    سلسلة اختيارية

    يتم ضبط الإعدادات التلقائية على مجلد "الإشارات المرجعية الأخرى".

  • title

    سلسلة اختيارية

  • url

    سلسلة اختيارية

أماكن إقامة

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

متوقّفة نهائيًا

لم يعُد متصفِّح Chrome مقيَّدًا بعمليات كتابة الإشارات المرجعية.

القيمة

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

متوقّفة نهائيًا

لم يعُد متصفِّح Chrome مقيَّدًا بعمليات كتابة الإشارات المرجعية.

القيمة

1000000

الطُرق

create()

وعود 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

ينشئ إشارة مرجعية أو مجلدًا ضمن المعرّف parentId المحدّد. إذا كان عنوان URL فارغًا أو غير متوفّر، سيكون مجلدًا.

المعلمات

المرتجعات

  • Promise<BookmarkTreeNode>

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

get()

وعود 
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
)

يسترد الإشارات المرجعية المحددة.

المعلمات

  • idOrIdList

    string | [سلسلة، ...سلسلة[]]

    رقم تعريف فردي بقيمة سلسلة أو مصفوفة من أرقام التعريف ذات قيم السلاسل

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getChildren()

وعود 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

استرداد العناصر الثانوية لمعرّف BookmarkTreeNode المحدد.

المعلمات

  • id

    سلسلة

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getRecent()

وعود 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

استرداد الإشارات المرجعية المضافة مؤخرًا.

المعلمات

  • numberOfItems

    الرقم

    تمثّل هذه السمة الحد الأقصى لعدد السلع المطلوب عرضها.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getSubTree()

وعود 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

يسترد جزءًا من التسلسل الهرمي للإشارات المرجعية، بدءًا من العقدة المحددة.

المعلمات

  • id

    سلسلة

    رقم تعريف جذر الشجرة الفرعية المطلوب استردادها.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getTree()

وعود 
chrome.bookmarks.getTree(
  callback?: function,
)

يسترجع العرض الهرمي للإشارات المرجعية بالكامل.

المعلمات

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

move()

وعود 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

ينقل عقدة الإشارات المرجعية المحددة إلى الموقع المحدد.

المعلمات

  • id

    سلسلة

  • الوجهة

    كائن

    • المؤشر

      الرقم اختياري

    • parentId

      سلسلة اختيارية

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (result: BookmarkTreeNode) => void

المرتجعات

  • Promise<BookmarkTreeNode>

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

remove()

وعود 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

إزالة إشارة مرجعية أو مجلد إشارات مرجعية فارغ

المعلمات

  • id

    سلسلة

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

removeTree()

وعود 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

يؤدي هذا الإجراء إلى إزالة مجلد إشارات مرجعية بشكل متكرر.

المعلمات

  • id

    سلسلة

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

وعود 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
)

للبحث عن عُقد إشارات مرجعية تتطابق مع طلب البحث المحدّد ينتج عن طلبات البحث المحدّدة باستخدام كائن عُقدة إشارات مرجعية تتطابق مع جميع السمات المحدّدة.

المعلمات

  • query

    string | كائن

    هي عبارة عن سلسلة من الكلمات والعبارات المقتبسة التي تتم مطابقتها مع عناوين URL والعناوين الخاصة بالإشارات المرجعية، أو مع عنصر معيَّن. إذا كان الكائن معيّنًا، قد يتم تحديد السمات query وurl وtitle، وسيتم إنشاء إشارات مرجعية تتطابق مع جميع السمات المحدّدة.

    • query

      سلسلة اختيارية

      سلسلة من الكلمات والعبارات المقتبسة التي تتم مطابقتها مع عناوين URL والعناوين الخاصة بالإشارات المرجعية

    • title

      سلسلة اختيارية

      عنوان الإشارة المرجعية يتطابق حرفيًا.

    • url

      سلسلة اختيارية

      عنوان URL للإشارة المرجعية يتطابق حرفيًا. يُرجى العِلم أنّ المجلدات لا تتضمّن عناوين URL.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise&lt;BookmarkTreeNode[]&gt;

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

update()

وعود 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

لتعديل خصائص إشارة أو مجلد حدِّد السمات التي تريد تغييرها فقط. تبقى الخصائص غير المحددة دون تغيير. ملاحظة: حاليًا، يمكن استخدام "title" فقط و"url"

المعلمات

  • id

    سلسلة

  • التغييرات

    كائن

    • title

      سلسلة اختيارية

    • url

      سلسلة اختيارية

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (result: BookmarkTreeNode) => void

المرتجعات

  • Promise&lt;BookmarkTreeNode&gt;

    الإصدار 90 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

فعاليات

onChanged

chrome.bookmarks.onChanged.addListener(
  callback: function,
)

يتم إطلاقه عند تغيير إشارة مرجعية أو مجلد. ملاحظة: في الوقت الحالي، تؤدي تغييرات العنوان وعناوين URL فقط إلى تشغيل ذلك.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (id: string, changeInfo: object) => void

    • id

      سلسلة

    • changeInfo

      كائن

      • title

        سلسلة

      • url

        سلسلة اختيارية

onChildrenReordered

chrome.bookmarks.onChildrenReordered.addListener(
  callback: function,
)

يتم الإطلاق عندما تغيّر العناصر الثانوية لمجلد ترتيبها بسبب الترتيب الذي يتم ترتيبها في واجهة المستخدم. لا يسمى هذا نتيجة لنقل (()).

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (id: string, reorderInfo: object) => void

    • id

      سلسلة

    • reorderInfo

      كائن

      • childIds

        سلسلة[]

onCreated

chrome.bookmarks.onCreated.addListener(
  callback: function,
)

يتم إطلاقه عند إنشاء إشارة مرجعية أو مجلد.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (id: string, bookmark: BookmarkTreeNode) => void

onImportBegan

chrome.bookmarks.onImportBegan.addListener(
  callback: function,
)

يتم الإطلاق عند بدء جلسة استيراد الإشارات المرجعية. على المراقبين الباهظين تجاهل تحديثات onCreated حتى يتم تنشيط onImportEnded. ويجب أن يتعامل المراقبون مع الإشعارات الأخرى على الفور.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    () => void

onImportEnded

chrome.bookmarks.onImportEnded.addListener(
  callback: function,
)

يتم الإطلاق عند انتهاء جلسة استيراد إشارات مرجعية.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    () => void

onMoved

chrome.bookmarks.onMoved.addListener(
  callback: function,
)

يتم الإطلاق عند نقل إشارة مرجعية أو مجلد إلى مجلد رئيسي مختلف.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (id: string, moveInfo: object) => void

    • id

      سلسلة

    • moveInfo

      كائن

      • المؤشر

        الرقم

      • oldIndex

        الرقم

      • oldParentId

        سلسلة

      • parentId

        سلسلة

onRemoved

chrome.bookmarks.onRemoved.addListener(
  callback: function,
)

يتم إطلاقه عند إزالة إشارة مرجعية أو مجلد. وعند إزالة مجلد بشكل متكرر، يتم تنشيط إشعار واحد له ولا يتم إطلاق أي إشعار لمحتواه.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (id: string, removeInfo: object) => void

    • id

      سلسلة

    • removeInfo

      كائن

      • المؤشر

        الرقم

      • عقدة

        BookmarkTreeNode

        الإصدار 48 من Chrome أو الإصدارات الأحدث
      • parentId

        سلسلة