chrome.storage

refresh date: 2026-09-25 robots: noindex

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 mirip dengan API penyimpanan platform web (IndexedDB, dan Storage), tetapi dirancang untuk memenuhi kebutuhan penyimpanan ekstensi. Berikut adalah beberapa fitur utamanya:

  • Semua konteks ekstensi, termasuk skrip konten dan pekerja layanan ekstensi, 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.

Meskipun ekstensi dapat menggunakan antarmuka [Storage][mdn-storage] (dapat diakses dari window.localStorage) dalam beberapa konteks (pop-up dan halaman HTML lainnya), hal ini tidak direkomendasikan karena alasan berikut:

  • Service worker ekstensi tidak dapat mengakses Storage.
  • Skrip konten berbagi penyimpanan dengan halaman host.
  • Data yang disimpan menggunakan antarmuka Storage akan hilang saat pengguna menghapus histori penjelajahannya.

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

  1. Buat dokumen di luar 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 data Anda.
  4. Jika data Anda tidak ditemukan, [buat][create-offscreen] dokumen di luar layar dan panggil [sendMessage()][send-message] untuk memulai rutinitas konversi.
  5. Di dalam pengendali onMessage dokumen di luar layar, panggil rutinitas konversi.

Ada juga beberapa perbedaan dalam cara kerja API penyimpanan web di ekstensi. Pelajari lebih lanjut di artikel [Penyimpanan dan Cookie][storage-and-cookies].

Area penyimpanan

Storage API dibagi menjadi empat bucket ("area penyimpanan") berikut:

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 guna menyimpan data dalam jumlah yang lebih besar.
storage.sync
Jika sinkronisasi diaktifkan, data akan disinkronkan ke browser Chrome mana pun yang digunakan pengguna untuk login. Jika dinonaktifkan, kebijakan ini akan berperilaku seperti storage.local. Chrome menyimpan data secara lokal saat browser offline dan melanjutkan sinkronisasi saat kembali online. Batasan kuota adalah sekitar 100 KB, 8 KB per item. Sebaiknya gunakan API ini untuk mempertahankan setelan pengguna di seluruh browser yang disinkronkan.
storage.session
Menyimpan data dalam memori selama durasi sesi browser. Secara default, API ini tidak diekspos ke skrip konten, tetapi perilaku ini dapat diubah dengan menyetel chrome.storage.session.setAccessLevel(). Batasan kuotanya adalah sekitar 10 MB. Pertimbangkan untuk menggunakannya guna menyimpan variabel global di seluruh eksekusi pekerja layanan.
storage.managed
Administrator dapat menggunakan skema dan kebijakan Enterprise untuk mengonfigurasi setelan ekstensi pendukung di lingkungan terkelola. Area penyimpanan ini bersifat hanya baca.

Manifes

Untuk menggunakan storage API, deklarasikan izin "storage" di 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 menambahkan data ke Storage API seperti memasukkan barang ke dalam truk besar. Anggaplah menambahkan ke penyimpanan seperti memasukkan sesuatu ke dalam pipa. Pipa mungkin sudah berisi material, dan bahkan mungkin sudah penuh. Selalu asumsikan adanya penundaan antara saat Anda menambahkan ke penyimpanan dan saat data tersebut benar-benar dicatat.

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 update penyimpanan

Untuk melacak perubahan yang dilakukan pada penyimpanan, Anda dapat menambahkan pemroses ke peristiwa onChanged-nya. Jika ada perubahan di penyimpanan, peristiwa tersebut akan diaktifkan. Kode contoh memproses perubahan berikut:

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 jauh lagi. Dalam contoh ini, kita memiliki halaman opsi yang memungkinkan pengguna mengaktifkan/menonaktifkan "mode debug" (implementasi tidak ditampilkan di sini). Halaman opsi akan langsung menyimpan setelan baru ke storage.sync, dan pekerja layanan akan 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 peristiwa. 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);
});

Contoh ekstensi

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.

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 komputer.

Jenis

StorageArea & objek

Properti

  • QUOTA_BYTES

    10485760

    Jumlah maksimum (dalam byte) data yang dapat disimpan di penyimpanan lokal, 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 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

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. Ini 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. Ini adalah 2 per detik, yang memberikan throughput lebih tinggi daripada penulisan 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 dari 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 individual dalam penyimpanan sinkronisasi, yang diukur dengan stringifikasi JSON dari 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