Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

chrome.storage

Deskripsi

Gunakan chrome.storage API untuk menyimpan, mengambil, dan melacak perubahan pada data pengguna.

Izin

storage

Untuk menggunakan Storage API, deklarasikan izin "storage" dalam ekstensi manifes. Contoh:

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

Contoh

Contoh berikut menunjukkan area penyimpanan local, sync, dan session:

Contoh (Lokal)

await chrome.storage.local.set({ key: value });
console.log("Value is set");
const result = await chrome.storage.local.get(["key"]);
console.log("Value is " + result.key);

Contoh (Sinkronisasi)

await chrome.storage.sync.set({ key: value });
console.log("Value is set");
const result = await chrome.storage.sync.get(["key"]);
console.log("Value is " + result.key);

Contoh (Sesi)

await chrome.storage.session.set({ key: value });
console.log("Value is set");
const result = await chrome.storage.session.get(["key"]);
console.log("Value is " + result.key);

Untuk melihat demo Storage API lainnya, jelajahi salah satu contoh berikut:

Konsep dan penggunaan

Storage API menyediakan cara khusus ekstensi untuk mempertahankan data dan status pengguna. API ini mirip dengan Storage API platform web (IndexedDB dan Storage), tetapi dirancang untuk memenuhi kebutuhan penyimpanan ekstensi. Berikut adalah beberapa fitur utamanya:

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 yang disimpan akan tetap ada meskipun menggunakan mode samaran terpisah .
Menyertakan area penyimpanan terkelola hanya baca 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), sebaiknya jangan gunakan antarmuka ini 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 saat pengguna menghapus histori penjelajahan.

Untuk memindahkan data dari Web Storage API ke Storage API ekstensi dari pekerja layanan:

Siapkan halaman HTML dokumen offscreen dan file skrip. File skrip harus berisi rutin konversi dan pengendali onMessage.
Di pekerja layanan ekstensi, periksa chrome.storage untuk data Anda.
Jika data Anda tidak ditemukan, panggil createDocument().
Setelah Promise yang ditampilkan diselesaikan, panggil sendMessage() untuk memulai rutin konversi.
Di dalam pengendali onMessage dokumen offscreen, panggil rutin konversi.

Ada juga beberapa nuansa terkait cara kerja Web Storage API di ekstensi. Pelajari lebih lanjut di artikel Penyimpanan dan Cookie.

Batas penyimpanan dan throttling

Storage API memiliki batasan penggunaan:

Menyimpan data memiliki biaya performa, dan API menyertakan kuota penyimpanan. Rencanakan data yang ingin Anda simpan, sehingga Anda dapat mempertahankan ruang penyimpanan.
Penyimpanan dapat memerlukan waktu untuk diselesaikan. Strukturkan kode Anda untuk memperhitungkan waktu tersebut.

Untuk mengetahui detail batasan area penyimpanan dan apa yang terjadi jika batasan tersebut terlampaui, lihat informasi kuota untuk sync, local, dan session.

Area penyimpanan

Storage API dibagi menjadi area penyimpanan berikut:

Lokal

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 gunakan storage.local untuk menyimpan data dalam jumlah yang lebih besar. Secara default, data ini ditampilkan ke skrip konten, tetapi perilaku ini dapat diubah dengan memanggil chrome.storage.local.setAccessLevel().

Terkelola

Penyimpanan terkelola bersifat hanya baca untuk ekstensi yang diinstal kebijakan. Penyimpanan ini dikelola oleh administrator sistem, menggunakan kebijakan perusahaan dan skema yang ditentukan developer. Kebijakan mirip dengan opsi, tetapi dikonfigurasi oleh administrator sistem, bukan pengguna. Hal ini memungkinkan ekstensi dikonfigurasi sebelumnya untuk semua pengguna organisasi.

Secara default, storage.managed ditampilkan ke skrip konten, tetapi perilaku ini dapat diubah dengan memanggil chrome.storage.managed.setAccessLevel(). Untuk mengetahui informasi tentang kebijakan, lihat Dokumentasi untuk Administrator. Untuk mempelajari area penyimpanan managed lebih lanjut, lihat Manifes untuk area penyimpanan.

Sesi

Penyimpanan sesi menyimpan data dalam memori saat ekstensi dimuat. Penyimpanan akan dihapus jika ekstensi dinonaktifkan, dimuat ulang, diperbarui, dan saat browser dimulai ulang. Secara default, penyimpanan ini tidak ditampilkan ke skrip konten, tetapi perilaku ini dapat diubah dengan memanggil chrome.storage.session.setAccessLevel(). Batas penyimpanan adalah 10 MB (1 MB di Chrome 111 dan yang lebih lama).

Antarmuka storage.session adalah salah satu dari beberapa yang kami rekomendasikan untuk pekerja layanan.

Sinkronisasi

