chrome.storage

Açıklama

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

İzinler

storage

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

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

Kavramlar ve kullanım

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

  • Uzantı hizmet işçisi ve içerik komut dosyaları dahil tüm uzantı bağlamları Storage API'ye erişebilir.
  • JSON dilinde serileştirilebilir değerler, nesne özellikleri olarak depolanır.
  • Storage API, toplu okuma ve yazma işlemleriyle senkronize değildir.
  • 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 devam eder.
  • Kuruluş 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 adresinden erişilebilir) kullanabilir ancak aşağıdaki nedenlerden dolayı bunu önermeyiz:

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

Bir hizmet çalışanından web depolama API'lerinden uzantı depolama API'lerine veri taşımak için:

  1. Ekran dışı doküman HTML sayfası ve komut dosyası hazırlayın. Komut dosyası, bir dönüşüm rutini ve onMessage işleyici içermelidir.
  2. Uzantı hizmet işçisinde, verileriniz için chrome.storage seçeneğini işaretleyin.
  3. Verileriniz bulunamazsa createDocument() numaralı telefonu arayın.
  4. Döndürülen Promise çözüldükten sonra dönüşüm rutinini başlatmak için sendMessage() işlevini çağırın.
  5. Ekran dışı dokümanın onMessage işleyicisinde dönüşüm rutinini çağırın.

Web depolama alanı API'lerinin uzantılarda işleyiş şekliyle ilgili bazı farklılıklar da vardır. Daha fazla bilgi için Depolama alanı 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 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 fazla veri depolamak için storage.local kullanmanızı öneririz.
storage.managed
Yönetilen depolama alanı, politikayla yüklenen 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şun tüm kullanıcıları için önceden yapılandırılabilir. Politikalar hakkında bilgi edinmek için Yöneticiler İç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
Verileri tarayıcı oturumu boyunca bellekte tutar. Varsayılan olarak içerik komut dosyalarına maruz kalmaz ancak bu davranış, chrome.storage.session.setAccessLevel() ayarlanarak 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.
storage.sync
Senkronizasyon etkinse veriler, kullanıcının oturum açtığı tüm Chrome Tarayıcılarla senkronize edilir. Devre dışıysa storage.local gibi davranır. Chrome, tarayıcı çevrimdışıyken verileri yerel olarak depolar ve tekrar çevrimiçi olduğunda senkronizasyonu devam ettirir. Kota sınırı 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 değerini kullanın.

Depolama alanı ve akış sınırlamaları

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

  • Veri depolama genellikle performans maliyetleri içerir ve API'de depolama kotaları bulunur. Veri depolama özelliğini kaybetmemek için hangi verileri depoladığınız konusunda dikkatli olmanızı öneririz.
  • Depolama alanı 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ırlar 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

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 izler:

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 ileri götürebiliriz. Bu örnekte, kullanıcının "hata ayıklama modunu" etkinleştirmesine olanak tanıyan bir seçenekler sayfamız var (uygulaması burada gösterilmemiştir). Seçenekler sayfası yeni ayarları hemen storage.sync alanına kaydeder ve servis çalışanı, ayarı en kısa sürede uygulamak için storage.onChanged değerini 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 ön yükleme

Hizmet çalışanları her zaman çalışmadığından, Manifest V3 uzantılarının bazen etkinlik işleyicilerini yürütmeden önce verileri depolama alanından eşzamansız olarak yüklemesi gerekir. Bunu yapmak için aşağıdaki snippet'te, mantığını yürütmeden önce storageCache global değişkeninin doldurulmasını bekleyen bir asynkron action.onClicked etkinlik işleyicisi kullanılı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);
});

Ö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 birini keşfedin:

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

StorageArea

