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 والإصدارات الأحدث

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

• folderType

  ‫FolderType اختياري

  في انتظار المراجعة

  إذا كان هذا المجلد متوفّرًا، يعني ذلك أنّه مجلد أضافه المتصفّح ولا يمكن للمستخدم أو الإضافة تعديله. يمكن تعديل العقد الفرعية إذا لم تكن هذه العقدة قد تم ضبط خاصية unmodifiable فيها. يتم حذفها إذا كان بإمكان المستخدم والإضافة تعديل العقدة (الإعداد التلقائي).

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

• id

  سلسلة

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

• الفهرس

  رقم اختياري

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

• parentId

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

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

• جارٍ المزامنة…

  قيمة منطقية

  في انتظار المراجعة

  ما إذا كان المتصفّح يُزامن هذه العقدة مع مساحة تخزين حساب المستخدم عن بُعد ويمكن استخدام هذا الإجراء للتمييز بين الإصدارات على الحساب والإصدارات المحلية فقط من FolderType نفسها. قد تتغيّر قيمة هذه السمة لعقدة حالية، على سبيل المثال نتيجةً لفعل المستخدِم.

  ملاحظة: يشير ذلك إلى ما إذا كان يتم حفظ العقدة في مقدّم الحساب المضمّن في المتصفّح. من الممكن أن تتم مزامنة عقدة من خلال جهة خارجية، حتى إذا كانت هذه القيمة غير صحيحة.

  بالنسبة إلى العقد المُدارة (العقد التي تم ضبط unmodifiable فيها على true)، سيكون هذا السمة دائمًا false.

• title

  سلسلة

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

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

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

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

• url

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

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

BookmarkTreeNodeUnmodifiable

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

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

القيمة

"مُدار"

CreateDetails

العنصر الذي تم تمريره إلى الدالة create()

الخصائص

• الفهرس

  رقم اختياري

• parentId

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

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

• title

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

• url

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

FolderType

في انتظار المراجعة

يشير إلى نوع المجلد.

Enum

"bookmarks-bar"
المجلد الذي يتم عرض محتوياته في أعلى نافذة المتصفّح

"غير ذلك"
الإشارات المرجعية التي يتم عرضها في القائمة الكاملة للإشارات المرجعية على جميع المنصات

‫"mobile"
الإشارات المرجعية المتاحة بشكل عام على الأجهزة الجوّالة للمستخدم، ولكن يمكن تعديلها من خلال إضافة أو في مدير الإشارات المرجعية.

"مُدار"
مجلد من المستوى الأعلى قد يكون متوفّرًا إذا أعدّ مشرف النظام أو الوصي على مستخدم خاضع للإشراف الإشارات المرجعية.

الخصائص

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

  • نتيجة

    BookmarkTreeNode

المرتجعات

• Promise<BookmarkTreeNode>

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

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

get()

الوعد

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

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

المعلمات

• idOrIdList

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

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

• ردّ الاتصال

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

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

  (results: BookmarkTreeNode[]) => void

  • النتائج

    BookmarkTreeNode[]

المرتجعات

• Promise<BookmarkTreeNode[]>

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

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

getChildren()

الوعد

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

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

المعلمات

• id

  سلسلة

• ردّ الاتصال

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

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

  (results: BookmarkTreeNode[]) => void

  • النتائج

    BookmarkTreeNode[]

المرتجعات

• Promise<BookmarkTreeNode[]>

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

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

getRecent()

الوعد

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

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

المعلمات

• numberOfItems

  الرقم

  الحد الأقصى لعدد العناصر التي سيتم عرضها

• ردّ الاتصال

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

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

  (results: BookmarkTreeNode[]) => void

  • النتائج

    BookmarkTreeNode[]

المرتجعات

• Promise<BookmarkTreeNode[]>

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

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

getSubTree()

الوعد

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

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

المعلمات

• id

  سلسلة

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

• ردّ الاتصال

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

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

  (results: BookmarkTreeNode[]) => void

  • النتائج

    BookmarkTreeNode[]

المرتجعات

• Promise<BookmarkTreeNode[]>

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

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

getTree()

الوعد

chrome.bookmarks.getTree(
  callback?: function,
)

يستردّ التسلسل الهرمي الكامل للإشارات المرجعية.

المعلمات

• ردّ الاتصال

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

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

  (results: BookmarkTreeNode[]) => void

  • النتائج

    BookmarkTreeNode[]

المرتجعات

• Promise<BookmarkTreeNode[]>

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

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

move()

الوعد

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

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

المعلمات

• id

  سلسلة

• الوجهة

  عنصر

  • الفهرس

    رقم اختياري

  • parentId

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

• ردّ الاتصال

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

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

  (result: BookmarkTreeNode) => void

  • نتيجة

    BookmarkTreeNode

المرتجعات

• Promise<BookmarkTreeNode>

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

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

remove()

الوعد

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

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

المعلمات

• id

  سلسلة

• ردّ الاتصال

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

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

  () => void

المرتجعات

• Promise<void>

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

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

removeTree()

الوعد

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

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

المعلمات

• id

  سلسلة

• ردّ الاتصال

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

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

  () => void

المرتجعات

• Promise<void>

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

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

search()

الوعد

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

  • النتائج

    BookmarkTreeNode[]

المرتجعات

• Promise<BookmarkTreeNode[]>

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

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

update()

الوعد

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

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

المعلمات

• id

  سلسلة

• التغييرات

  عنصر

  • title

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

  • url

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

• ردّ الاتصال

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

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

  (result: BookmarkTreeNode) => void

  • نتيجة

    BookmarkTreeNode

المرتجعات

• Promise<BookmarkTreeNode>

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

  تتوفّر الوعود في الإصدار 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

  • id

    سلسلة

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

    BookmarkTreeNode

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

      سلسلة