browser.storage

תיאור

הרשאות

כדי להשתמש ב-Storage API, צריך להצהיר על ההרשאה "storage" במניפסט של התוסף. לדוגמה:

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

דוגמאות

בדוגמאות הבאות מוצגים אזורי האחסון local, sync ו-session:

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

כדי לראות הדגמות נוספות של Storage API, אפשר לעיין בדוגמאות הבאות:

• תוסף חיפוש גלובלי.
• תוסף של חיישן הצפה.

מושגים ושימוש

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

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

האם תוספים יכולים להשתמש בממשקי API של אחסון אינטרנט?

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

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

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

1. מכינים דף HTML של מסמך מחוץ למסך וקובץ סקריפט. קובץ הסקריפט צריך להכיל שגרת המרה ומטפל onMessage.
2. בודקים את browser.storage ב-Service Worker של התוסף כדי לראות את הנתונים.
3. אם הנתונים לא נמצאו, צריך להתקשר אל createDocument().
4. אחרי שה-Promise שמוחזר יסתיים, קוראים ל-sendMessage() כדי להתחיל את שגרת ההמרה.
5. בתוך ה-handler‏ onMessage של המסמך מחוץ למסך, קוראים לשגרה של ההמרה.

יש גם כמה ניואנסים לגבי אופן הפעולה של ממשקי API לאחסון נתונים בדפדפן בתוספים. מידע נוסף זמין במאמר בנושא אחסון וקובצי Cookie.

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

יש מגבלות שימוש ב-Storage API:

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

פרטים על מגבלות נפח האחסון ומה קורה כשחורגים מהן זמינים במידע על המכסות של sync,‏ local ו-session.

אזורי אחסון

ממשק Storage API מחולק לאזורי האחסון הבאים:

מקומי

הנתונים נשמרים באופן מקומי ונמחקים כשמסירים את התוסף. מגבלת האחסון היא 10MB (5MB בגרסה 113 של Chrome ובגרסאות קודמות), אבל אפשר להגדיל אותה על ידי בקשת ההרשאה "unlimitedStorage". מומלץ להשתמש ב-storage.local כדי לאחסן כמויות גדולות יותר של נתונים. כברירת מחדל, הוא חשוף לסקריפטים של תוכן, אבל אפשר לשנות את ההתנהגות הזו על ידי קריאה ל-browser.storage.local.setAccessLevel().

מנוהל

אחסון מנוהל הוא לקריאה בלבד עבור תוספים שהותקנו באמצעות מדיניות. היא מנוהלת על ידי אדמינים של המערכת, באמצעות סכימה שהוגדרה על ידי מפתחים ומדיניות ארגונית. כללי המדיניות דומים לאפשרויות, אבל אדמין המערכת מגדיר אותם במקום המשתמש. כך אפשר להגדיר מראש את התוסף לכל המשתמשים בארגון.

כברירת מחדל, storage.managed נחשף לסקריפטים של תוכן, אבל אפשר לשנות את ההתנהגות הזו על ידי קריאה ל-browser.storage.managed.setAccessLevel(). מידע על מדיניות זמין במסמכי התיעוד לאדמינים. מידע נוסף על אזור האחסון managed זמין במאמר Manifest לאזורי אחסון.

סשן

אחסון הסשן שומר נתונים בזיכרון בזמן שהתוסף נטען. האחסון נמחק אם התוסף מושבת, נטען מחדש, מתעדכן וכשהדפדפן מופעל מחדש. כברירת מחדל, הוא לא נחשף לסקריפטים של תוכן, אבל אפשר לשנות את ההתנהגות הזו על ידי קריאה ל-browser.storage.session.setAccessLevel(). מגבלת האחסון היא 10MB (1MB ב-Chrome 111 ובגרסאות קודמות).

ממשק storage.session הוא אחד מכמה ממשקים שמומלצים ל-Service Worker.

סנכרון

אם המשתמש מפעיל את הסנכרון, הנתונים מסתנכרנים עם כל דפדפן Chrome שהמשתמש מחובר אליו. אם ההגדרה מושבתת, ההתנהגות שלה זהה לזו של storage.local. ‫Chrome שומר את הנתונים באופן מקומי כשהדפדפן במצב אופליין, וממשיך לסנכרן כשהוא חוזר למצב אונליין. מגבלת הנפח היא כ-100KB, כלומר 8KB לכל פריט.

מומלץ להשתמש ב-storage.sync כדי לשמור על הגדרות המשתמש בדפדפנים מסונכרנים. אם אתם עובדים עם נתוני משתמש רגישים, השתמשו במקום זאת ב-storage.session. כברירת מחדל, storage.sync נחשף לסקריפטים של תוכן, אבל אפשר לשנות את ההתנהגות הזו על ידי קריאה ל-browser.storage.sync.setAccessLevel().

שיטות ואירועים

כל אזורי האחסון מטמיעים את הממשק StorageArea.

get()‎

השיטה get() מאפשרת לקרוא מפתח אחד או יותר מ-StorageArea.

getBytesInUse()

השיטה getBytesInUse() מאפשרת לראות את המכסה שנוצלה על ידי StorageArea.

getKeys()

ה-method‏ getKeys() מאפשר לקבל את כל המפתחות שמאוחסנים ב-StorageArea.

remove()‎

השיטה remove() מאפשרת להסיר פריט מ-StorageArea.

set()‎

השיטה set() מאפשרת להגדיר פריט ב-StorageArea.

setAccessLevel()

השיטה setAccessLevel() מאפשרת לכם לשלוט בגישה אל StorageArea.

clear()‎

השיטה clear() מאפשרת לכם לנקות את כל הנתונים מStorageArea.

onChanged

האירוע onChanged מאפשר לעקוב אחרי שינויים בStorageArea.

תרחישים לדוגמה

בקטעים הבאים מפורטים תרחישי שימוש נפוצים ב-Storage API.

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

כדי לעקוב אחרי שינויים שבוצעו באחסון, מוסיפים listener לאירוע onChanged שלו. כשמשהו משתנה באחסון, האירוע הזה מופעל. קוד לדוגמה שמחכה לשינויים האלה:

background.js:

browser.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;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.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
browser.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 worker לא פועל כל הזמן, תוספים של Manifest V3 צריכים לפעמים לטעון נתונים מהאחסון באופן אסינכרוני לפני שהם מפעילים את ה-event handlers שלהם. לשם כך, בקטע הקוד הבא נעשה שימוש בגורם מטפל אסינכרוני באירוע 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 = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.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;
  browser.storage.sync.set(storageCache);
});

כלי פיתוח

אתם יכולים להציג ולערוך נתונים שמאוחסנים באמצעות ה-API בכלי הפיתוח. מידע נוסף זמין בדף View and edit extension storage (הצגה ועריכה של אחסון נתונים של תוספים) במסמכי התיעוד של כלי הפיתוח.

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