chrome.readingList

الوصف

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

الأذونات

readingList

لاستخدام واجهة برمجة التطبيقات Read List (قائمة القراءة)، أضِف إذن "readingList" في ملف manifest الخاص بالإضافة:

manifest.json:

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

مدى التوفّر

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

يعرض Chrome قائمة قراءة تظهر في اللوحة الجانبية. يتيح للمستخدمين حفظ صفحات الويب لقراءتها لاحقًا أو بلا اتصال بالإنترنت. استخدِم واجهة برمجة التطبيقاتRead 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

    boolean

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

  • title

    سلسلة

    تمثّل هذه السمة عنوان المشاركة.

  • url

    سلسلة

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

QueryInfo

أماكن إقامة

  • hasBeenRead

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

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

  • title

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

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

  • url

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

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

ReadingListEntry

أماكن إقامة

  • creationTime

    الرقم

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

  • hasBeenRead

    boolean

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

  • lastUpdateTime

    الرقم

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

  • title

    سلسلة

    تمثّل هذه السمة عنوان المشاركة.

  • url

    سلسلة

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

RemoveOptions

أماكن إقامة

  • url

    سلسلة

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

UpdateEntryOptions

أماكن إقامة

  • hasBeenRead

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

    حالة القراءة المعدَّلة تظل الحالة الحالية غير متوفّرة إذا لم يتم تقديم قيمة.

  • title

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

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

  • url

    سلسلة

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

الطُرق

addEntry()

وعد 
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

المرتجعات

  • Promise<ReadingListEntry[]>

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

removeEntry()

وعد 
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

onEntryRemoved

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (entry: ReadingListEntry)=>void

onEntryUpdated

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (entry: ReadingListEntry)=>void