chrome.storage

Açıklama

Kullanıcı verilerini depolamak, almak ve izlemek için chrome.storage API'yi kullanın.

İzinler

storage

Storage API'yi kullanmak için uzantıda "storage" iznini beyan edin manifest dosyası olarak adlandırılır. Örneğin:

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

Kavramlar ve kullanım

Storage API, kullanıcı verilerini ve durumunu saklamak için uzantıya özel 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ı hizmeti çalışanı ve içerik komut dosyaları dahil tüm uzantı bağlamları Storage API'ye erişebilir.
  • JSON seri haline getirilebilir değerler nesne özellikleri olarak depolanır.
  • Storage API, toplu okuma ve yazma işlemleriyle eşzamansız bir şekilde çalışır.
  • Kullanıcı, önbelleği ve tarama geçmişini temizlese bile veriler değişmeden kalır.
  • Depolanan ayarlar, gizli 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) kullanabilir. Ancak, aşağıdaki nedenlerden dolayı önerilmez:

  • 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.

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

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

Web depolama API'lerinin uzantılarda çalışma şekliyle ilgili de bazı ince ayrıntılar vardır. Daha fazla bilgi: Depolama ve Çerezler başlıklı makaleyi inceleyin.

Depolama alanları

Storage API, aşağıdaki depolama alanlarına ayrılır:

storage.local
Veriler yerel olarak depolanır ve uzantı kaldırıldığında silinir. Depolama alanı sınırı 10 MB'tır (Chrome 113 ve önceki sürümlerde 5 MB), ancak "unlimitedStorage" izni istenerek artırılabilir. Daha fazla veri depolamak için storage.local kullanmanızı öneririz.
storage.managed
Yönetilen depolama, politika tarafından yüklenen uzantılar için salt okunur depolama alanıdır ve sistem yöneticileri tarafından geliştirici tarafından tanımlanmış bir şema ve kurumsal politikalar kullanılarak yönetilir. Politikalar, seçeneklere benzer ancak kullanıcı yerine bir sistem yöneticisi tarafından yapılandırılır. Bu da uzantının bir kuruluştaki tüm kullanıcılar için önceden yapılandırılmasına olanak tanır. Politikalar hakkında bilgi edinmek için Yöneticiler için Dokümanlar sayfasına göz atın. managed depolama alanı hakkında daha fazla bilgi edinmek için Depolama alanları için manifeste göz atın.
storage.session
Tarayıcı oturumu boyunca verileri bellekte tutar. Varsayılan olarak içerik komut dosyaları gösterilmez, 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 çeşitli arayüzlerden biridir.
storage.sync
Senkronizasyon etkinse veriler kullanıcının giriş yaptığı herhangi bir 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ı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.

Depolama alanı ve kısıtlama sınırları

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

  • Verilerin depolanması genellikle performans maliyetlerini de beraberinde getirir. API'ye depolama alanı kotaları da dahildir. Veri saklama olanağını kaybetmemek için depoladığınız veriler konusunda dikkatli olmanızı öneririz.
  • Depolama alanının tamamlanması zaman alabilir. Kodunuzu bu süreyi hesaba katacak şekilde yapılandırdığınızdan emin olun.

Depolama alanı sınırlamaları ve aşıldıklarında ne olacağıyla ilgili ayrıntılar için sync, local ve session ile ilgili kota bilgilerine göz atı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 işleyici ekleyin. Depolama alanında herhangi bir değişiklik olursa bu etkinlik tetiklenir. Örnek kod şu değişiklikleri işler:

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 taşıyabiliriz. Bu örnekte, Google Etiket Yöneticisi için bir seçenekler sayfamız Kullanıcının "hata ayıklama modunu" açıp kapatmasına olanak tanır (uygulama burada gösterilmez). Seçenekler sayfası, yeni ayarları hemen storage.sync cihazına kaydeder ve hizmet çalışanı, ayarı mümkün olan en kısa sürede uygulamak için storage.onChanged özelliğini 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ığı için Manifest V3 uzantılarının bazen etkinlik işleyicilerini yürütmeden önce depolama alanından eşzamansız olarak veri yükler. Bunu yapmak için Aşağıdaki snippet, storageCache için bekleyen eşzamansız bir action.onClicked etkinlik işleyicisi kullanıyor global olarak doldurulacağından emin olun.

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 alanı:

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 örnekleri inceleyin:

Türler

AccessLevel

Chrome 102 ve sonraki sürümler 'nı inceleyin.

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

Enum

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

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
Uzantının dışından gelen bağlamları belirtir.

StorageArea

