chrome.storage

תיאור

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

הרשאות

storage

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

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

דוגמאות

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

דוגמה (מקומית)

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

דוגמה (סנכרון)

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

דוגמה (סשן)

await chrome.storage.session.set({ key: value });
console.log("Value is set");
const result = await chrome.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 של אחסון תוספים מ-service worker:

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

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

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

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

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

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

אזורי אחסון

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

מקומי

הנתונים מאוחסנים באופן מקומי ונמחקים כשמסירים את התוסף. מגבלת האחסון היא 10MB (5MB ב-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 Worker.

סנכרון

אם המשתמש מפעיל את הסנכרון, הנתונים מסתנכרנים עם כל דפדפן 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.

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

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

כלי פיתוח

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

סוגים

AccessLevel

‫Chrome 102 ואילך

רמת הגישה לאזור האחסון.

Enum

‫TRUSTED_CONTEXTS
מציין הקשרים שמקורם בתוסף עצמו.

‫"TRUSTED_AND_UNTRUSTED_CONTEXTS"
מציין הקשרים שמקורם מחוץ לתוסף.

StorageChange

מאפיינים

• newValue

  כל אופציונלי

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

• oldValue

  כל אופציונלי

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

מאפיינים

local

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

סוג

StorageArea ו-object

מאפיינים

• QUOTA_BYTES

  10485760
  

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

managed

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

סוג

StorageArea

session

‫Chrome 102 ואילך MV3 ואילך

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

סוג

StorageArea ו-object

מאפיינים

• QUOTA_BYTES

  10485760
  

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

sync

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

סוג

StorageArea ו-object

מאפיינים

• MAX_ITEMS

  ‫512
  

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

• MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

  ‫1000000
  

  הוצא משימוש

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

• MAX_WRITE_OPERATIONS_PER_HOUR

  ‫1800
  

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

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

• MAX_WRITE_OPERATIONS_PER_MINUTE

  ‫120
  

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

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

• QUOTA_BYTES

  102400
  

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

• QUOTA_BYTES_PER_ITEM

  ‫8192
  

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

אירועים

onChanged

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

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

פרמטרים

• callback

  פונקציה

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

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

  • שינויים

    אובייקט

  • areaName

    מחרוזת