Açıklama
Kullanıcı verilerini depolamak, almak ve izlemek için chrome.storage
API'yi kullanın.
İzinler
storage
Genel Bakış
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 bazı bağlamlarda [Storage
][mdn-storage] arayüzünü (window.localStorage
adresinden erişilebilir) kullanabilse de (pop-up ve diğer HTML sayfaları) aşağıdaki nedenlerden dolayı önerilmez:
- Uzantının hizmet çalışanı
Storage
dosyasına erişemez. - İç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.
Bir hizmet çalışanından web depolama alanı API'lerinden uzantı depolama API'lerine veri taşımak için:
- Dönüşüm rutini ve [
onMessage
][mesaj üzerinde] işleyici ile ekran dışı bir doküman oluşturun. - Ekran dışındaki bir dokümana dönüşüm rutini ekleyin.
- Uzantı hizmet çalışanında,
chrome.storage
kontrol ederek verilerinizi kontrol eder. - Verileriniz bulunamazsa dönüşüm rutinini başlatmak için ekran dışı bir doküman [oluştur][create-offscreen] ve [
sendMessage()
][send-message] araması yapın. - 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][depolama-ve-çerezler] makalesi.
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 istenerek artırılabilir. Daha büyük miktarda veri depolamak için kullanmayı düşünebilirsiniz. ziyaret edin.
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. Bu seçeneği, senkronize edilmiş tarayıcılarda kullanıcı ayarlarını korumak için kullanabilirsiniz. ziyaret edin.
- 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. Kota sınırı yaklaşık 10 MB'tır. Bunu Service Worker çalıştırmalarında global değişkenleri depolamak için kullanabilirsiniz. ziyaret edin.
- storage.managed
- Yöneticiler, yönetilen bir ortamda destekleyici uzantıların ayarlarını yapılandırmak için bir şema ve kurumsal politikalar kullanabilir. Bu depolama alanı salt okunurdur.
Manifest
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"
],
...
}
Kullanım
Aşağıdaki örneklerde local
, sync
ve
session
depolama alanı:
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 manifeste bakın.
Depolama alanı ve kısıtlama sınırları
Storage API'ye ekleme yapmak, işleri büyük bir kamyona sokmak gibi olmamalıdır. Mevcut müşterilerinize boruya bir şey koymak gibidir. Boruda zaten malzeme olabilir ve doldurulabilir. Her zaman depolama alanına ekleme işlemi ile depolama alanının gerçekten kaydedilir.
Depolama alanı sınırlamaları ve bu sınırlar aşıldıktan sonra ne olacağı hakkında ayrıntılı bilgi 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 ekleyebilirsiniz. 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ığından, 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);
});
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<İş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.Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.
-
-
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<object>
Chrome 88 ve sonraki sürümler 'nı inceleyin.Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.
-
-
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<number>
Chrome 88 ve sonraki sürümler 'nı inceleyin.Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.
-
-
getKeys
geçersiz
Söz BeklemedeDepolama 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<string[]>
Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.
-
-
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.Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.
-
-
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
veRegex
(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.Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.
-
-
setAccessLevel
geçersiz
Söz Chrome 102 ve sonraki sürümlerDepolama 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
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>
Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.
-
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ırkenruntime.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
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ı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
veyaclear
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
veyaclear
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
-