chrome.storage

תיאור

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

הרשאות

storage

סקירה כללית

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

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

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

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

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

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

מניפסט

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

מגבלות אחסון וויסות נתונים (throttle)

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

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
ההגדרה קובעת הקשרים שמקורם מחוץ לתוסף.

StorageArea

מאפיינים

  • onChanged

    אירוע<functioncancelcancel>

    Chrome 73 ואילך

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

    הפונקציה onChanged.addListener נראית כך: 

    (callback: function) => {...}

    • קריאה חוזרת (callback)

      פונקציה

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

      (changes: object) => void

      • שינויים

        אובייקט

  • נקה

    ריק

    הבטחה

    מתבצעת הסרה של כל הפריטים מהאחסון.

    הפונקציה clear נראית כך: 

    (callback?: function) => {...}

    • קריאה חוזרת (callback)

      פונקציה אופציונלית

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

      () => void

    • החזרות

      הבטחה<Empty>

      Chrome מגרסה 88 ואילך

      הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

  • get

    ריק

    הבטחה

    מקבל פריט אחד או יותר מהאחסון.

    הפונקציה get נראית כך: 

    (keys?: string | string[] | object, callback?: function) => {...}

    • מפתחות

      string | string[] | אובייקט אופציונלי

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

    • קריאה חוזרת (callback)

      פונקציה אופציונלית

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

      (items: object) => void

      • פריטים

        אובייקט

        אובייקט עם פריטים במיפויים של מפתח/ערך.

    • החזרות

      Promise&lt;object&gt;

      Chrome מגרסה 88 ואילך

      הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

  • getBytesInUse

    ריק

    הבטחה

    הפונקציה מקבלת את נפח האחסון (בבייטים) שמשמש פריט אחד או יותר.

    הפונקציה getBytesInUse נראית כך: 

    (keys?: string | string[], callback?: function) => {...}

    • מפתחות

      string | string[] אופציונלי

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

    • קריאה חוזרת (callback)

      פונקציה אופציונלית

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

      (bytesInUse: number) => void

      • bytesInUse

        number

        כמות השטח שבשימוש באחסון, בבייטים.

    • החזרות

      Promise&lt;number&gt;

      Chrome מגרסה 88 ואילך

      הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

  • getKeys

    ריק

    הבטחה בהמתנה

    מקבל את כל המפתחות מהאחסון.

    הפונקציה getKeys נראית כך: 

    (callback?: function) => {...}

    • קריאה חוזרת (callback)

      פונקציה אופציונלית

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

      (keys: string[]) => void

      • מפתחות

        String[]

        מערך עם מפתחות שנקראו מהאחסון.

    • החזרות

      Promise&lt;string[]&gt;

      הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

  • remove

    ריק

    הבטחה

    מתבצעת הסרה של פריט אחד או יותר מהאחסון.

    הפונקציה remove נראית כך: 

    (keys: string | string[], callback?: function) => {...}

    • מפתחות

      string | String[]

      מפתח יחיד או רשימת מפתחות של פריטים להסרה.

    • קריאה חוזרת (callback)

      פונקציה אופציונלית

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

      () => void

    • החזרות

      הבטחה<Empty>

      Chrome מגרסה 88 ואילך

      הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

  • הוגדר

    ריק

    הבטחה

    להגדרת פריטים מרובים.

    הפונקציה set נראית כך: 

    (items: object, callback?: function) => {...}

    • פריטים

      אובייקט

      אובייקט שמספק לכל צמד מפתח/ערך שרוצים לעדכן באמצעותו את האחסון. צמדי מפתח/ערך אחרים באחסון לא יושפעו.

      ערכים פרימיטיביים, כמו מספרים, יופיעו בהמשכים כמצופה. ערכים עם typeof "object" ו-"function" יופיעו בדרך כלל בסדר טורי ל-{}, פרט ל-Array (מעבדים כמצופה), Date ו-Regex (יוצרים סריאליזציה באמצעות ייצוג String שלהם).

    • קריאה חוזרת (callback)

      פונקציה אופציונלית

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

      () => void

    • החזרות

      הבטחה<Empty>

      Chrome מגרסה 88 ואילך

      הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

  • setAccessLevel

    ריק

    הבטחה Chrome 102 ואילך

    הגדרת רמת הגישה הרצויה לאזור האחסון. ברירת המחדל תהיה רק הקשרים מהימנים.

    הפונקציה setAccessLevel נראית כך: 

    (accessOptions: object, callback?: function) => {...}

    • accessOptions

      אובייקט

      • accessLevel

        AccessLevel

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

    • קריאה חוזרת (callback)

      פונקציה אופציונלית

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

      () => void

    • החזרות

      הבטחה<Empty>

      הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

StorageChange

מאפיינים

  • newValue

    כל אופציונלי

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

  • oldValue

    כל אופציונלי

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

מאפיינים

local

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

סוג

StorageArea ו אובייקט

מאפיינים

  • QUOTA_BYTES

    10485760

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

managed

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

סוג

StorageArea

session

Chrome 102+ MV3+

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

סוג

StorageArea ו אובייקט

מאפיינים

  • QUOTA_BYTES

    10485760

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

sync

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

סוג

StorageArea ו אובייקט

מאפיינים

  • MAX_ITEMS

    512

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

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    הוצא משימוש

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

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

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

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

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

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

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

  • QUOTA_BYTES

    102400

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

  • QUOTA_BYTES_PER_ITEM

    8192

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

אירועים

onChanged

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

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

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

    • שינויים

      אובייקט

    • areaName

      מחרוזת