browser.storage

شرح

از chrome.storage API برای ذخیره، بازیابی، و پیگیری تغییرات داده‌های کاربر استفاده کنید.

اجازه‌ها

storage

برای استفاده از میانای برنامه‌سازی کاربردی فضای ذخیره‌سازی، اجازه "storage" را در مانیفست افزونه اعلام کنید. برای مثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

مثال‌ها

نمونه‌های زیر فضاهای ذخیره‌سازی local، sync، و session را نشان می‌دهند:

نمونه (محلی)

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

مثال (همگام‌سازی)

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

مثال (جلسه)

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

برای دیدن نسخه‌های نمایشی دیگر Storage API، هرکدام از نمونه‌های زیر را کاوش کنید:

• افزونه جستجوی سراسری.
• افزونه هشدار آب.

مفاهیم و کاربرد

‫Storage API روشی مختص افزونه برای حفظ داده‌ها و وضعیت کاربر ارائه می‌دهد. این میانای برنامه‌سازی کاربردی مشابه میاناهای برنامه‌سازی کاربردی فضای ذخیره‌سازی پلاتفرم وب (IndexedDB و Storage) است، اما برای برآورده کردن نیازهای فضای ذخیره‌سازی افزونه‌ها طراحی شده است. در زیر چند ویژگی کلیدی آورده شده است:

• همه زمینه‌های افزونه، ازجمله کارگر سرویس افزونه و دستورگان‌های محتوا، به Storage API دسترسی دارند.
• مقادیر قابل‌سریال‌سازی JSON به‌عنوان ویژگی‌های شیء ذخیره می‌شوند.
• Storage API با عملیات خواندن و نوشتن انبوه ناهمگام است.
• حتی اگر کاربر حافظه پنهان و سابقه مرور را پاک کند، داده‌ها باقی می‌مانند.
• تنظیمات ذخیره‌شده حتی هنگام استفاده از حالت ناشناس تقسیم‌شده نیز باقی می‌مانند.
• شامل فضای ذخیره‌سازی مدیریت‌شده انحصاری فقط‌خواندنی برای خط‌مشی‌های سازمانی است.

آیا افزونه‌ها می‌توانند از میاناهای برنامه‌سازی کاربردی فضای ذخیره‌سازی وب استفاده کنند؟

درحالی‌که افزونه‌ها می‌توانند از میانای Storage (قابل‌دسترسی از window.localStorage) در برخی زمینه‌ها (صفحات بالاپر و دیگر صفحات HTML) استفاده کنند، ما این کار را به‌دلایل زیر توصیه نمی‌کنیم:

• کارگران سرویس افزونه نمی‌توانند از Web Storage API استفاده کنند.
• متن‌های محتوا فضای ذخیره‌سازی را با صفحه میزبان هم‌رسانی می‌کنند.
• داده‌های ذخیره‌شده بااستفاده از Web Storage API وقتی کاربر سابقه مرور خود را پاک می‌کند ازبین می‌رود.

برای انتقال داده‌ها از میاناهای برنامه‌سازی کاربردی فضای ذخیره‌سازی وب به میاناهای برنامه‌سازی کاربردی فضای ذخیره‌سازی افزونه ازطریق سرویس‌کار:

1. یک صفحه html سند خارج از صفحه و فایل اسکریپت آماده کنید. فایل متن باید حاوی روال تبدیل و گرداننده onMessage باشد.
2. در کارگر سرویس افزونه، browser.storage را برای داده‌هایتان بررسی کنید.
3. اگر داده‌هایتان پیدا نشد، با createDocument() تماس بگیرید.
4. پس‌از حل شدن Promise برگردانده‌شده، sendMessage() را فراخوانی کنید تا روال تبدیل شروع شود.
5. در کنترل‌کننده onMessage سند خارج‌از صفحه، روال تبدیل را فراخوانی کنید.

همچنین تفاوت‌های ظریفی در نحوه عملکرد میاناهای برنامه‌سازی کاربردی فضای ذخیره‌سازی وب در افزونه‌ها وجود دارد. در مقاله فضای ذخیره‌سازی و کوکی‌ها بیشتر بدانید.

محدودیت‌های فضای ذخیره‌سازی و محدود کردن شبکه

‫Storage API محدودیت‌های استفاده دارد:

