توضیحات
از chrome.storage
API برای ذخیره، بازیابی و پیگیری تغییرات داده های کاربر استفاده کنید.
مجوزها
storage
برای استفاده از API ذخیره سازی، مجوز "storage"
را در مانیفست برنامه افزودنی اعلام کنید. به عنوان مثال:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
مفاهیم و کاربرد
Storage API یک راه مخصوص برنامه افزودنی برای تداوم داده ها و وضعیت کاربر ارائه می دهد. این شبیه به APIهای ذخیره سازی پلتفرم وب ( IndexedDB و Storage ) است، اما برای رفع نیازهای ذخیره سازی برنامه های افزودنی طراحی شده است. در زیر چند ویژگی کلیدی ذکر شده است:
- همه زمینه های برنامه افزودنی، از جمله کارگر سرویس برنامه افزودنی و اسکریپت های محتوا، به Storage API دسترسی دارند.
- مقادیر سریالسازی JSON به عنوان ویژگیهای شی ذخیره میشوند.
- Storage API با عملیات خواندن و نوشتن انبوه ناهمزمان است.
- حتی اگر کاربر حافظه پنهان و تاریخچه مرور را پاک کند، داده ها باقی می مانند.
- تنظیمات ذخیره شده حتی با استفاده از حالت ناشناس تقسیم شده باقی می مانند.
- شامل یک فضای ذخیرهسازی مدیریتشده فقط خواندنی برای خطمشیهای سازمانی است.
آیا برنامه های افزودنی می توانند از API های ذخیره سازی وب استفاده کنند؟
در حالی که برنامههای افزودنی میتوانند از رابط Storage
(قابل دسترسی از window.localStorage
) در برخی زمینهها (پاپآپ و سایر صفحات HTML) استفاده کنند، به دلایل زیر آن را توصیه نمیکنیم:
- کارکنان خدمات برنامه افزودنی نمی توانند از Web Storage API استفاده کنند.
- اسکریپت های محتوا فضای ذخیره سازی را با صفحه میزبان به اشتراک می گذارند.
- اطلاعات ذخیره شده با استفاده از Web Storage API زمانی که کاربر تاریخچه مرور خود را پاک می کند از بین می رود.
برای انتقال داده ها از API های ذخیره سازی وب به API های ذخیره سازی افزونه از یک سرویس دهنده:
- یک صفحه html سند خارج از صفحه و فایل اسکریپت آماده کنید. فایل اسکریپت باید شامل یک روال تبدیل و یک کنترل کننده
onMessage
باشد. - در کارگر خدمات افزودنی،
chrome.storage
برای اطلاعات خود بررسی کنید. - اگر دادههای شما پیدا نشد،
createDocument()
فراخوانی کنید. - پس از حل شدن Promise برگشتی، برای شروع روال تبدیل
sendMessage()
فراخوانی کنید. - در کنترل کننده
onMessage
سند خارج از صفحه، روال تبدیل را فراخوانی کنید.
همچنین برخی تفاوت های ظریف در مورد نحوه عملکرد API های ذخیره سازی وب در برنامه های افزودنی وجود دارد. در مقاله ذخیره سازی و کوکی ها بیشتر بیاموزید.
مناطق ذخیره سازی
Storage API به مناطق ذخیره سازی زیر تقسیم می شود:
-
storage.local
- داده ها به صورت محلی ذخیره می شوند و با حذف برنامه افزودنی پاک می شوند. محدودیت فضای ذخیره سازی 10 مگابایت است (5 مگابایت در کروم 113 و نسخه های قبلی)، اما می توان با درخواست مجوز
"unlimitedStorage"
آن را افزایش داد. توصیه می کنیم ازstorage.local
برای ذخیره حجم بیشتری از داده استفاده کنید. -
storage.managed
- فضای ذخیرهسازی مدیریتشده، فضای ذخیرهسازی فقط خواندنی برای برنامههای افزودنی نصبشده خطمشی است و توسط مدیران سیستم با استفاده از طرح و خطمشیهای سازمانی تعریفشده توسط توسعهدهنده مدیریت میشود. خطمشیها مشابه گزینهها هستند، اما توسط مدیر سیستم به جای کاربر پیکربندی میشوند و اجازه میدهند افزونه برای همه کاربران یک سازمان از پیش پیکربندی شود. برای اطلاعات در مورد خطمشیها، به مستندات برای مدیران مراجعه کنید. برای کسب اطلاعات بیشتر در مورد فضای ذخیره سازی
managed
، به Manifest برای مناطق ذخیره سازی مراجعه کنید. -
storage.session
- داده ها را برای مدت یک جلسه مرورگر در حافظه نگه می دارد. بهطور پیشفرض، در معرض اسکریپتهای محتوا قرار نمیگیرد، اما این رفتار را میتوان با تنظیم
chrome.storage.session.setAccessLevel()
تغییر داد. محدودیت فضای ذخیره سازی 10 مگابایت است (1 مگابایت در کروم 111 و نسخه های قبلی). رابطstorage.session
یکی از چندین موردی است که ما برای سرویسکاران توصیه می کنیم . -
storage.sync
- اگر همگامسازی فعال باشد، دادهها با هر مرورگر Chrome که کاربر به آن وارد شده است همگامسازی میشود. اگر غیرفعال باشد، مانند
storage.local
عمل میکند. وقتی مرورگر آفلاین است، Chrome دادهها را به صورت محلی ذخیره میکند و وقتی دوباره آنلاین شد همگامسازی را از سر میگیرد. محدودیت سهمیه تقریباً 100 کیلوبایت، 8 کیلوبایت برای هر مورد است. توصیه میکنیم ازstorage.sync
برای حفظ تنظیمات کاربر در مرورگرهای همگامسازی شده استفاده کنید. اگر با داده های حساس کاربر کار می کنید، در عوض ازstorage.session
استفاده کنید.
محدودیت های ذخیره سازی و گاز
Storage API دارای محدودیتهای استفاده زیر است:
- ذخیره سازی داده ها اغلب با هزینه های عملکرد همراه است و 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 گاهی اوقات قبل از اجرای کنترلکنندههای رویداد خود، نیاز به بارگیری ناهمزمان دادهها از فضای ذخیرهسازی دارند. برای انجام این کار، قطعه زیر از یک مدیریت رویداد async 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
سطح دسترسی منطقه ذخیره سازی
Enum
"TRUSTED_CONTEXTS" "TRUSTED_AND_UNTRUSTED_CONTEXTS"
زمینه هایی را مشخص می کند که از خود پسوند نشات می گیرند.
زمینه هایی را مشخص می کند که از خارج از پسوند منشا می گیرند.
StorageArea
خواص
- در تغییر
رویداد<functionvoidvoid>
Chrome 73+هنگامی که یک یا چند مورد تغییر می کند، فعال می شود.
تابع
onChanged.addListener
به شکل زیر است:(callback: function) => {...}
- پاسخ به تماس
تابع
پارامتر
callback
به نظر می رسد:(changes: object) => void
- تغییر می کند
شی
- روشن
باطل
قول بدههمه موارد را از فضای ذخیره سازی حذف می کند.
تابع
clear
به نظر می رسد:(callback?: function) => {...}
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
- برمی گرداند
قول<باطل>
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوع که به callback ارسال می شود حل می شود.
- دریافت کنید
باطل
قول بدهیک یا چند مورد را از ذخیره سازی دریافت می کند.
تابع
get
به نظر می رسد:(keys?: string | string[] | object, callback?: function) => {...}
- کلیدها
رشته | رشته[] | شی اختیاری
یک کلید برای دریافت، فهرست کلیدهایی که باید دریافت کنید، یا یک فرهنگ لغت که مقادیر پیشفرض را مشخص میکند (به توضیحات شی مراجعه کنید). یک لیست یا شی خالی یک شی نتیجه خالی را برمی گرداند. برای دریافت کل محتویات فضای ذخیره سازی، به صورت
null
عبور دهید. - پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(items: object) => void
- موارد
شی
شیء با موارد در نگاشتهای کلید-مقدار آنها.
- برمی گرداند
قول<object>
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
- getBytesInUse
باطل
قول بدهمقدار فضای استفاده شده توسط یک یا چند مورد را (بر حسب بایت) دریافت می کند.
تابع
getBytesInUse
به شکل زیر است:(keys?: string | string[], callback?: function) => {...}
- کلیدها
رشته | رشته[] اختیاری است
یک کلید یا فهرستی از کلیدها برای دریافت کل مصرف. یک لیست خالی 0 را برمیگرداند. برای دریافت کل استفاده از کل فضای ذخیرهسازی، آن را
null
کنید. - پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(bytesInUse: number) => void
- bytesInUse
شماره
مقدار فضای مورد استفاده در ذخیره سازی، بر حسب بایت.
- برمی گرداند
قول <تعداد>
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
- getKeys
باطل
Promise Chrome 130+همه کلیدها را از فضای ذخیرهسازی دریافت میکند.
تابع
getKeys
به نظر می رسد:(callback?: function) => {...}
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(keys: string[]) => void
- کلیدها
رشته[]
آرایه ای با کلیدهای خوانده شده از ذخیره سازی.
- برمی گرداند
قول<string[]>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
- حذف کنید
باطل
قول بدهیک یا چند مورد را از فضای ذخیره سازی حذف می کند.
تابع
remove
به نظر می رسد:(keys: string | string[], callback?: function) => {...}
- کلیدها
رشته | رشته[]
یک کلید یا فهرستی از کلیدها برای حذف موارد.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
- برمی گرداند
قول<باطل>
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
- مجموعه
باطل
قول بدهچندین آیتم را تنظیم می کند.
تابع
set
به نظر می رسد:(items: object, callback?: function) => {...}
- موارد
شی
شیئی که به هر جفت کلید/مقدار می دهد تا فضای ذخیره سازی را با آن به روز کند. سایر جفتهای کلید/مقدار موجود در فضای ذخیرهسازی تحت تأثیر قرار نمیگیرند.
مقادیر اولیه مانند اعداد همانطور که انتظار می رود سریال می شوند. مقادیر با یک
typeof
"object"
و"function"
معمولاً به صورت سریال به{}
تبدیل میشوند، به استثنایArray
(مرتبسازیشده طبق انتظار)،Date
وRegex
(سریالسازی با استفاده از نمایشString
آنها). - پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
- برمی گرداند
قول<باطل>
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
- setAccessLevel
باطل
Promise Chrome 102+سطح دسترسی مورد نظر را برای منطقه ذخیره سازی تنظیم می کند. پیش فرض فقط زمینه های قابل اعتماد خواهد بود.
تابع
setAccessLevel
به شکل زیر است:(accessOptions: object, callback?: function) => {...}
- گزینه های دسترسی
شی
- سطح دسترسی
سطح دسترسی به فضای ذخیره سازی
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
- برمی گرداند
قول<باطل>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
StorageChange
خواص
- newValue
هر اختیاری
مقدار جدید مورد، در صورت وجود مقدار جدید.
- oldValue
هر اختیاری
ارزش قدیمی مورد، اگر مقدار قدیمی وجود داشته باشد.
خواص
local
اقلام در منطقه ذخیره سازی local
برای هر دستگاه محلی هستند.
تایپ کنید
Storage Area & Object
خواص
- QUOTA_BYTES
10485760
حداکثر مقدار (بر حسب بایت) داده ای که می تواند در حافظه محلی ذخیره شود، همانطور که با رشته JSON هر مقدار به اضافه طول هر کلید اندازه گیری می شود. اگر برنامه افزودنی دارای مجوز
unlimitedStorage
باشد، این مقدار نادیده گرفته میشود. بهروزرسانیهایی که باعث فراتر رفتن از این محدودیت میشوند، فوراً با شکست مواجه میشوند وruntime.lastError
هنگام استفاده از پاسخ به تماس یا Promise رد شده در صورت استفاده از async/wait تنظیم میکنند.
managed
موارد موجود در ناحیه ذخیرهسازی managed
توسط یک خطمشی سازمانی که توسط سرپرست دامنه پیکربندی شده است، تنظیم میشوند و برای برنامه افزودنی فقط خواندنی هستند. تلاش برای تغییر این فضای نام منجر به خطا می شود. برای اطلاعات در مورد پیکربندی یک خط مشی، به Manifest برای مناطق ذخیره سازی مراجعه کنید.
تایپ کنید
session
موارد موجود در قسمت ذخیره سازی session
در حافظه ذخیره می شوند و روی دیسک باقی نمی مانند.
تایپ کنید
Storage Area & Object
خواص
- QUOTA_BYTES
10485760
حداکثر مقدار (بر حسب بایت) داده ای که می تواند در حافظه ذخیره شود، که با تخمین میزان مصرف حافظه تخصیص یافته به صورت پویا از هر مقدار و کلید اندازه گیری می شود. بهروزرسانیهایی که باعث تجاوز از این محدودیت میشوند، فوراً با شکست مواجه میشوند و
runtime.lastError
هنگام استفاده از تماس برگشتی یا زمانی که یک Promise رد میشود، تنظیم میکنند.
sync
موارد موجود در فضای ذخیرهسازی sync
با استفاده از Chrome Sync همگامسازی میشوند.
تایپ کنید
Storage Area & Object
خواص
- MAX_ITEMS
512
حداکثر تعداد مواردی که می توان در فضای ذخیره سازی همگام ذخیره کرد. بهروزرسانیهایی که باعث تجاوز از این محدودیت میشوند، فوراً با شکست مواجه میشوند و
runtime.lastError
را هنگام استفاده از پاسخ به تماس یا زمانی که یک Promise رد میشود تنظیم میکنند. - MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1000000
منسوخ شده استStorage.sync API دیگر سهمیه عملیات نوشتن پایدار ندارد.
- MAX_WRITE_OPERATIONS_PER_HOUR
1800
حداکثر تعداد عملیات
set
،remove
یاclear
که میتوان در هر ساعت انجام داد. این 1 در هر 2 ثانیه است، سقف کمتری نسبت به محدودیت نوشتن در دقیقه بالاتر کوتاه مدت.بهروزرسانیهایی که باعث تجاوز از این محدودیت میشوند، فوراً با شکست مواجه میشوند و
runtime.lastError
هنگام استفاده از تماس برگشتی یا زمانی که یک Promise رد میشود، تنظیم میکنند. - MAX_WRITE_OPERATIONS_PER_MINUTE
120
حداکثر تعداد عملیات
set
،remove
یاclear
که می توان در هر دقیقه انجام داد. این 2 در ثانیه است که در مدت زمان کوتاه تری توان عملیاتی بالاتری نسبت به نوشتن در ساعت دارد.بهروزرسانیهایی که باعث تجاوز از این محدودیت میشوند، فوراً با شکست مواجه میشوند و
runtime.lastError
هنگام استفاده از تماس برگشتی یا زمانی که یک Promise رد میشود، تنظیم میکنند. - QUOTA_BYTES
102400
حداکثر مقدار کل (بر حسب بایت) دادهای که میتوان در فضای ذخیرهسازی همگامسازی ذخیره کرد، همانطور که با رشتهبندی JSON هر مقدار به اضافه طول هر کلید اندازهگیری میشود. بهروزرسانیهایی که باعث تجاوز از این محدودیت میشوند، فوراً با شکست مواجه میشوند و
runtime.lastError
هنگام استفاده از تماس برگشتی یا زمانی که یک Promise رد میشود، تنظیم میکنند. - QUOTA_BYTES_PER_ITEM
8192
حداکثر اندازه (بر حسب بایت) هر مورد جداگانه در فضای ذخیره سازی همگام، همانطور که با رشته JSON مقدار آن به اضافه طول کلید اندازه گیری می شود. بهروزرسانیهایی که حاوی موارد بزرگتر از این حد هستند، فوراً با شکست مواجه میشوند و هنگام استفاده از پاسخ به تماس یا زمانی که یک Promise رد میشود،
runtime.lastError
تنظیم میکند.
رویدادها
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
هنگامی که یک یا چند مورد تغییر می کند، فعال می شود.
پارامترها
- پاسخ به تماس
تابع
پارامتر
callback
به نظر می رسد:(changes: object, areaName: string) => void
- تغییر می کند
شی
- ناحیه نام
رشته