chrome.storage

Açıklama

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

İzinler

storage

Storage API'yi kullanmak için manifest uzantısında "storage" iznini belirtin. Ö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 yol sunar. Web platformunun depolama API'lerine (IndexedDB ve Storage) benzer, ancak uzantıların depolama gereksinimlerini karşılayacak şekilde tasarlanmıştır. Temel özelliklerden bazıları şunlardır:

  • Uzantı hizmeti çalışanı ve içerik komut dosyaları da dahil olmak üzere tüm uzantı bağlamları, Storage API'ye erişebilir.
  • Serileştirilebilir JSON değerleri 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ılsa bile korunur.
  • Kurumsal politikalar için özel, salt okunur bir yönetilen depolama alanı içerir.

Uzantılar, web depolama API'larını 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ı bu arayüzü kullanmanızı önermeyiz:

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

Verileri, bir hizmet çalışanı üzerinden uzantı depolama API'lerine 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 çalışanında, verilerinizi chrome.storage için kontrol edin.
  3. Verileriniz bulunamazsa createDocument() numaralı telefonu arayın.
  4. Geri verilen Promise çözümlendikten sonra dönüşüm rutinini başlatmak için sendMessage() numarasını arayın.
  5. Ekran dışı dokümanın onMessage işleyicisinde, dönüşüm rutinini çağırın.

Web depolama API'lerinin uzantılarda nasıl çalıştığıyla ilgili bazı nüanslar da vardır. Depolama Alanı ve Çerezler makalesinden daha fazla bilgi edinebilirsiniz.

Depolama alanları

Storage API, aşağıdaki depolama alanlarına bölünmüş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 isteyerek artırılabilir. Daha büyük miktarlarda veri depolamak için storage.local kullanmanızı öneririz.
storage.managed
Yönetilen depolama alanı, politika tarafından yüklenen uzantılar için kullanılan ve geliştirici tarafından tanımlanan bir şema ile kurumsal politikalar kullanan sistem yöneticileri tarafından yönetilen salt okunur depolama alanıdır. Politikalar seçeneklere benzer, ancak kullanıcı yerine bir sistem yöneticisi tarafından yapılandırılır ve uzantının bir kuruluştaki tüm kullanıcılar için önceden yapılandırılmasına olanak tanır. Politikalarla ilgili bilgi edinmek için Yöneticiler için Dokümanlar'ı 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 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. Depolama alanı sınırı 10 MB'tır (Chrome 111 ve önceki sürümlerde 1 MB). storage.session arayüzü, Service Worker'lar 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ı, öğe başına yaklaşık 100 KB, 8 KB'tır. Senkronize edilen tarayıcılarda kullanıcı ayarlarının korunması için storage.sync kullanmanızı öneririz. Hassas kullanıcı verileriyle çalışıyorsanız bunun yerine storage.session kullanın.

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

Storage API'nin kullanım sınırlamaları şu şekildedir:

  • Veri depolama genellikle performans maliyetiyle birlikte gelir ve API, depolama kotaları içerir. Veri depolama olanağını 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ırlar aşıldığında ne olacağı hakkında ayrıntılı bilgi edinmek üzere sync, local ve session için 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üncellemeleri için eşzamanlı yanıt

Depolama alanında yapılan değişiklikleri izlemek için onChanged etkinliğine işleyici 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 bir "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 hesabına kaydeder ve hizmet çalışanı, ayarı 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 biriminden eşzamansız önceden yükleme

Service Worker'lar sürekli ç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 global değerinin 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);
});

Örnekler

