chrome.storage

Açıklama

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

İzinler

storage

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

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

Kavramlar ve kullanım

Storage API, kullanıcı verilerini ve durumunu kalıcı hale getirmek için uzantıya özgü bir yol sağlar. Web platformunun depolama API'lerine (IndexedDB ve Storage) benzer ancak uzantıların depolama ihtiyaçlarını karşılamak için 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ı, ana makine sayfasıyla depolama alanını 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 bilgi için Depolama ve Çerezler başlıklı makaleyi inceleyin.

Depolama alanları

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

storage.local
Veriler yerel olarak saklanı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.
storage.managed
Yönetilen depolama alanı, politika yüklü uzantılar için salt okunur depolama alanıdır ve 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. 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.
storage.session
Bir uzantı yüklenirken verileri bellekte tutar. Uzantı devre dışı bırakılırsa, yeniden yüklenirse veya güncellenirse ve tarayıcı yeniden başlatıldığında 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ü, servis çalışanları için önerdiğimiz birkaç arayüzden biridir.
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ışıyken verileri yerel olarak depolar ve tekrar çevrimiçi olduğunda senkronizasyona devam eder. Kota sınırı yaklaşık 100 KB, öğe başına 8 KB'tır. 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.

Depolama alanı ve sınırlama sınırları

