chrome.storage

refresh date: 2026-09-25 robots: noindex

תיאור

אפשר להשתמש ב-API של chrome.storage כדי לאחסן, לאחזר ולעקוב אחרי שינויים בנתוני המשתמשים.

הרשאות

storage

סקירה כללית

‫Storage API מספק דרך ספציפית לתוסף לשמור את נתוני המשתמשים ואת המצב שלהם. הוא דומה לממשקי ה-API לאחסון של פלטפורמת האינטרנט (IndexedDB ו-Storage), אבל הוא תוכנן כדי לענות על צורכי האחסון של תוספים. הנה כמה מהתכונות העיקריות:

  • לכל ההקשרים של התוסף, כולל ה-service worker של התוסף והסקריפטים של התוכן, יש גישה ל-Storage API.
  • הערכים שניתנים להמרה ל-JSON נשמרים כמאפייני אובייקט.
  • ‫Storage API הוא אסינכרוני עם פעולות קריאה וכתיבה בכמות גדולה.
  • גם אם המשתמש מנקה את המטמון ואת היסטוריית הגלישה, הנתונים נשמרים.
  • ההגדרות שנשמרו נשארות גם כשמשתמשים במצב פרטי מפוצל.
  • כולל אזור אחסון מנוהל לקריאה בלבד, שמיועד למדיניות ארגונית.

למרות שתוספים יכולים להשתמש בממשק [Storage][mdn-storage] (נגיש מ-window.localStorage) בהקשרים מסוימים (חלונות קופצים ודפי HTML אחרים), לא מומלץ להשתמש בו מהסיבות הבאות:

  • ל-Service Worker של התוסף אין גישה אל Storage.
  • סקריפטים של תוכן חולקים את נפח האחסון עם הדף המארח.
  • נתונים שנשמרו באמצעות הממשק Storage יאבדו כשהמשתמש ימחק את היסטוריית הגלישה שלו.

כדי להעביר נתונים מממשקי API של אחסון באינטרנט לממשקי API של אחסון בתוספים מ-Service Worker:

  1. יוצרים מסמך מחוץ למסך עם שגרת המרה ו-handler של [onMessage][on-message].
  2. מוסיפים שגרת המרה למסמך מחוץ למסך.
  3. ב-Service Worker של התוסף, מחפשים את הנתונים ב-chrome.storage.
  4. אם הנתונים לא נמצאים, [יוצרים][create-offscreen] מסמך מחוץ למסך וקוראים ל-[sendMessage()][send-message] כדי להתחיל את שגרת ההמרה.
  5. בתוך ה-handler של onMessage במסמך מחוץ למסך, מפעילים את שגרת ההמרה.

יש גם כמה הבדלים באופן שבו ממשקי API לאחסון באינטרנט פועלים בתוספים. מידע נוסף זמין במאמר [אחסון וקובצי Cookie][storage-and-cookies].

אזורי אחסון

‫Storage API מחולק לארבע הקטגוריות הבאות ("אזורי אחסון"):

storage.local
הנתונים נשמרים באופן מקומי, והם נמחקים כשהתוסף מוסר. מגבלת המכסה היא בערך 10MB, אבל אפשר להגדיל אותה אם מבקשים את ההרשאה "unlimitedStorage". כדאי להשתמש בו כדי לאחסן כמויות גדולות יותר של נתונים.
storage.sync
אם הסנכרון מופעל, הנתונים מסונכרנים עם כל דפדפן Chrome שהמשתמש מחובר אליו. אם המדיניות מושבתת, ההתנהגות תהיה כמו במדיניות storage.local. ‫Chrome מאחסן את הנתונים באופן מקומי כשהדפדפן במצב אופליין, וממשיך את הסנכרון כשהוא חוזר למצב אונליין. מגבלת המכסה היא בערך 100KB, ‏ 8KB לכל פריט. כדאי להשתמש בה כדי לשמור את הגדרות המשתמש בדפדפנים מסונכרנים.
storage.session
שומר נתונים בזיכרון למשך הסשן בדפדפן. כברירת מחדל, הוא לא חשוף לסקריפטים של תוכן, אבל אפשר לשנות את ההתנהגות הזו על ידי הגדרת chrome.storage.session.setAccessLevel(). מגבלת המכסה היא בערך 10MB. כדאי להשתמש בו כדי לאחסן משתנים גלובליים בהפעלות של Service Worker.
storage.managed
אדמינים יכולים להשתמש בסכימה ובמדיניות הארגונית כדי לקבוע את ההגדרות של תוסף תומך בסביבה מנוהלת. אזור האחסון הזה הוא לקריאה בלבד.

מניפסט

כדי להשתמש ב-storage API, צריך להצהיר על ההרשאה "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.

תגובה סינכרונית לעדכוני אחסון

