chrome.storage

תיאור

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

הרשאות

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. יוצרים מסמך מחוץ למסך עם שגרת המרה ומטפל [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 זמין במאמר קובץ המניפסט של אזורי אחסון.

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

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

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

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

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

דוגמאות לתוספים

כדי לראות הדגמות נוספות של Storage 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

sync

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

סוג

StorageArea ו-object

מאפיינים

  • 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 יוגדר כשמשתמשים בפונקציית קריאה חוזרת או כשמתבצעת דחייה של 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

      מחרוזת