Özellikler

  • onChanged

    Etkinlik<İşlevler geçersiz>

    Chrome 73 ve sonraki sürümler 'nı inceleyin.

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

    onChanged.addListener işlevi aşağıdaki gibi 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

    Söz 'nı inceleyin.

    Depolama alanındaki tüm öğeler kaldırılır.

    clear işlevi aşağıdaki gibi 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

      Taahhüt<void>

      Chrome 88 ve sonraki sürümler 'nı inceleyin.

      Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

  • get

    geçersiz

    Söz 'nı inceleyin.

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

    get işlevi aşağıdaki gibi görünür: 

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

    • anahtarlar

      string | string[] | nesne 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 tamamından yararlanmak için null kartınızı geçin.

    • 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 eşlemelerinde öğe bulunan nesne.

    • returns

      Promise&lt;object&gt;

      Chrome 88 ve sonraki sürümler 'nı inceleyin.

      Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

  • getBytesInUse

    geçersiz

    Söz 'nı inceleyin.

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

    getBytesInUse işlevi aşağıdaki gibi görünür: 

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

    • anahtarlar

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

      Toplam kullanımı öğrenebileceğiniz tek bir tuş veya anahtar listesi. Boş liste 0 değerini döndürür. Depolama alanınızın toplam kullanımından yararlanmak için null geçin.

    • 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&lt;number&gt;

      Chrome 88 ve sonraki sürümler 'nı inceleyin.

      Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

  • getKeys

    geçersiz

    Söz Beklemede

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

    getKeys işlevi aşağıdaki gibi 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ın yer aldığı dizi.

    • returns

      Promise&lt;string[]&gt;

      Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

  • remove

    geçersiz

    Söz 'nı inceleyin.

    Bir veya daha fazla öğeyi depolama alanından kaldırır.

    remove işlevi aşağıdaki gibi görünür: 

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

    • anahtarlar

      string | dize[]

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

    • geri çağırma

      işlev isteğe bağlı

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

      () => void

    • returns

      Taahhüt<void>

      Chrome 88 ve sonraki sürümler 'nı inceleyin.

      Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

  • grup

    geçersiz

    Söz 'nı inceleyin.

    Birden çok öğeyi ayarlar.

    set işlevi aşağıdaki gibi görünür: 

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

    • items

      nesne

      Depolama alanının güncellenmesi için her bir anahtar/değer çiftini sağlayan bir nesne. Depolama alanındaki 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 temsillerini kullanarak serileştir) hariç tutulur.

    • geri çağırma

      işlev isteğe bağlı

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

      () => void

    • returns

      Taahhüt<void>

      Chrome 88 ve sonraki sürümler 'nı inceleyin.

      Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

  • setAccessLevel

    geçersiz

    Söz 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 aşağıdaki gibi 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

      Taahhüt<void>

      Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

StorageChange

Özellikler

  • newValue

    isteğe bağlı herhangi bir

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

  • oldValue

    isteğe bağlı herhangi bir

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

Özellikler

local

local depolama alanındaki öğeler her makine için yereldir.

Tür

StorageArea ve nesne

Özellikler

  • QUOTA_BYTES

    10485760

    Her değerin ve her anahtarın uzunluğunun JSON dizeleştirmesiyle ö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 bir geri çağırma kullanılırken runtime.lastError değerini ya da eşzamansız/bekleme yöntemini kullanıyorsanız reddedilen bir Vaat'i 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 hatayla sonuçlanır. Politika yapılandırma hakkında bilgi edinmek için Depolama alanları için manifest başlıklı makaleye bakın.

Tür

StorageArea

session

Chrome 102 ve sonraki sürümler MV3+

session depolama alanındaki öğeler bellekte depolanır ve diskte saklanmaz.

Tür

StorageArea ve nesne

Özellikler

  • QUOTA_BYTES

    10485760

    Bellekte depolanabilecek maksimum veri miktarı (bayt cinsinden). Her değer ve anahtarın dinamik olarak ayrılmış bellek kullanımının tahmin edilmesiyle ö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ılırken veya bir Promise reddedildiğinde runtime.lastError değerini ayarlar.

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 kullanılırken veya bir Promise reddedildiğinde runtime.lastError değeri ayarlanır.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1.000.000

    Desteği sonlandırıldı

    Storage.sync API'de artık sürekli yazma işlemi kotası mevcut değil.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1.800

    Her saat gerçekleştirilebilecek maksimum set, remove veya clear işlemi sayısı. Bu değer, 2 saniyede bir 1'dir. Bu değer, kısa vadede yüksek olan dakika başına yazma sınırına göre 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ılırken 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 değer saniyede 2 olabilir ve daha kısa sürede saat başına 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 değerini ayarlar.

  • QUOTA_BYTES

    102.400

    Her değerin ve her anahtarın uzunluğunun JSON dizeleştirmesiyle ö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 kullanılırken 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, öğenin değerinin JSON dizeleştirmesiyle ve anahtar uzunluğunun toplamıyla ölçülür. Bu sınırdan büyük öğeler içeren güncellemeler hemen başarısız olur ve geri arama kullanılırken ya da bir Vaat reddedildiğinde runtime.lastError olarak ayarlanı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