chrome.storage

الوصف

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

الأذونات

storage

نظرة عامة

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

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

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

البيان

لاستخدام واجهة برمجة التطبيقات Storage، حدِّد إذن "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 على أنها وضع الأشياء في شاحنة كبيرة. فكر في الإضافة إلى التخزين على أنه وضع شيء ما في ممر. قد يحتوي الممر على مواد بالفعل، وقد يتم ملؤه. افتراض دائمًا وجود تأخير بين وقت الإضافة إلى مساحة التخزين ووقت تسجيلها فعليًا.

للحصول على تفاصيل عن حدود منطقة التخزين وما يحدث عند تجاوزها، يمكنك الاطّلاع على معلومات الحصّة لكل من 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

    الحدث<functionvitvit>

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

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

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

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

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

      الوظيفة

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

      (changes: object)=>void

      • التغييرات

        كائن

  • محو

    void

    وعد

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

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

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

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

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

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

      ()=>void

    • returns

      Promise<void>

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

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

  • الحصول على

    void

    وعد

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

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

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

    • مفاتيح

      string|string[]|object optional

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

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

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

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

      (items: object)=>void

      • عناصر

        كائن

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

    • returns

      Promise<object>

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

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

  • getBytesInUse

    void

    وعد

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

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

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

    • مفاتيح

      string|string[] optional

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

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

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

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

      (bytesInUse: number)=>void

      • bytesInUse

        الرقم

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

    • returns

      وعد<الرقم>

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

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

  • إزالة

    void

    وعد

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

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

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

    • مفاتيح

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

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

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

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

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

      ()=>void

    • returns

      Promise<void>

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

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

  • ضبط

    void

    وعد

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

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

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

    • عناصر

      كائن

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

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

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

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

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

      ()=>void

    • returns

      Promise<void>

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

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

  • setAccessLevel

    void

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

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

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

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

    • accessOptions

      كائن

      • accessLevel

        AccessLevel

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

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

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

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

      ()=>void

    • returns

      Promise<void>

      لا تتوفّر الوعود إلا في الإصدار 3 من 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

      سلسلة