chrome.storage

الوصف

الأذونات

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

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

أمثلة

تعرض العيّنات التالية مناطق التخزين local وsync وsession:

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

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

await chrome.storage.session.set({ key: value });
console.log("Value is set");
const result = await chrome.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. في مشغّل الخدمات للإضافة، ابحث عن بياناتك في chrome.storage.
3. إذا لم يتم العثور على بياناتك، استخدِم createDocument().
4. بعد أن يتم حلّ الوعد الذي تم عرضه، استخدِم sendMessage() لبدء روتين التحويل.
5. داخل معالج onMessage للمستند خارج الشاشة، استخدِم روتين التحويل.

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

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

تفرض واجهة برمجة التطبيقات Storage API قيودًا على الاستخدام:

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

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

مناطق التخزين

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

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

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

مساحة التخزين المُدارة

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

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

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

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

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

مزامنة

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

ننصحك باستخدام storage.sync للاحتفاظ بإعدادات المستخدمين على مستوى المتصفّحات التي تتم مزامنتها. إذا كنت تعمل على بيانات حسّاسة للمستخدمين، استخدِم storage.session بدلاً من ذلك. تكون storage.sync متاحة للنصوص البرمجية للمحتوى بشكل تلقائي، ولكن يمكن تغيير هذا السلوك من خلال استخدام chrome.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:

chrome.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;
  chrome.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await chrome.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
chrome.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 = chrome.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

chrome.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;
  chrome.storage.sync.set(storageCache);
});

DevTools

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

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