כדי לעקוב אחרי שינויים שבוצעו באחסון, אפשר להוסיף פונקציית listener לאירוע 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, ו-Service Worker משתמש ב-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);
  }
});

טעינה מראש אסינכרונית מהאחסון

מכיוון ש-Service Workers לא תמיד פועלים, תוספי Manifest V3 צריכים לפעמים לטעון נתונים מהאחסון באופן אסינכרוני לפני שהם מפעילים את הגורמים המטפלים באירועים. כדי לעשות את זה, קטע הקוד הבא משתמש בגורם מטפל אסינכרוני באירועים של 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"
מציין הקשרים שמקורם מחוץ לתוסף.

StorageChange

מאפיינים

  • newValue

    any optional

    הערך החדש של הפריט, אם יש ערך חדש.

  • oldValue

    any optional

    הערך הישן של הפריט, אם היה ערך ישן.

מאפיינים

local

הפריטים באזור האחסון local הם מקומיים לכל מכונה.

סוג

StorageArea ואובייקט

מאפיינים

  • QUOTA_BYTES

    10485760

    כמות הנתונים המקסימלית (בבייטים) שאפשר לאחסן באחסון המקומי, כפי שנמדדת על ידי מחרוזת JSON של כל ערך בתוספת האורך של כל מפתח. המערכת תתעלם מהערך הזה אם לתוסף יש את ההרשאה unlimitedStorage. עדכונים שגורמים לחריגה מהמגבלה הזו נכשלים מיד ומגדירים את runtime.lastError כשמשתמשים בקריאה חוזרת (callback), או Promise שנדחה אם משתמשים ב-async/await.

managed

הפריטים באזור האחסון managed מוגדרים על ידי מדיניות ארגונית שנקבעה על ידי מנהל הדומיין, והם לקריאה בלבד עבור התוסף. ניסיון לשנות את מרחב השמות הזה יגרום לשגיאה. מידע על הגדרת מדיניות זמין במאמר מניפסט לאזורי אחסון.

סוג

StorageArea

sync

פריטים באזור האחסון sync מסונכרנים באמצעות סנכרון Chrome.

סוג

StorageArea ואובייקט

מאפיינים

  • MAX_ITEMS

    512

    המספר המקסימלי של פריטים שאפשר לאחסן באחסון מסונכרן. עדכונים שיגרמו לחריגה מהמגבלה הזו ייכשלו באופן מיידי ויגדירו את runtime.lastError כשמשתמשים בקריאה חוזרת (callback), או כשההבטחה (Promise) נדחית.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    הוצא משימוש

    ל-API‏ storage.sync אין יותר מכסה לפעולות כתיבה מתמשכות.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    המספר המקסימלי של פעולות set, remove או clear שאפשר לבצע בכל שעה. כלומר, פעולה אחת כל 2 שניות, תקרה נמוכה יותר מהמגבלה לטווח הקצר של יותר פעולות כתיבה לדקה.

    עדכונים שגורמים לחריגה מהמגבלה הזו נכשלים באופן מיידי ומגדירים את runtime.lastError כשמשתמשים בקריאה חוזרת (callback), או כש-Promise נדחה.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    מספר הפעולות המקסימלי של set,‏ remove או clear שאפשר לבצע בכל דקה. זה אומר 2 פעולות בשנייה, מה שמאפשר תפוקה גבוהה יותר מאשר פעולות כתיבה לשעה בפרק זמן קצר יותר.

    עדכונים שגורמים לחריגה מהמגבלה הזו נכשלים באופן מיידי ומגדירים את runtime.lastError כשמשתמשים בקריאה חוזרת (callback), או כש-Promise נדחה.

  • QUOTA_BYTES

    102,400

    הכמות הכוללת המקסימלית (בבייטים) של נתונים שאפשר לאחסן באחסון הסנכרון, כפי שנמדדת על ידי מחרוזת JSON של כל ערך בתוספת האורך של כל מפתח. עדכונים שגורמים לחריגה מהמגבלה הזו נכשלים באופן מיידי ומגדירים את runtime.lastError כשמשתמשים בקריאה חוזרת (callback), או כש-Promise נדחה.

  • QUOTA_BYTES_PER_ITEM

    8192

    הגודל המקסימלי (בבייטים) של כל פריט בנפרד באחסון הסנכרון, כפי שנמדד על ידי מחרוזת ה-JSON של הערך שלו בתוספת אורך המפתח שלו. עדכונים שמכילים פריטים שגדולים מהמגבלה הזו ייכשלו מיד ויוגדר runtime.lastError כשמשתמשים בקריאה חוזרת (callback), או כש-Promise נדחה.

אירועים

onChanged

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

מופעל כשפריט אחד או יותר משתנה.

פרמטרים

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

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

    • שינויים

      אובייקט

    • areaName

      מחרוזת