chrome.storage

refresh date: 2026-09-25 robots: noindex

شرح

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

اجازه‌ها

storage

نمای کلی

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

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

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

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

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

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

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

محل‌های نگهداری

‫Storage API به چهار دسته زیر («فضاهای ذخیره‌سازی») تقسیم می‌شود:

storage.local
داده‌ها به‌صورت محلی ذخیره می‌شوند و با برداشتن افزونه پاک می‌شوند. محدودیت سهمیه تقریباً ۱۰ مگابایت است، اما با درخواست اجازه "unlimitedStorage" می‌توان آن را افزایش داد. برای ذخیره کردن حجم بیشتری از داده‌ها، از آن استفاده کنید.
storage.sync
اگر همگام‌سازی فعال باشد، داده‌ها با هر مرورگر Chrome که کاربر به سیستم آن وارد شده است همگام‌سازی می‌شود. اگر غیرفعال باشد، مانند storage.local عمل می‌کند. وقتی مرورگر آفلاین است، Chrome داده‌ها را به‌صورت محلی ذخیره می‌کند و وقتی دوباره آنلاین شد، همگام‌سازی را ازسر می‌گیرد. محدودیت سهمیه تقریباً ۱۰۰ کیلوبایت، ۸ کیلوبایت برای هر مورد است. برای حفظ تنظیمات کاربر در مرورگرهای همگام‌سازی‌شده، از آن استفاده کنید.
storage.session
داده‌ها را درطول جلسه مرورگر در حافظه نگه می‌دارد. به‌طور پیش‌فرض، درمعرض اسکریپت‌های محتوا قرار نمی‌گیرد، اما این رفتار را می‌توان با تنظیم chrome.storage.session.setAccessLevel() تغییر داد. محدودیت سهمیه تقریباً ۱۰ مگابایت است. از آن برای ذخیره متغیرهای سراسری در سراسر اجراهای سرویس‌کار استفاده کنید.
storage.managed
سرپرستان می‌توانند از طرح‌واره و خط‌مشی‌های سازمانی برای پیکربندی تنظیمات افزونه پشتیبانی در محیط مدیریت‌شده استفاده کنند. این فضای ذخیره‌سازی فقط خواندنی است.

مانیفست

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

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

کاربرد

نمونه‌های زیر فضاهای ذخیره‌سازی local، sync، و session را نشان می‌دهند:

storage.local

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);
});

storage.session

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

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

افزودن به 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);
  }
});

پیش‌بارگیری ناهمگام از فضای ذخیره‌سازی

ازآنجایی‌که کارگران سرویس همیشه درحال اجرا نیستند، افزونه‌های «مانیفست نسخه ۳» گاهی اوقات باید داده‌ها را به‌صورت ناهمگام از فضای ذخیره‌سازی بار کنند تا بتوانند گرداننده‌های رویداد خود را اجرا کنند. برای انجام این کار، قطعه کد زیر از یک کنترل‌کننده رویداد 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 نسخه ۱۰۲ و بالاتر

سطح دسترسی محوطه انبار.

شمارشی

"TRUSTED_CONTEXTS"
زمینه‌هایی را که از خود افزونه منشأ می‌گیرند مشخص می‌کند.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
زمینه‌هایی را که از خارج افزونه منشأ می‌گیرند مشخص می‌کند.

StorageChange

مشخصات

  • newValue

    هر اختیاری

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

  • oldValue

    هر اختیاری

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

مشخصات

local

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

نوع

StorageArea و شیء

مشخصات

  • QUOTA_BYTES

    ۱۰۴۸۵۷۶۰

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

managed

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

نوع

StorageArea

sync

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

نوع

StorageArea و شیء

مشخصات

  • MAX_ITEMS

    ۵۱۲

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

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    ۱۰۰۰۰۰۰

    منسوخ‌شده

    storage.sync API دیگر سهمیه عملیات نوشتن پایدار ندارد.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    ۱۸۰۰

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

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

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    ۱۲۰

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

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

  • QUOTA_BYTES

    ۱۰۲۴۰۰

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

  • QUOTA_BYTES_PER_ITEM

    8192

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

رویدادها

onChanged

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

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • تغییرات

      شیء

    • areaName

      رشته