chrome.readingList

الوصف

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

الأذونات

readingList

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

manifest.json:

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

مدى التوفّر

‫Chrome 120 أو الإصدارات الأحدث الإصدار 3 أو الإصدارات الأحدث من بيان الإضافات

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

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

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

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

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

تفرّد السلعة

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

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

توضّح الأقسام التالية بعض حالات الاستخدام الشائعة لواجهة برمجة التطبيقات "قائمة القراءة". يمكنك الاطّلاع على نماذج الإضافات للحصول على أمثلة كاملة للإضافات.

إضافة عنصر

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

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

عرض العناصر

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

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

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

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

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

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

إزالة عنصر

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

chrome.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 في قائمة القراءة.

المعلمات