chrome.storage

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

הרשאות

סקירה כללית

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

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

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

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

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

1. יוצרים מסמך מחוץ למסך באמצעות שגרת המרה ומטפל [onMessage][on-message].
2. מוסיפים שגרת המרה למסמך מחוץ למסך.
3. בודקים את הנתונים ב-chrome.storage של תוסף Service Worker.
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

אדמינים יכולים להשתמש בסכימה ובהגדרות מדיניות Chrome Enterprise כדי לקבוע את ההגדרות של תוסף תומך בסביבה מנוהלת. אזור האחסון הזה הוא לקריאה בלבד.

מניפסט

כדי להשתמש ב-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 זמין במאמר Manifest לאזורי אחסון.

מגבלות אחסון והגבלת קצב

אל תחשבו על הוספה ל-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 global יאוכלס לפני הרצת הלוגיקה שלו.

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, אפשר לעיין בדוגמאות הבאות:

• תוסף חיפוש גלובלי.
• Water alarm extension (תוסף של אזעקת מים).

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