Jika pengguna mengaktifkan sinkronisasi, data akan disinkronkan dengan setiap browser Chrome yang digunakan pengguna untuk login. Jika dinonaktifkan, perilaku ini akan seperti storage.local. Chrome menyimpan data secara lokal saat browser offline dan melanjutkan sinkronisasi saat kembali online. Batasan kuota sekitar 100 KB, 8 KB per item.

Sebaiknya gunakan storage.sync untuk mempertahankan setelan pengguna di seluruh browser yang disinkronkan. Jika Anda menggunakan data pengguna yang sensitif, gunakan storage.session sebagai gantinya. Secara default, storage.sync ditampilkan ke skrip konten, tetapi perilaku ini dapat diubah dengan memanggil chrome.storage.sync.setAccessLevel().

Metode dan peristiwa

Semua area penyimpanan menerapkan antarmuka StorageArea.

get()

Metode get() memungkinkan Anda membaca satu atau beberapa kunci dari StorageArea.

getBytesInUse()

Metode getBytesInUse() memungkinkan Anda melihat kuota yang digunakan oleh StorageArea.

getKeys()

Metode getKeys() memungkinkan Anda mendapatkan semua kunci yang disimpan di StorageArea.

remove()

Metode remove() memungkinkan Anda menghapus item dari StorageArea.

set()

Metode set() memungkinkan Anda menetapkan item di StorageArea.

setAccessLevel()

Metode setAccessLevel() memungkinkan Anda mengontrol akses ke StorageArea.

clear()

Metode clear() memungkinkan Anda menghapus semua data dari StorageArea.

onChanged

Peristiwa onChanged memungkinkan Anda memantau perubahan pada StorageArea.

Kasus penggunaan

Bagian berikut menunjukkan kasus penggunaan umum untuk Storage API.

Merespons update penyimpanan

Untuk melacak perubahan yang dilakukan pada penyimpanan, tambahkan pemroses ke peristiwa onChanged. Jika ada perubahan pada penyimpanan, peristiwa tersebut 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 mengembangkan ide ini lebih lanjut. Dalam contoh ini, kita memiliki halaman opsi yang memungkinkan pengguna mengaktifkan atau menonaktifkan "mode debug" (implementasi 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 selalu berjalan, ekstensi Manifest 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);
});

DevTools

Anda dapat melihat dan mengedit data yang disimpan menggunakan API di DevTools. Untuk mempelajari lebih lanjut, lihat halaman Melihat dan mengedit penyimpanan ekstensi di dokumentasi DevTools.

Jenis

AccessLevel

Chrome 102+

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.

StorageChange

Properti

newValue

opsional apa pun

Nilai baru item, jika ada nilai baru.
oldValue

opsional apa pun

Nilai lama item, jika ada nilai lama.

Properti

local

Item di area penyimpanan local bersifat lokal untuk setiap mesin.

Jenis

StorageArea & objek

Properti

QUOTA_BYTES

10485760

Jumlah maksimum (dalam byte) data yang dapat disimpan di penyimpanan lokal, yang diukur dengan stringifikasi JSON 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 menetapkan runtime.lastError saat menggunakan callback, atau Promise yang ditolak jika menggunakan async/await.

managed

Item di area penyimpanan managed ditetapkan 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

StorageArea

session

Chrome 102+ MV3+

Item di area penyimpanan session disimpan dalam memori dan tidak akan dipertahankan 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 lagi

Storage.sync API tidak lagi memiliki kuota operasi tulis berkelanjutan.
MAX_WRITE_OPERATIONS_PER_HOUR

1800

Jumlah maksimum operasi set, remove, atau clear yang dapat dilakukan setiap jam. Jumlahnya adalah 1 setiap 2 detik, batas yang lebih rendah daripada batas 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, atau clear yang dapat dilakukan setiap menit. Jumlahnya adalah 2 per detik, yang memberikan throughput lebih tinggi daripada 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

102400

Jumlah total maksimum (dalam byte) data yang dapat disimpan di penyimpanan sinkronisasi, yang diukur dengan stringifikasi JSON 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 di penyimpanan sinkronisasi, yang diukur dengan stringifikasi JSON nilainya ditambah panjang kuncinya. Update yang berisi item yang lebih besar dari batas ini akan langsung gagal dan menetapkan 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

chrome.storage Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Deskripsi

Izin

Contoh

Contoh (Lokal)

Contoh (Sinkronisasi)

Contoh (Sesi)

Konsep dan penggunaan

Dapatkah ekstensi menggunakan Web Storage API?

Batas penyimpanan dan throttling

Area penyimpanan

Lokal

Terkelola

Sesi

Sinkronisasi

Metode dan peristiwa

get()

getBytesInUse()

getKeys()

remove()

set()

setAccessLevel()

clear()

onChanged

Kasus penggunaan

Merespons update penyimpanan

Pramuat asinkron dari penyimpanan

DevTools

Jenis

AccessLevel

Enum

StorageChange

Properti

Properti

local

Jenis

Properti

managed

Jenis

session

Jenis

Properti

sync

Jenis

Properti

Acara

onChanged

Parameter

chrome.storage