Halaman ini diterjemahkan oleh Cloud Translation API.

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

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:

Buat dokumen di balik layar dengan rutin konversi dan handler [onMessage][on-message].
Menambahkan rutin konversi ke dokumen di luar layar.
Di pemeriksaan pekerja layanan ekstensi, chrome.storage untuk data Anda.
Jika data Anda tidak ditemukan, [buat][create-offscreen] dokumen di luar layar dan panggil [sendMessage()][send-message] untuk memulai rutin konversi.
Di dalam handler onMessage dokumen di balik layar, panggil rutin konversi.

Ada juga beberapa nuansa terkait 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 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 tempat pengguna 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. Pertimbangkan untuk menggunakannya guna mempertahankan setelan pengguna di seluruh browser yang disinkronkan.

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

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 kuota sekitar 10 MB. Pertimbangkan untuk menggunakannya guna menyimpan variabel global di seluruh proses 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 pembatasan

Jangan menganggap penambahan ke Storage API seperti memasukkan barang ke dalam truk besar. Bayangkan menambahkan ke penyimpanan seperti memasukkan sesuatu ke dalam pipa. Pipa mungkin sudah berisi material di dalamnya, dan bahkan mungkin sudah terisi penuh. Selalu asumsikan adanya jeda 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 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, Anda dapat menambahkan 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" (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);
  }
});

Pemuatan awal asinkron dari penyimpanan

Karena service worker tidak selalu berjalan, ekstensi Manifes V3 terkadang perlu memuat data dari penyimpanan secara asinkron sebelum mengeksekusi handler 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);
});

Contoh ekstensi

Untuk melihat demo lain dari Storage API, 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

Event<functionvoidvoid>

Chrome 73+

Diaktifkan saat satu atau beberapa item berubah.

Fungsi onChanged.addListener akan terlihat seperti:
```
(callback: function) => {...}
```
- callback
  
  fungsi
  
  Parameter callback terlihat seperti:
```
(changes: object) => void
```
  - perubahan
    
    objek
hapus

void

Janji

Menghapus semua item dari penyimpanan.

Fungsi clear akan terlihat seperti:
```
(callback?: function) => {...}
```
- callback
  
  fungsi opsional
  
  Parameter callback terlihat seperti:
```
() => void
```
- return
  Promise<void>
  
  Chrome 95+
  
  Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.
get

void

Janji

Mendapatkan satu atau beberapa item dari penyimpanan.

Fungsi get akan terlihat seperti:
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- kunci
  
  string | string[] | object 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.
- return
  Promise<object>
  
  Chrome 95+
  
  Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.
getBytesInUse

void

Janji

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

Fungsi getBytesInUse akan 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.
- return
  Promise<number>
  
  Chrome 95+
  
  Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.
getKeys

void

Promise Chrome 130+

Mendapatkan semua kunci dari penyimpanan.

Fungsi getKeys akan terlihat seperti:
```
(callback?: function) => {...}
```
- callback
  
  fungsi opsional
  
  Parameter callback terlihat seperti:
```
(keys: string[]) => void
```
  - kunci
    
    string[]
    
    Array dengan kunci yang dibaca dari penyimpanan.
- return
  Promise<string[]>
  
  Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.
hapus

void

Janji

Menghapus satu atau beberapa item dari penyimpanan.

Fungsi remove akan 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
```
- return
  Promise<void>
  
  Chrome 95+
  
  Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.
tetapkan

void

Janji

Menetapkan beberapa item.

Fungsi set akan terlihat seperti:
```
(items: object, callback?: function) => {...}
```
- item
  
  objek
  
  Objek yang memberikan setiap key-value pair untuk memperbarui penyimpanan. Pasangan nilai/kunci 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 {}, kecuali Array (diserialisasi seperti yang diharapkan), Date, dan Regex (diserialisasi menggunakan representasi String-nya).
- callback
  
  fungsi opsional
  
  Parameter callback terlihat seperti:
```
() => void
```
- return
  Promise<void>
  
  Chrome 95+
  
  Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.
setAccessLevel

void

Promise Chrome 102+

Menetapkan tingkat akses yang diinginkan untuk area penyimpanan. Secara default, penyimpanan session dibatasi untuk konteks tepercaya (halaman ekstensi dan pekerja layanan), sementara penyimpanan managed, local, dan sync mengizinkan akses dari konteks tepercaya dan tidak tepercaya.

Fungsi setAccessLevel akan terlihat seperti:
```
(accessOptions: object, callback?: function) => {...}
```
- accessOptions
  
  objek
  - accessLevel
    
    AccessLevel
    
    Tingkat akses area penyimpanan.
- callback
  
  fungsi opsional
  
  Parameter callback terlihat seperti:
```
() => void
```
- return
  Promise<void>
  
  Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan 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 data (dalam byte) yang dapat disimpan di penyimpanan lokal, sebagaimana diukur oleh 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. Nilainya adalah 1 setiap 2 detik, yang merupakan batas atas 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, sebagaimana diukur oleh 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 individual dalam penyimpanan sinkron, sebagaimana diukur oleh 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

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

Deskripsi

Izin

Ringkasan

Area penyimpanan

Manifes

Penggunaan

storage.local

storage.sync

storage.session

Batas penyimpanan dan pembatasan

Kasus penggunaan

Respons sinkron terhadap update penyimpanan

Pemuatan awal asinkron dari penyimpanan

Contoh ekstensi

Jenis

AccessLevel

Enum

StorageArea

Properti

StorageChange

Properti

Properti

local

Jenis

Properti

managed

Jenis

sync

Jenis

Properti

Acara

onChanged

Parameter

chrome.storage