browser.readingList

الوصف

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

الأذونات

readingList

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

manifest.json:

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

مدى التوفّر

الإصدار 120 من Chrome والإصدارات الأحدث الإصدار 3 من Manifest والإصدارات الأحدث

يتضمّن 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

    boolean اختياري

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

  • title

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

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

  • url

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

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

ReadingListEntry

الخصائص

  • creationTime

    الرقم

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

  • hasBeenRead

    قيمة منطقية

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

  • lastUpdateTime

    الرقم

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

  • title

    سلسلة

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

  • url

    سلسلة

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

RemoveOptions

الخصائص

  • url

    سلسلة

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

UpdateEntryOptions

الخصائص

  • hasBeenRead

    boolean اختياري

    حالة القراءة المعدَّلة سيظلّ الوضع الحالي كما هو إذا لم يتم تقديم قيمة.

  • title

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

    تمثّل هذه السمة العنوان الجديد. سيظل المربّع الحالي إذا لم يتم تقديم قيمة.

  • url

    سلسلة

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

الطُرق

addEntry()

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

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

المعلمات

  • إدخال

    AddEntryOptions

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

المرتجعات

  • Promise<void>

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

query()

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

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

المعلمات

  • معلومات

    QueryInfo

    السمات المطلوب البحث عنها.

المرتجعات

  • Promise<ReadingListEntry[]>

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

removeEntry()

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

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

المعلمات

  • معلومات

    RemoveOptions

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

المرتجعات

  • Promise<void>

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

updateEntry()

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

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

المعلمات

المرتجعات

  • Promise<void>

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

الفعاليات

onEntryAdded

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

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

المعلمات

onEntryRemoved

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

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

المعلمات

onEntryUpdated

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

يتم تشغيل هذا المشغّل عند تعديل ReadingListEntry في قائمة القراءة.

المعلمات