chrome.storage

Açıklama

İzinler

Depolama API'sini kullanmak için uzantı manifest dosyasında "storage" iznini bildirin. Örneğin:

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

Örnekler

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

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);
});

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);
});

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Storage API'nin diğer demolarını görmek için aşağıdaki örneklerden herhangi birini 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 özgü bir yöntem sunar. Web platformunun depolama API'lerine (IndexedDB ve Storage) benzer ancak uzantıların depolama ihtiyaçlarını karşılayacak şekilde tasarlanmıştır. Temel özelliklerden bazıları şunlardır:

• Uzantı hizmet çalışanı ve içerik komut dosyaları da dahil olmak üzere tüm uzantı bağlamları, Storage API'ye erişebilir.
• JSON'a dönüştürülebilir 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ıcı olur.
• Depolanan ayarlar, bölünmüş gizli mod kullanılırken bile korunur.
• Kurumsal politikalar için özel bir salt okunur yönetilen depolama alanı içerir.

Uzantılar web depolama 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ı hizmeti ç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 hizmet çalışanından web depolama API'lerinden uzantı depolama API'lerine taşımak için:

1. Ekran dışı bir doküman HTML sayfası ve komut dosyası hazırlayın. Komut dosyası, bir dönüştürme rutini ve bir onMessage işleyici içermelidir.
2. Uzantı hizmeti çalışanında verilerinizi chrome.storage ile kontrol edin.
3. Verileriniz bulunamazsa createDocument() numaralı telefonu arayın.
4. Döndürülen Promise çözüldükten sonra, dönüştürme rutinini başlatmak için sendMessage() işlevini çağırın.
5. Ekran dışı dokümanın onMessage işleyicisinde dönüştürme rutinini çağırın.

Web depolama API'lerinin uzantılarda işleyiş şekliyle ilgili bazı nüanslar da vardır. Daha fazla bilgiyi Depolama ve Çerezler makalesinde bulabilirsiniz.

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 kotaları bulunur. Depolama alanını korumak için depolamayı planladığınız verileri belirleyin.
• Depolama işleminin tamamlanması 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 bilgilerine bakın.

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 temizlenir. Depolama alanı sınırı 10 MB'tır (Chrome 113 ve önceki sürümlerde 5 MB). Ancak "unlimitedStorage" izni istenerek bu sınır artırılabilir. Daha büyük miktarda veri depolamak için storage.local kullanmanızı öneririz. Varsayılan olarak içerik komut dosyalarına sunulur ancak bu davranış chrome.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 bir 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.

storage.managed, varsayılan olarak içerik komut dosyalarına sunulur ancak bu davranış chrome.storage.managed.setAccessLevel() çağrılarak değiştirilebilir. Politikalar hakkında bilgi edinmek için Yöneticiler için Dokümanlar 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 depolaması, bir uzantı yüklendiğinde 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 sunulmaz ancak bu davranış chrome.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ü, service worker'lar için önerdiğimiz birkaç arayüzden biridir.

Sync

Kullanıcı senkronizasyonu etkinleştirirse veriler, kullanıcının oturum açtığı 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).

Senkronize edilen tarayıcılarda kullanıcı ayarlarını korumak için storage.sync kullanmanızı öneririz. Hassas kullanıcı verileriyle çalışıyorsanız bunun yerine storage.session kullanın. storage.sync, varsayılan olarak içerik komut dosyalarına sunulur ancak bu davranış chrome.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 içindeki bir veya daha fazla anahtarı okumanıza olanak tanır.

getBytesInUse()

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

getKeys()

getKeys() yöntemi, StorageArea içinde depolanan tüm anahtarları almanıza olanak tanır.

remove()

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

set()

set() yöntemi, bir öğeyi StorageArea içine yerleştirmenize olanak tanır.

setAccessLevel()

setAccessLevel() yöntemi, StorageArea erişimini kontrol etmenizi sağlar.

clear()

clear() yöntemi, StorageArea cihazındaki tüm verileri temizlemenize olanak tanır.

onChanged

onChanged etkinliği, StorageArea ile ilgili değişiklikleri izlemenizi sağlar.

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:

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

Bu fikri daha da ileriye taşıyabiliriz. Bu örnekte, kullanıcının "hata ayıklama modu"nu etkinleştirmesine olanak tanıyan bir seçenekler sayfası var (uygulama burada gösterilmemiştir). Seçenekler sayfası, yeni ayarları hemen storage.sync konumuna kaydeder ve servis çalışanı, ayarı en kısa sürede uygulamak için storage.onChanged konumunu 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;
  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);
  }
});

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

Service worker'lar 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 genel değişkeninin doldurulmasını bekleyen eşzamansız bir action.onClicked etkinlik işleyicisi 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 = 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);
});

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ına bakın.

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