chrome.storage

توضیحات

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

مجوزها

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، یکی از نمونه‌های زیر را بررسی کنید:

انواع

AccessLevel

Chrome 102+

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

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

  • دریافت کنید

    باطل

    قول بده

    یک یا چند مورد را از ذخیره سازی دریافت می کند.

    تابع get به نظر می رسد: 

    (keys?: string | string[] | object, callback?: function) => {...}

    • کلیدها

      رشته | رشته[] | شی اختیاری

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

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      (items: object) => void

      • موارد

        شی

        شیء با موارد در نگاشتهای کلید-مقدار آنها.

    • برمی گرداند

      قول<object>

      Chrome 88+

      Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

  • getBytesInUse

    باطل

    قول بده

    مقدار فضای استفاده شده توسط یک یا چند مورد را (بر حسب بایت) دریافت می کند.

    تابع getBytesInUse به شکل زیر است: 

    (keys?: string | string[], callback?: function) => {...}

    • کلیدها

      رشته | رشته[] اختیاری است

      یک کلید یا فهرستی از کلیدها برای دریافت کل مصرف. یک لیست خالی 0 را برمی‌گرداند. برای دریافت کل استفاده از کل فضای ذخیره‌سازی، آن را null کنید.

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      (bytesInUse: number) => void

      • bytesInUse

        شماره

        مقدار فضای مورد استفاده در ذخیره سازی، بر حسب بایت.

    • برمی گرداند

      قول <تعداد>

      Chrome 88+

      Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

  • getKeys

    باطل

    وعده در انتظار

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

    تابع getKeys به نظر می رسد: 

    (callback?: function) => {...}

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      (keys: string[]) => void

      • کلیدها

        رشته[]

        آرایه ای با کلیدهای خوانده شده از ذخیره سازی.

    • برمی گرداند

      قول<string[]>

      Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

  • حذف کنید

    باطل

    قول بده

    یک یا چند مورد را از فضای ذخیره سازی حذف می کند.

    تابع remove به نظر می رسد: 

    (keys: string | string[], callback?: function) => {...}

    • کلیدها

      رشته | رشته[]

      یک کلید یا فهرستی از کلیدها برای حذف موارد.

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      () => void

    • برمی گرداند

      قول<باطل>

      Chrome 88+

      Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

  • مجموعه

    باطل

    قول بده

    چندین آیتم را تنظیم می کند.

    تابع set به نظر می رسد: 

    (items: object, callback?: function) => {...}

    • موارد

      شی

      شیئی که به هر جفت کلید/مقدار می دهد تا فضای ذخیره سازی را با آن به روز کند. سایر جفت‌های کلید/مقدار موجود در فضای ذخیره‌سازی تحت تأثیر قرار نمی‌گیرند.

      مقادیر اولیه مانند اعداد همانطور که انتظار می رود سریال می شوند. مقادیر با یک typeof "object" و "function" معمولاً به صورت سریال به {} تبدیل می‌شوند، به استثنای Array (مرتب‌سازی‌شده طبق انتظار)، Date و Regex (سریال‌سازی با استفاده از نمایش String آنها).

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      () => void

    • برمی گرداند

      قول<باطل>

      Chrome 88+

      Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

  • setAccessLevel

    باطل

    Promise Chrome 102+

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

    تابع setAccessLevel به شکل زیر است: 

    (accessOptions: object, callback?: function) => {...}

    • گزینه های دسترسی

      شی

      • سطح دسترسی

        AccessLevel

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

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      () => void

    • برمی گرداند

      قول<باطل>

      Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

StorageChange

خواص

  • newValue

    هر اختیاری

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

  • oldValue

    هر اختیاری

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

خواص

local

اقلام در منطقه ذخیره سازی local برای هر دستگاه محلی هستند.

تایپ کنید

Storage Area & Object

خواص

  • QUOTA_BYTES

    10485760

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

managed

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

تایپ کنید

Storage Area

session

Chrome 102+ MV3+

موارد موجود در قسمت ذخیره سازی 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

    • تغییر می کند

      شی

    • ناحیه نام

      رشته