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
Genel bakış
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 bazı bağlamlarda (pop-up ve diğer HTML sayfaları) [Storage
][mdn-storage] arayüzünü (window.localStorage
adresinden erişilebilir) kullanabilse de, aşağıdaki nedenlerden dolayı önerilmez:
- Uzantının hizmet çalışanı
Storage
ürününe erişemiyor. - İçerik komut dosyaları, depolama alanını ana makine sayfasıyla paylaşır.
Storage
arayüzü kullanılarak kaydedilen veriler, kullanıcı tarama geçmişini temizlediğinde kaybolur.
Verileri, bir hizmet çalışanı üzerinden uzantı depolama API'lerine taşımak için:
- Dönüşüm rutini ve [
onMessage
][on-message] işleyici ile ekran dışı doküman oluşturun. - Ekran dışı bir dokümana dönüştürme rutini ekleme.
- Uzantı hizmet çalışanında, verilerinizi
chrome.storage
kontrol edin. - Verileriniz bulunamazsa ekran dışı bir doküman [create][create-offscreen] ve dönüştürme rutinini başlatmak için [
sendMessage()
][send-message] komutunu çağırın. - 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 ve Çerezler][depolama-ve-çerezler] makalesinden daha fazla bilgi edinebilirsiniz.
Depolama alanları
Storage API, aşağıdaki dört pakete ("depolama alanları") ayrılmıştır:
storage.local
- Veriler yerel olarak depolanır ve uzantı kaldırıldığında silinir. Kota sınırı yaklaşık 10 MB'tır ancak
"unlimitedStorage"
izni isteyerek artırılabilir. Daha büyük miktarlarda veri depolamak için bu yöntemi kullanabilirsiniz.
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 edilmiş tarayıcılarda kullanıcı ayarlarını korumak için bu özelliği kullanabilirsiniz.
- 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. Kota sınırı yaklaşık 10 MB'tır. Bu API'yi, hizmet çalışanı çalıştırmalarında genel değişkenleri depolamak için kullanabilirsiniz.
- storage.managed
- Yöneticiler, yönetilen bir ortamda destekleyici uzantıların ayarlarını yapılandırmak için şema ve kuruluş politikaları kullanabilir. Bu depolama alanı salt okunurdur.
Manifest
Storage API'yi kullanmak için manifest uzantısında "storage"
iznini belirtin. Örneğin:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
Kullanım
Aşağıdaki örnekler local
, sync
ve session
depolama alanlarını gösterir:
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ıyla ilgili daha fazla bilgi edinmek için Depolama alanları için manifest başlıklı makaleyi inceleyin.
Depolama ve kısıtlama sınırları
Storage API'ye ekleme yapmayı, bir şeyleri büyük bir kamyona yerleştirmek gibi düşünmeyin. Depolama alanına ekleme yapmayı boruya bir şey koymaya benzetebiliriz. Boruda zaten malzeme olabilir, hatta dolu da olabilir. Depolama alanına eklediğiniz zaman ile fiilen kaydedildiği zaman arasında her zaman bir gecikme olduğunu varsayın.
Depolama alanı sınırlamaları ve bu sınırların aşılması durumunda ne olacağı hakkında ayrıntılı bilgi için sync
, local
ve session
ile ilgili 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 ekleyebilirsiniz. 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 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, 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);
});
Uzantı örnekleri
Storage API'nin diğer demolarını görmek için aşağıdaki örneklerden birini inceleyin:
Türler
AccessLevel
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ümlerBir 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özTü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ümlerVaatler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırmaları kullanması gerekir.
-
-
get
void
SözDepolama 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[] | 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ı 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ümlerVaatler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırmaları kullanması gerekir.
-
-
getBytesInUse
void
SözBir 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[] isteğe bağlı
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ümlerVaatler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırmaları kullanması gerekir.
-
-
remove
void
SözBir 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ümlerVaatler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırmaları kullanması gerekir.
-
-
grup
void
SözBirden 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
veRegex
(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ümlerVaatler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırmaları kullanması gerekir.
-
-
setAccessLevel
void
Söz Chrome 102 ve sonraki sürümleriDepolama 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
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 yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırmaları kullanması gerekir.
-
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 ve 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ırkenruntime.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
session
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ı 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 ve 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
veyaclear
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
veyaclear
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
-