chrome.storage

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. 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 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 eksklusif hanya baca 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 saat pengguna menghapus histori penjelajahan.

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

1. Buat dokumen di balik layar dengan rutinitas konversi dan pengendali [onMessage][on-message].
2. Menambahkan rutinitas konversi ke dokumen di luar layar.
3. Di pekerja layanan ekstensi, periksa chrome.storage untuk menemukan data Anda.
4. Jika data Anda tidak ditemukan, [buat][create-offscreen] dokumen di balik layar dan panggil [sendMessage()][kirim-pesan] untuk memulai rutinitas konversi.
5. Di dalam pengendali onMessage dokumen di balik layar, panggil rutinitas konversi.

Ada juga beberapa perbedaan cara kerja Web Storage API di 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. Batasan kuota adalah sekitar 10 MB, tetapi dapat ditingkatkan dengan meminta izin "unlimitedStorage". Pertimbangkan untuk menggunakannya untuk menyimpan data dalam jumlah yang lebih besar.

Perhatian: Sebelum Chrome 114, kuotanya adalah sekitar 5 MB.

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 offline dan melanjutkan sinkronisasi saat kembali online. Batasan kuota sekitar 100 KB, 8 KB per item. Pertimbangkan untuk menggunakannya guna mempertahankan setelan pengguna di seluruh browser yang disinkronkan.

Peringatan: Area penyimpanan lokal dan sinkronisasi tidak boleh menyimpan data rahasia pengguna karena tidak dienkripsi. Saat menangani data sensitif, pertimbangkan untuk menggunakan area penyimpanan session untuk menyimpan nilai dalam memori hingga browser dimatikan.

storage.session

Menyimpan data dalam memori selama durasi sesi browser. Secara default, ini tidak diekspos ke skrip konten, tetapi perilaku ini dapat diubah dengan menetapkan chrome.storage.session.setAccessLevel(). Batasan kuota adalah sekitar 10 MB. Pertimbangkan untuk menggunakannya untuk menyimpan variabel global di seluruh operasi pekerja layanan.

Peringatan: Sebelum Chrome 112, kuotanya adalah sekitar 1 MB.

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 storage API, deklarasikan izin "storage" di ekstensi manifes. Contoh:

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

Penggunaan

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

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 barang ke dalam truk besar. Pikirkan untuk menambahkan penyimpanan seperti memasukkan sesuatu ke dalam pipa. Pipa mungkin sudah memiliki bahan di dalamnya, dan itu bahkan mungkin terisi. Selalu asumsikan adanya keterlambatan antara saat Anda menambahkan ke penyimpanan dan saat data tersebut benar-benar direkam.

Untuk mengetahui detail tentang batasan area penyimpanan dan apa yang terjadi jika batasan tersebut 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, Anda dapat menambahkan pemroses ke peristiwa onChanged-nya. 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 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 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 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 ekstensi

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

• Ekstensi penelusuran global.
• Ekstensi alarm air.

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 jika satu atau beberapa item berubah.

  Fungsi onChanged.addListener akan terlihat seperti ini:

  (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 ini:

    () => void

  • akan menampilkan

    Promise<void>

    Chrome 88+

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

• get

  void

  Promise

  Mendapatkan satu atau beberapa item dari penyimpanan.

  Fungsi get akan terlihat seperti ini:

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

  • kunci

    string | string[] | objek opsional

    Satu kunci yang akan diambil, daftar kunci yang akan diambil, 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

    • item

      objek

      Objek dengan item dalam pemetaan nilai kuncinya.

  • akan menampilkan

    Promise<object>

    Chrome 88+

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

• getBytesInUse

  void

  Janji

  Mendapatkan 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

    Janji<number>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

• getKeys

  void

  Janji Chrome 130 dan yang lebih baru

  Mendapatkan semua kunci dari penyimpanan.

  Fungsi getKeys akan terlihat seperti ini:

  (callback?: function) => {...}

  • callback

    fungsi opsional

    Parameter callback terlihat seperti:

    (keys: string[]) => void

    • kunci

      string[]

      Array dengan kunci yang dibaca dari penyimpanan.

  • akan menampilkan

    Promise<string[]>

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

• hapus

  void

  Promise

  Menghapus satu atau beberapa item dari penyimpanan.

  Fungsi remove akan terlihat seperti ini:

  (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 ini:

    () => void

  • akan menampilkan

    Promise<void>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

• set

  void

  Janji

  Menetapkan beberapa item.

  Fungsi set terlihat seperti:

  (items: object, callback?: function) => {...}

  • item

    objek

    Objek yang memberikan setiap pasangan nilai kunci untuk memperbarui penyimpanan. Pasangan kunci/nilai lainnya dalam penyimpanan tidak akan terpengaruh.

    Nilai primitif 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 ini:

    () => void

  • akan menampilkan

    Promise<void>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

• setAccessLevel

  void

  Janji Chrome 102 dan yang lebih baru

  Menetapkan tingkat akses yang diinginkan untuk area penyimpanan. Secara default, hanya konteks tepercaya yang akan digunakan.

  Fungsi setAccessLevel terlihat seperti:

  (accessOptions: object, callback?: function) => {...}

  • accessOptions

    objek

    • accessLevel

      AccessLevel

      Tingkat akses area penyimpanan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini:

    () => void

  • akan menampilkan

    Promise<void>

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

StorageChange

Properti

• newValue

  apa pun 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 (dalam byte) data yang dapat disimpan di penyimpanan lokal, seperti yang diukur dengan stringifikasi JSON dari 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 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

StorageArea

session

Chrome 102+ MV3+

Item di area penyimpanan session disimpan di dalam memori dan tidak akan dipertahankan di disk.

Jenis

StorageArea & objek

Properti

• QUOTA_BYTES

  10485760
  

  Jumlah maksimum (dalam byte) data yang dapat disimpan dalam memori, seperti 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 segera 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

  1.800
  

  Jumlah maksimum operasi set, remove, atau clear yang dapat dilakukan setiap jam. Batas ini adalah 1 setiap 2 detik, batas yang lebih rendah daripada batas operasi tulis per menit yang lebih tinggi dalam jangka pendek.

  Update yang akan menyebabkan batas ini terlampaui akan segera 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. Nilai ini adalah 2 per detik, yang memberikan throughput lebih tinggi daripada operasi tulis per jam selama 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 dalam penyimpanan sinkronisasi, yang diukur dengan stringifikasi JSON setiap nilai ditambah panjang setiap kunci. Update yang akan menyebabkan batas ini terlampaui akan segera gagal dan menetapkan runtime.lastError saat menggunakan callback, atau saat Promise ditolak.

• QUOTA_BYTES_PER_ITEM

  8192
  

  Ukuran maksimum (dalam byte) setiap item dalam penyimpanan sinkronisasi, seperti 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