chrome.bookmarks

الوصف

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

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

الأذونات

bookmarks

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

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

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

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

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

يتم استخدام خصائص BookmarkTreeNode في chrome.bookmarks API. على سبيل المثال، عند استدعاء 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-pattern.

الأنواع

BookmarkTreeNode

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

أماكن إقامة

• الأطفال

  BookmarkTreeNode[] اختيارية

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

• dateAdded

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

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

• dateGroupModified

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

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

• dateLastUsed

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

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

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

• 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,
)

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

المَعلمات

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

  CreateDetails

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (result: BookmarkTreeNode)=>void

  • نتيجة

    BookmarkTreeNode

المرتجعات

• Promise<BookmarkTreeNode>

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

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

get()

وعد

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

يسترد BookmarkTreeNode(s) المحدد.

المَعلمات

• 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

      سلسلة[]

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

      سلسلة