chrome.storage

Deskripsi

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

Izin

storage

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

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

Konsep dan penggunaan

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.

Dapatkah ekstensi menggunakan API penyimpanan web?

Meskipun ekstensi dapat menggunakan antarmuka Storage (dapat diakses dari window.localStorage) dalam beberapa konteks (popup 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 saat pengguna menghapus histori penjelajahan mereka.

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

  1. Siapkan halaman html dokumen di balik layar dan file skrip. File skrip harus berisi rutinitas konversi dan pengendali 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 di-resolve, panggil sendMessage() untuk memulai rutinitas konversi.
  5. Di dalam pengendali onMessage dokumen di luar layar, panggil rutinitas konversi.

Ada juga beberapa perbedaan kecil mengenai cara kerja API penyimpanan web dalam ekstensi. Pelajari lebih lanjut di artikel Penyimpanan dan Cookie.

Area penyimpanan

Storage API dibagi menjadi area penyimpanan berikut:

storage.local
Data disimpan secara lokal dan akan 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.
storage.managed
Penyimpanan terkelola adalah penyimpanan hanya baca untuk ekstensi yang diinstal oleh kebijakan dan dikelola oleh administrator sistem menggunakan skema yang ditentukan developer dan kebijakan perusahaan. Kebijakan serupa dengan opsi, tetapi dikonfigurasi oleh administrator sistem, bukan pengguna, sehingga memungkinkan ekstensi 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 menetapkan 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.
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. Sebaiknya gunakan storage.sync untuk mempertahankan setelan pengguna di seluruh browser yang disinkronkan. Jika Anda menangani data pengguna yang sensitif, gunakan storage.session.

Batas penyimpanan dan throttling

Storage API memiliki batasan penggunaan berikut:

  • Menyimpan data sering kali menimbulkan biaya performa, dan API menyertakan kuota penyimpanan. Sebaiknya perhatikan data yang Anda simpan agar tidak kehilangan kemampuan penyimpanan data.
  • Proses penyimpanan dapat memerlukan waktu beberapa saat. Pastikan untuk menyusun kode Anda untuk memperhitungkan waktu tersebut.

Untuk mengetahui detail tentang batasan 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, tambahkan 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 berjalan sepanjang waktu, ekstensi Manifes 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 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

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

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 lainnya, pelajari salah satu contoh berikut:

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.

StorageArea

Properti

  • onChanged

    Peristiwa<functionvoidvoid>

    Chrome 73 dan yang lebih baru

    Diaktifkan 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

    Promise

    Menghapus 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 baru

      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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

  • get

    void

    Promise

    Mendapatkan satu atau beberapa item dari penyimpanan.

    Fungsi get terlihat seperti: 

    (keys?: string|string[]|object,callback?: function)=> {...}

    • kunci

      string|string[]|object optional

      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 baru

      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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

  • getBytesInUse

    void

    Promise

    Mendapatkan jumlah ruang (dalam byte) yang digunakan oleh satu atau beberapa item.

    Fungsi getBytesInUse terlihat seperti: 

    (keys?: string|string[],callback?: function)=> {...}

    • kunci

      string|string[] optional

      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 baru

      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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

  • hapus

    void

    Promise

    Menghapus 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 baru

      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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

  • set

    void

    Promise

    Menetapkan 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 pengecualian Array (diserialisasi seperti yang diharapkan), Date, dan Regex (diserialisasi menggunakan representasi String-nya).

    • callback

      fungsi opsional

      Parameter callback terlihat seperti: 

      ()=>void

    • akan menampilkan

      Promise<void>

      Chrome 88 dan yang lebih baru

      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. Promise di-resolve dengan jenis yang sama yang diteruskan ke 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

        AccessLevel

        Tingkat akses area penyimpanan.

    • callback

      fungsi opsional

      Parameter callback terlihat seperti: 

      ()=>void

    • akan menampilkan

      Promise<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. Promise di-resolve dengan jenis yang sama yang diteruskan ke 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 menetapkan runtime.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

StorageArea

session

Chrome 102+ MV3+

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 lagi

    API storage.sync 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. 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, atau clear 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