browser.readingList

الوصف

استخدِم واجهة برمجة التطبيقات chrome.readingList لقراءة العناصر في قائمة القراءة وتعديلها.

الأذونات

readingList

لاستخدام Reading List API، أضِف الإذن "readingList" في ملف البيان الخاص بالإضافة:

manifest.json:

{
  "name": "My reading list extension",
  ...
  "permissions": [
    "readingList"
  ]
}

مدى التوفّر

الإصدار 120 من Chrome والإصدارات الأحدث browser.* منذ الإصدار 148 من Chrome الإصدار 3 من MV والإصدارات الأحدث

يوفّر Chrome قائمة قراءة في اللوحة الجانبية. تتيح هذه الميزة للمستخدمين حفظ صفحات الويب لقراءتها لاحقًا أو بلا إنترنت. استخدِم Reading List API لاسترداد العناصر الحالية وإضافة عناصر إلى القائمة أو إزالتها منها.

قائمة قراءة تعرض عددًا من المقالات

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

ترتيب العناصر

لا يتم ترتيب العناصر في قائمة القراءة بأي ترتيب مضمون.

تفرُّد السلع

يتم تحديد العناصر حسب عنوان URL. ويشمل ذلك علامة التجزئة وسلسلة طلب البحث.

حالات الاستخدام

توضّح الأقسام التالية بعض حالات الاستخدام الشائعة لواجهة Reading List API. يُرجى الاطّلاع على أمثلة على الإضافات للحصول على أمثلة كاملة على الإضافات.

إضافة عنصر

لإضافة عنصر إلى قائمة القراءة، استخدِم browser.readingList.addEntry():

browser.readingList.addEntry({
  title: "New to the web platform in September | web.dev",
  url: "https://developer.chrome.com/",
  hasBeenRead: false
});

عرض العناصر

لعرض العناصر من قائمة القراءة، استخدِم طريقة browser.readingList.query() لاستردادها.

const items = await browser.readingList.query({});

for (const item of items) {
  // Do something do display the item
}

وضع علامة "مقروء" على عنصر

يمكنك استخدام browser.readingList.updateEntry() لتعديل العنوان وعنوان URL وحالة القراءة. يضع الرمز التالي علامة على عنصر كـ "مقروء":

browser.readingList.updateEntry({
  url: "https://developer.chrome.com/",
  hasBeenRead: true
});

إزالة عنصر

لإزالة عنصر، استخدِم browser.readingList.removeEntry():

browser.readingList.removeEntry({
  url: "https://developer.chrome.com/"
});

نماذج الإضافات

للاطّلاع على المزيد من العروض التوضيحية لإضافات Reading List API، يُرجى مراجعة نموذج Reading List API.

الأنواع

AddEntryOptions

الخصائص

• hasBeenRead

  قيمة منطقية

  ستكون القيمة true إذا تمت قراءة الإدخال.

• title

  سلسلة

  تمثّل هذه السمة عنوان الإدخال.

• url

  سلسلة

  تمثّل هذه السمة عنوان URL الخاص بالإدخال.

QueryInfo

الخصائص

• hasBeenRead

  قيمة منطقية اختيارية

  تشير إلى ما إذا كان سيتم البحث عن العناصر المقروءة (true) أو غير المقروءة (false).

• title

  string اختياري

  عنوان للبحث عنه

• url

  string اختياري

  عنوان URL المطلوب البحث عنه

ReadingListEntry

الخصائص

• creationTime

  الرقم

  وقت إنشاء الإدخال يتم تسجيله بالملي ثانية منذ 1 يناير 1970.

• hasBeenRead

  قيمة منطقية

  ستكون القيمة true إذا تمت قراءة الإدخال.

• lastUpdateTime

  الرقم

  يشير هذا الحقل إلى تاريخ آخر مرة تم فيها تعديل الإدخال. تكون هذه القيمة بالملي ثانية منذ 1 يناير 1970.

• title

  سلسلة

  تمثّل هذه السمة عنوان الإدخال.

• url

  سلسلة

  تمثّل هذه السمة عنوان URL الخاص بالإدخال.

RemoveOptions

الخصائص

• url

  سلسلة

  عنوان URL المطلوب إزالته

UpdateEntryOptions

الخصائص

• hasBeenRead

  قيمة منطقية اختيارية

  حالة القراءة المعدَّلة ستبقى الحالة الحالية إذا لم يتم تقديم قيمة.

• title

  string اختياري

  العنوان الجديد يبقى المربّع الحالي إذا لم يتم تقديم قيمة.

• url

  سلسلة

  عنوان URL الذي سيتم تعديله

الطُرق

addEntry()

browser.readingList.addEntry(
  entry: AddEntryOptions,
): Promise<void>

يضيف هذا الإجراء إدخالاً إلى قائمة القراءة إذا لم يكن موجودًا.

المعلمات

• إدخال

  AddEntryOptions

  تمثّل هذه المَعلمة الإدخال المطلوب إضافته إلى قائمة القراءة.

المرتجعات

• وعد<فراغ>

  يتم حلّ المشكلة بعد إضافة الإدخال.

query()

browser.readingList.query(
  info: QueryInfo,
): Promise<ReadingListEntry[]>

يستردّ جميع الإدخالات التي تتطابق مع سمات QueryInfo. ولن تتم مطابقة السمات التي لم يتم تقديمها.

المعلمات

• معلومات

  QueryInfo

  تمثّل هذه المَعلمة المواقع المطلوب البحث عنها.

المرتجعات

• Promise<ReadingListEntry[]>

  يتم حلّ المشكلة بعد مطابقة الإدخالات.

removeEntry()

browser.readingList.removeEntry(
  info: RemoveOptions,
): Promise<void>

يزيل هذا الإجراء إدخالاً من قائمة القراءة إذا كان موجودًا.

المعلمات

• معلومات

  RemoveOptions

  الإدخال المطلوب إزالته من قائمة القراءة

المرتجعات

• وعد<فراغ>

  يتم حلّ المشكلة بعد إزالة الإدخال.

updateEntry()

browser.readingList.updateEntry(
  info: UpdateEntryOptions,
): Promise<void>

يتم تعديل إدخال قائمة القراءة إذا كان متوفّرًا.

المعلمات

• معلومات

  UpdateEntryOptions

  الإدخال المطلوب تعديله

المرتجعات

• وعد<فراغ>

  يتم حلّ المشكلة بعد تعديل الإدخالات المطابقة.

الفعاليات

onEntryAdded

browser.readingList.onEntryAdded.addListener(
  callback: function,
)

يتم تشغيل هذا الحدث عند إضافة ReadingListEntry إلى قائمة القراءة.

المعلمات

• callback

  دالة

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

  (entry: ReadingListEntry) => void

  • إدخال

    ReadingListEntry

onEntryRemoved

browser.readingList.onEntryRemoved.addListener(
  callback: function,
)

يتم تفعيل هذا الإجراء عند إزالة ReadingListEntry من قائمة القراءة.

المعلمات

• callback

  دالة

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

  (entry: ReadingListEntry) => void

  • إدخال

    ReadingListEntry

onEntryUpdated

browser.readingList.onEntryUpdated.addListener(
  callback: function,
)

يتم تفعيل هذا الحدث عند تعديل ReadingListEntry في قائمة القراءة.

المعلمات

• callback

  دالة

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

  (entry: ReadingListEntry) => void

  • إدخال

    ReadingListEntry