browser.storage

الوصف

استخدِم واجهة برمجة التطبيقات chrome.storage لتخزين بيانات المستخدمين واستردادها وتتبُّع التغييرات التي تطرأ عليها.

الأذونات

storage

لاستخدام واجهة برمجة التطبيقات Storage API، يجب الإفصاح عن إذن "storage" في بيان الإضافة. على سبيل المثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

أمثلة

توضّح النماذج التالية مساحات التخزين local وsync وsession:

مثال (محلي)

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

مثال (مزامنة)

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

مثال (جلسة)

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

للاطّلاع على عروض توضيحية أخرى لواجهة Storage API، يمكنك استكشاف أي من النماذج التالية:

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

توفّر واجهة برمجة التطبيقات Storage API طريقة خاصة بالإضافة لحفظ بيانات المستخدم وحالته. وهي تشبه واجهات برمجة التطبيقات الخاصة بالتخزين على منصة الويب (IndexedDB وStorage)، ولكن تم تصميمها لتلبية احتياجات التخزين في الإضافات. في ما يلي بعض الميزات الرئيسية:

  • يمكن لجميع سياقات الإضافات، بما في ذلك مشغّل خدمات الإضافة والنصوص البرمجية للمحتوى، الوصول إلى Storage API.
  • يتم تخزين قيم JSON القابلة للتسلسل كسمات للعناصر.
  • تكون واجهة Storage API غير متزامنة مع عمليات القراءة والكتابة المجمّعة.
  • حتى إذا محا المستخدم ذاكرة التخزين المؤقت وسجلّ التصفّح، ستظل البيانات محفوظة.
  • تظل الإعدادات المخزَّنة محفوظة حتى عند استخدام وضع التصفّح المتخفي المنفصل.
  • يتضمّن مساحة تخزين مُدارة حصرية للقراءة فقط لسياسات المؤسسة.

هل يمكن للإضافات استخدام واجهات برمجة تطبيقات تخزين الويب؟

على الرغم من أنّ الإضافات يمكنها استخدام واجهة Storage (التي يمكن الوصول إليها من window.localStorage) في بعض السياقات (النوافذ المنبثقة وصفحات HTML الأخرى)، لا ننصح بذلك للأسباب التالية:

  • لا يمكن لمشغّلي خدمات الإضافات استخدام Web Storage API.
  • تشارك النصوص البرمجية للمحتوى مساحة التخزين المشتركة مع الصفحة المضيفة.
  • يتم فقدان البيانات المحفوظة باستخدام واجهة Web Storage API عندما يمحو المستخدم سجلّ التصفّح.

لنقل البيانات من واجهات برمجة تطبيقات مساحة التخزين على الويب إلى واجهات برمجة تطبيقات مساحة التخزين في الإضافات من مشغّل خدمات، اتّبِع الخطوات التالية:

  1. جهِّز صفحة HTML وملف نص برمجي لمستند خارج الشاشة. يجب أن يحتوي ملف النص البرمجي على روتين تحويل ومعالج onMessage.
  2. في مشغّل خدمات الإضافة، تحقَّق من browser.storage بحثًا عن بياناتك.
  3. إذا لم يتم العثور على بياناتك، يُرجى الاتصال بالرقم createDocument().
  4. بعد حلّ Promise الذي تم إرجاعه، يمكنك استدعاء sendMessage() لبدء عملية الإحالة الناجحة.
  5. داخل معالج onMessage للمستند خارج الشاشة، يمكنك استدعاء روتين الإحالة الناجحة.

هناك أيضًا بعض الفروق الدقيقة في آلية عمل واجهات برمجة التطبيقات الخاصة بالتخزين على الويب في الإضافات. يمكنك الاطّلاع على مزيد من المعلومات في مقالة مساحة التخزين وملفات تعريف الارتباط.

حدود مساحة التخزين والتقييد

تتضمّن واجهة Storage API قيودًا على الاستخدام:

  • يؤدي تخزين البيانات إلى تكاليف في الأداء، وتتضمّن واجهة برمجة التطبيقات مساحة تخزين متوفّرة. خطِّط للبيانات التي تنوي تخزينها، حتى تتمكّن من الحفاظ على مساحة التخزين.
  • قد يستغرق اكتمال عملية التخزين بعض الوقت. يجب تنظيم الرمز البرمجي لمراعاة هذا الوقت.

