Deskripsi
Gunakan chrome.storage
API untuk menyimpan, mengambil, dan melacak perubahan pada data pengguna.
Izin
storage
Ringkasan
Storage API menyediakan cara khusus ekstensi untuk mempertahankan data dan status pengguna. Penyimpanan ini serupa dengan API penyimpanan platform web (IndexedDB, dan Storage), tetapi dirancang untuk memenuhi kebutuhan penyimpanan ekstensi. Berikut 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 bersifat asinkron dengan operasi baca dan tulis massal.
- Meskipun pengguna menghapus cache dan histori penjelajahan, data akan tetap ada.
- Setelan tersimpan tetap ada meskipun menggunakan mode samaran terpisah.
- Mencakup area penyimpanan terkelola hanya baca eksklusif untuk kebijakan perusahaan.
Meskipun ekstensi dapat menggunakan antarmuka [Storage
][mdn-storage] (dapat diakses dari window.localStorage
) dalam beberapa konteks (popup dan halaman HTML lainnya), hal ini tidak direkomendasikan karena alasan berikut:
- Pekerja layanan ekstensi tidak dapat mengakses
Storage
. - Skrip konten berbagi penyimpanan dengan halaman host.
- Data yang disimpan menggunakan antarmuka
Storage
akan hilang jika pengguna menghapus histori penjelajahan mereka.
Untuk memindahkan data dari API penyimpanan web ke API penyimpanan ekstensi dari pekerja layanan:
- Buat dokumen di balik layar dengan rutinitas konversi dan pengendali [
onMessage
][dalam pesan]. - Tambahkan rutinitas konversi ke dokumen di balik layar.
- Di pekerja layanan ekstensi, periksa
chrome.storage
untuk data Anda. - Jika data Anda tidak ditemukan, [buat][buat][buat][buat]offscreen] dokumen di luar layar dan panggil [
sendMessage()
][kirim pesan] untuk memulai rutinitas konversi. - Di dalam pengendali
onMessage
dokumen di luar layar, panggil rutinitas konversi.
Ada juga perbedaan mengenai cara kerja API penyimpanan web dalam ekstensi. Pelajari lebih lanjut di artikel [Penyimpanan dan Cookie][storage-and-cookies].
Area penyimpanan
Storage API dibagi menjadi empat bucket berikut ("area penyimpanan"):
storage.local
- Data disimpan secara lokal, yang akan dihapus saat ekstensi dihapus. Batas kuota sekitar 10 MB, tetapi dapat ditingkatkan dengan meminta izin
"unlimitedStorage"
. Pertimbangkan untuk menggunakannya untuk menyimpan data dalam jumlah yang lebih besar.
storage.sync
- Jika sinkronisasi diaktifkan, data akan disinkronkan ke browser Chrome apa pun yang digunakan pengguna untuk login. Jika dinonaktifkan, kode akan berperilaku seperti
storage.local
. Chrome menyimpan data secara lokal saat browser offline dan melanjutkan sinkronisasi saat browser kembali online. Batasan kuota sekitar 100 KB, 8 KB per item. Pertimbangkan untuk menggunakannya untuk mempertahankan setelan pengguna di seluruh browser yang disinkronkan.
- storage.session
- Menyimpan data di memori selama durasi sesi browser. Secara default, skrip tidak diekspos ke skrip konten, tetapi perilaku ini dapat diubah dengan menetapkan
chrome.storage.session.setAccessLevel()
. Batas kuota sekitar 10 MB. Pertimbangkan untuk menggunakannya untuk menyimpan variabel global di seluruh pekerja layanan yang berjalan.
- storage.managed
- Administrator dapat menggunakan skema dan kebijakan perusahaan untuk mengonfigurasi setelan ekstensi pendukung di lingkungan terkelola. Area penyimpanan ini bersifat hanya baca.
Manifes
Untuk menggunakan API penyimpanan, deklarasikan izin "storage"
dalam
manifes ekstensi. Contoh:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
Penggunaan
Contoh berikut menunjukkan area penyimpanan local
, sync
, dan
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);
});
Untuk mempelajari area penyimpanan managed
lebih lanjut, lihat Manifes untuk area penyimpanan.
Batas penyimpanan dan throttling
Jangan menganggap Storage API seperti memasukkan sesuatu ke dalam truk besar. Bayangkan menambahkan ke penyimpanan seperti memasukkan sesuatu ke dalam pipa. Pipa itu mungkin sudah memiliki material, dan bahkan mungkin telah diisi. Selalu asumsikan penundaan dari saat Anda menambahkan penyimpanan hingga saat penyimpanan benar-benar direkam.
Untuk mengetahui detail tentang batas area penyimpanan dan apa yang akan terjadi jika batas tersebut terlampaui, lihat informasi kuota untuk sync
, local
, dan session
.
Kasus penggunaan
Bagian berikut menunjukkan kasus penggunaan umum untuk Storage API.
Respons sinkron terhadap update penyimpanan
Untuk melacak perubahan yang dilakukan pada penyimpanan, Anda dapat menambahkan pemroses ke peristiwa onChanged
. Ketika ada perubahan dalam penyimpanan, peristiwa itu dipicu. Kode contoh akan 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 membawa ide
ini lebih jauh lagi. Dalam contoh ini, kami memiliki halaman opsi yang
memungkinkan pengguna beralih ke "mode debug" (implementasi tidak ditampilkan di sini). Halaman opsi akan langsung 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 selalu berjalan, 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 global storageCache
diisi sebelum menjalankan 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 ekstensi
Untuk melihat demo Storage API lainnya, pelajari 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 saat satu atau beberapa item berubah.
Fungsi
onChanged.addListener
terlihat seperti:(callback: function) => {...}
-
callback
fungsi
Parameter
callback
terlihat seperti:(changes: object) => void
-
perubahan
objek
-
-
-
hapus
void
PromiseMenghapus semua item dari penyimpanan.
Fungsi
clear
terlihat seperti:(callback?: function) => {...}
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
-
akan menampilkan
Promise<void>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
-
get
void
PromiseMendapatkan satu atau beberapa item dari penyimpanan.
Fungsi
get
terlihat seperti:(keys?: string | string[] | object, callback?: function) => {...}
-
kunci
string | string[] | objek opsional
Kunci tunggal untuk 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:(items: object) => void
-
items
objek
Objek dengan item dalam pemetaan nilai kuncinya.
-
-
akan menampilkan
Promise<object>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
-
getBytesInUse
void
PromiseMendapatkan jumlah ruang (dalam byte) yang digunakan oleh satu atau beberapa item.
Fungsi
getBytesInUse
terlihat seperti:(keys?: string | string[], callback?: function) => {...}
-
kunci
string | string[] opsional
Satu kunci atau daftar kunci untuk mendapatkan total penggunaan. Daftar kosong akan menampilkan 0. Teruskan
null
untuk mendapatkan total penggunaan semua penyimpanan. -
callback
fungsi opsional
Parameter
callback
terlihat seperti:(bytesInUse: number) => void
-
bytesInUse
angka
Jumlah ruang yang digunakan dalam penyimpanan, dalam byte.
-
-
akan menampilkan
Promise<number>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
-
hapus
void
PromiseMenghapus satu atau beberapa item dari penyimpanan.
Fungsi
remove
terlihat seperti:(keys: string | string[], callback?: function) => {...}
-
kunci
string | string[]
Satu kunci atau daftar kunci untuk item yang akan dihapus.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
-
akan menampilkan
Promise<void>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
-
set
void
PromiseMenetapkan beberapa item.
Fungsi
set
terlihat seperti:(items: object, callback?: function) => {...}
-
items
objek
Objek yang memberikan setiap key-value pair untuk digunakan dalam mengupdate penyimpanan. Key-value pair lainnya dalam penyimpanan tidak akan terpengaruh.
Nilai dasar 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
(diserialisasi menggunakan representasiString
-nya). -
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
-
akan menampilkan
Promise<void>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
-
setAccessLevel
void
Promise Chrome 102+Menetapkan tingkat akses yang diinginkan untuk area penyimpanan. Defaultnya hanya akan berupa konteks tepercaya.
Fungsi
setAccessLevel
terlihat seperti:(accessOptions: object, callback?: function) => {...}
-
accessOptions
objek
-
accessLevel
Tingkat akses area penyimpanan.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
-
akan menampilkan
Promise<void>
Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
StorageChange
Properti
-
newValue
opsional
Nilai baru item, jika ada nilai baru.
-
oldValue
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 (dalam byte) data yang dapat disimpan di 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 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 namespace ini akan menghasilkan error. Untuk mengetahui informasi tentang cara mengonfigurasi kebijakan, lihat Manifes untuk area penyimpanan.
Jenis
session
Item di area penyimpanan session
disimpan di memori dan tidak akan disimpan ke disk.
Jenis
StorageArea & objek
Properti
-
QUOTA_BYTES
10485760
Jumlah maksimum (dalam byte) data 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 saat Promise ditolak. -
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1000000
Tidak digunakan lagiAPI storage.sync tidak lagi memiliki kuota operasi tulis berkelanjutan.
-
MAX_WRITE_OPERATIONS_PER_HOUR
1800
Jumlah maksimum operasi
set
,remove
, atauclear
yang dapat dilakukan setiap jam. Jumlah ini adalah 1 setiap 2 detik, batas yang lebih rendah dari batas penulisan-per-menit jangka pendek yang lebih tinggi.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. Ini adalah 2 per detik, yang memberikan throughput lebih tinggi daripada operasi tulis per jam dalam periode 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
102400
Jumlah total maksimum (dalam byte) data yang dapat disimpan di penyimpanan sinkronisasi, sebagaimana 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) untuk setiap item dalam penyimpanan sinkronisasi, yang diukur berdasarkan stringifikasi JSON terhadap nilainya ditambah panjang kuncinya. Update yang berisi item yang lebih besar dari batas ini akan langsung gagal dan ditetapkan
runtime.lastError
saat menggunakan callback, atau saat Promise ditolak.
Acara
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
Diaktifkan saat satu atau beberapa item berubah.
Parameter
-
callback
fungsi
Parameter
callback
terlihat seperti:(changes: object, areaName: string) => void
-
perubahan
objek
-
areaName
string
-