chrome.readingList

الوصف

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

الأذونات

readingList

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

‫manifest.json:

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

مدى التوفّر

الإصدار 120 من Chrome أو الإصدارات الأحدث MV3+

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

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

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

طلب العنصر

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

تفرُّد السلعة

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

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

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

إضافة عنصر

لإضافة عنصر إلى قائمة القراءة، استخدِم 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/"
});

عيّنات الإضافات

لمزيد من العروض التوضيحية لإضافات واجهة برمجة التطبيقات لقائمة القراءة، يُرجى الاطّلاع على نموذج واجهة برمجة التطبيقات لقائمة القراءة.

الأنواع

AddEntryOptions

أماكن إقامة

• hasBeenRead

  منطقي

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

• title

  سلسلة

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

• url

  سلسلة

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

QueryInfo

أماكن إقامة

• hasBeenRead

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

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

• title

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

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

• url

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

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

ReadingListEntry

أماكن إقامة

• creationTime

  الرقم

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

• hasBeenRead

  منطقي

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

• lastUpdateTime

  الرقم

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

• title

  سلسلة

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

• url

  سلسلة

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

RemoveOptions

أماكن إقامة

• url

  سلسلة

  تمثّل هذه السمة عنوان URL المطلوب إزالته.

UpdateEntryOptions

أماكن إقامة

• hasBeenRead

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

  حالة القراءة المعدَّلة. تظل الحالة الحالية سارية في حال عدم تقديم قيمة.

• title

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

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

• url

  سلسلة

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

الطُرق

addEntry()

Promise

chrome.readingList.addEntry(
  entry: AddEntryOptions,
  callback?: function,
)

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

المعلمات

• إدخال

  AddEntryOptions

  الإدخال المطلوب إضافته إلى قائمة القراءة

• ردّ الاتصال

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

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

  () => void

المرتجعات

• Promise<void>

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

query()

الوعد

chrome.readingList.query(
  info: QueryInfo,
  callback?: function,
)

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

المعلمات

• معلومات

  QueryInfo

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

• رد الاتصال

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

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

  (entries: ReadingListEntry[]) => void

  • الإدخالات

    ReadingListEntry[]

المرتجعات

• Promise<ReadingListEntry[]>

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

removeEntry()

Promise

chrome.readingList.removeEntry(
  info: RemoveOptions,
  callback?: function,
)

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

المعلمات

• معلومات

  RemoveOptions

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

• رد الاتصال

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

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

  () => void

المرتجعات

• Promise<void>

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

updateEntry()

الوعد

chrome.readingList.updateEntry(
  info: UpdateEntryOptions,
  callback?: function,
)

تعديل إدخال قائمة القراءة في حال توفّره

المعلمات

• معلومات

  UpdateEntryOptions

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

• ردّ الاتصال

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

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

  () => void

المرتجعات

• Promise<void>

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

الفعاليات

onEntryAdded

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

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

المعلمات

• رد الاتصال

  دالة

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

  (entry: ReadingListEntry) => void

  • إدخال

    ReadingListEntry

onEntryRemoved

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

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

المعلمات

• رد الاتصال

  دالة

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

  (entry: ReadingListEntry) => void

  • إدخال

    ReadingListEntry

onEntryUpdated

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

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

المعلمات

• رد الاتصال

  دالة

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

  (entry: ReadingListEntry) => void

  • الإدخال

    ReadingListEntry