تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

chrome.storage

الوصف

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

الأذونات

storage

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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"
تحدّد هذه السمة السياقات التي تنشأ من خارج الإضافة.

StorageArea

الخصائص

onChanged

Event<functionvoidvoid>

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

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

تبدو الدالة onChanged.addListener على النحو التالي:
```
(callback: function) => {...}
```
- callback
  
  دالة
  
  تظهر المَعلمة callback على النحو التالي:
```
(changes: object) => void
```
  - التغييرات
    
    عنصر
محو

void

الوعد

تتم إزالة جميع العناصر من مساحة التخزين.

تبدو الدالة clear على النحو التالي:
```
(callback?: function) => {...}
```
- callback
  
  الدالة اختيارية
  
  تظهر المَعلمة callback على النحو التالي:
```
() => void
```
- returns
  Promise<void>
  
  الإصدار 95 من Chrome والإصدارات الأحدث
  
  لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.
الحصول على

void

الوعد

تعرض هذه الطريقة عنصرًا واحدًا أو أكثر من مساحة التخزين.

تبدو الدالة get على النحو التالي:
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- مفاتيح
  
  string | string[] | object اختيارية
  
  مفتاح واحد للحصول على البيانات، أو قائمة بالمفاتيح للحصول على البيانات، أو قاموس يحدّد القيم التلقائية (راجِع وصف العنصر). ستعرض القائمة أو العنصر الفارغَين عنصر نتيجة فارغًا. مرِّر null للحصول على محتوى مساحة التخزين بالكامل.
- callback
  
  الدالة اختيارية
  
  تظهر المَعلمة callback على النحو التالي:
```
(items: object) => void
```
  - items
    
    عنصر
    
    عنصر يتضمّن عناصر في عمليات الربط بين المفتاح والقيمة
- returns
  Promise<object>
  
  الإصدار 95 من Chrome والإصدارات الأحدث
  
  لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.
getBytesInUse

void

الوعد

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

تبدو الدالة getBytesInUse على النحو التالي:
```
(keys?: string | string[], callback?: function) => {...}
```
- مفاتيح
  
  string | string[] اختيارية
  
  مفتاح واحد أو قائمة مفاتيح للحصول على إجمالي الاستخدام. ستعرض القائمة الفارغة القيمة 0. أدخِل null للحصول على إجمالي استخدام جميع مساحات التخزين.
- callback
  
  الدالة اختيارية
  
  تظهر المَعلمة callback على النحو التالي:
```
(bytesInUse: number) => void
```
  - bytesInUse
    
    الرقم
    
    مقدار المساحة المستخدَمة في التخزين، بالبايت
- returns
  Promise<number>
  
  الإصدار 95 من Chrome والإصدارات الأحدث
  
  لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.
getKeys

void

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

تعرض هذه الطريقة جميع المفاتيح من مساحة التخزين.

تبدو الدالة getKeys على النحو التالي:
```
(callback?: function) => {...}
```
- callback
  
  الدالة اختيارية
  
  تظهر المَعلمة callback على النحو التالي:
```
(keys: string[]) => void
```
  - مفاتيح
    
    string[]
    
    مصفوفة تتضمّن المفاتيح التي تمّت قراءتها من مساحة التخزين
- returns
  Promise<string[]>
  
  لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.
إزالة

void

الوعد

تزيل هذه الطريقة عنصرًا واحدًا أو أكثر من مساحة التخزين.

تبدو الدالة remove على النحو التالي:
```
(keys: string | string[], callback?: function) => {...}
```
- مفاتيح
  
  سلسلة | سلسلة[]
  
  مفتاح واحد أو قائمة مفاتيح للعناصر المطلوب إزالتها
- callback
  
  الدالة اختيارية
  
  تظهر المَعلمة callback على النحو التالي:
```
() => void
```
- returns
  Promise<void>
  
  الإصدار 95 من Chrome والإصدارات الأحدث
  
  لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.
محدّدة

void

الوعد

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

تبدو الدالة set على النحو التالي:
```
(items: object, callback?: function) => {...}
```
- items
  
  عنصر
  
  عنصر يقدّم كل زوج من المفاتيح والقيم لتعديل مساحة التخزين. ولن تتأثر أي أزواج أخرى من المفاتيح والقيم في مساحة التخزين.
  
  سيتم تسلسل القيم الأساسية، مثل الأرقام، على النحو المتوقّع. سيتم عادةً تحويل القيم التي تتضمّن typeof و"object" و"function" إلى {}، باستثناء Array (يتم تحويلها كما هو متوقّع) وDate وRegex (يتم تحويلها باستخدام تمثيل String).
- callback
  
  الدالة اختيارية
  
  تظهر المَعلمة callback على النحو التالي:
```
() => void
```
- returns
  Promise<void>
  
  الإصدار 95 من Chrome والإصدارات الأحدث
  
  لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.
setAccessLevel

void

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

تُحدِّد مستوى الوصول المطلوب إلى مساحة التخزين. بشكلٍ تلقائي، يقتصر تخزين session على السياقات الموثوق بها (صفحات الإضافات ومشغّلات الخدمات)، بينما يسمح تخزين managed وlocal وsync بالوصول من السياقات الموثوق بها وغير الموثوق بها.

تبدو الدالة setAccessLevel على النحو التالي:
```
(accessOptions: object, callback?: function) => {...}
```
- accessOptions
  
  عنصر
  - accessLevel
    
    AccessLevel
    
    مستوى الوصول إلى مساحة التخزين
- callback
  
  الدالة اختيارية
  
  تظهر المَعلمة callback على النحو التالي:
```
() => void
```
- returns
  Promise<void>
  
  لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

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

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

دالة

تظهر المَعلمة callback على النحو التالي:
```
(changes: object, areaName: string) => void
```
- التغييرات
  
  عنصر
- areaName
  
  سلسلة

chrome.storage تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الوصف

الأذونات

نظرة عامة

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

البيان

الاستخدام

storage.local

storage.sync

storage.session

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

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

الردّ المتزامن على التعديلات في مساحة التخزين

التحميل المُسبَق غير المتزامن من مساحة التخزين

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

الأنواع

AccessLevel

Enum

StorageArea

الخصائص

StorageChange

الخصائص

الخصائص

local

النوع

الخصائص

managed

النوع

sync

النوع

الخصائص

الفعاليات

onChanged

المعلمات

chrome.storage