chrome.storage

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات 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 و object

الخصائص

  • QUOTA_BYTES

    10485760

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

managed

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

النوع

StorageArea

sync

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

النوع

StorageArea و object

الخصائص

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

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

  • QUOTA_BYTES

    102400

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

  • QUOTA_BYTES_PER_ITEM

    8192

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

الفعاليات

onChanged

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

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

المعلمات

  • callback

    دالة

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

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

    • التغييرات

      عنصر

    • areaName

      سلسلة