للحصول على تفاصيل حول القيود المفروضة على مساحة التخزين وما يحدث عند تجاوزها، يُرجى الاطّلاع على معلومات الحصة لكل من sync وlocal وsession.

مساحات التخزين

تنقسم واجهة Storage API إلى مساحات التخزين التالية:

بالتوقيت المحلي

يتم تخزين البيانات محليًا ومحوها عند إزالة الإضافة. الحدّ الأقصى لمساحة التخزين هو 10 ميغابايت (5 ميغابايت في الإصدار 113 من Chrome والإصدارات الأقدم)، ولكن يمكن زيادته من خلال طلب إذن "unlimitedStorage". ننصحك باستخدام storage.local لتخزين كميات أكبر من البيانات. يتم عرضها تلقائيًا على نصوص المحتوى البرمجية، ولكن يمكن تغيير هذا السلوك من خلال طلب browser.storage.local.setAccessLevel().

مُدار

تكون مساحة التخزين المُدارة للقراءة فقط للإضافات المثبَّتة من خلال السياسة. وتتم إدارتها من قِبل مشرفي النظام، باستخدام مخطط يحدّده المطوّر وسياسات المؤسسة. تتشابه السياسات مع الخيارات، ولكن يتم ضبطها من قِبل مشرف النظام بدلاً من المستخدم. يتيح ذلك ضبط الإضافة مسبقًا لجميع مستخدمي المؤسسة.

بشكل تلقائي، يتم عرض storage.managed لنصوص المحتوى البرمجية، ولكن يمكن تغيير هذا السلوك من خلال طلب browser.storage.managed.setAccessLevel(). للحصول على معلومات عن السياسات، يُرجى الاطّلاع على مستندات المشرفين. لمزيد من المعلومات حول مساحة التخزين managed، يُرجى الاطّلاع على ملف البيان لمساحات التخزين.

الجلسة

تحتفظ مساحة تخزين الجلسة بالبيانات في الذاكرة أثناء تحميل الإضافة. يتم محو مساحة التخزين في حال إيقاف الإضافة أو إعادة تحميلها أو تحديثها وعند إعادة تشغيل المتصفّح. لا يتم عرضها تلقائيًا في نصوص المحتوى البرمجية، ولكن يمكن تغيير هذا السلوك من خلال طلب browser.storage.session.setAccessLevel(). الحدّ الأقصى لمساحة التخزين هو 10 ميغابايت (ميغابايت واحد في الإصدار 111 من Chrome والإصدارات الأقدم).

تُعدّ واجهة storage.session إحدى الواجهات المتعددة التي ننصح بها لمشغّلي الخدمات.

مزامنة

إذا فعّل المستخدم المزامنة، تتم مزامنة البيانات مع كل متصفّح Chrome يسجّل المستخدم الدخول إليه. وفي حال إيقافها، سيكون سلوكها مماثلاً لـ storage.local. يخزّن Chrome البيانات محليًا عندما يكون المتصفّح غير متصل بالإنترنت ويستأنف المزامنة عند الاتصال بالإنترنت مرة أخرى. يبلغ الحد الأقصى للحصة 100 كيلوبايت تقريبًا، و8 كيلوبايت لكل عنصر.

ننصحك باستخدام storage.sync للحفاظ على إعدادات المستخدم في جميع المتصفّحات التي تتم مزامنتها. إذا كنت تتعامل مع بيانات مستخدمين حساسة، استخدِم storage.session بدلاً من ذلك. بشكل تلقائي، يتم عرض storage.sync لنصوص المحتوى البرمجية، ولكن يمكن تغيير هذا السلوك من خلال طلب browser.storage.sync.setAccessLevel().

الطرق والأحداث

تنفّذ جميع مساحات التخزين واجهة StorageArea.

get()‎

تتيح لك طريقة get() قراءة مفتاح واحد أو أكثر من StorageArea.

getBytesInUse()‎

تتيح لك طريقة getBytesInUse() الاطّلاع على الحصة التي يستخدمها StorageArea.

getKeys()

تتيح لك طريقة getKeys() الحصول على جميع المفاتيح المخزَّنة في StorageArea.

remove()

يتيح لك الإجراء remove() إزالة عنصر من StorageArea.

set()‎

تتيح لك الطريقة set() ضبط عنصر في StorageArea.

setAccessLevel()