Aşağıdaki örnekler local, sync ve session depolama alanlarını gösterir:

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

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Uzantının 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

  • clear

    void

    Söz

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

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

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

    • geri çağırma

      Functions (isteğe bağlı)

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

      ()=>void

    • returns

      Promise<void>

      Chrome 88 ve sonraki sürümler

      Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

  • get

    void

    Söz

    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)=> {...}

    • anahtar

      string|string[]|object optional

      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ı içeriğinin tamamını almak için null aktarın.

    • geri çağırma

      Functions (isteğe bağlı)

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

      (items: object)=>void

      • items

        nesne

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

    • returns

      Promise<object>

      Chrome 88 ve sonraki sürümler

      Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

  • getBytesInUse

    void

    Söz

    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)=> {...}

    • anahtar

      string|string[] optional

      Toplam kullanımın alınacağı tek bir anahtar veya anahtar listesi. Boş bir liste 0 sonucunu döndürecektir. Depolama alanının toplam kullanımını öğrenmek için null kartını geçin.

    • geri çağırma

      Functions (isteğe bağlı)

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

      (bytesInUse: number)=>void

      • bytesInUse

        sayı

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

    • returns

      Vaat<sayı>

      Chrome 88 ve sonraki sürümler

      Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

  • remove

    void

    Söz

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

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

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

    • anahtar

      dize|dize[]

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

    • geri çağırma

      Functions (isteğe bağlı)

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

      ()=>void

    • returns

      Promise<void>

      Chrome 88 ve sonraki sürümler

      Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

  • ayarla

    void

    Söz

    Birden fazla öğeyi ayarlar.

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

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

    • items

      nesne

      Depolama alanının güncelleneceği her anahtar/değer çiftini içeren bir nesne. Depolama alanındaki diğer anahtar/değer çiftleri bundan etkilenmez.

      Sayılar gibi temel değerler beklendiği gibi serileştirilir. typeof "object" ve "function" içeren değerler genellikle {} için serileştirilir, Array (beklendiği gibi seri hale getirilir), Date ve Regex (String temsillerini kullanarak seri hale getirilir).

    • geri çağırma

      Functions (isteğe bağlı)

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

      ()=>void

    • returns

      Promise<void>

      Chrome 88 ve sonraki sürümler

      Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

  • setAccessLevel

    void

    Söz Chrome 102 ve sonraki sürümleri

    Depolama alanı için istenen erişim düzeyini ayarlar. Varsayılan, yalnızca güvenilir bağlamlar olacaktı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

      Functions (isteğe bağlı)

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

      ()=>void

    • returns

      Promise<void>

      Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

StorageChange

Özellikler

  • newValue

    isteğe bağlı

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

  • oldValue

    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&nesne

Özellikler

  • QUOTA_BYTES

    10485760

    Yerel depolamada depolanabilecek maksimum veri miktarıdır (bayt cinsinden). Her değer ve her anahtarın uzunluğunun JSON dizeleştirilmesiyle ölçülür. Uzantının unlimitedStorage izni varsa bu değer yoksayılır. Bu sınırın aşılmasına neden olan güncellemeler hemen başarısız olur ve geri çağırma kullanılırken runtime.lastError, eşzamansız/bekleyen kullanılıyorsa reddedilen Promise olarak ayarlanır.

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ı değiştirilmeye çalışıldığında hata oluşur. 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 sonraki sürümler MV3 ve sonraki sürümler

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

Tür

StorageArea&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ı tahmin ederek ölçülür. Bu sınırın aşılmasına neden olacak güncellemeler, geri arama kullanılırken veya bir Promise reddedildiğinde hemen başarısız olur ve runtime.lastError olarak ayarlanır.

sync

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

Tür

StorageArea&nesne

Özellikler

  • MAX_ITEMS

    512

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

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1.000.000

    Kullanımdan kaldırıldı

    Storage.sync API'nin artık uzun süreli yazma işlemi kotası yoktur.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1.800

    Her bir saat içinde gerçekleştirilebilecek maksimum set, remove veya clear işlemi sayısı. Bu değer, her 2 saniyede 1'dir ve kısa vadeli yüksek dakika başına yazma sınırından daha düşük bir tavandır.

    Bu sınırın aşılmasına neden olacak güncellemeler, geri arama kullanılırken veya bir Promise reddedildiğinde hemen başarısız olur ve runtime.lastError olarak ayarlanır.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Her bir dakikada gerçekleştirilebilecek maksimum set, remove veya clear işlemi sayısı. Bu hız saniyede 2'dir ve daha kısa bir sürede saatlik yazma işleminden daha yüksek işleme hızı sağlar.

    Bu sınırın aşılmasına neden olacak güncellemeler, geri arama kullanılırken veya bir Promise reddedildiğinde hemen başarısız olur ve runtime.lastError olarak ayarlanır.

  • QUOTA_BYTES

    102400

    Senkronizasyon depolama alanında depolanabilecek verilerin maksimum toplam miktarı (bayt cinsinden) (her değer artı her anahtarın uzunluğu JSON dizesiyle ölçülür). Bu sınırın aşılmasına neden olacak güncellemeler, geri arama kullanılırken veya bir Promise reddedildiğinde hemen başarısız olur ve runtime.lastError olarak ayarlanır.

  • QUOTA_BYTES_PER_ITEM

    8192

    Senkronizasyon depolama alanındaki her bir öğenin, değerinin JSON dizesi ve anahtar uzunluğu ile ölçülen maksimum boyutu (bayt cinsinden). Bu sınırın üzerinde öğeleri içeren güncellemeler hemen başarısız olur ve geri arama 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

  • geri çağırma

    işlev

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

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

    • değişiklikler

      nesne

    • areaName

      dize