chrome.bookmarks

الوصف

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

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

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

  • folderType

    FolderType اختياري

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

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

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

  • id

    سلسلة

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

  • الفهرس

    number اختياري

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

  • parentId

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

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

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

    قيمة منطقية

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

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

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

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

  • title

    سلسلة

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

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

    "managed"
     اختياري

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

  • url

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

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

BookmarkTreeNodeUnmodifiable

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

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

القيمة

"managed"

CreateDetails

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

الخصائص

  • الفهرس

    number اختياري

  • parentId

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

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

  • title

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

  • url

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

FolderType

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

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

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,
): Promise<BookmarkTreeNode>

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

المعلمات

المرتجعات

get()

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

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

المعلمات

  • idOrIdList

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

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

المرتجعات

getChildren()

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

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

المعلمات

  • id

    سلسلة

المرتجعات

getRecent()

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

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

المعلمات

  • numberOfItems

    الرقم

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

المرتجعات

getSubTree()

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

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

المعلمات

  • id

    سلسلة

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

المرتجعات

getTree()

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

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

المرتجعات

move()

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

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

المعلمات

  • id

    سلسلة

  • الوجهة

    عنصر

    • الفهرس

      number اختياري

    • parentId

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

المرتجعات

remove()

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

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

المعلمات

  • id

    سلسلة

المرتجعات

  • Promise<void>

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

removeTree()

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

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

المعلمات

  • id

    سلسلة

المرتجعات

  • Promise<void>

    Chrome 90 والإصدارات الأحدث 
chrome.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

يبحث عن BookmarkTreeNodes المطابقة لطلب البحث المحدّد. تنتج طلبات البحث المحدّدة باستخدام عنصر BookmarkTreeNodes تطابق جميع الخصائص المحدّدة.

المعلمات

  • query

    سلسلة | كائن

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

    • query

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

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

    • title

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

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

    • url

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

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

المرتجعات

update()

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

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

المعلمات

  • id

    سلسلة

  • التغييرات

    عنصر

    • title

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

    • url

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

المرتجعات

الفعاليات

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

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

        سلسلة