تتيح لك طريقة setAccessLevel() التحكّم في الوصول إلى StorageArea.

clear()

تتيح لك طريقة clear() محو جميع البيانات من StorageArea.

onChanged

يتيح لك الحدث onChanged تتبُّع التغييرات التي تطرأ على StorageArea.

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

توضّح الأقسام التالية حالات الاستخدام الشائعة لواجهة Storage API.

الردّ على التعديلات المتعلّقة بمساحة التخزين

لتتبُّع التغييرات التي تم إجراؤها على مساحة التخزين، أضِف مستمعًا إلى حدث onChanged. عندما يتغيّر أي شيء في مساحة التخزين، يتم تنشيط هذا الحدث. يستمع الرمز النموذجي إلى هذه التغييرات:

background.js:

browser.storage.onChanged.addListener((changes, namespace) => {
  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(
      `Storage key "${key}" in namespace "${namespace}" changed.`,
      `Old value was "${oldValue}", new value is "${newValue}".`
    );
  }
});

يمكننا تطوير هذه الفكرة أكثر. في هذا المثال، لدينا صفحة خيارات تتيح للمستخدم تفعيل "وضع تصحيح الأخطاء" (لم يتم عرض التنفيذ هنا). تحفظ صفحة الخيارات الإعدادات الجديدة على الفور في storage.sync، ويستخدم مشغّل الخدمات storage.onChanged لتطبيق الإعداد في أقرب وقت ممكن.

options.html:

<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
  <label for="debug">
    <input type="checkbox" name="debug" id="debug">
    Enable debug mode
  </label>
</form>

options.js:

// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");

// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
  options.debug = event.target.checked;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);

background.js:

function setDebugMode() { /* ... */ }

// Watch for changes to the user's options & apply them
browser.storage.onChanged.addListener((changes, area) => {
  if (area === 'sync' && changes.options?.newValue) {
    const debugMode = Boolean(changes.options.newValue.debug);
    console.log('enable debug mode?', debugMode);
    setDebugMode(debugMode);
  }
});

التحميل المُسبق غير المتزامن من مساحة التخزين

بما أنّ نصوص الخدمة البرمجية لا تعمل طوال الوقت، تحتاج إضافات Manifest V3 أحيانًا إلى تحميل البيانات بشكل غير متزامن من مساحة التخزين قبل تنفيذ معالِجات الأحداث. لإجراء ذلك، يستخدم المقتطف التالي معالج أحداث action.onClicked غير متزامن ينتظر تعبئة المتغيّر العام storageCache قبل تنفيذ منطقه.

background.js:

// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
    // Handle error that occurred during storage initialization.
  }

  // Normal action handler logic.
  storageCache.count++;
  storageCache.lastTabId = tab.id;
  browser.storage.sync.set(storageCache);
});

أدوات مطوري البرامج

يمكنك عرض البيانات المخزّنة وتعديلها باستخدام واجهة برمجة التطبيقات في "أدوات مطوّري البرامج في Chrome". لمزيد من المعلومات، يُرجى الاطّلاع على صفحة عرض مساحة تخزين الإضافات وتعديلها في مستندات &quot;أدوات مطوّري البرامج&quot;.

الأنواع

AccessLevel

الإصدار 102 من Chrome والإصدارات الأحدث browser.* منذ الإصدار 148 من Chrome

مستوى الوصول إلى منطقة التخزين

Enum

‫"TRUSTED_CONTEXTS"
تحدّد السياقات التي تنشأ من الإضافة نفسها.

‫"TRUSTED_AND_UNTRUSTED_CONTEXTS"
تحدّد السياقات التي تنشأ من خارج الإضافة.

StorageChange

الخصائص

  • newValue

    أيّ اختياري

    القيمة الجديدة للعنصر، في حال توفّر قيمة جديدة

  • oldValue

    أيّ اختياري

    القيمة القديمة للعنصر، إذا كانت هناك قيمة قديمة.

الخصائص

local

تكون العناصر في مساحة التخزين local محلية لكل جهاز.

النوع

StorageArea و object