• ذخیره کردن داده‌ها هزینه عملکردی دارد و میانای برنامه‌سازی کاربردی شامل سهمیه فضای ذخیره‌سازی است. داده‌هایی را که قصد دارید ذخیره کنید برنامه‌ریزی کنید تا فضای ذخیره‌سازی را حفظ کنید.
• تکمیل شدن فضای ذخیره‌سازی ممکن است زمان ببرد. کدتان را طوری ساختاربندی کنید که آن زمان را درنظر بگیرد.

برای جزئیات مربوط به محدودیت‌های فضای ذخیره‌سازی و آنچه درصورت فراتر رفتن از آن‌ها اتفاق می‌افتد، اطلاعات سهمیه را برای sync، local، و session ببینید.

محل‌های نگهداری

Storage API به بخش‌های ذخیره‌سازی زیر تقسیم می‌شود:

محلی

داده‌ها به‌صورت محلی ذخیره می‌شوند و با برداشته شدن افزونه پاک می‌شوند. حد فضای ذخیره‌سازی ۱۰ مگابایت است (۵ مگابایت در Chrome نسخه ۱۱۳ و قدیمی‌تر)، اما با درخواست اجازه "unlimitedStorage" می‌توان آن را افزایش داد. توصیه می‌کنیم برای ذخیره کردن مقادیر بیشتر داده از storage.local استفاده کنید. به‌طور پیش‌فرض، درمعرض اسکریپت‌های محتوا قرار می‌گیرد، اما این رفتار را می‌توان با فراخوانی browser.storage.local.setAccessLevel() تغییر داد.

مدیریت‌شده

فضای ذخیره‌سازی مدیریت‌شده برای افزونه‌های نصب‌شده با خط‌مشی فقط خواندنی است. این تنظیمات توسط سرپرستان سیستم و بااستفاده از طرح‌واره تعریف‌شده توسط توسعه‌دهنده و خط‌مشی‌های سازمانی مدیریت می‌شود. خط‌مشی‌ها شبیه گزینه‌ها هستند اما به‌جای کاربر، توسط سرپرست سیستم پیکربندی می‌شوند. این کار امکان پیکربندی پیشاپیش افزونه را برای همه کاربران سازمان فراهم می‌کند.

به‌طور پیش‌فرض، storage.managed درمعرض اسکریپت‌های محتوا قرار می‌گیرد، اما این رفتار را می‌توان با فراخوانی browser.storage.managed.setAccessLevel() تغییر داد. برای اطلاعات درباره خط‌مشی‌ها، به اسناد برای سرپرستان مراجعه کنید. برای کسب اطلاعات بیشتر درباره فضای ذخیره‌سازی managed، به مانیفست برای فضاهای ذخیره‌سازی مراجعه کنید.

جلسه

فضای ذخیره‌سازی جلسه داده‌ها را در حافظه نگه می‌دارد تا زمانی که افزونه بار شود. اگر افزونه غیرفعال، بازبارگیری، یا به‌روزرسانی شود و وقتی مرورگر بازراه‌اندازی شود، فضای ذخیره‌سازی پاک می‌شود. به‌طور پیش‌فرض، درمعرض اسکریپت‌های محتوا قرار نمی‌گیرد، اما این رفتار را می‌توان با فراخوانی browser.storage.session.setAccessLevel() تغییر داد. محدودیت فضای ذخیره‌سازی ۱۰ مگابایت است (۱ مگابایت در Chrome 111 و نسخه‌های قدیمی‌تر).

میانای storage.session یکی از چندین میانایی است که برای کارگران خدماتی توصیه می‌کنیم.

همگام‌سازی

اگر کاربر همگام‌سازی را فعال کند، داده‌ها با هر مرورگر Chrome که کاربر به سیستم آن وارد شده است همگام‌سازی می‌شود. اگر غیرفعال باشد، مانند storage.local عمل می‌کند. وقتی مرورگر آفلاین است، Chrome داده‌ها را به‌صورت محلی ذخیره می‌کند و وقتی دوباره آنلاین شد، همگام‌سازی را ازسر می‌گیرد. محدودیت سهمیه تقریباً ۱۰۰ کیلوبایت، ۸ کیلوبایت برای هر مورد است.

توصیه می‌کنیم از storage.sync استفاده کنید تا تنظیمات کاربر در مرورگرهای همگام‌سازی‌شده حفظ شود. اگر با داده‌های حساس کاربر کار می‌کنید، به‌جای آن از storage.session استفاده کنید. به‌طور پیش‌فرض، storage.sync درمعرض اسکریپت‌های محتوا قرار می‌گیرد، اما این رفتار را می‌توان با فراخوانی browser.storage.sync.setAccessLevel() تغییر داد.

روش‌ها و رویدادها

