chrome.storage

توضیحات

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

مجوزها

storage

نمای کلی

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

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

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

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

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

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

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

انبارها

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

storage.local
داده‌ها به صورت محلی ذخیره می‌شوند که با حذف افزونه پاک می‌شوند. محدودیت سهمیه تقریباً 10 مگابایت است، اما می‌توان با درخواست مجوز "unlimitedStorage" آن را افزایش داد. استفاده از آن را برای ذخیره مقادیر بیشتر داده در نظر بگیرید.
storage.sync
اگر همگام‌سازی فعال باشد، داده‌ها با هر مرورگر کرومی که کاربر در آن وارد شده باشد، همگام‌سازی می‌شوند. اگر غیرفعال باشد، مانند storage.local عمل می‌کند. کروم وقتی مرورگر آفلاین است، داده‌ها را به صورت محلی ذخیره می‌کند و وقتی دوباره آنلاین شد، همگام‌سازی را از سر می‌گیرد. محدودیت سهمیه تقریباً ۱۰۰ کیلوبایت است، ۸ کیلوبایت برای هر مورد. استفاده از آن را برای حفظ تنظیمات کاربر در مرورگرهای همگام‌سازی شده در نظر بگیرید.
جلسه ذخیره‌سازی
داده‌ها را در طول مدت زمان یک جلسه مرورگر در حافظه نگه می‌دارد. به طور پیش‌فرض، در معرض اسکریپت‌های محتوا قرار نمی‌گیرد، اما این رفتار را می‌توان با تنظیم 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);
});

همگام‌سازی ذخیره‌سازی 

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 برای نواحی ذخیره‌سازی مراجعه کنید.

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

اضافه کردن به API ذخیره‌سازی را مانند قرار دادن چیزها در یک کامیون بزرگ در نظر نگیرید. اضافه کردن به ذخیره‌سازی را مانند قرار دادن چیزی در یک لوله در نظر بگیرید. لوله ممکن است از قبل حاوی مواد باشد و حتی ممکن است پر شده باشد. همیشه بین زمانی که به ذخیره‌سازی اضافه می‌کنید و زمانی که واقعاً ثبت می‌شود، تأخیری را در نظر بگیرید.

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

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

بخش‌های زیر موارد استفاده رایج برای 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 ذخیره‌سازی، هر یک از مثال‌های زیر را بررسی کنید:

انواع

AccessLevel

کروم ۱۰۲+

سطح دسترسی به فضای ذخیره‌سازی.

شمارشی

«زمینه‌های مورد اعتماد»
زمینه‌هایی را مشخص می‌کند که از خود افزونه سرچشمه می‌گیرند.

«متن‌های_قابل_اعتماد_و_غیرقابل_اعتماد»
زمینه‌هایی را مشخص می‌کند که از خارج از افزونه سرچشمه می‌گیرند.

StorageChange

خواص

  • مقدار جدید

    هر اختیاری

    مقدار جدید کالا، در صورت وجود مقدار جدید.

  • مقدار قدیمی

    هر اختیاری

    ارزش قدیمی کالا، در صورتی که ارزش قدیمی وجود داشته باشد.

خواص

local

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

نوع

فضای ذخیره‌سازی و شیء

خواص

  • سهمیه بایت‌ها

    ۱۰۴۸۵۷۶۰

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

managed

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

نوع

فضای ذخیره‌سازی

sync

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

نوع

فضای ذخیره‌سازی و شیء

خواص

  • حداکثر اقلام

    ۵۱۲

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

  • حداکثر عملیات نوشتن پایدار در هر دقیقه

    ۱۰۰۰۰۰۰

    منسوخ شده

    رابط برنامه‌نویسی کاربردی storage.sync دیگر سهمیه عملیات نوشتن پایداری ندارد.

  • حداکثر عملیات نوشتن در هر ساعت

    ۱۸۰۰

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

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

  • حداکثر عملیات نوشتن در هر دقیقه

    ۱۲۰

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

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

  • سهمیه بایت‌ها

    ۱۰۲۴۰۰

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

  • سهمیه بایت به ازای هر آیتم

    ۸۱۹۲

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

رویدادها

onChanged

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

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

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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

    • تغییرات

      شیء

    • نام منطقه

      رشته