chrome.storage

الوصف

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

الأذونات

storage

نظرة عامة

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

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

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

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

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

  1. أنشئ مستندًا خارج الشاشة يتضمّن روتين تحويل ومعالج [onMessage][on-message].
  2. أضِف روتين إحالة ناجحة إلى مستند خارج الشاشة.
  3. في عامل خدمة الإضافة، ابحث عن بياناتك في chrome.storage.
  4. إذا لم يتم العثور على بياناتك، [أنشئ][create-offscreen] مستندًا خارج الشاشة واستدعِ [sendMessage()][send-message] لبدء روتين التحويل.
  5. داخل معالج onMessage للمستند خارج الشاشة، استدعِ إجراء التحويل.

هناك أيضًا بعض الفروق الدقيقة في طريقة عمل واجهات برمجة التطبيقات لتخزين البيانات على الويب في الإضافات. يمكنك الاطّلاع على مزيد من المعلومات في مقالة [مساحة التخزين وملفات تعريف الارتباط][storage-and-cookies].

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

تنقسم Storage API إلى أربع مجموعات ("مساحات تخزين") على النحو التالي:

storage.local
يتم تخزين بيانات
محليًا، ويتم محوها عند إزالة الإضافة. يبلغ الحدّ الأقصى للحصة 10 ميغابايت تقريبًا، ولكن يمكن زيادته من خلال طلب الإذن "unlimitedStorage". ننصحك باستخدامه لتخزين كميات أكبر من البيانات.
storage.sync
في حال تفعيل المزامنة، تتم مزامنة البيانات مع أي متصفّح Chrome سجّل المستخدم الدخول إليه. في حال إيقافه، سيتصرف مثل storage.local. يخزِّن Chrome البيانات محليًا عندما يكون المتصفّح غير متصل بالإنترنت، ويستأنف المزامنة عند إعادة الاتصال بالإنترنت. يبلغ الحدّ الأقصى للحصة 100 كيلوبايت تقريبًا، أي 8 كيلوبايت لكل عنصر. ننصحك باستخدامه للحفاظ على إعدادات المستخدمين في جميع المتصفّحات التي تمت مزامنتها.
storage.session
تخزِّن البيانات في الذاكرة طوال مدة جلسة المتصفّح. لا يتم عرضه تلقائيًا على نصوص المحتوى البرمجية، ولكن يمكن تغيير هذا السلوك من خلال ضبط chrome.storage.session.setAccessLevel(). يبلغ الحدّ الأقصى للحصة المتاحة 10 ميغابايت تقريبًا. يمكنك استخدامها لتخزين المتغيرات العامة في جميع عمليات تشغيل عامِل الخدمة.
storage.managed
يمكن للمشرفين استخدام مخطط وسياسات المؤسسة لضبط إعدادات إضافة متوافقة في بيئة مُدارة. مساحة التخزين هذه مخصّصة للقراءة فقط.

البيان

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

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

الاستخدام

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

storage.local

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

storage.sync

chrome.storage.sync.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.sync.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

storage.session

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

لمزيد من المعلومات عن مساحة التخزين managed، يمكنك الاطّلاع على بيان مساحات التخزين.

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

لا تفكّر في إضافة بيانات إلى Storage API على أنّها وضع بيانات في شاحنة كبيرة. يمكنك التفكير في عملية الإضافة إلى مساحة التخزين على أنّها شبيهة بوضع شيء ما في أنبوب. قد يكون الأنبوب يحتوي على مادة بداخله، وقد يكون ممتلئًا. يجب دائمًا افتراض حدوث تأخير بين وقت إضافة البيانات إلى مساحة التخزين ووقت تسجيلها فعليًا.

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

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

توضّح الأقسام التالية حالات الاستخدام الشائعة لواجهة برمجة التطبيقات 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);
});

أمثلة على الإضافات

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

الأنواع

AccessLevel

الإصدار 102 من Chrome والإصدارات الأحدث

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

Enum

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

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

StorageChange

الخصائص

  • newValue

    أي اختياري

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

  • oldValue

    أي اختياري

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

الخصائص

local

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

النوع

StorageArea والكائن

الخصائص

  • QUOTA_BYTES

    10485760

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

managed

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

النوع

StorageArea

sync

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

النوع

StorageArea والكائن

الخصائص

  • 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 التي يمكن تنفيذها كل دقيقة هذا يعني 2 في الثانية، ما يوفّر معدّل نقل بيانات أعلى من عمليات الكتابة في الساعة على مدار فترة زمنية أقصر.

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

  • QUOTA_BYTES

    102400

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

  • QUOTA_BYTES_PER_ITEM

    8192

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

الفعاليات

onChanged

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

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

المعلمات

  • callback

    دالة

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

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

    • التغييرات

      عنصر

    • areaName

      سلسلة