الخصائص

  • QUOTA_BYTES

    10485760

    الحد الأقصى لكمية البيانات (بالبايت) التي يمكن تخزينها في مساحة التخزين المحلية، ويتم قياسها من خلال تحويل كل قيمة إلى سلسلة JSON بالإضافة إلى طول كل مفتاح. سيتم تجاهل هذه القيمة إذا كانت الإضافة تملك الإذن unlimitedStorage. التعديلات التي تؤدي إلى تجاوز هذا الحدّ الأقصى ستفشل على الفور وتضبط runtime.lastError عند استخدام دالة ردّ اتصال، أو دالة Promise مرفوضة في حال استخدام async/await.

managed

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

النوع

StorageArea

session

الإصدار 102 من Chrome والإصدارات الأحدث ‫browser.* ‎ منذ الإصدار 148 من Chrome الإصدار 3 من MV والإصدارات الأحدث

يتم تخزين العناصر في مساحة التخزين "session" في الذاكرة ولن يتم الاحتفاظ بها على القرص.

النوع

StorageArea و object

الخصائص

  • QUOTA_BYTES

    10485760

    الحد الأقصى لكمية البيانات (بالبايت) التي يمكن تخزينها في الذاكرة، ويتم قياسها من خلال تقدير استخدام الذاكرة المخصّصة ديناميكيًا لكل قيمة ومفتاح. التعديلات التي تؤدي إلى تجاوز هذا الحدّ الأقصى ستفشل على الفور وتضبط runtime.lastError عند استخدام دالة ردّ اتصال أو عند رفض Promise.

sync

تتم مزامنة العناصر في مساحة التخزين sync باستخدام ميزة "مزامنة Chrome".

النوع

StorageArea و object

الخصائص

  • MAX_ITEMS

    512

    الحد الأقصى لعدد العناصر التي يمكن تخزينها في مساحة تخزين المزامنة. ستفشل على الفور التعديلات التي تؤدي إلى تجاوز هذا الحدّ، وسيتم ضبط runtime.lastError عند استخدام دالة ردّ اتصال أو عند رفض Promise.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    متوقّف نهائيًا

    لم تعُد واجهة برمجة التطبيقات storage.sync تتضمّن حصة لعمليات الكتابة المستدامة.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    الحد الأقصى لعدد عمليات set أو remove أو clear التي يمكن إجراؤها كل ساعة. وهذا يعني عملية واحدة كل ثانيتين، وهو حدّ أقصى أقل من الحدّ الأقصى الأعلى لعدد عمليات الكتابة في الدقيقة على المدى القصير.

    التعديلات التي تؤدي إلى تجاوز هذا الحدّ الأقصى ستفشل على الفور وتضبط runtime.lastError عند استخدام دالة ردّ اتصال أو عند رفض Promise.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    الحد الأقصى لعدد عمليات set أو remove أو clear التي يمكن تنفيذها كل دقيقة. وهذا يعني عمليتَي كتابة في الثانية، ما يوفّر معدّل نقل بيانات أعلى من عمليات الكتابة في الساعة خلال فترة زمنية أقصر.

    التعديلات التي تؤدي إلى تجاوز هذا الحدّ الأقصى ستفشل على الفور وتضبط runtime.lastError عند استخدام دالة ردّ اتصال أو عند رفض Promise.

  • QUOTA_BYTES

    102400

    الحد الأقصى لإجمالي مقدار البيانات (بالبايت) التي يمكن تخزينها في مساحة التخزين المتزامنة، ويتم قياسه من خلال تحويل كل قيمة إلى سلسلة JSON بالإضافة إلى طول كل مفتاح. التعديلات التي تؤدي إلى تجاوز هذا الحدّ الأقصى ستفشل على الفور وتضبط runtime.lastError عند استخدام دالة ردّ اتصال أو عند رفض Promise.

  • QUOTA_BYTES_PER_ITEM

    8192

    الحد الأقصى للحجم (بالبايت) لكل عنصر فردي في مساحة التخزين المتزامنة، ويتم قياسه من خلال تحويل قيمته إلى سلسلة JSON بالإضافة إلى طول مفتاحه. ستتعذّر على الفور التحديثات التي تحتوي على عناصر أكبر من هذا الحدّ، وسيتم ضبط runtime.lastError عند استخدام دالة ردّ اتصال أو عند رفض Promise.

الفعاليات

onChanged

browser.storage.onChanged.addListener(
  callback: function,
)

يتم تنشيطه عند تغيير عنصر واحد أو أكثر.

المعلمات

  • callback

    دالة

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

    (changes: object, areaName: string) => void

    • التغييرات

      عنصر

    • areaName

      سلسلة