Storage API'de aşağıdaki kullanım sınırlamaları vardır:

  • Veri depolama genellikle performans maliyetlerine yol açar ve API, depolama kotalarını içerir. Veri depolama özelliğini kaybetmemek için hangi verileri depoladığınıza dikkat etmenizi öneririz.
  • Depolama işleminin tamamlanması zaman alabilir. Kodunuzu bu süreyi hesaba katacak şekilde yapılandırdığınızdan emin olun.

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 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, 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 (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

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.

Örnekler

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

Yerel

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

Sync

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

Oturum

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was 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:

Türler

AccessLevel

Chrome 102 veya daha yeni bir sürüm

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 gelen bağlamları belirtir.

StorageArea

Özellikler

  • onChanged

    Event<functionvoidvoid>

    Chrome 73 veya daha yeni bir sürüm

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

    onChanged.addListener işlevi şu şekilde görünür: 

    (callback: function) => {...}

    • callback

      işlev

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

      (changes: object) => void

      • değişiklikler

        nesne

  • temizle

    geçersiz

    Promise

    Tüm öğeler depolamadan kaldırılır.

    clear işlevi şu şekilde görünür: 

    (callback?: function) => {...}

    • callback

      işlev isteğe bağlı

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

      () => void

    • returns

      Promise<void>

      Chrome 95 veya daha yeni bir sürüm

      Promises, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. İkisini de aynı işlev çağrısında kullanamazsınız. The promise resolves with the same type that is passed to the callback.

  • get

    geçersiz

    Promise

    Depolama alanından bir veya daha fazla öğe alır.

    get işlevi şu şekilde görünür: 

    (keys?: string | string[] | object, callback?: function) => {...}

    • anahtarlar

      dize | dize[] | nesne isteğe bağlı

      Alınacak tek bir anahtar, alınacak anahtar listesi veya varsayılan değerleri belirten bir sözlük (nesnenin açıklamasına bakın). Boş bir liste veya nesne, boş bir sonuç nesnesi döndürür. Depolama alanının tüm içeriğini almak için null değerini iletin.

    • callback

      işlev isteğe bağlı

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

      (items: object) => void

      • items

        nesne

        Anahtar/değer çifti eşlemelerinde öğeler içeren nesne.

    • returns

      Promise<object>

      Chrome 95 veya daha yeni bir sürüm

      Promises, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. İkisini de aynı işlev çağrısında kullanamazsınız. The promise resolves with the same type that is passed to the callback.

  • getBytesInUse

    geçersiz

    Promise

    Bir veya daha fazla öğe tarafından kullanılan alan miktarını (bayt cinsinden) alır.

    getBytesInUse işlevi şu şekilde görünür: 

    (keys?: string | string[], callback?: function) => {...}

    • anahtarlar

      string | string[] isteğe bağlı

      Toplam kullanımını almak için tek bir anahtar veya anahtar listesi. Boş bir liste 0 sonucunu döndürür. Tüm depolama alanının toplam kullanımını almak için null değerini iletin.

    • callback

      işlev isteğe bağlı

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

      (bytesInUse: number) => void

      • bytesInUse

        sayı

        Depolama alanında kullanılan alan miktarı (bayt).

    • returns

      Promise<number>

      Chrome 95 veya daha yeni bir sürüm

      Promises, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. İkisini de aynı işlev çağrısında kullanamazsınız. The promise resolves with the same type that is passed to the callback.

  • getKeys

    geçersiz

    Promise Chrome 130 ve sonraki sürümler

    Depolamadaki tüm anahtarları alır.

    getKeys işlevi şu şekilde görünür: 

    (callback?: function) => {...}

    • callback

      işlev isteğe bağlı

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

      (keys: string[]) => void

      • anahtarlar

        dize[]

        Depolama alanından okunan anahtarlara sahip dizi.

    • returns

      Promise<string[]>

      Promises, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. İkisini de aynı işlev çağrısında kullanamazsınız. The promise resolves with the same type that is passed to the callback.

  • remove

    geçersiz

    Promise

    Depolama alanından bir veya daha fazla öğeyi kaldırır.

    remove işlevi şu şekilde görünür: 

    (keys: string | string[], callback?: function) => {...}

    • anahtarlar

      dize | dize[]

      Kaldırılacak öğeler için tek bir anahtar veya anahtar listesi.

    • callback

      işlev isteğe bağlı

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

      () => void

    • returns

      Promise<void>

      Chrome 95 veya daha yeni bir sürüm

      Promises, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. İkisini de aynı işlev çağrısında kullanamazsınız. The promise resolves with the same type that is passed to the callback.

  • grup

    geçersiz

    Promise

    Birden fazla öğeyi ayarlar.

    set işlevi şu şekilde görünür: 

    (items: object, callback?: function) => {...}

    • items

      nesne

      Depolama alanını güncellemek için her anahtar/değer çiftini veren bir nesne. Depolamadaki diğer anahtar/değer çiftleri etkilenmez.

      Sayılar gibi temel değerler beklendiği gibi serileştirilir. typeof "object" ve "function" içeren değerler genellikle {} olarak serileştirilir. Array (beklendiği gibi serileştirilir), Date ve Regex (String gösterimleriyle serileştirilir) bu kuralın dışındadır.

    • callback

      işlev isteğe bağlı

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

      () => void

    • returns

      Promise<void>

      Chrome 95 veya daha yeni bir sürüm

      Promises, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. İkisini de aynı işlev çağrısında kullanamazsınız. The promise resolves with the same type that is passed to the callback.

  • setAccessLevel

    geçersiz

    Promise Chrome 102 ve sonraki sürümler

    Depolama alanı için istenen erişim düzeyini ayarlar. Varsayılan olarak, session depolama alanı güvenilir bağlamlarla (uzantı sayfaları ve hizmet çalışanları) sınırlıdır. local ve sync depolama alanları ise hem güvenilir hem de güvenilmeyen bağlamlardan erişime izin verir.

    setAccessLevel işlevi şu şekilde görünür: 

    (accessOptions: object, callback?: function) => {...}

    • accessOptions

      nesne

      • accessLevel

        AccessLevel

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

    • callback

      işlev isteğe bağlı

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

      () => void

    • returns

      Promise<void>

      Promises, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. İkisini de aynı işlev çağrısında kullanamazsınız. The promise resolves with the same type that is passed to the callback.

StorageChange

Özellikler

  • newValue

    herhangi bir isteğe bağlı

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

  • oldValue

    herhangi bir 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

    Her değerin JSON dizesi oluşturma işlemi ve her anahtarın uzunluğu ölçülerek yerel depolama alanında depolanabilecek maksimum veri miktarı (bayt cinsinden). Uzantının unlimitedStorage izni varsa 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ırken runtime.lastError, async/await kullanılırken ise reddedilen bir Promise ayarlar.

managed

managed depolama alanındaki öğeler, alan yöneticisi tarafından yapılandırılan bir kuruluş politikasıyla 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

session

Chrome 102+ MV3+

session depolama alanındaki öğeler bellekte depolanır ve diske kalıcı olarak kaydedilmez.

Tür

StorageArea ve nesne

Özellikler

  • QUOTA_BYTES

    10485760

    Her değerin ve anahtarın dinamik olarak ayrılan bellek kullanımı tahmin edilerek ölçülen, bellekte depolanabilecek maksimum veri miktarı (bayt cinsinden). 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 ayarlanır.

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 ayarlanır.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Kullanımdan kaldırıldı

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

  • 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 olmak üzere kısa vadeli daha yüksek yazma işlemi/dakika sınırından daha düşük bir 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ılırken veya bir Promise reddedildiğinde runtime.lastError ayarlanır.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Her dakika gerçekleştirilebilecek maksimum set, remove veya clear işlemi sayısı. Bu değer, saniyede 2 olup daha kısa bir süre içinde saatte yazma işlemine göre 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ılırken veya bir Promise reddedildiğinde runtime.lastError ayarlanır.

  • QUOTA_BYTES

    102400

    Her değerin JSON dizesi oluşturma işlemi ve her anahtarın uzunluğu ölçülerek, senkronizasyon depolama alanında depolanabilecek maksimum toplam veri miktarı (bayt cinsinden). 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 ayarlanır.

  • QUOTA_BYTES_PER_ITEM

    8192

    Senkronize depolama alanındaki her bir öğenin maksimum boyutu (bayt cinsinden). Bu boyut, değerinin JSON dizesi haline getirilmesi ve anahtar uzunluğuyla ölçülür. Bu sınırdan büyük öğeler içeren güncellemeler hemen başarısız olur ve geri çağırma kullanılırken veya bir Promise reddedildiğinde runtime.lastError ayarlanır.

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