chrome.storage

الوصف

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

الأذونات

storage

نظرة عامة

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

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

مع أنّ الإضافات يمكنها استخدام واجهة [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". ننصحك باستخدامه لتخزين كميات أكبر من البيانات.

تنبيه: قبل الإصدار 114 من Chrome، كانت الحصة المخصّصة تبلغ 5 ميغابايت تقريبًا.

storage.sync

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

تحذير: يجب ألا تخزن مناطق التخزين المحلية أو التي تتم مزامنتها بيانات المستخدم السرية لأنها غير مشفرة. عند التعامل مع البيانات الحسّاسة، ننصحك باستخدام مساحة التخزين في "session" للاحتفاظ بالقيم في الذاكرة إلى أن يتم إيقاف المتصفّح.

storage.session

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

تحذير: قبل الإصدار 112 من Chrome، كانت الحصة 1 ميغابايت تقريبًا.

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

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

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

التعداد

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

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

StorageArea

أماكن إقامة

• onChanged

  الحدث<functionvoidvoid>

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

  يتم الإطلاق عند تغيير عنصر واحد أو أكثر.

  تبدو دالة onChanged.addListener كما يلي:

  (callback: function) => {...}

  • ردّ الاتصال

    دالة

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

    (changes: object) => void

    • التغييرات

      كائن

• محو

  غير صالح

  وعود

  إزالة كل الملفات من مساحة التخزين

  تبدو الدالة clear على النحو التالي:

  (callback?: function) => {...}

  • رد الاتصال

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

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

    () => void

  • returns

    Promise<void>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

• الحصول على

  غير صالح

  وعود

  الحصول على عنصر واحد أو أكثر من مساحة التخزين

  تبدو الدالة get على النحو التالي:

  (keys?: string | string[] | object, callback?: function) => {...}

  • مفاتيح

    string | string[] | الكائن اختياري

    مفتاح واحد للحصول عليه أو قائمة المفاتيح المطلوب الحصول عليها أو قاموس يحدد القيم التلقائية (راجع وصف الكائن). ستؤدي القائمة أو الكائن الفارغان إلى عرض كائن نتيجة فارغ. أدخِل null للحصول على محتوى مساحة التخزين بالكامل.

  • رد الاتصال

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

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

    (items: object) => void

    • items

      كائن

      عنصر يتضمّن عناصر في عمليات الربط بين المفاتيح والقيم

  • returns

    وعد <object>

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

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

• getBytesInUse

  فراغ

  وعود

  الحصول على مقدار المساحة (بالبايت) الذي يستخدمه عنصر أو أكثر.

  تبدو دالة getBytesInUse كما يلي:

  (keys?: string | string[], callback?: function) => {...}

  • مفاتيح

    string | string[] اختيارية

    مفتاح واحد أو قائمة مفاتيح للحصول على إجمالي الاستخدام ستعرض القائمة الفارغة القيمة 0. أدخِل null للحصول على إجمالي استخدام كل مساحة التخزين.

  • ردّ الاتصال

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

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

    (bytesInUse: number) => void

    • bytesInUse

      الرقم

      مقدار المساحة المستخدَمة في مساحة التخزين، بايت

  • returns

    Promise<number>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

• getKeys

  فراغ

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

  الحصول على جميع المفاتيح من مساحة التخزين

  تبدو دالة getKeys كما يلي:

  (callback?: function) => {...}

  • رد الاتصال

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

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

    (keys: string[]) => void

    • مفاتيح

      string[]

      مصفوفة تتضمّن مفاتيح تتم قراءتها من مساحة التخزين

  • returns

    Promise<string[]>

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

• إزالة

  غير صالح

  وعود

  يؤدي هذا الإجراء إلى إزالة عنصر واحد أو أكثر من مساحة التخزين.

  تبدو الدالة remove على النحو التالي:

  (keys: string | string[], callback?: function) => {...}

  • مفاتيح

    string | string[]

    مفتاح واحد أو قائمة بالمفاتيح للعناصر المطلوب إزالتها

  • رد الاتصال

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

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

    () => void

  • returns

    Promise<void>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

• محدّدة

  غير صالح

  وعود

  لضبط عناصر متعدّدة.

  تبدو الدالة set على النحو التالي:

  (items: object, callback?: function) => {...}

  • items

    كائن

    كائن يتيح لكل زوج مفتاح/قيمة لتعديل مساحة التخزين باستخدامه. لن تتأثر أي أزواج مفاتيح/قيم أخرى في مساحة التخزين.

    سيتم تسلسل القيم الأساسية، مثل الأرقام، على النحو المتوقّع. يتم عادةً تسلسل القيم التي تحتوي على typeof "object" و"function" إلى {}، باستثناء Array (يتم تسلسلها على النحو المتوقّع) وDate وRegex (يتم تسلسلها باستخدام تمثيل String).

  • ردّ الاتصال

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

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

    () => void

  • returns

    Promise<void>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

• setAccessLevel

  غير صالح

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

  لضبط مستوى الوصول المطلوب لمنطقة التخزين. وستكون الإعدادات التلقائية هي السياقات الموثوق بها فقط.

  تبدو الدالة setAccessLevel على النحو التالي:

  (accessOptions: object, callback?: function) => {...}

  • accessOptions

    كائن

    • accessLevel

      AccessLevel

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

  • رد الاتصال

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

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

    () => void

  • returns

    وعود <باطلة>

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

StorageChange

أماكن إقامة

• newValue

  أي اختياري

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

• oldValue

  أي خيار اختياري

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

أماكن إقامة

local

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

النوع

StorageArea و كائن

أماكن إقامة

• QUOTA_BYTES

  10485760
  

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

managed

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

النوع

StorageArea

session

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

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

النوع

StorageArea و كائن

أماكن إقامة

• QUOTA_BYTES

  10485760
  

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

sync

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

النوع

StorageArea و كائن

أماكن إقامة

• MAX_ITEMS

  512
  

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

• MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

  1000000
  

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

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

• MAX_WRITE_OPERATIONS_PER_HOUR

  1800
  

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

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

• MAX_WRITE_OPERATIONS_PER_MINUTE

  120
  

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

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

• QUOTA_BYTES

  102400
  

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

• QUOTA_BYTES_PER_ITEM

  8192
  

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

الفعاليات

onChanged

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

يتم الإطلاق عند تغيير عنصر واحد أو أكثر.

المعلمات

• ردّ الاتصال

  دالة

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

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

  • التغييرات

    كائن

  • areaName

    سلسلة