browser.storage

Açıklama

İzinler

Storage API'yi kullanmak için uzantı manifest dosyasında "storage" iznini belirtin. Örneğin:

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

Örnekler

Aşağıdaki örneklerde local, sync ve session depolama alanları gösterilmektedir:

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

Storage API'nin diğer demolarını görmek için aşağıdaki örnekleri inceleyin:

• Global arama uzantısı.
• Su alarmı uzantısı.

Kavramlar ve kullanım

Storage API, kullanıcı verilerini ve durumunu kalıcı hale getirmek için uzantıya özel bir yöntem sunar. Web platformunun depolama alanı API'lerine (IndexedDB ve Storage) benzer ancak uzantıların depolama alanı ihtiyaçlarını karşılayacak şekilde tasarlanmıştır. Aşağıda, temel özelliklerden bazıları verilmiştir:

• Uzantı hizmet çalışanı ve içerik komut dosyaları dahil olmak üzere tüm uzantı bağlamları, Storage API'ye erişebilir.
• JSON ile serileştirilebilir değerler, nesne özellikleri olarak depolanır.
• Storage API, toplu okuma ve yazma işlemleriyle eşzamansızdır.
• Kullanıcı önbelleği ve tarama geçmişini temizlese bile veriler kalır.
• Saklanan ayarlar, bölünmüş gizli mod kullanılırken bile geçerliliğini korur.
• Kurumsal politikalar için özel bir salt okunur yönetilen depolama alanı içerir.

Uzantılar, web depolama alanı API'lerini kullanabilir mi?

Uzantılar bazı bağlamlarda (pop-up ve diğer HTML sayfaları) Storage arayüzünü (window.localStorage üzerinden erişilebilir) kullanabilse de aşağıdaki nedenlerden dolayı bunu önermiyoruz:

• Uzantı hizmet çalışanları, Web Storage API'yi kullanamaz.
• İçerik komut dosyaları, depolama alanını ana makine sayfasıyla paylaşır.
• Web Storage API kullanılarak kaydedilen veriler, kullanıcı tarama geçmişini temizlediğinde kaybolur.

Verileri web depolama alanı API'lerinden bir hizmet çalışanının uzantı depolama alanı API'lerine taşımak için:

1. Ekran dışı belge HTML sayfası ve komut dosyası hazırlayın. Komut dosyası, bir dönüşüm rutini ve bir onMessage işleyici içermelidir.
2. Uzantı hizmet çalışanında verileriniz için browser.storage değerini kontrol edin.
3. Verileriniz bulunamazsa createDocument() numaralı telefonu arayın.
4. Döndürülen Promise çözümlendikten sonra dönüşüm rutinini başlatmak için sendMessage() yöntemini çağırın.
5. Ekran dışı dokümanın onMessage işleyicisinde dönüşüm rutinini çağırın.

Web Storage API'lerin uzantılarda çalışma şekliyle ilgili bazı farklılıklar da vardır. Daha fazla bilgi için Depolama ve Çerezler makalesini inceleyin.

Depolama alanı ve kısıtlama sınırları

Storage API'nin kullanım sınırlamaları vardır:

• Veri depolamanın performans maliyetleri vardır ve API'de depolama alanı kotaları bulunur. Depolama alanını korumak için depolamayı planladığınız verileri planlayın.
• Depolama işleminin tamamlanması biraz zaman alabilir. Kodunuzu bu süreyi hesaba katacak şekilde yapılandırın.

Depolama alanı sınırlamaları ve bu sınırlamalar aşıldığında ne olacağı hakkında ayrıntılı bilgi için sync, local ve session ile ilgili kota bilgilerini inceleyin.

Depolama alanları

Storage API, aşağıdaki depolama alanlarına ayrılmıştır:

Yerel

Veriler yerel olarak depolanır ve uzantı kaldırıldığında silinir. Depolama alanı sınırı 10 MB'tır (Chrome 113 ve önceki sürümlerde 5 MB) ancak "unlimitedStorage" izni istenerek artırılabilir. Daha büyük miktarlarda veri depolamak için storage.local kullanmanızı öneririz. Varsayılan olarak içerik komut dosyalarına gösterilir ancak bu davranış browser.storage.local.setAccessLevel() çağrılarak değiştirilebilir.

Yönetilen

Yönetilen depolama alanı, politikayla yüklenen uzantılar için salt okunurdur. Geliştirici tarafından tanımlanan bir şema ve kurumsal politikalar kullanılarak sistem yöneticileri tarafından yönetilir. Politikalar seçeneklere benzer ancak kullanıcı yerine sistem yöneticisi tarafından yapılandırılır. Bu sayede uzantı, bir kuruluştaki tüm kullanıcılar için önceden yapılandırılabilir.

