chrome.readingList

الوصف

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

الأذونات

readingList

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

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()

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

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

المعلمات

  • الإدخال

    AddEntryOptions

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

query()

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

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

المعلمات

  • معلومات

    QueryInfo

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

  • رد الاتصال

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

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

    (entries: ReadingListEntry[]) => void

المرتجعات

  • Promise&lt;ReadingListEntry[]&gt;

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

removeEntry()

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

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

المعلمات

  • معلومات

    RemoveOptions

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

updateEntry()

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

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

المعلمات

  • معلومات

    UpdateEntryOptions

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

  • رد الاتصال

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

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

    () => 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