همه فضاهای ذخیره‌سازی میانای StorageArea را پیاده‌سازی می‌کنند.

get()‎

روش get() به شما امکان می‌دهد یک یا چند کلید را از StorageArea بخوانید.

getBytesInUse()

روش getBytesInUse() به شما امکان می‌دهد سهمیه استفاده‌شده توسط StorageArea را ببینید.

getKeys()

روش getKeys() به شما امکان می‌دهد همه کلیدهای ذخیره‌شده در StorageArea را دریافت کنید.

remove()‎

روش remove() به شما امکان می‌دهد موردی را از StorageArea بردارید.

set()

روش set() به شما امکان می‌دهد موردی را در StorageArea تنظیم کنید.

setAccessLevel()

روش setAccessLevel() به شما امکان می‌دهد دسترسی به StorageArea را کنترل کنید.

clear()

روش clear() به شما امکان می‌دهد همه داده‌ها را از StorageArea پاک کنید.

onChanged

رویداد onChanged به شما امکان می‌دهد تغییرات StorageArea را پایش کنید.

موارد استفاده

بخش‌های زیر موارد استفاده رایج Storage API را نشان می‌دهد.

پاسخ به به‌روزرسانی‌های فضای ذخیره‌سازی

برای ردیابی تغییرات ایجادشده در فضای ذخیره‌سازی، شنونده‌ای به رویداد onChanged آن اضافه کنید. وقتی چیزی در فضای ذخیره‌سازی تغییر می‌کند، آن رویداد فعال می‌شود. کد نمونه به این تغییرات گوش می‌دهد:

background.js:

browser.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;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.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
browser.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);
  }
});

پیش‌بارگیری ناهمگام از فضای ذخیره‌سازی

چون کارگران سرویس همیشه اجرا نمی‌شوند، افزونه‌های «مانیفست نسخه ۳» گاهی اوقات باید قبل‌از اجرای گرداننده‌های رویداد، داده‌ها را به‌صورت ناهمگام از فضای ذخیره‌سازی بار کنند. برای انجام این کار، قطعه کد زیر از یک کنترل‌کننده رویداد 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 = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.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;
  browser.storage.sync.set(storageCache);
});

DevTools

می‌توانید داده‌های ذخیره‌شده بااستفاده از API را در DevTools مشاهده و ویرایش کنید. برای کسب اطلاعات بیشتر، به صفحه مشاهده و ویرایش فضای ذخیره‌سازی افزونه در سند DevTools مراجعه کنید.

انواع

AccessLevel

Chrome نسخه ۱۰۲ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

سطح دسترسی محوطه انبار.

شمارشی

"TRUSTED_CONTEXTS"
زمینه‌هایی را که از خود افزونه منشأ می‌گیرند مشخص می‌کند.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
زمینه‌هایی را که از خارج افزونه منشأ می‌گیرند مشخص می‌کند.

StorageChange

مشخصات

• newValue

  هر اختیاری

  مقدار جدید مورد، اگر مقدار جدیدی وجود داشته باشد.

• oldValue

  هر اختیاری

  مقدار قدیمی مورد، اگر مقدار قدیمی وجود داشته باشد.

مشخصات

local

موارد موجود در فضای ذخیره‌سازی local برای هر دستگاه محلی هستند.

نوع

StorageArea و شیء

مشخصات

• QUOTA_BYTES

  ۱۰۴۸۵۷۶۰
  

  حداکثر مقدار داده (به بایت) که می‌تواند در فضای ذخیره‌سازی محلی ذخیره شود، که با رشته‌سازی JSON هر مقدار به‌علاوه طول هر کلید اندازه‌گیری می‌شود. اگر افزونه اجازه unlimitedStorage را داشته باشد، این مقدار نادیده گرفته خواهد شد. به‌روزرسانی‌هایی که باعث فراتر رفتن از این حد مجاز می‌شوند فوراً ناموفق می‌شوند و هنگام استفاده از فراخوانی برگشتی، runtime.lastError را تنظیم می‌کنند، یا اگر از async/await استفاده شود، Promise رد می‌شود.

managed

موارد موجود در فضای ذخیره‌سازی managed توسط خط‌مشی سازمانی پیکربندی‌شده توسط سرپرست دامنه تنظیم می‌شوند و برای افزونه فقط خواندنی هستند؛ تلاش برای اصلاح این فضای نام منجر به خطا می‌شود. برای کسب اطلاعات درباره پیکربندی خط‌مشی، به مانیفست برای فضاهای ذخیره‌سازی مراجعه کنید.

