chrome.storage

refresh date: 2026-09-25 robots: noindex

Açıklama

Kullanıcı verilerini depolamak, almak ve verilerde yapılan değişiklikleri izlemek için chrome.storage API'yi kullanın.

İzinler

storage

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 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 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 önerilmez:

  • Uzantının hizmet çalışanı Storage adresine erişemiyor.
  • İçerik komut dosyaları, depolama alanını ana makine sayfasıyla paylaşır.
  • Storage arayüzü 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. Dönüşüm rutini ve [onMessage][on-message] işleyici içeren bir ekran dışı doküman oluşturun.
  2. Ekran dışı bir dokümana dönüşüm rutini ekleyin.
  3. Uzantı hizmet çalışanında verileriniz için chrome.storage simgesini kontrol edin.
  4. Verileriniz bulunamazsa ekran dışı bir doküman [oluşturun][create-offscreen] ve dönüşüm rutinini başlatmak için [sendMessage()][send-message] 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][storage-and-cookies] makalesine göz atın.

Depolama alanları

Storage API, aşağıdaki dört gruba ("depolama alanları") ayrılmıştı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 büyük miktarlarda veri depolamak için bu seçeneği kullanabilirsiniz.
storage.sync
Senkronizasyon etkinse veriler, kullanıcının giriş yaptığı tüm Chrome tarayıcılarla 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 bu ayarı kullanabilirsiniz.
storage.session
Verileri tarayıcı oturumu süresince bellekte tutar. Varsayılan olarak içerik komut dosyalarına gösterilmez ancak bu davranış chrome.storage.session.setAccessLevel() ayarlanarak değiştirilebilir. Kota sınırı yaklaşık 10 MB'tır. Hizmet çalışanı çalıştırmaları genelinde global değişkenleri depolamak için bu API'yi kullanabilirsiniz.
storage.managed
Yöneticiler, yönetilen bir ortamda destekleyici bir uzantının ayarlarını yapılandırmak için şema ve kurumsal politikaları kullanabilir. Bu depolama alanı salt okunur.

Manifest

Storage API'yi kullanmak için uzantı manifest dosyasında "storage" iznini belirtin. Ö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 kısıtlama sınırları

Storage API'ye veri eklemeyi, büyük bir kamyona eşya yüklemek gibi düşünmeyin. Depolama alanına ekleme yapmayı, bir boruya bir şey koymak gibi düşünebilirsiniz. Boruda zaten malzeme olabilir ve hatta boru dolu olabilir. Depolama alanına eklediğiniz verilerin kaydedilmesi her zaman biraz zaman alır.

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.

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

Depolama alanında 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, ş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 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;
  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

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 = 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 birini inceleyin:

Türler

AccessLevel

Chrome 102 ve sonraki sürümler

Depolama alanının erişim düzeyi.

Enum

"TRUSTED_CONTEXTS"
Uzantının kendisinden kaynaklanan bağlamları belirtir.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Uzantının dışından kaynaklanan bağlamları belirtir.

StorageChange

Özellikler

  • newValue

    isteğe bağlı

    Öğenin yeni değeri (yeni bir değer varsa).

  • oldValue

    isteğe bağlı

    Öğenin eski değeri (varsa).

Özellikler

local

local depolama alanındaki öğeler her makineye özeldir.

Tür

StorageArea ve nesne

Özellikler

  • QUOTA_BYTES

    10485760

    Yerel depolama alanında depolanabilecek maksimum veri miktarı (bayt cinsinden). Bu miktar, her değerin JSON dizeleştirmesi ve her anahtarın uzunluğu ölçülerek hesaplanır. Uzantı unlimitedStorage iznine sahipse bu değer yoksayılır. Bu sınırın aşılmasına neden olacak güncellemeler hemen başarısız olur ve geri çağırma kullanılıyorsa runtime.lastError değerini, async/await kullanılıyorsa reddedilen bir Promise değerini ayarlar.

managed

managed depolama alanındaki öğeler, alan yöneticisi tarafından yapılandırılan bir kurumsal politika tarafından ayarlanır ve uzantı için salt okunurdur. Bu ad alanını değiştirmeye çalışmak hataya neden olur. Politika yapılandırma hakkında bilgi edinmek için Depolama alanları için manifest başlıklı makaleyi inceleyin.

Tür

StorageArea

sync

sync depolama alanındaki öğeler Chrome Senkronizasyonu kullanılarak senkronize edilir.

Tür

StorageArea ve nesne

Özellikler

  • MAX_ITEMS

    512

    Senkronizasyon depolama alanında saklanabilecek maksimum öğe sayısı. Bu sınırın aşılmasına neden olacak güncellemeler hemen başarısız olur ve geri çağırma kullanılırken veya bir Promise reddedildiğinde runtime.lastError değerini ayarlar.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Kullanımdan kaldırıldı

    storage.sync API'nin artık sürekli yazma işlemi kotası yoktur.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    Her saat gerçekleştirilebilecek maksimum set, remove veya clear işlemi sayısı. Bu, her 2 saniyede 1 yazma işlemine karşılık gelir ve kısa vadeli daha yüksek dakika başına yazma sınırından daha düşük bir üst sınırdır.

    Bu sınırın aşılmasına neden olacak güncellemeler hemen başarısız olur ve geri çağırma kullanıldığında veya bir Promise reddedildiğinde runtime.lastError değerini ayarlar.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Her dakika gerçekleştirilebilecek maksimum set, remove veya clear işlemi sayısı. Bu sınır saniyede 2'dir ve daha kısa bir süre içinde saat başına yazma işleminden daha yüksek işleme hızı sağlar.

    Bu sınırın aşılmasına neden olacak güncellemeler hemen başarısız olur ve geri çağırma kullanıldığında veya bir Promise reddedildiğinde runtime.lastError değerini ayarlar.

  • QUOTA_BYTES

    102400

    Senkronizasyon depolama alanında depolanabilecek maksimum toplam veri miktarı (bayt cinsinden). Bu miktar, her değerin JSON dizeleştirmesi ve her anahtarın uzunluğu ile ölçülür. Bu sınırın aşılmasına neden olacak güncellemeler hemen başarısız olur ve geri çağırma kullanıldığında veya bir Promise reddedildiğinde runtime.lastError değerini ayarlar.

  • QUOTA_BYTES_PER_ITEM

    8192

    Senkronizasyon depolama alanındaki her bir öğenin maksimum boyutu (bayt cinsinden). Bu boyut, değerinin JSON dizeleştirmesi ve anahtar uzunluğu ile ölçülür. Bu sınırdan daha büyük öğeler içeren güncellemeler hemen başarısız olur ve geri çağırma kullanıldığında veya bir Promise reddedildiğinde runtime.lastError değerini ayarlar.

Etkinlikler

onChanged

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

Bir veya daha fazla öğe değiştiğinde tetiklenir.

Parametreler

  • callback

    işlev

    callback parametresi şu şekilde görünür: 

    (changes: object, areaName: string) => void

    • değişiklikler

      nesne

    • areaName

      dize