الوصف
استخدِم واجهة برمجة تطبيقات 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 عندما يمحو المستخدم سجلّ التصفُّح.
لنقل البيانات من واجهات برمجة التطبيقات لتخزين الويب إلى واجهات برمجة تطبيقات لتخزين الإضافات من عامل خدمات، يُرجى اتّباع الخطوات التالية:
- إعداد صفحة html لمستند خارج الشاشة وملف نص برمجي. يجب أن يحتوي ملف النص البرمجي على سلسلة إجراءات إحالة ناجحة ومعالج
onMessage
. - في مشغّل خدمات الإضافات، تحقَّق من "
chrome.storage
" للحصول على بياناتك. - إذا لم يتم العثور على بياناتك، اتّصِل بالرقم
createDocument()
. - بعد حلّ الوعد الذي تم عرضه، اتّصِل بالرقم
sendMessage()
لبدء سلسلة إجراءات الإحالة الناجحة. - داخل معالِج
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
مستوى الوصول إلى منطقة التخزين.
التعداد
"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) => {...}
-
مفاتيح
سلسلة | سلسلة[] | كائن اختياري
مفتاح واحد يجب الحصول عليه أو قائمة بالمفاتيح المطلوب الحصول عليها أو قاموس يحدد القيم التلقائية (اطّلِع على وصف الكائن). ستعرض القائمة أو الكائن الفارغة كائن نتيجة فارغًا. مرِّر خلال
null
للحصول على كامل محتوى مساحة التخزين. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(items: object) => void
-
items
عنصر
كائن يحتوي على عناصر في تعيينات القيمة الرئيسية.
-
-
returns
Promise<object>
Chrome 88 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
-
-
getBytesInUse
void
وعدلمع��فة مقدار المساحة (بالبايت) التي يستخدمها عنصر أو أكثر.
تبدو الدالة
getBytesInUse
على النحو التالي:(keys?: string | string[], callback?: function) => {...}
-
مفاتيح
سلسلة | string[] اختيارية
مفتاح واحد أو قائمة مفاتيح للحصول على إجمالي الاستخدام لها. ستعرض القائمة الفارغة 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) => {...}
-
items
عنصر
يشير ذلك المصطلح إلى كائن يمنح كل زوج مفتاح/قيمة لتعديل مساحة التخزين باستخدامه. ولن تتأثر أي أزواج أخرى من المفاتيح/القيم في مساحة التخزين.
وسيتم ترتيب القيم الأولية مثل الأرقام في تسلسل كما هو متوقع. عادةً ما يتم عرض القيم ذات الترميزَين
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
مستوى الوصول إلى مساحة التخزين.
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
-
returns
Promise<void>
تتوفّر الوعود في إصدار 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
سلسلة
-