chrome.bookmarks

refresh date: 2026-09-25 robots: noindex

يؤدي هذا الإذن إلى ظهور تحذير.

الوصف

استخدِم واجهة برمجة التطبيقات 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',
});

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

الأنواع

BookmarkTreeNode

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

الخصائص

  • الأطفال

    BookmarkTreeNode[] اختيارية

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

  • dateAdded

    number اختياري

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

  • dateGroupModified

    number اختياري

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

  • dateLastUsed

    number اختياري

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

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

  • folderType

    ‫FolderType اختيارية

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

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

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

  • id

    سلسلة

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

  • الفهرس

    number اختياري

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

  • parentId

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

    تمثّل id المجلد الرئيسي. تم استبعادها للعقدة الجذر.

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

    قيمة منطقية

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

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

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

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

  • title

    سلسلة

    تمثّل هذه السمة النص المعروض للعقدة.

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

    "managed"
     اختيارية

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

  • url

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

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

BookmarkTreeNodeUnmodifiable

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

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

القيمة

"managed"

CreateDetails

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

الخصائص

  • الفهرس

    number اختياري

  • parentId

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

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

  • title

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

  • url

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

FolderType

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

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

تعداد

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

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

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

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

الخصائص

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Deprecated

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

القيمة

‫1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Deprecated

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

القيمة

‫1000000

ROOT_NODE_ID

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

تمثّل هذه السمة id المرتبطة بعقدة المستوى الجذر.

القيمة

"0"

الطُرق

create()

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

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

المعلمات

المرتجعات

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

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

get()

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

يستردّ هذا النوع من العقد عقد BookmarkTreeNode المحدّدة.

المعلمات

  • idOrIdList

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

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

  • callback

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

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

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

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

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

getChildren()

وعد 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

المعلمات

  • id

    سلسلة

  • callback

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

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

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

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

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

getRecent()

وعد 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

المعلمات

  • numberOfItems

    الرقم

    الحدّ الأقصى لعدد العناصر المطلوب عرضها

  • callback

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

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

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

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

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

getSubTree()

وعد 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

المعلمات

  • id

    سلسلة

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

  • callback

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

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

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

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

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

getTree()

وعد 
chrome.bookmarks.getTree(
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

المعلمات

  • callback

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

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

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

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

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

move()

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

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

المعلمات

  • id

    سلسلة

  • الوجهة

    عنصر

    • الفهرس

      number اختياري

    • parentId

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

  • callback

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

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

    (result: BookmarkTreeNode) => void

المرتجعات

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

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

remove()

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

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

المعلمات

  • id

    سلسلة

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

removeTree()

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

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

المعلمات

  • id

    سلسلة

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

وعد 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

المعلمات

  • query

    string | object

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

    • query

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

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

    • title

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

      تمثّل هذه السمة عنوان الإشارة المرجعية، ويجب أن يكون مطابقًا تمامًا.

    • url

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

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

  • callback

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

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

    (results: BookmarkTreeNode[]) => void

المرتجعات

  • Promise<BookmarkTreeNode[]>

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

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

update()

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

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

المعلمات

  • id

    سلسلة

  • التغييرات

    عنصر

    • title

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

    • url

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

  • callback

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

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

    (result: BookmarkTreeNode) => void

المرتجعات

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

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

الفعاليات

onChanged

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

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

المعلمات

  • callback

    دالة

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

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

    • id

      سلسلة

    • changeInfo

      عنصر

      • title

        سلسلة

      • url

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

onChildrenReordered

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

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

المعلمات

  • callback

    دالة

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

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

    • id

      سلسلة

    • reorderInfo

      عنصر

      • childIds

        string[]

onCreated

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

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

المعلمات

  • callback

    دالة

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

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

onImportBegan

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

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

المعلمات

  • callback

    دالة

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

    () => void

onImportEnded

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

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

المعلمات

  • callback

    دالة

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

    () => void

onMoved

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

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

المعلمات

  • callback

    دالة

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

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

    • id

      سلسلة

    • moveInfo

      عنصر

      • الفهرس

        الرقم

      • oldIndex

        الرقم

      • oldParentId

        سلسلة

      • parentId

        سلسلة

onRemoved

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

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

المعلمات

  • callback

    دالة

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

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

    • id

      سلسلة

    • removeInfo

      عنصر

      • الفهرس

        الرقم

      • عقدة

        BookmarkTreeNode

        Chrome 48+
      • parentId

        سلسلة