نوع

StorageArea

session

Chrome 102+ browser.* از Chrome 148 MV3+

موارد موجود در فضای ذخیره‌سازی session در حافظه ذخیره می‌شوند و در دیسک باقی نخواهند ماند.

نوع

StorageArea و شیء

مشخصات

• QUOTA_BYTES

  ۱۰۴۸۵۷۶۰
  

  حداکثر مقدار (به بایت) داده‌ای که می‌تواند در حافظه ذخیره شود، که با تخمین استفاده از حافظه تخصیص‌یافته پویا برای هر مقدار و کلید اندازه‌گیری می‌شود. به‌روزرسانی‌هایی که باعث فراتر رفتن از این حد می‌شوند بلافاصله ناموفق می‌شوند و هنگام استفاده از فراخوانی برگشتی یا وقتی Promise رد می‌شود، runtime.lastError را تنظیم می‌کنند.

sync

موارد موجود در فضای ذخیره‌سازی sync بااستفاده از «همگام‌سازی Chrome» همگام‌سازی می‌شوند.

نوع

StorageArea و شیء

مشخصات

• MAX_ITEMS

  ۵۱۲
  

  حداکثر تعداد مواردی که می‌توان در فضای ذخیره‌سازی همگام‌سازی ذخیره کرد. به‌روزرسانی‌هایی که باعث فراتر رفتن از این حد مجاز شوند بلافاصله ناموفق خواهند بود و هنگام استفاده از فراخوانی برگشتی یا رد شدن Promise، runtime.lastError را تنظیم می‌کنند.

• MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

  ۱۰۰۰۰۰۰
  

  منسوخ‌شده

  storage.sync API دیگر سهمیه عملیات نوشتن پایدار ندارد.

• MAX_WRITE_OPERATIONS_PER_HOUR

  ۱۸۰۰
  

  حداکثر تعداد عملیات set، remove، یا clear که می‌توان در هر ساعت انجام داد. این مقدار برابر با ۱ نوشتن در هر ۲ ثانیه است که سقفی پایین‌تر از حد مجاز بالاتر نوشتن در دقیقه در کوتاه‌مدت است.

  به‌روزرسانی‌هایی که باعث فراتر رفتن از این حد می‌شوند بلافاصله ناموفق می‌شوند و هنگام استفاده از فراخوانی برگشتی یا وقتی Promise رد می‌شود، runtime.lastError را تنظیم می‌کنند.

• MAX_WRITE_OPERATIONS_PER_MINUTE

  ۱۲۰
  

  حداکثر تعداد عملیات set، remove، یا clear که می‌توان در هر دقیقه انجام داد. این مقدار ۲ در ثانیه است که توان عملیاتی بالاتری نسبت‌به نوشتن در ساعت در مدت زمان کوتاه‌تر ارائه می‌دهد.

  به‌روزرسانی‌هایی که باعث فراتر رفتن از این حد می‌شوند بلافاصله ناموفق می‌شوند و هنگام استفاده از فراخوانی برگشتی یا وقتی Promise رد می‌شود، runtime.lastError را تنظیم می‌کنند.

• QUOTA_BYTES

  ۱۰۲۴۰۰
  

  حداکثر مقدار کل (به بایت) داده‌ای که می‌تواند در فضای ذخیره‌سازی همگام‌سازی ذخیره شود، که با رشته‌سازی JSON هر مقدار به‌علاوه طول هر کلید اندازه‌گیری می‌شود. به‌روزرسانی‌هایی که باعث فراتر رفتن از این حد می‌شوند بلافاصله ناموفق می‌شوند و هنگام استفاده از فراخوانی برگشتی یا وقتی Promise رد می‌شود، runtime.lastError را تنظیم می‌کنند.

• QUOTA_BYTES_PER_ITEM

  8192
  

  حداکثر اندازه (به بایت) هر مورد مجزا در فضای ذخیره‌سازی همگام‌سازی، که با رشته‌سازی JSON مقدار آن به‌علاوه طول کلید آن اندازه‌گیری می‌شود. به‌روزرسانی‌های حاوی موارد بزرگ‌تر از این حد فوراً ناموفق خواهند بود و هنگام استفاده از فراخوانی برگشتی یا وقتی Promise رد می‌شود، runtime.lastError را تنظیم می‌کنند.

رویدادها

onChanged

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

وقتی یک یا چند مورد تغییر کند، فعال می‌شود.

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

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

  • تغییرات

    شیء

  • areaName

    رشته