Deskripsi
Gunakan chrome.storage
API untuk menyimpan, mengambil, dan melacak perubahan pada data pengguna.
Izin
storage
Untuk menggunakan storage API, deklarasikan izin "storage"
di ekstensi
manifes. Contoh:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
Konsep dan penggunaan
Storage API menyediakan cara khusus ekstensi untuk mempertahankan data dan status pengguna. API ini serupa dengan API penyimpanan platform web (IndexedDB, dan Storage), tetapi dirancang untuk memenuhi kebutuhan penyimpanan ekstensi. Berikut ini adalah beberapa fitur utama:
- Semua konteks ekstensi, termasuk pekerja layanan ekstensi dan skrip konten memiliki akses ke Storage API.
- Nilai yang dapat diserialisasi JSON disimpan sebagai properti objek.
- Storage API asinkron dengan operasi baca dan tulis massal.
- Meskipun pengguna menghapus cache dan histori penjelajahan, data akan tetap ada.
- Setelan tersimpan akan tetap ada meskipun Anda menggunakan mode samaran terpisah.
- Mencakup area penyimpanan terkelola hanya baca yang eksklusif untuk kebijakan perusahaan.
Dapatkah ekstensi menggunakan Web Storage API?
Meskipun ekstensi dapat menggunakan antarmuka Storage
(dapat diakses dari window.localStorage
) dalam beberapa konteks (pop-up dan halaman HTML lainnya), kami tidak merekomendasikannya karena alasan berikut:
- Pekerja layanan ekstensi tidak dapat menggunakan Web Storage API.
- Skrip konten berbagi penyimpanan dengan halaman host.
- Data yang disimpan menggunakan Web Storage API akan hilang jika pengguna menghapus histori penjelajahannya.
Untuk memindahkan data dari Web Storage API ke API penyimpanan ekstensi dari pekerja layanan:
- Siapkan halaman HTML dokumen dan file skrip di luar layar. File skrip harus berisi rutinitas konversi dan pengendali
onMessage
. - Di pekerja layanan ekstensi, periksa
chrome.storage
untuk menemukan data Anda. - Jika data Anda tidak ditemukan, panggil
createDocument()
. - Setelah Promise yang ditampilkan di-resolve, panggil
sendMessage()
untuk memulai rutinitas konversi. - Di dalam pengendali
onMessage
dokumen di luar layar, panggil rutinitas konversi.
Ada juga beberapa perbedaan cara kerja Web Storage API di ekstensi. Pelajari lebih lanjut di Artikel Penyimpanan dan Cookie.
Area penyimpanan
Storage API dibagi ke dalam area penyimpanan berikut:
storage.local
- Data disimpan secara lokal dan dihapus saat ekstensi dihapus. Batas penyimpanan adalah 10 MB (5 MB di Chrome 113 dan yang lebih lama), tetapi dapat ditingkatkan dengan meminta izin
"unlimitedStorage"
. Sebaiknya gunakanstorage.local
untuk menyimpan data dalam jumlah yang lebih besar. storage.managed
- Penyimpanan terkelola adalah penyimpanan hanya baca untuk ekstensi yang diinstal kebijakan dan dikelola oleh administrator sistem menggunakan skema yang ditentukan developer dan kebijakan perusahaan. Kebijakan setara dengan opsi, tetapi dikonfigurasi oleh administrator sistem, bukan pengguna, sehingga ekstensi dapat dikonfigurasi sebelumnya untuk semua pengguna di organisasi. Untuk informasi tentang kebijakan, lihat Dokumentasi untuk Administrator. Untuk mempelajari area penyimpanan
managed
lebih lanjut, lihat Manifes untuk area penyimpanan. storage.session
- Menyimpan data di memori selama durasi sesi browser. Secara default, skrip tidak diekspos ke skrip konten, tetapi perilaku ini dapat diubah dengan menyetel
chrome.storage.session.setAccessLevel()
. Batas penyimpanan adalah 10 MB (1 MB di Chrome 111 dan yang lebih lama). Antarmukastorage.session
adalah salah satu dari beberapa yang kami rekomendasikan untuk pekerja layanan. storage.sync
- Jika sinkronisasi diaktifkan, data akan disinkronkan ke browser Chrome apa pun yang digunakan pengguna untuk login. Jika dinonaktifkan, perilakunya akan menjadi seperti
storage.local
. Chrome menyimpan data secara lokal saat browser sedang offline dan melanjutkan sinkronisasi saat browser kembali online. Batasan kuota sekitar 100 KB, 8 KB per item. Sebaiknya gunakanstorage.sync
untuk mempertahankan setelan pengguna di seluruh browser yang disinkronkan. Jika Anda menangani data pengguna yang sensitif, gunakanstorage.session
.
Batas penyimpanan dan throttling
Storage API memiliki batasan penggunaan berikut:
- Menyimpan data sering kali menimbulkan biaya performa, dan API menyertakan kuota penyimpanan. Sebaiknya berhati-hatilah terhadap data yang Anda simpan sehingga Anda tidak kehilangan kemampuan untuk menyimpan data.
- Mungkin perlu waktu beberapa saat untuk menyelesaikan penyimpanan. Pastikan untuk menyusun kode Anda untuk memperhitungkan waktu tersebut.
Untuk mengetahui detail tentang batasan area penyimpanan dan hal yang terjadi jika area penyimpanan terlampaui, lihat informasi kuota untuk sync
, local
, dan session
.
Kasus penggunaan
Bagian berikut menunjukkan kasus penggunaan umum untuk Storage API.
Respons sinkron terhadap pembaruan penyimpanan
Untuk melacak perubahan yang dilakukan pada penyimpanan, tambahkan pemroses ke peristiwa onChanged
. Ketika ada perubahan dalam penyimpanan, peristiwa itu akan diaktifkan. Kode contoh memproses perubahan ini:
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}".`
);
}
});
Kita dapat menerapkan ide ini lebih jauh. Dalam contoh ini, kita memiliki halaman opsi yang
memungkinkan pengguna untuk beralih ke "mode debug" (penerapan tidak ditampilkan di sini). Halaman opsi akan segera menyimpan setelan baru ke storage.sync
, dan pekerja layanan menggunakan storage.onChanged
untuk menerapkan setelan sesegera mungkin.
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);
}
});
Pramuat asinkron dari penyimpanan
Karena pekerja layanan tidak berjalan sepanjang waktu, ekstensi Manifes V3 terkadang perlu
memuat data secara asinkron dari penyimpanan sebelum menjalankan pengendali peristiwanya. Untuk melakukannya,
cuplikan berikut menggunakan pengendali peristiwa action.onClicked
asinkron yang menunggu storageCache
global yang akan diisi sebelum mengeksekusi logikanya.
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);
});
Contoh
Contoh berikut menunjukkan local
, sync
, dan
session
area penyimpanan:
Lokal
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);
});
Sinkronisasi
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);
});
Sesi
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);
});
Untuk melihat demo Storage API lain, jelajahi salah satu contoh berikut:
Jenis
AccessLevel
Tingkat akses area penyimpanan.
Enum
"TRUSTED_CONTEXTS"
Menentukan konteks yang berasal dari ekstensi itu sendiri.
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Menentukan konteks yang berasal dari luar ekstensi.
StorageArea
Properti
-
onChanged
Peristiwa<functionvoidvoid>
Chrome 73 dan yang lebih baruDiaktifkan jika satu atau beberapa item berubah.
Fungsi
onChanged.addListener
akan terlihat seperti ini:(callback: function) => {...}
-
callback
fungsi
Parameter
callback
terlihat seperti ini:(changes: object) => void
-
perubahan
objek
-
-
-
hapus
void
JanjiMenghapus semua item dari penyimpanan.
Fungsi
clear
akan terlihat seperti ini:(callback?: function) => {...}
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
-
akan menampilkan
Janji<void>
Chrome 88 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
-
get
void
JanjiMendapatkan satu atau beberapa item dari penyimpanan.
Fungsi
get
akan terlihat seperti ini:(keys?: string | string[] | object, callback?: function) => {...}
-
kunci
string | string[] | objek opsional
Kunci tunggal yang akan didapatkan, daftar kunci yang akan didapatkan, atau kamus yang menentukan nilai default (lihat deskripsi objek). Daftar atau objek kosong akan menampilkan objek hasil kosong. Teruskan
null
untuk mendapatkan seluruh konten penyimpanan. -
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(items: object) => void
-
item
objek
Objek dengan item dalam pemetaan nilai kuncinya.
-
-
akan menampilkan
Promise<object>
Chrome 88 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
-
getBytesInUse
void
JanjiMendapatkan jumlah ruang (dalam byte) yang digunakan oleh satu atau beberapa item.
Fungsi
getBytesInUse
akan terlihat seperti ini:(keys?: string | string[], callback?: function) => {...}
-
kunci
string | string[] opsional
Satu kunci atau daftar kunci untuk mengetahui total penggunaan. Daftar kosong akan menampilkan 0. Teruskan
null
untuk mendapatkan total penggunaan dari semua penyimpanan. -
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(bytesInUse: number) => void
-
bytesInUse
angka
Jumlah ruang yang digunakan dalam penyimpanan, dalam byte.
-
-
akan menampilkan
Promise<number>
Chrome 88 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
-
getKey
void
Janji TertundaMendapatkan semua kunci dari penyimpanan.
Fungsi
getKeys
akan terlihat seperti ini:(callback?: function) => {...}
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(keys: string[]) => void
-
kunci
{i>string<i}[]
Array dengan kunci yang dibaca dari penyimpanan.
-
-
akan menampilkan
Promise<string[]>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
-
hapus
void
JanjiMenghapus satu atau beberapa item dari penyimpanan.
Fungsi
remove
akan terlihat seperti ini:(keys: string | string[], callback?: function) => {...}
-
kunci
string | {i>string<i}[]
Tombol tunggal atau daftar kunci untuk item yang akan dihapus.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
-
akan menampilkan
Janji<void>
Chrome 88 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
-
set
void
JanjiMenetapkan beberapa item.
Fungsi
set
akan terlihat seperti ini:(items: object, callback?: function) => {...}
-
item
objek
Objek yang memberi setiap key-value pair untuk mengupdate penyimpanan. Key-value pair lainnya di penyimpanan tidak akan terpengaruh.
Nilai primitif seperti angka akan diserialisasi seperti yang diharapkan. Nilai dengan
typeof
"object"
dan"function"
biasanya akan diserialisasi ke{}
, dengan pengecualianArray
(diserialisasi seperti yang diharapkan),Date
, danRegex
(serialisasi menggunakan representasiString
-nya). -
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
-
akan menampilkan
Janji<void>
Chrome 88 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
-
setAccessLevel
void
Janji Chrome 102 dan yang lebih baruMenetapkan tingkat akses yang diinginkan untuk area penyimpanan. Setelan defaultnya hanya akan menampilkan konteks tepercaya.
Fungsi
setAccessLevel
akan terlihat seperti ini:(accessOptions: object, callback?: function) => {...}
-
accessOptions
objek
-
accessLevel
Tingkat akses area penyimpanan.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
-
akan menampilkan
Janji<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
StorageChange
Properti
-
newValue
semua opsional
Nilai baru item, jika ada nilai baru.
-
oldValue
semua opsional
Nilai lama item, jika ada nilai lama.
Properti
local
Item di area penyimpanan local
bersifat lokal untuk setiap komputer.
Jenis
StorageArea & objek
Properti
-
QUOTA_BYTES
10485760
Jumlah maksimum data (dalam byte) yang dapat disimpan dalam penyimpanan lokal, yang diukur dengan stringifikasi JSON untuk setiap nilai ditambah panjang setiap kunci. Nilai ini akan diabaikan jika ekstensi memiliki izin
unlimitedStorage
. Update yang akan menyebabkan batas ini terlampaui akan langsung gagal dan menetapkanruntime.lastError
saat menggunakan callback, atau Promise yang ditolak jika menggunakan async/await.
managed
Item di area penyimpanan managed
disetel oleh kebijakan perusahaan yang dikonfigurasi oleh administrator domain, dan bersifat hanya baca untuk ekstensi; mencoba mengubah ruang nama
ini akan mengakibatkan kesalahan. Untuk mengetahui informasi tentang cara mengonfigurasi kebijakan, lihat Manifes untuk area penyimpanan.
Jenis
session
Item di area penyimpanan session
disimpan di dalam memori dan tidak akan dipertahankan di disk.
Jenis
StorageArea & objek
Properti
-
QUOTA_BYTES
10485760
Jumlah maksimum data (dalam byte) yang dapat disimpan dalam memori, yang diukur dengan memperkirakan penggunaan memori yang dialokasikan secara dinamis dari setiap nilai dan kunci. Update yang akan menyebabkan batas ini terlampaui akan langsung gagal dan menetapkan
runtime.lastError
saat menggunakan callback, atau saat Promise ditolak.
sync
Item di area penyimpanan sync
disinkronkan menggunakan Sinkronisasi Chrome.
Jenis
StorageArea & objek
Properti
-
MAX_ITEMS
512
Jumlah maksimum item yang dapat disimpan di penyimpanan sinkronisasi. Update yang akan menyebabkan batas ini terlampaui akan langsung gagal dan menetapkan
runtime.lastError
saat menggunakan callback, atau jika Promise ditolak. -
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1.000.000
Tidak digunakan lagistorage.sync API tidak lagi memiliki kuota operasi tulis berkelanjutan.
-
MAX_WRITE_OPERATIONS_PER_HOUR
1.800
Jumlah maksimum operasi
set
,remove
, atauclear
yang dapat dilakukan setiap jam. Nilai ini adalah 1 setiap 2 detik, plafon yang lebih rendah daripada batas operasi tulis per menit yang lebih tinggi dalam jangka pendek.Update yang akan menyebabkan batas ini terlampaui akan langsung gagal dan menetapkan
runtime.lastError
saat menggunakan callback, atau saat Promise ditolak. -
MAX_WRITE_OPERATIONS_PER_MINUTE
120
Jumlah maksimum operasi
set
,remove
, atauclear
yang dapat dilakukan setiap menit. Kecepatannya adalah 2 per detik, sehingga memberikan throughput yang lebih tinggi daripada operasi tulis per jam dalam jangka waktu yang lebih singkat.Update yang akan menyebabkan batas ini terlampaui akan langsung gagal dan menetapkan
runtime.lastError
saat menggunakan callback, atau saat Promise ditolak. -
QUOTA_BYTES
102.400
Jumlah total maksimum (dalam byte) data yang dapat disimpan dalam penyimpanan sinkronisasi, yang diukur dengan stringifikasi JSON untuk setiap nilai ditambah panjang setiap kunci. Update yang akan menyebabkan batas ini terlampaui akan langsung gagal dan menetapkan
runtime.lastError
saat menggunakan callback, atau saat Promise ditolak. -
QUOTA_BYTES_PER_ITEM
8192
Ukuran maksimum (dalam byte) setiap item individual dalam penyimpanan sinkronisasi, yang diukur dengan stringifikasi JSON nilainya ditambah panjang kuncinya. Update berisi item yang lebih besar dari batas ini akan langsung gagal dan menetapkan
runtime.lastError
saat menggunakan callback, atau jika Promise ditolak.
Acara
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
Diaktifkan jika satu atau beberapa item berubah.
Parameter
-
callback
fungsi
Parameter
callback
terlihat seperti ini:(changes: object, areaName: string) => void
-
perubahan
objek
-
areaName
string
-