chrome.storage

شرح

مجوزها

بررسی اجمالی

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

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

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

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

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

1. یک سند خارج از صفحه با یک روال تبدیل و یک کنترل کننده [ onMessage ][on-Message] ایجاد کنید.
2. یک روال تبدیل را به یک سند خارج از صفحه اضافه کنید.
3. در کارگر خدمات افزودنی chrome.storage برای داده‌های خود بررسی کنید.
4. اگر داده‌های شما پیدا نشد، یک سند خارج از صفحه [ایجاد][ایجاد-خارج از صفحه] و برای شروع روال تبدیل، [ sendMessage() ][send-message] را فراخوانی کنید.
5. در کنترل کننده onMessage سند خارج از صفحه، روال تبدیل را فراخوانی کنید.

همچنین برخی تفاوت های ظریف در مورد نحوه عملکرد API های ذخیره سازی وب در برنامه های افزودنی وجود دارد. در مقاله [Storage and Cookies][storage-and-Cookies] بیشتر بیاموزید.

مناطق ذخیره سازی

Storage API به چهار سطل زیر ("مناطق ذخیره") تقسیم می شود:

storage.local

داده ها به صورت محلی ذخیره می شوند که با حذف برنامه افزودنی پاک می شوند. محدودیت سهمیه تقریباً 10 مگابایت است، اما با درخواست مجوز "unlimitedStorage" قابل افزایش است. استفاده از آن را برای ذخیره حجم بیشتری از داده ها در نظر بگیرید.

storage.sync

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

ذخیره سازی. جلسه

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

ذخیره سازی.مدیریت شده

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

آشکار

برای استفاده از 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 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);
});

ذخیره سازی. جلسه

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 ، به Manifest برای مناطق ذخیره سازی مراجعه کنید.

محدودیت های ذخیره سازی و گاز

اضافه کردن به 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 گاهی اوقات قبل از اجرای کنترل‌کننده‌های رویداد خود، نیاز به بارگیری ناهمزمان داده‌ها از فضای ذخیره‌سازی دارند. برای انجام این کار، قطعه زیر از یک مدیریت رویداد 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);
});

نمونه های پسوند

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

• پسوند جستجوی جهانی
• پسوند دزدگیر آب .

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