Bu sayfa, Cloud Translation API ile çevrilmiştir.

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

Genel Bakış

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 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 arayüzün kullanılması önerilmez:

Uzantının hizmet çalışanı Storage adresine erişemiyor.
İçerik komut dosyaları, ana makine sayfasıyla depolama alanını paylaşır.
Storage arayüzü 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:

Dönüşüm rutini ve [onMessage][on-message] işleyicisi içeren bir ekran dışı doküman oluşturun.
Ekranda görünmeyen bir dokümana dönüştürme rutini ekleyin.
Uzantı hizmeti çalışanı bölümünde verileriniz için chrome.storage işaretini bulun.
Verileriniz bulunamazsa [create][create-offscreen] ekran dışı bir doküman oluşturun ve dönüştürme rutinini başlatmak için [sendMessage()][send-message] işlevini çağırın.
Ekran dışı dokümanın onMessage işleyicisinde dönüştürme rutinini çağırın.

Web depolama API'lerinin uzantılarda çalışma şekliyle ilgili bazı nüanslar da vardır. Daha fazla bilgiyi [Depolama ve Çerezler][storage-and-cookies] makalesinde bulabilirsiniz.

Depolama alanları

Storage API aşağıdaki dört pakete ("depolama alanları") ayrılı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 fazla veri depolamak için kullanabilirsiniz.

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ı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 özelliği kullanabilirsiniz.

Uyarı: Yerel ve senkronize depolama alanları şifrelenmediğinden gizli kullanıcı verilerini depolamamalıdır. Hassas verilerle çalışırken tarayıcı kapatılana kadar değerleri bellekte tutmak için session depolama alanını kullanabilirsiniz.

storage.session: Verileri tarayıcı oturumu süresince bellekte tutar. Varsayılan olarak içerik komut dosyalarına sunulmaz 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ı arasında genel değişkenleri depolamak için 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 okunurdur.

Manifest

Depolama API'sini kullanmak için uzantı manifest dosyasında "storage" iznini bildirin. Ö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 sınırlama sınırları

Storage API'ye ekleme işlemini büyük bir kamyona eşya koyma olarak düşünmeyin. Depolama alanına ekleme işlemini bir boruya bir şey koymaya benzetebiliriz. Borunun içinde malzeme olabilir ve hatta boru dolu olabilir. Depolamaya ekleme ile kaydın yapılması arasında her zaman gecikme olduğunu varsayın.

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 eşzamanlı yanıt

Depolamada yapılan değişiklikleri izlemek için onChanged etkinliğine bir işleyici ekleyebilirsiniz. Depolamada 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 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 global değişkeninin doldurulmasını bekleyen bir asenkron action.onClicked etkinlik işleyicisini 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 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 yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdı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
  
  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 yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdı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
  
  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 yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdır.
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 yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdır.
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 yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdır.
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 yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdı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 session depolama alanı güvenilir bağlamlarla (uzantı sayfaları ve hizmet çalışanları) sınırlıyken managed, local ve sync depolama alanı 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 yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdır.

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

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

chrome.storage Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Açıklama

İzinler

Genel Bakış

Depolama alanları

Manifest

Kullanım

storage.local

storage.sync

storage.session

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

Kullanım alanları

Depolama alanı güncellemelerine eşzamanlı yanıt

Depolama alanından eşzamansız önceden yükleme

Uzantı örnekleri

Türler

AccessLevel

Enum

StorageArea

Özellikler

StorageChange

Özellikler

Özellikler

local

Tür

Özellikler

managed

Tür

sync

Tür

Özellikler

Etkinlikler

onChanged

Parametreler

chrome.storage