chrome.storage

תיאור

הרשאות

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

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

דוגמאות

בדוגמאות הבאות מוצגים אזורי האחסון 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 is set");
});

chrome.storage.session.get(["key"]).then((result) => {
  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 של אחסון תוספים מ-service worker:

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

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

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

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

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

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

אזורי אחסון

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

מקומי

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

מנוהל

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

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

סשן

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

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

סנכרון

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

מומלץ להשתמש ב-storage.sync כדי לשמור על הגדרות המשתמש בדפדפנים מסונכרנים. אם אתם עובדים עם נתוני משתמש רגישים, עדיף להשתמש ב-storage.session. כברירת מחדל, storage.sync נחשף לסקריפטים של תוכן, אבל אפשר לשנות את ההתנהגות הזו על ידי קריאה ל-chrome.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.

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

כדי לעקוב אחרי שינויים שבוצעו באחסון, מוסיפים מאזין לאירוע 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 Worker לא פועלים כל הזמן, לפעמים תוספים של Manifest V3 צריכים לטעון נתונים מהאחסון באופן אסינכרוני לפני שהם מריצים את המטפלים באירועים שלהם. לשם כך, בקטע הקוד הבא נעשה שימוש ב-handler אסינכרוני של אירוע 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);
});

כלי פיתוח

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

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