chrome.storage

Deskripsi

Izin

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

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

Contoh

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

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);
});

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);
});

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

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

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

• Ekstensi penelusuran global.
• Ekstensi alarm air.

Konsep dan penggunaan

Storage API menyediakan cara khusus ekstensi untuk mempertahankan data dan status pengguna. API ini mirip dengan API penyimpanan platform web (IndexedDB, dan Storage), tetapi dirancang untuk memenuhi kebutuhan penyimpanan ekstensi. Berikut 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 yang disimpan tetap ada meskipun saat menggunakan mode samaran terpisah.
• Mencakup area penyimpanan terkelola hanya baca eksklusif untuk kebijakan perusahaan.

Dapatkah ekstensi menggunakan API penyimpanan web?

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:

• Service worker 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 penjelajahannya.

Untuk memindahkan data dari API penyimpanan web ke API penyimpanan ekstensi dari pekerja layanan:

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

Ada juga beberapa nuansa tentang cara kerja API penyimpanan web di ekstensi. Pelajari lebih lanjut di artikel Penyimpanan dan Cookie.

Batas penyimpanan dan throttling

Storage API memiliki batasan penggunaan:

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

Untuk mengetahui detail tentang batasan area penyimpanan dan apa yang terjadi jika batas 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, API ini diekspos 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. Fitur ini dikelola oleh administrator sistem, menggunakan skema yang ditentukan developer dan kebijakan perusahaan. Kebijakan serupa dengan opsi, tetapi dikonfigurasi oleh administrator sistem, bukan pengguna. Dengan demikian, ekstensi dapat dikonfigurasi sebelumnya untuk semua pengguna organisasi.

Secara default, storage.managed diekspos 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, diupdate, dan saat browser dimulai ulang. Secara default, API ini tidak diekspos 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).

Antarmukastorage.session adalah salah satu dari beberapa antarmuka 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, perilakunya 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.

Sebaiknya gunakan storage.sync untuk mempertahankan setelan pengguna di seluruh browser yang disinkronkan. Jika Anda menangani data pengguna sensitif, gunakan storage.session. Secara default, storage.sync diekspos 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 dalam StorageArea.

remove()

Metode remove() memungkinkan Anda menghapus item dari StorageArea.

set()

Metode set() memungkinkan Anda menyetel item dalam 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 pembaruan penyimpanan

Untuk melacak perubahan yang dilakukan pada penyimpanan, tambahkan pemroses ke peristiwa onChanged-nya. Saat ada perubahan di penyimpanan, peristiwa tersebut akan diaktifkan. Kode contoh memantau 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 bisa mengembangkan ide ini lebih jauh. Dalam contoh ini, kita memiliki halaman opsi yang memungkinkan pengguna mengaktifkan/menonaktifkan "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);
  }
});

Pemuatan awal asinkron dari penyimpanan

Karena pekerja layanan tidak selalu berjalan, ekstensi Manifest V3 terkadang perlu memuat data dari penyimpanan secara asinkron sebelum menjalankan pengendali peristiwanya. Untuk melakukannya, cuplikan berikut menggunakan pengendali peristiwa action.onClicked asinkron yang menunggu storageCache global 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.

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