תיאור
שימוש ב-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:
- אפשר ליצור מסמך שלא נמצא במסך עם תרחיש המרות ו-handler של [
onMessage
][on-message]. - מוסיפים תרחיש המרות למסמך שלא מוצג במסך.
- בקובץ השירות של התוסף, בודקים את הנתונים ב-
chrome.storage
. - אם הנתונים לא נמצאו, צריך [ליצור][create-offscreen] של מסמך שלא מופיע במסך, ולהתקשר אל [
sendMessage()
][send-message] כדי להתחיל את תרחיש ההמרות. - בתוך ה-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
רמת הגישה של אזור האחסון.
Enum
"TRUSTED_CONTEXTS"
מציין הקשרים שמקורם מהתוסף עצמו.
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
ההגדרה קובעת הקשרים שמקורם מחוץ לתוסף.
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<object>
Chrome מגרסה 88 ואילךהבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
-
-
getBytesInUse
ריק
הבטחההפונקציה מקבלת את נפח האחסון (בבייטים) שמשמש פריט אחד או יותר.
הפונקציה
getBytesInUse
נראית כך:(keys?: string | string[], callback?: function) => {...}
-
מפתחות
string | string[] אופציונלי
מקש בודד או רשימת מפתחות לקבלת השימוש הכולל עבורם. רשימה ריקה תחזיר את הערך 0. כדי לנצל את כל נפח האחסון, עליך לעבור בעוד
null
. -
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(bytesInUse: number) => void
-
bytesInUse
number
כמות השטח שבשימוש באחסון, בבייטים.
-
-
החזרות
Promise<number>
Chrome מגרסה 88 ואילךהבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
-
-
getKeys
ריק
הבטחה בהמתנהמקבל את כל המפתחות מהאחסון.
הפונקציה
getKeys
נראית כך:(callback?: function) => {...}
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(keys: string[]) => void
-
מפתחות
String[]
מערך עם מפתחות שנקראו מהאחסון.
-
-
החזרות
Promise<string[]>
הבטחות נתמכות רק במניפסט מגרסה 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
רמת הגישה של אזור האחסון.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
-
החזרות
הבטחה<Empty>
הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
-
StorageChange
מאפיינים
-
newValue
כל אופציונלי
הערך החדש של הפריט, אם קיים ערך חדש.
-
oldValue
כל אופציונלי
הערך הישן של הפריט, אם היה ערך ישן.
מאפיינים
local
הפריטים באזור האחסון של local
הם מקומיים לכל מכונה.
סוג
StorageArea ו אובייקט
מאפיינים
-
QUOTA_BYTES
10485760
הכמות המקסימלית (בבייטים) של נתונים שאפשר לאחסן באחסון המקומי, כפי שנמדדת באמצעות מחרוזות JSON של כל ערך ואורך כל מפתח. המערכת תתעלם מהערך הזה אם לתוסף יש את ההרשאה
unlimitedStorage
. עדכונים שעלולים לגרום לחריגה מהמגבלה הזו נכשלים באופן מיידי ומגדירים את הערךruntime.lastError
כשמשתמשים בקריאה חוזרת (callback), או בהבטחה שנדחתה אם משתמשים בפורמט async/await.
managed
הפריטים באזור האחסון של managed
מוגדרים על ידי מדיניות ארגונית שהוגדרה על ידי מנהל הדומיין, והם לקריאה בלבד עבור התוסף. הניסיון לשנות את מרחב השמות הזה יגרום לשגיאה. למידע נוסף על הגדרת מדיניות, ראו מניפסט לאזורי אחסון.
סוג
session
פריטים באזור האחסון של 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
מחרוזת
-