chrome.storage

توضیحات

مجوزها

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

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

مثال‌ها

نمونه‌های زیر، فضاهای ذخیره‌سازی 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 is set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

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

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

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

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

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

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

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

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

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

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

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

محدودیت‌های ذخیره‌سازی و کنترل سرعت

API ذخیره‌سازی محدودیت‌هایی در استفاده دارد:

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

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

انبارها

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

محلی

داده‌ها به صورت محلی ذخیره می‌شوند و با حذف افزونه پاک می‌شوند. محدودیت ذخیره‌سازی 10 مگابایت (5 مگابایت در کروم 113 و قبل از آن) است، اما می‌توان با درخواست مجوز "unlimitedStorage" را افزایش داد. توصیه می‌کنیم برای ذخیره حجم بیشتری از داده‌ها storage.local استفاده کنید. به طور پیش‌فرض، این فایل در معرض اسکریپت‌های محتوا قرار دارد، اما این رفتار را می‌توان با فراخوانی chrome.storage.local.setAccessLevel() تغییر داد.

مدیریت شده

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

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

جلسه

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

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

همگام‌سازی

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

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

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

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

دریافت()

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

تابع getBytesInUse()

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

دریافت کلیدها()

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

حذف()

متد remove() به شما امکان می‌دهد یک آیتم را از StorageArea حذف کنید.

مجموعه()

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

تنظیم سطح دسترسی ()

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

پاک کردن()

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

روی تغییر یافته

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

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

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

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

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

پس‌زمینه.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 برای اعمال تنظیمات در اسرع وقت استفاده می‌کند.

گزینه‌ها.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);

پس‌زمینه.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 می‌ماند.

پس‌زمینه.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);
});

ابزارهای توسعه

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

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