Varsayılan olarak storage.managed, içerik komut dosyalarına gösterilir ancak bu davranış browser.storage.managed.setAccessLevel() çağrılarak değiştirilebilir. Politikalar hakkında bilgi edinmek için Yöneticiler İçin Belgeler başlıklı makaleyi inceleyin. managed depolama alanı hakkında daha fazla bilgi edinmek için Depolama alanları için manifest başlıklı makaleyi inceleyin.

Oturum

Oturum depolama alanı, bir uzantı yüklüyken verileri bellekte tutar. Uzantı devre dışı bırakılırsa, yeniden yüklenirse, güncellenirse ve tarayıcı yeniden başlatılırsa depolama alanı temizlenir. Varsayılan olarak içerik komut dosyalarına gösterilmez ancak bu davranış browser.storage.session.setAccessLevel() çağrılarak değiştirilebilir. Depolama alanı sınırı 10 MB'tır (Chrome 111 ve önceki sürümlerde 1 MB).

storage.session arayüzü, hizmet çalışanları için önerdiğimiz birkaç arayüzden biridir.

Sync

Kullanıcı senkronizasyonu etkinleştirirse veriler, kullanıcının giriş yaptığı her Chrome tarayıcıyla senkronize edilir. Devre dışı bırakılırsa storage.local gibi davranır. Chrome, tarayıcı çevrimdışıyken verileri yerel olarak depolar ve tekrar çevrimiçi olduğunda senkronizasyona devam eder. Kota sınırlaması yaklaşık 100 KB'tır (öğe başına 8 KB).

Kullanıcı ayarlarını senkronize edilen tarayıcılarda korumak için storage.sync kullanmanızı öneririz. Hassas kullanıcı verileriyle çalışıyorsanız storage.session kullanın. Varsayılan olarak storage.sync, içerik komut dosyalarına gösterilir ancak bu davranış browser.storage.sync.setAccessLevel() çağrılarak değiştirilebilir.

Yöntemler ve etkinlikler

Tüm depolama alanları StorageArea arayüzünü uygular.

get()

get() yöntemi, bir StorageArea öğesinden bir veya daha fazla anahtarı okumanıza olanak tanır.

getBytesInUse()

getBytesInUse() yöntemi, bir StorageArea tarafından kullanılan kotayı görmenizi sağlar.

getKeys()

getKeys() yöntemi, bir StorageArea içinde depolanan tüm anahtarları almanızı sağlar.

remove()

remove() yöntemi, bir öğeyi StorageArea öğesinden kaldırmanıza olanak tanır.

set()

set() yöntemi, StorageArea içinde bir öğe ayarlamanıza olanak tanır.

setAccessLevel()

setAccessLevel() yöntemi, bir StorageArea için erişimi kontrol etmenizi sağlar.

clear()

clear() yöntemi, bir StorageArea içindeki tüm verileri temizlemenize olanak tanır.

onChanged

onChanged etkinliği, StorageArea üzerinde yapılan değişiklikleri izlemenize olanak tanır.

Kullanım alanları

Aşağıdaki bölümlerde, Storage API'nin yaygın kullanım alanları gösterilmektedir.

Depolama alanı güncellemelerine yanıt verme

Depolama alanında yapılan değişiklikleri izlemek için onChanged etkinliğine bir dinleyici ekleyin. Depolama alanında herhangi bir değişiklik olduğunda bu etkinlik tetiklenir. Örnek kod, şu değişiklikleri dinler:

background.js:

browser.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}".`
    );
  }
});

Bu fikri daha da ileriye taşıyabiliriz. Bu örnekte, kullanıcının "hata ayıklama modunu" açıp kapatmasına olanak tanıyan bir seçenekler sayfamız var (uygulama burada gösterilmemiştir). Seçenekler sayfası, yeni ayarları hemen storage.sync konumuna kaydeder ve hizmet çalışanı, ayarı mümkün olan en kısa sürede uygulamak için storage.onChanged kullanır.

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;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.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
browser.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);
  }
});

Depolama alanından eşzamansız önceden yükleme

Hizmet çalışanları her zaman çalışmadığından Manifest V3 uzantılarının bazen etkinlik işleyicilerini yürütmeden önce depolama alanından verileri eşzamansız olarak yüklemesi gerekir. Bunu yapmak için aşağıdaki snippet, mantığını yürütmeden önce storageCache globalinin doldurulmasını bekleyen eşzamansız bir action.onClicked etkinlik işleyici kullanır.

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 = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.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;
  browser.storage.sync.set(storageCache);
});

Geliştirici Araçları

API kullanılarak depolanan verileri Geliştirici Araçları'nda görüntüleyebilir ve düzenleyebilirsiniz. Daha fazla bilgi edinmek için Geliştirici Araçları belgelerindeki Uzantı depolama alanını görüntüleme ve düzenleme sayfasını inceleyin.

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