chrome.storage

תיאור

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

הרשאות

storage

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

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

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

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

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

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

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

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

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

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

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

אזורי אחסון

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

storage.local
הנתונים מאוחסנים באופן מקומי ונמחקים לאחר הסרת התוסף. מגבלת האחסון היא 10MB (5MB ב-Chrome 113 ומטה), אבל אפשר להגדיל אותה על ידי בקשה להרשאת "unlimitedStorage". מומלץ להשתמש ב-storage.local כדי לאחסן כמויות גדולות יותר של נתונים.
storage.managed
אחסון מנוהל הוא אחסון לקריאה בלבד לתוספים שהותקנו על ידי מדיניות, ומנוהל על ידי אדמינים באמצעות סכימה וכללי מדיניות ארגונית שהוגדרו על ידי המפתח. כללי מדיניות מקבילים לאפשרויות, אבל מוגדרים על ידי מנהל מערכת במקום על ידי המשתמש, וכך אפשר להגדיר מראש את התוסף לכל המשתמשים בארגון. למידע על מדיניות, ראו מסמכים לאדמינים. מידע נוסף על אזור האחסון של managed זמין במניפסט לאזורי אחסון.
storage.session
שומרים נתונים בזיכרון למשך הזמן של סשן בדפדפן. כברירת מחדל, הוא לא חשוף לסקריפטים של תוכן, אבל אפשר לשנות את ההתנהגות הזו על ידי הגדרה של chrome.storage.session.setAccessLevel(). מגבלת האחסון היא 10MB (1 MB ב-Chrome בגרסה 111 ומטה). הממשק של storage.session הוא אחד מתוך כמה הממשקים המומלצים ל-service worker.
storage.sync
אם הסנכרון מופעל, הנתונים מסונכרנים לכל דפדפן Chrome שהמשתמש מחובר אליו. אם ההגדרה מושבתת, הוא יפעל כמו storage.local. Chrome מאחסן את הנתונים באופן מקומי כשהדפדפן לא מחובר לאינטרנט, וממשיך לסנכרן אותו כשיהיה שוב חיבור לאינטרנט. מגבלת המכסה היא בערך 100KB, 8KB לכל פריט. כדי לשמור את הגדרות המשתמש בדפדפנים מסונכרנים, מומלץ להשתמש ב-storage.sync. אם עובדים עם נתונים רגישים של משתמשים, צריך להשתמש במקום זאת ב-storage.session.

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

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

  • אחסון נתונים כרוך בדרך כלל בעלויות ביצועים, וה-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);
});

דוגמאות

הדוגמאות הבאות מדגימות את 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 was set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

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

      מחרוזת