chrome.storage

refresh date: 2026-09-25 robots: noindex

Açıklama

İzinler

Genel Bakış

Storage API, kullanıcı verilerini ve durumunu kalıcı hale getirmek için uzantıya özel bir yöntem sunar. Web platformunun depolama API'lerine (IndexedDB ve Storage) benzer ancak uzantıların depolama ihtiyaçlarını karşılamak için tasarlanmıştır. Bazı temel özellikler ş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ır.
• Depolanan ayarlar, bölünmüş gizli mod kullanılırken bile kalıcı olur.
• Kurumsal politikalar için özel bir salt okunur yönetilen depolama alanı içerir.

Uzantılar bazı bağlamlarda (pop-up ve diğer HTML sayfaları) [Storage][mdn-storage] arayüzünü (window.localStorage üzerinden erişilebilir) kullanabilse de aşağıdaki nedenlerden dolayı bu arayüzün kullanılması önerilmez:

• Uzantının hizmet çalışanı Storage adresine erişemiyor.
• İçerik komut dosyaları, ana makine sayfasıyla depolama alanını paylaşır.
• Storage arayüzü 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. Dönüşüm rutini ve [onMessage][on-message] işleyicisi içeren bir ekran dışı doküman oluşturun.
2. Ekran dışında kalan bir dokümana dönüşüm rutini ekleyin.
3. Uzantı hizmeti çalışanı kontrolünde verileriniz için chrome.storage simgesini bulun.
4. Verileriniz bulunamazsa [create][create-offscreen] ekran dışı bir doküman oluşturun ve dönüştürme rutinini başlatmak için [sendMessage()][send-message] işlevini çağırın.
5. Ekran dışı belgenin onMessage işleyicisinde dönüştürme yordamını ç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][storage-and-cookies] makalesinde bulabilirsiniz.

Depolama alanları

Storage API aşağıdaki dört pakete ("depolama alanları") ayrılır:

storage.local

Veriler yerel olarak depolanır ve uzantı kaldırıldığında temizlenir. Kota sınırlaması yaklaşık 10 MB'tır ancak "unlimitedStorage" izni istenerek artırılabilir. Daha fazla miktarda veri depolamak için kullanabilirsiniz.

storage.sync

Senkronizasyon etkinse veriler, kullanıcının oturum açtığı tüm Chrome tarayıcılarla senkronize edilir. Devre dışı bırakılırsa storage.local gibi davranır. Chrome, tarayıcı çevrimdışı olduğunda verileri yerel olarak depolar ve tekrar internete bağlandığında senkronizasyonu devam ettirir. Kota sınırlaması yaklaşık 100 KB, öğe başına 8 KB'tır. Senkronize edilen tarayıcılarda kullanıcı ayarlarını korumak için bu ayarı kullanabilirsiniz.

storage.session

Verileri tarayıcı oturumu süresince bellekte tutar. Varsayılan olarak içerik komut dosyalarına sunulmaz ancak bu davranış chrome.storage.session.setAccessLevel() ayarlanarak değiştirilebilir. Kota sınırlaması yaklaşık 10 MB'tır. Hizmet çalışanı çalıştırmaları arasında genel değişkenleri depolamak için kullanabilirsiniz.

storage.managed

Yöneticiler, yönetilen bir ortamda destekleyici bir uzantının ayarlarını yapılandırmak için şema ve kuruluş politikalarını kullanabilir. Bu depolama alanı salt okunurdur.

Manifest

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

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

Kullanım

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

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

managed depolama alanı hakkında daha fazla bilgi edinmek için Depolama alanları için manifest başlıklı makaleyi inceleyin.

Depolama alanı ve sıklık sınırlaması

Storage API'ye ekleme işlemini büyük bir kamyona eşya koyma olarak düşünmeyin. Depolama alanına ekleme işlemini bir boruya bir şey koymaya benzetebiliriz. Borunun içinde malzeme olabilir ve hatta boru dolu olabilir. Depolama alanına ekleme ile kaydın yapılması arasında her zaman bir gecikme olduğunu varsayı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.

Kullanım alanları

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

Depolama alanı güncellemelerine eşzamanlı yanıt

Depolamada yapılan değişiklikleri izlemek için onChanged etkinliğine bir dinleyici ekleyebilirsiniz. Depolama alanında herhangi bir değişiklik olduğunda bu etkinlik tetiklenir. Örnek kod, aşağıdaki 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 açıp kapatmasına olanak tanıyan bir seçenekler sayfası var (burada uygulama gösterilmemiştir). Seçenekler sayfası, yeni ayarları hemen storage.sync konumuna kaydeder ve hizmet ç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 depolamadan 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 bir eş zamansız 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);
});

Uzantı örnekleri

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

• Küresel arama uzantısı
• Su alarmı uzantısı.

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