chrome.storage

الوصف

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

الأذونات

storage

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

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

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

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

• يمكن لجميع سياقات الإضافات، بما في ذلك مشغّل خدمات الإضافات والنصوص البرمجية للمحتوى، الوصول إلى واجهة برمجة التطبيقات 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.local

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

storage.managed

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

storage.session

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

storage.sync

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

حدود التخزين والتقييد

تخضع واجهة برمجة التطبيقات 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);
});

أمثلة

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

حملة محلية

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

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

مزامنة

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

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

الجلسة

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

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

للاطّلاع على الإصدارات التجريبية الأخرى من Storage API، يمكنك الاطّلاع على أيّ من النماذج التالية:

• إضافة البحث العام:
• إضافة إنذار الماء:

الأنواع

AccessLevel

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

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

التعداد

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

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

StorageArea

أماكن إقامة

• onChanged

  الحدث<functionvitvit>

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

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

  تبدو الدالة onChanged.addListener على النحو التالي:

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

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي:

    (changes: object)=>void

    • التغييرات

      عنصر

• محو

  void

  وعد

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

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

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي:

    ()=>void

  • returns

    Promise<void>

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

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

• الحصول على

  void

  وعد

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

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

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

  • مفاتيح

    string|string[]|object optional

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي:

    (items: object)=>void

    • عناصر

      عنصر

      كائن يحتوي على عناصر في تعيينات القيمة الرئيسية.

  • returns

    Promise<object>

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

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

• getBytesInUse

  void

  وعد

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

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

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

  • مفاتيح

    string|string[] optional

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي:

    (bytesInUse: number)=>void

    • bytesInUse

      الرقم

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

  • returns

    وعد<الرقم>

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

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

• إزالة

  void

  وعد

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

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

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

  • مفاتيح

    سلسلة|سلسلة[]

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي:

    ()=>void

  • returns

    Promise<void>

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

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

• ضبط

  void

  وعد

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

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

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

  • عناصر

    عنصر

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

    وسيتم ترتيب القيم الأولية مثل الأرقام في تسلسل كما هو متوقع. عادةً ما يتم عرض القيم ذات الترميزَين typeof "object" و"function" في تسلسل على {}، باستثناء Array (يتم الترتيب بالتسلسل كما هو متوقع) وDate وRegex (التسلسل باستخدام تمثيل String).

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي:

    ()=>void

  • returns

    Promise<void>

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

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

• setAccessLevel

  void

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

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

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

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

  • accessOptions

    عنصر

    • accessLevel

      AccessLevel

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي:

    ()=>void

  • returns

    Promise<void>

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

StorageChange

أماكن إقامة

• newValue

  أي اختياري

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

• oldValue

  أي اختياري

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

أماكن إقامة

local

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

النوع

كائن StorageArea

أماكن إقامة

• QUOTA_BYTES

  10485760
  

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

managed

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

النوع

StorageArea

session

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

يتم تخزين العناصر الموجودة في منطقة التخزين 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 لها حصة عمليات كتابة مستدامة.

• MAX_WRITE_OPERATIONS_PER_HOUR

  1800
  

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

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

• MAX_WRITE_OPERATIONS_PER_MINUTE

  120
  

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

  إنّ التحديثات التي قد تؤدي إلى تجاوز هذا الحدّ ستتعذّر على الفور وضبط 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

    سلسلة