chrome.bookmarks

الوصف

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

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

الأذونات

bookmarks

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

{
  "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);
  },
);

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

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

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال Bookmarks API من مستودع chrome-extension-samples.

الأنواع

BookmarkTreeNode

عقدة (إما إشارة مرجعية أو مجلد) في شجرة الإشارات المرجعية يتم ترتيب العقد الفرعية ضمن المجلد الرئيسي.

أماكن إقامة

  • الأطفال

    BookmarkTreeNode[] اختياري

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

  • dateAdded

    رقم اختياري

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

  • dateGroupModified

    رقم اختياري

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

  • dateLastUsed

    رقم اختياري

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

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

  • id

    سلسلة

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

  • المؤشر

    رقم اختياري

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

  • parentId

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

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

  • title

    سلسلة

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

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

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

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

  • url

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

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

BookmarkTreeNodeUnmodifiable

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

يشير إلى سبب عدم إمكانية تعديل هذه العقدة. تشير القيمة 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 غير صحيح أو غير متوفّر، سيكون المجلد.

المعلمات

  • إشارة مرجعية

    CreateDetails

  • ردّ الاتصال

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

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

    (result: BookmarkTreeNode) => void

المرتجعات

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

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

get()

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

لاسترداد BookmarkTreeNodes المحدّدة

المعلمات

  • idOrIdList

    سلسلة | [سلسلة, ...سلسلة[]]

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

  • ردّ الاتصال

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

    تظهر المَعلمة 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,
)

تنقل هذه الوظيفة عنصر BookmarkTreeNode المحدّد إلى الموقع المقدَّم.

المعلمات

  • id

    سلسلة

  • الوجهة

    عنصر

    • المؤشر

      رقم اختياري

    • parentId

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

  • ردّ الاتصال

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

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

    (result: BookmarkTreeNode) => void

المرتجعات

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

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

remove()

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

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

المعلمات

  • id

    سلسلة

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

removeTree()

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

تزيل بشكل متكرر مجلد إشارة مرجعية.

المعلمات

  • id

    سلسلة

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

تبحث عن BookmarkTreeNodes التي تتطابق مع طلب البحث المحدّد. تؤدي طلبات البحث المحدّدة باستخدام عنصر إلى إنشاء BookmarkTreeNodes تتطابق مع جميع المواقع المحدّدة.

المعلمات

  • query

    سلسلة | عنصر

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

    • query

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

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

    • title

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

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

    • url

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

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

  • ردّ الاتصال

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

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

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

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

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

update()

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

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

المعلمات

  • id

    سلسلة

  • التغييرات

    عنصر

    • title

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

    • url

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

  • ردّ الاتصال

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

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

    (result: BookmarkTreeNode) => void

المرتجعات

  • الإصدار 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,
)

يتم تشغيله عندما يتغيّر ترتيب العناصر الفرعية في مجلد بسبب ترتيبها في واجهة المستخدم. ولا يتمّ استدعاء هذا الإجراء نتيجةً لـ move().

المعلمات

  • ردّ الاتصال

    دالة

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

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

    • id

      سلسلة

    • reorderInfo

      عنصر

      • childIds

        string[]

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

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

        سلسلة