Özellikler

  • onChanged

    Etkinlik<functionvoidvoid>

    Chrome 73 ve sonraki sürümler

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

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

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

    • geri çağırma

      işlev

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

      (changes: object) => void

      • değişiklikler

        nesne

  • temizle

    geçersiz

    Promise

    Tüm öğeler depolama alanından kaldırılır.

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

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

    • geri çağırma

      işlev isteğe bağlı

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

      () => void

    • returns

      Promise<void>

      Chrome 88 ve sonraki sürümler

      Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

  • 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

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

      Alınacak tek bir anahtar, alınacak anahtarların 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 parametresini iletin.

    • geri çağırma

      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 88 ve sonraki sürümler

      Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

  • 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

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

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

    • geri çağırma

      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 cinsinden).

    • returns

      Promise<number>

      Chrome 88 ve sonraki sürümler

      Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

  • getKeys

    geçersiz

    Promise Chrome 130 ve üzeri sürümler

    Depolama alanındaki tüm anahtarları alır.

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

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

    • geri çağırma

      işlev isteğe bağlı

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

      (keys: string[]) => void

      • anahtarlar

        dize[]

        Depolama alanından okunan anahtarları içeren dizi.

    • returns

      Promise<string[]>

      Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

  • remove

    geçersiz

    Promise

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

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

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

    • anahtarlar

      dize | dize[]

      Kaldırılacak öğelerin tek bir anahtarı veya listesi.

    • geri çağırma

      işlev isteğe bağlı

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

      () => void

    • returns

      Promise<void>

      Chrome 88 ve sonraki sürümler

      Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

  • grup

    geçersiz

    Promise

    Birden fazla öğe ayarlar.

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

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

    • items

      nesne

      Her anahtar/değer çiftine depolama alanını güncellemesi için bir nesne verir. Depolama alanındaki diğer anahtar/değer çiftleri etkilenmez.

      Sayılar gibi ilkel değerler beklendiği gibi serileştirilir. typeof "object" ve "function" içeren değerler genellikle {} olarak serileştirilir. Bunun istisnası Array (beklenen şekilde serileştirilir), Date ve Regex'dir (String gösterimlerini kullanarak serileştirilir).

    • geri çağırma

      işlev isteğe bağlı

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

      () => void

    • returns

      Promise<void>

      Chrome 88 ve sonraki sürümler

      Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

  • setAccessLevel

    geçersiz

    Promise Chrome 102 ve sonraki sürümler

    Depolama alanı için istenen erişim düzeyini ayarlar. Varsayılan olarak yalnızca güvenilir bağlamlar kullanılır.

    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.

    • geri çağırma

      işlev isteğe bağlı

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

      () => void

    • returns

      Promise<void>

      Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

StorageChange

Özellikler

  • newValue

    herhangi bir isteğe bağlı

    Yeni bir değer varsa öğenin yeni değeri.

  • oldValue

    herhangi bir isteğe bağlı

    Eski bir değer varsa öğenin eski değeri.

Özellikler

local

local depolama alanındaki öğeler her makinede yereldir.

Tür

StorageArea ve nesne

Özellikler

  • QUOTA_BYTES

    10485760

    Her bir değerin JSON dizeleştirmesi ve her bir anahtarın uzunluğuna göre ölçülen, yerel depolama alanında depolanabilecek maksimum veri miktarı (bayt cinsinden). 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 işlevi kullanılırken runtime.lastError, async/await kullanılırken ise reddedilen bir Promise ayarlanır.

managed

managed depolama alanındaki öğeler, alan yöneticisi tarafından yapılandırılmış bir kurumsal politika tarafından ayarlanır ve uzantı için salt okunurdur. Bu ad alanını değiştirmeye çalışmak hatayla sonuçlanır. 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 ve üzeri MV3 ve üzeri

session depolama alanındaki öğeler bellekte depolanır ve diskte kalıcı olmaz.

Tür

StorageArea ve nesne

Özellikler

  • QUOTA_BYTES

    10485760

    Her değer ve anahtarın dinamik olarak ayrılan bellek kullanımının tahmin edilmesiyle ö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 işlevi kullanıldığında veya bir Promise reddedildiğinde runtime.lastError olarak 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 depolanabilecek 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 işlevi kullanıldığında veya bir Promise reddedildiğinde runtime.lastError değerini alır.

  • 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, 2 saniyede 1 yazma işlemidir ve kısa vadeli daha yüksek dakika başına yazma sınırından daha düşük bir tavan değeridir.

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

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Her dakika gerçekleştirilebilecek maksimum set, remove veya clear işlemi sayısı. Bu, saniye başına 2'dir ve daha kısa bir süre içinde saat başına yazma işleminden daha yüksek bir 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 işlevi kullanıldığında veya bir Promise reddedildiğinde runtime.lastError olarak ayarlanır.

  • QUOTA_BYTES

    102400

    Her değerin JSON dizeleştirmesi ve her anahtarın uzunluğuna göre ölçülen, 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 işlevi kullanıldığında veya bir Promise reddedildiğinde runtime.lastError olarak ayarlanır.

  • QUOTA_BYTES_PER_ITEM

    8192

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

Etkinlikler

onChanged

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

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

Parametreler

  • geri çağırma

    işlev

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

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

    • değişiklikler

      nesne

    • areaName

      dize