browser.bookmarks

الوصف

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

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

الأذونات

bookmarks

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

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

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

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

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

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

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

أمثلة

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

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

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

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

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

الأنواع

BookmarkTreeNode

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

الخصائص

• الأطفال

  BookmarkTreeNode[] اختياري

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

• dateAdded

  number اختيارية

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

• dateGroupModified

  number اختيارية

  تاريخ آخر تغيير لمحتوى هذا المجلد، بالمللي ثانية منذ بداية العصر

• dateLastUsed

  number اختيارية

  الإصدار 114 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• folderType

  FolderType اختياري

  الإصدار 134 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

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

• id

  سلسلة

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

• الفهرس

  number اختيارية

  موضع هذه العقدة ضمن المجلد الرئيسي، بدءًا من 0.

• parentId

  string اختياري

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

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

  قيمة منطقية

  الإصدار 134 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

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

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

• title

  سلسلة

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

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

  ‫"managed"
   اختيارية

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

• url

  string اختياري

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

BookmarkTreeNodeUnmodifiable

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

القيمة

"managed"

CreateDetails

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

الخصائص

• الفهرس

  number اختيارية

• parentId

  string اختياري

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

• title

  string اختياري

• url

  string اختياري

FolderType

الإصدار 134 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

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

"other"
الإشارات المرجعية التي تظهر في القائمة الكاملة للإشارات المرجعية على جميع الأنظمة الأساسية

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

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

الخصائص

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

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

لم يعُد Chrome يفرض قيودًا على عمليات كتابة الإشارات المرجعية.

القيمة

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

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

لم يعُد Chrome يفرض قيودًا على عمليات كتابة الإشارات المرجعية.

القيمة

1000000

ROOT_NODE_ID

الإصدار 145 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

‫id المرتبط بالعقدة على مستوى الجذر

القيمة

"0"

الطُرق

create()

browser.bookmarks.create(
  bookmark: CreateDetails,
): Promise<BookmarkTreeNode>

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

المعلمات

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

  CreateDetails

المرتجعات

• Promise<BookmarkTreeNode>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

get()

browser.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
): Promise<BookmarkTreeNode[]>

يستردّ هذا الإذن BookmarkTreeNode(s) المحدّدة.

المعلمات

• idOrIdList

  string | [string, ...string[]]

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

المرتجعات

• Promise<BookmarkTreeNode[]>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getChildren()

browser.bookmarks.getChildren(
  id: string,
): Promise<BookmarkTreeNode[]>

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

المعلمات

• id

  سلسلة

المرتجعات

• Promise<BookmarkTreeNode[]>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getRecent()

browser.bookmarks.getRecent(
  numberOfItems: number,
): Promise<BookmarkTreeNode[]>

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

المعلمات

• numberOfItems

  الرقم

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

المرتجعات

• Promise<BookmarkTreeNode[]>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getSubTree()

browser.bookmarks.getSubTree(
  id: string,
): Promise<BookmarkTreeNode[]>

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

المعلمات

• id

  سلسلة

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

المرتجعات

• Promise<BookmarkTreeNode[]>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getTree()

browser.bookmarks.getTree(): Promise<BookmarkTreeNode[]>

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

المرتجعات

• Promise<BookmarkTreeNode[]>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

move()

browser.bookmarks.move(
  id: string,
  destination: object,
): Promise<BookmarkTreeNode>

لنقل BookmarkTreeNode المحدّد إلى الموقع الجغرافي المقدَّم

المعلمات

• id

  سلسلة

• الوجهة

  عنصر

  • الفهرس

    number اختيارية

  • parentId

    string اختياري

المرتجعات

• Promise<BookmarkTreeNode>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

remove()

browser.bookmarks.remove(
  id: string,
): Promise<void>

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

المعلمات

• id

  سلسلة

المرتجعات

• وعد<فراغ>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

removeTree()

browser.bookmarks.removeTree(
  id: string,
): Promise<void>

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

المعلمات

• id

  سلسلة

المرتجعات

• وعد<فراغ>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

search()

browser.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

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

المعلمات

• query

  string | object

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

  • query

    string اختياري

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

  • title

    string اختياري

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

  • url

    string اختياري

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

المرتجعات

• Promise<BookmarkTreeNode[]>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

update()

browser.bookmarks.update(
  id: string,
  changes: object,
): Promise<BookmarkTreeNode>

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

المعلمات

• id

  سلسلة

• التغييرات

  عنصر

  • title

    string اختياري

  • url

    string اختياري

المرتجعات

• Promise<BookmarkTreeNode>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الفعاليات

onChanged

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

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

المعلمات

• callback

  دالة

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

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

  • id

    سلسلة

  • changeInfo

    عنصر

    • title

      سلسلة

    • url

      string اختياري

onChildrenReordered

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

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

المعلمات

• callback

  دالة

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

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

  • id

    سلسلة

  • reorderInfo

    عنصر

    • childIds

      string[]

onCreated

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

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

المعلمات

• callback

  دالة

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

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

  • id

    سلسلة

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

    BookmarkTreeNode

onImportBegan

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

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

المعلمات

• callback

  دالة

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

  () => void

onImportEnded

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

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

المعلمات

• callback

  دالة

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

  () => void

onMoved

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

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

المعلمات

• callback

  دالة

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

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

  • id

    سلسلة

  • moveInfo

    عنصر

    • الفهرس

      الرقم

    • oldIndex

      الرقم

    • oldParentId

      سلسلة

    • parentId

      سلسلة

onRemoved

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

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

المعلمات

• callback

  دالة

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

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

  • id

    سلسلة

  • removeInfo

    عنصر

    • الفهرس

      الرقم

    • عقدة

      BookmarkTreeNode

      الإصدار 48 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome
    • parentId

      سلسلة