الوصف
استخدِم واجهة برمجة تطبيقات chrome.storage
لتخزين بيانات المستخدمين واستردادها وتتبُّعها.
الأذونات
storage
نظرة عامة
توفّر واجهة برمجة التطبيقات Storage API طريقة خاصة بالإضافة للاحتفاظ ببيانات المستخدم وحالته. وهو يشبه واجهات برمجة تطبيقات التخزين في النظام الأساسي للويب (IndexedDB ومساحة التخزين)، ولكنه مصمّم لتلبية احتياجات التخزين للإضافات. وفي ما يلي بعض الميزات الأساسية:
- يمكن لجميع سياقات الإضافات، بما في ذلك مشغّل خدمات الإضافات والنصوص البرمجية للمحتوى، الوصول إلى واجهة برمجة التطبيقات 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 إلى المجموعات الأربع التالية ("مناطق التخزين"):
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
مستوى الوصول إلى منطقة التخزين.
التعداد
"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) => {...}
-
مفاتيح
سلسلة | سلسلة[] | كائن اختياري
مفتاح واحد يجب الحصول عليه أو قائمة بالمفاتيح المطلوب الحصول عليها أو قاموس يحدد القيم التلقائية (اطّلِع على وصف الكائن). ستعرض القائمة أو الكائن الفارغة كائن نتيجة فارغًا. مرِّر خلال
null
للحصول على كامل محتوى مساحة التخزين. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(items: object) => void
-
items
عنصر
كائن يحتوي على عناصر في تعيينات القيمة الرئيسية.
-
-
returns
Promise<object>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
-
-
getBytesInUse
void
وعدلمعرفة مقدار المساحة (بالبايت) التي يستخدمها عنصر أو أكثر.
تبدو الدالة
getBytesInUse
على النحو التالي:(keys?: string | string[], callback?: function) => {...}
-
مفاتيح
سلسلة | string[] اختيارية
مفتاح واحد أو قائمة مفاتيح للحصول على إجمالي الاستخدام لها. ستعرض القائمة الفارغة 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) => {...}
-
items
عنصر
يشير ذلك المصطلح إلى كائن يمنح كل زوج مفتاح/قيمة لتعديل مساحة التخزين باستخدامه. ولن تتأثر أي أزواج أخرى من المفاتيح/القيم في مساحة التخزين.
وسيتم ترتيب القيم الأولية مثل الأرقام في تسلسل كما هو متوقع. عادةً ما يتم عرض القيم ذات الترميزَين
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
مستوى الوصول إلى مساحة التخزين.
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
-
returns
Promise<void>
لا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
-
StorageChange
أماكن إقامة
-
newValue
أي اختياري
القيمة الجديدة للعنصر، إذا كانت هناك قيمة جديدة.
-
oldValue
أي اختياري
القيمة القديمة للسلعة، إذا كانت هناك قيمة قديمة.
أماكن إقامة
local
وتكون العناصر الموجودة في منطقة التخزين local
محلية لكل جهاز.
النوع
StorageArea والكائن
أماكن إقامة
-
QUOTA_BYTES
10485760
الحد الأقصى لحجم البيانات (بالبايت) الذي يمكن تخزينه في مساحة التخزين المحلية، يتم قياسه من خلال سلسلة JSON لكل قيمة بالإضافة إلى طول كل مفتاح. سيتم تجاهل هذه القيمة إذا كانت الإضافة تمتلك إذن
unlimitedStorage
. تجدر الإشارة إلى أنّ التحديثات التي قد تؤدي إلى تجاوز هذا الحدّ ستتعذّر على الفور، ويتم ضبطruntime.lastError
عند استخدام معاودة الاتصال، أو "وعد مرفوض" في حال استخدام "غير متزامن" أو "انتظار".
managed
يتم ضبط العناصر في مساحة التخزين على managed
من خلال سياسة مؤسسة ضبطها مشرف النطاق، وتكون متاحة للقراءة فقط للإضافة. عند محاولة تعديل مساحة الاسم هذه، تظهر خطأ. للحصول على معلومات عن ضبط السياسة، يُرجى الاطّلاع على ملف البيان الخاص بمناطق التخزين.
النوع
session
يتم تخزين العناصر الموجودة في منطقة التخزين 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
سلسلة
-