chrome.storage

توضیحات

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

مجوزها

storage

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

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

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

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

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

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

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

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

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

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

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

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

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

storage.local
داده ها به صورت محلی ذخیره می شوند و با حذف برنامه افزودنی پاک می شوند. محدودیت فضای ذخیره سازی 10 مگابایت است (5 مگابایت در کروم 113 و نسخه های قبلی)، اما می توان با درخواست مجوز "unlimitedStorage" آن را افزایش داد. توصیه می کنیم از storage.local برای ذخیره حجم بیشتری از داده استفاده کنید.
storage.managed
فضای ذخیره‌سازی مدیریت‌شده، فضای ذخیره‌سازی فقط خواندنی برای برنامه‌های افزودنی نصب‌شده خط‌مشی است و توسط مدیران سیستم با استفاده از طرح و خط‌مشی‌های سازمانی تعریف‌شده توسط توسعه‌دهنده مدیریت می‌شود. خط‌مشی‌ها مشابه گزینه‌ها هستند، اما توسط مدیر سیستم به جای کاربر پیکربندی می‌شوند و اجازه می‌دهند افزونه برای همه کاربران یک سازمان از پیش پیکربندی شود. برای اطلاعات در مورد خط‌مشی‌ها، به مستندات برای مدیران مراجعه کنید. برای کسب اطلاعات بیشتر در مورد فضای ذخیره سازی managed ، به Manifest برای مناطق ذخیره سازی مراجعه کنید.
storage.session
داده ها را برای مدت یک جلسه مرورگر در حافظه نگه می دارد. به‌طور پیش‌فرض، در معرض اسکریپت‌های محتوا قرار نمی‌گیرد، اما این رفتار را می‌توان با تنظیم chrome.storage.session.setAccessLevel() تغییر داد. محدودیت فضای ذخیره سازی 10 مگابایت است (1 مگابایت در کروم 111 و نسخه های قبلی). رابط storage.session یکی از چندین موردی است که ما برای سرویسکاران توصیه می کنیم .
storage.sync
اگر همگام‌سازی فعال باشد، داده‌ها با هر مرورگر Chrome که کاربر به آن وارد شده است همگام‌سازی می‌شود. اگر غیرفعال باشد، مانند storage.local عمل می‌کند. وقتی مرورگر آفلاین است، Chrome داده‌ها را به صورت محلی ذخیره می‌کند و وقتی دوباره آنلاین شد همگام‌سازی را از سر می‌گیرد. محدودیت سهمیه تقریباً 100 کیلوبایت، 8 کیلوبایت برای هر مورد است. توصیه می‌کنیم از storage.sync برای حفظ تنظیمات کاربر در مرورگرهای همگام‌سازی شده استفاده کنید. اگر با داده های حساس کاربر کار می کنید، در عوض از storage.session استفاده کنید.

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

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

  • ذخیره سازی داده ها اغلب با هزینه های عملکرد همراه است و 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);
});

نمونه ها

نمونه‌های زیر مناطق ذخیره‌سازی 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 was set");
});

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

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

  • دریافت کنید

    باطل

    قول بده

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

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

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

    • کلیدها

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

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

    • پاسخ به تماس

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

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

      (items: object) => void

      • موارد

        شی

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

    • برمی گرداند

      قول<object>

      Chrome 88+

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

  • getBytesInUse

    باطل

    قول بده

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

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

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

    • کلیدها

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

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

    • پاسخ به تماس

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

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

      (bytesInUse: number) => void

      • bytesInUse

        شماره

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

    • برمی گرداند

      قول <تعداد>

      Chrome 88+

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

  • getKeys

    باطل

    Promise Chrome 130+

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

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

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

    • پاسخ به تماس

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

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

      (keys: string[]) => void

      • کلیدها

        رشته[]

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

    • برمی گرداند

      قول<string[]>

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

  • حذف کنید

    باطل

    قول بده

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

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

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

    • کلیدها

      رشته | رشته[]

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

    • پاسخ به تماس

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

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

      () => void

    • برمی گرداند

      قول<باطل>

      Chrome 88+

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

  • مجموعه

    باطل

    قول بده

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

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

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

    • موارد

      شی

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

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

    • پاسخ به تماس

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

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

      () => void

    • برمی گرداند

      قول<باطل>

      Chrome 88+

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

  • setAccessLevel

    باطل

    Promise Chrome 102+

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

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

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

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

      شی

      • سطح دسترسی

        AccessLevel

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

    • پاسخ به تماس

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

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

      () => void

    • برمی گرداند

      قول<باطل>

      Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به 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

    • تغییر می کند

      شی

    • ناحیه نام

      رشته