דף זה תורגם על ידי Cloud Translation API.

chrome.storage

תיאור

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

הרשאות

storage

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

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

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

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

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

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

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

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

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

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

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

אזורי אחסון

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

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

מגבלות על נפח האחסון והגבלת קצב העברת הנתונים

אלו מגבלות השימוש ב-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 &quot;${newValue}".`
    );
  }
});

אפשר להרחיב את הרעיון הזה. בדוגמה הזו יש דף אפשרויות שמאפשר למשתמש להפעיל או להשבית את 'מצב ניפוי באגים' (ההטמעה לא מוצגת כאן). דף האפשרויות שומר מיד את ההגדרות החדשות ב-storage.sync, וה-service worker משתמש ב-storage.onChanged כדי להחיל את ההגדרה בהקדם האפשרי.

options.html:

<!-- type="module" allows you to use top leve>l< await --
script defer src="options.js><" >t<ype="module">;/s<cript
form id=&qu>ot;op<tionsForm"
  label for="debug">
    input type="che<ckbox&>q<uot; >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 opti&ons  apply them
chrome.storage.onChanged.addListener((changes, are>a) = {
  if (area === &&9;sync'  changes.options?.newValue) {
    const debugMode = Boolean(changes.options.newValue.debug);
    console.log('enable debug mode?', debugMode);
    setDebugMode(debugMode);
  }
});

טעינה מראש אסינכרונית מהאחסון

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

כלי פיתוח

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

דוגמאות

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

מקומי

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key&quo>t;]).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&quo>t;]).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&quo>t;]).then((result) = {
  console.log("Value is " + result.key);
});

כדי לראות הדגמות נוספות של Storage API, אפשר לעיין באחת מהדוגמאות הבאות:

סוגים

AccessLevel

‫Chrome 102 ואילך

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

Enum

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

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

StorageArea

מאפיינים

onChanged

Event<functionvoidvoid>

‫Chrome 73 ואילך

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

הפונקציה onChanged.addListener נראית כך:
```
(callback: function) =& gt;{...}
```
- callback
  
  פונקציה
  
  הפרמטר callback נראה כך:
```
(changes: object) =& gt;void
```
  - שינויים
    
    אובייקט
נקה

void

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

הפונקציה clear נראית כך:
```
() =& gt;{...}
```
- החזרות
  Promise<void>
  
  ‫Chrome 95 ואילך
get

void

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

הפונקציה get נראית כך:
```
(keys?: string | string[] | object) =& gt;{...}
```
- מפתחות
  
  מחרוזת | מערך מחרוזות | אובייקט אופציונלי
  
  מפתח יחיד להשגה, רשימת מפתחות להשגה או מילון שמציין ערכי ברירת מחדל (ראו תיאור של האובייקט). רשימה או אובייקט ריקים יחזירו אובייקט תוצאה ריק. מעבירים את null כדי לקבל את כל התוכן של האחסון.
- החזרות
  Promise<object>
  
  ‫Chrome 95 ואילך
getBytesInUse

void

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

הפונקציה getBytesInUse נראית כך:
```
(keys?: string | string[]) =& gt;{...}
```
- מפתחות
  
  מחרוזת | מערך מחרוזות אופציונלי
  
  מפתח יחיד או רשימת מפתחות שרוצים לקבל את נתוני השימוש הכוללים שלהם. אם הרשימה ריקה, הפונקציה תחזיר 0. מעבירים את הערך null כדי לקבל את נפח האחסון הכולל בשימוש.
- החזרות
  Promise<number>
  
  ‫Chrome 95 ואילך
getKeys

void

‫Chrome 130 ואילך

אחזור כל המפתחות מהאחסון.

הפונקציה getKeys נראית כך:
```
() =& gt;{...}
```
- החזרות
  Promise<string[]>
remove

void

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

הפונקציה remove נראית כך:
```
(keys: string | string[]) =& gt;{...}
```
- מפתחות
  
  מחרוזת | מחרוזת[]
  
  מפתח יחיד או רשימת מפתחות של פריטים להסרה.
- החזרות
  Promise<void>
  
  ‫Chrome 95 ואילך
הוגדר

void

הגדרת כמה פריטים.

הפונקציה set נראית כך:
```
(items: object) =& gt;{...}
```
- פריטים
  
  אובייקט
  
  אובייקט שכולל כל צמד מפתח/ערך לעדכון האחסון. צמדי מפתח/ערך אחרים באחסון לא יושפעו.
  
  ערכים פרימיטיביים כמו מספרים יעברו סריאליזציה כמצופה. ערכים עם typeof "object" ו-"function" בדרך כלל יעברו סריאליזציה ל-{}, למעט Array (עובר סריאליזציה כצפוי), Date ו-Regex (עוברים סריאליזציה באמצעות הייצוג שלהם ב-String).
- החזרות
  Promise<void>
  
  ‫Chrome 95 ואילך
setAccessLevel

void

‫Chrome 102 ואילך

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

הפונקציה setAccessLevel נראית כך:
```
(accessOptions: object) =& gt;{...}
```
- accessOptions
  
  אובייקט
  - accessLevel
    
    AccessLevel
    
    רמת הגישה לאזור האחסון.
- החזרות
  Promise<void>

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) או כשמתבצעת דחייה של Promise.
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

‫1000000

הוצא משימוש

ל-storage.sync API אין יותר מכסת פעולות כתיבה מתמשכות.
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 כשמשתמשים בפונקציית קריאה חוזרת (callback) או כשדחיית הבטחה (Promise) מתרחשת.

אירועים

onChanged

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

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

פרמטרים

callback

פונקציה

הפרמטר callback נראה כך:
```
(changes: object, areaName: string) =& gt;void
```
- שינויים
  
  אובייקט
- areaName
  
  מחרוזת

chrome.storage קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

תיאור

הרשאות

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

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

אזורי אחסון

מגבלות על נפח האחסון והגבלת קצב העברת הנתונים

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

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

טעינה מראש אסינכרונית מהאחסון

כלי פיתוח

דוגמאות

מקומי

סנכרון

סשן

סוגים

AccessLevel

Enum

StorageArea

מאפיינים

StorageChange

מאפיינים

מאפיינים

local

סוג

מאפיינים

managed

סוג

session

סוג

מאפיינים

sync

סוג

מאפיינים

אירועים

onChanged

פרמטרים

chrome.storage