Mô tả
Sử dụng API chrome.storage
để lưu trữ, truy xuất và theo dõi các thay đổi đối với dữ liệu người dùng.
Quyền
storage
Để sử dụng API lưu trữ, hãy khai báo quyền "storage"
trong tiện ích
tệp kê khai. Ví dụ:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
Khái niệm và cách sử dụng
Storage API cung cấp một cách thức dành riêng cho tiện ích để duy trì dữ liệu và trạng thái của người dùng. API này tương tự như các API lưu trữ của nền tảng web (IndexedDB và Storage), nhưng được thiết kế để đáp ứng nhu cầu lưu trữ của các tiện ích. Sau đây là một vài tính năng chính:
- Tất cả ngữ cảnh của tiện ích, bao gồm cả trình chạy dịch vụ tiện ích và tập lệnh nội dung đều có quyền truy cập vào Storage API.
- Các giá trị JSON có thể chuyển đổi tuần tự được lưu trữ dưới dạng thuộc tính đối tượng.
- Storage API không đồng bộ với các thao tác đọc và ghi hàng loạt.
- Ngay cả khi người dùng xoá bộ nhớ đệm và nhật ký duyệt web, dữ liệu vẫn tồn tại.
- Các chế độ cài đặt đã lưu trữ sẽ vẫn tồn tại ngay cả khi bạn dùng chế độ chia tách ẩn danh.
- Bao gồm khu vực lưu trữ được quản lý độc quyền chỉ có thể đọc dành cho các chính sách dành cho doanh nghiệp.
Tiện ích có thể sử dụng API lưu trữ trên web không?
Mặc dù tiện ích có thể sử dụng giao diện Storage
(có thể truy cập từ window.localStorage
) trong một số ngữ cảnh (cửa sổ bật lên và các trang HTML khác), nhưng bạn không nên sử dụng giao diện này vì những lý do sau:
- Trình chạy dịch vụ tiện ích không thể sử dụng API Bộ nhớ web.
- Tập lệnh nội dung sẽ dùng chung dung lượng lưu trữ với trang lưu trữ.
- Dữ liệu được lưu bằng Web Storage API sẽ bị mất khi người dùng xoá nhật ký duyệt web.
Cách di chuyển dữ liệu từ API lưu trữ trên web sang API lưu trữ tiện ích từ một trình chạy dịch vụ:
- Chuẩn bị một trang html và tệp tập lệnh của tài liệu ngoài màn hình. Tệp tập lệnh phải chứa một quy trình chuyển đổi và một trình xử lý
onMessage
. - Trong trình chạy dịch vụ tiện ích, hãy kiểm tra
chrome.storage
để tìm dữ liệu của bạn. - Nếu không tìm thấy dữ liệu, hãy gọi
createDocument()
. - Sau khi Lời hứa được trả về khắc phục xong, hãy gọi
sendMessage()
để bắt đầu quy trình chuyển đổi. - Bên trong trình xử lý
onMessage
của tài liệu ngoài màn hình, hãy gọi quy trình chuyển đổi.
Ngoài ra, còn có một số điểm khác biệt nhỏ trong cách hoạt động của các API lưu trữ trên web trong các tiện ích. Tìm hiểu thêm trong Bài viết về Bộ nhớ và cookie.
Khu vực lưu trữ
Storage API được chia thành các khu vực lưu trữ sau:
storage.local
- Dữ liệu được lưu trữ cục bộ và sẽ bị xóa khi bạn xóa tiện ích. Hạn mức bộ nhớ là 10 MB (5 MB trong Chrome 113 trở xuống), nhưng bạn có thể tăng hạn mức bộ nhớ bằng cách yêu cầu quyền
"unlimitedStorage"
. Bạn nên sử dụngstorage.local
để lưu trữ lượng dữ liệu lớn hơn. storage.managed
- Bộ nhớ được quản lý là bộ nhớ chỉ có thể đọc cho các tiện ích đã cài đặt theo chính sách. Bộ nhớ được quản trị viên hệ thống quản lý bằng giản đồ do nhà phát triển xác định và các chính sách doanh nghiệp. Các chính sách cũng tương tự như các tuỳ chọn nhưng do quản trị viên hệ thống định cấu hình thay vì người dùng, cho phép định cấu hình trước tiện ích cho tất cả người dùng của tổ chức. Để biết thông tin về các chính sách, hãy xem Tài liệu dành cho quản trị viên. Để tìm hiểu thêm về khu vực lưu trữ
managed
, hãy xem bài viết Tệp kê khai cho khu vực lưu trữ. storage.session
- Lưu giữ dữ liệu trong bộ nhớ trong suốt một phiên hoạt động của trình duyệt. Theo mặc định, tập lệnh này không hiển thị với tập lệnh nội dung, nhưng bạn có thể thay đổi hành vi này bằng cách đặt
chrome.storage.session.setAccessLevel()
. Giới hạn bộ nhớ là 10 MB (1 MB trong Chrome 111 trở xuống). Giao diệnstorage.session
là một trong số nhiều mà chúng tôi đề xuất cho trình chạy dịch vụ. storage.sync
- Nếu bạn bật tính năng đồng bộ hoá, thì dữ liệu sẽ được đồng bộ hoá với bất kỳ trình duyệt Chrome nào mà người dùng đã đăng nhập. Nếu bị tắt, nó sẽ hoạt động như
storage.local
. Chrome lưu trữ dữ liệu trên thiết bị khi trình duyệt không có kết nối mạng và tiếp tục đồng bộ hoá khi trình duyệt có kết nối mạng trở lại. Giới hạn hạn mức là khoảng 100 KB, 8 KB cho mỗi mục. Bạn nên sử dụngstorage.sync
để duy trì chế độ cài đặt người dùng trên các trình duyệt đã đồng bộ hoá. Nếu bạn đang làm việc với dữ liệu nhạy cảm của người dùng, hãy sử dụngstorage.session
.
Các hạn mức về bộ nhớ và điều tiết
Storage API (API Bộ nhớ) có các giới hạn sử dụng sau:
- Việc lưu trữ dữ liệu thường đi kèm với chi phí hiệu suất và API bao gồm cả hạn mức bộ nhớ. Bạn nên cẩn thận về những dữ liệu mình lưu trữ để tránh bị mất khả năng lưu trữ dữ liệu.
- Quá trình lưu trữ có thể mất một chút thời gian để hoàn tất. Hãy nhớ định cấu trúc mã sao cho phù hợp với thời gian đó.
Để biết chi tiết về giới hạn đối với khu vực lưu trữ và những việc sẽ xảy ra khi vượt quá hạn mức, hãy xem thông tin về hạn mức cho sync
, local
và session
.
Trường hợp sử dụng
Các phần sau đây minh hoạ các trường hợp sử dụng phổ biến cho Storage API.
Phản hồi đồng bộ với các bản cập nhật bộ nhớ
Để theo dõi các thay đổi đối với bộ nhớ, hãy thêm một trình nghe vào sự kiện onChanged
. Khi có bất kỳ thay đổi nào trong bộ nhớ, sự kiện đó sẽ kích hoạt. Mã mẫu theo dõi những thay đổi sau:
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}".`
);
}
});
Chúng tôi có thể tiến bộ hơn nữa về ý tưởng này. Trong ví dụ này, chúng tôi có trang tuỳ chọn
cho phép người dùng chuyển đổi "chế độ gỡ lỗi" (cách triển khai không được hiển thị ở đây). Trang tuỳ chọn lưu ngay các cài đặt mới vào storage.sync
và trình chạy dịch vụ sẽ sử dụng storage.onChanged
để áp dụng cài đặt sớm nhất có thể.
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);
}
});
Tải trước không đồng bộ từ bộ nhớ
Vì trình chạy dịch vụ không phải lúc nào cũng chạy, nên đôi khi, tiện ích Manifest V3 cần phải
tải không đồng bộ dữ liệu từ bộ nhớ trước khi thực thi trình xử lý sự kiện. Để làm được điều này,
đoạn mã sau sử dụng trình xử lý sự kiện action.onClicked
không đồng bộ chờ storageCache
toàn cầu được điền trước khi thực thi logic của nó.
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);
});
Ví dụ
Các mẫu sau đây minh hoạ local
, sync
và
session
khu vực lưu trữ:
Địa phương
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);
});
Đồng bộ hoá
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);
});
Phiên hoạt động
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);
});
Để xem các bản minh hoạ khác về Storage API, hãy khám phá bất kỳ mẫu nào sau đây:
Loại
AccessLevel
Cấp truy cập của khu vực lưu trữ.
Enum
"TRUSTED_CONTEXTS"
Chỉ định ngữ cảnh bắt nguồn từ chính tiện ích.
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Chỉ định ngữ cảnh bắt nguồn từ bên ngoài tiện ích.
StorageArea
Thuộc tính
-
onChanged
Sự kiện<functionvoidvoid>
Chrome 73 trở lênĐược kích hoạt khi một hoặc nhiều mục thay đổi.
Hàm
onChanged.addListener
có dạng như sau:(callback: function) => {...}
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(changes: object) => void
-
các thay đổi
đối tượng
-
-
-
xóa
void
Lời hứaXoá tất cả mục khỏi bộ nhớ.
Hàm
clear
có dạng như sau:(callback?: function) => {...}
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
-
returns
Lời hứa<vô hiệu>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
-
-
get
void
Lời hứaLấy một hoặc nhiều mục từ bộ nhớ.
Hàm
get
có dạng như sau:(keys?: string | string[] | object, callback?: function) => {...}
-
khoá
string | string[] | đối tượng không bắt buộc
Một khoá duy nhất cần lấy, danh sách các khoá cần lấy hoặc từ điển chỉ định các giá trị mặc định (xem nội dung mô tả về đối tượng). Danh sách hoặc đối tượng trống sẽ trả về một đối tượng kết quả trống. Truyền
null
để nhận toàn bộ nội dung của bộ nhớ. -
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(items: object) => void
-
items
đối tượng
Đối tượng có các mục trong mối liên kết khoá-giá trị.
-
-
returns
Promise<object>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
-
-
getBytesInUse
void
Lời hứaLấy dung lượng (tính bằng byte) mà một hoặc nhiều mục đang sử dụng.
Hàm
getBytesInUse
có dạng như sau:(keys?: string | string[], callback?: function) => {...}
-
khoá
string | string[] không bắt buộc
Một khoá hoặc danh sách các khoá để biết tổng mức sử dụng. Danh sách trống sẽ trả về 0. Truyền vào
null
để biết tổng mức sử dụng của toàn bộ bộ nhớ. -
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(bytesInUse: number) => void
-
bytesInUse
số
Dung lượng đang được sử dụng trong bộ nhớ, tính bằng byte.
-
-
returns
Promise<number>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
-
-
getKeys
void
Lời hứa Đang chờ xử lýLấy tất cả khoá từ bộ nhớ.
Hàm
getKeys
có dạng như sau:(callback?: function) => {...}
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(keys: string[]) => void
-
khoá
chuỗi[]
Mảng có các khoá được đọc từ bộ nhớ.
-
-
returns
Promise<string[]>
Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
-
-
xoá
void
Lời hứaXoá một hoặc nhiều mục khỏi bộ nhớ.
Hàm
remove
có dạng như sau:(keys: string | string[], callback?: function) => {...}
-
khoá
string | chuỗi[]
Một khoá hoặc một danh sách các khoá của các mục cần xoá.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
-
returns
Lời hứa<vô hiệu>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
-
-
đặt
void
Lời hứaĐặt nhiều mục.
Hàm
set
có dạng như sau:(items: object, callback?: function) => {...}
-
items
đối tượng
Đối tượng cung cấp cho mỗi cặp khoá/giá trị để cập nhật bộ nhớ. Mọi cặp giá trị/khoá khác trong bộ nhớ sẽ không bị ảnh hưởng.
Các giá trị ban đầu như số sẽ được chuyển đổi tuần tự như dự kiến. Các giá trị có
typeof
"object"
và"function"
thường sẽ chuyển đổi tuần tự thành{}
, ngoại trừArray
(chuyển đổi tuần tự như dự kiến),Date
vàRegex
(chuyển đổi tuần tự bằng cách sử dụng cách biểu diễnString
). -
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
-
returns
Lời hứa<vô hiệu>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
-
-
setAccessLevel
void
Lời hứa Chrome 102 trở lênĐặt cấp truy cập mong muốn cho khu vực lưu trữ. Tuỳ chọn mặc định sẽ chỉ là ngữ cảnh đáng tin cậy.
Hàm
setAccessLevel
có dạng như sau:(accessOptions: object, callback?: function) => {...}
-
accessOptions
đối tượng
-
accessLevel
Cấp truy cập của khu vực lưu trữ.
-
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
-
returns
Lời hứa<vô hiệu>
Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
-
StorageChange
Thuộc tính
-
newValue
bất kỳ không bắt buộc
Giá trị mới của mặt hàng, nếu có giá trị mới.
-
oldValue
bất kỳ không bắt buộc
Giá trị cũ của mặt hàng, nếu có giá trị cũ.
Thuộc tính
local
Các mục trong vùng lưu trữ local
sẽ là cục bộ trên mỗi máy.
Loại
StorageArea & đối tượng
Thuộc tính
-
QUOTA_BYTES
10485760
Dung lượng dữ liệu tối đa (tính bằng byte) có thể được lưu trữ trong bộ nhớ cục bộ, được đo bằng chuỗi JSON của mọi giá trị cộng với độ dài của mỗi khoá. Giá trị này sẽ bị bỏ qua nếu tiện ích có quyền
unlimitedStorage
. Các bản cập nhật sẽ khiến giới hạn này bị vượt quá sẽ không thành công ngay lập tức và đặtruntime.lastError
khi sử dụng lệnh gọi lại hoặc Lời hứa bị từ chối nếu sử dụng chế độ không đồng bộ/chờ.
managed
Các mục trong vùng lưu trữ của managed
được thiết lập theo một chính sách doanh nghiệp do quản trị viên miền thiết lập và ở chế độ chỉ có thể đọc đối với tiện ích; việc cố gắng sửa đổi không gian tên này sẽ dẫn đến lỗi. Để biết thông tin về cách định cấu hình một chính sách, hãy xem bài viết Tệp kê khai cho khu vực lưu trữ.
Loại
session
Các mục trong khu vực lưu trữ session
được lưu trữ trong bộ nhớ và sẽ không được lưu trữ trên ổ đĩa.
Loại
StorageArea & đối tượng
Thuộc tính
-
QUOTA_BYTES
10485760
Dung lượng dữ liệu tối đa (tính bằng byte) có thể được lưu trữ trong bộ nhớ, được đo bằng cách ước tính mức sử dụng bộ nhớ được phân bổ động cho mọi giá trị và khoá. Các bản cập nhật sẽ khiến việc vượt quá giới hạn này sẽ không thành công ngay lập tức và đặt
runtime.lastError
khi sử dụng lệnh gọi lại hoặc khi Lời hứa bị từ chối.
sync
Các mục trong khu vực lưu trữ sync
được đồng bộ hoá bằng tính năng Đồng bộ hoá Chrome.
Loại
StorageArea & đối tượng
Thuộc tính
-
MAX_ITEMS
512
Số lượng mục tối đa có thể được lưu trữ trong bộ nhớ đồng bộ hoá. Những nội dung cập nhật khiến việc vượt quá giới hạn này sẽ bị lỗi ngay lập tức và đặt giá trị
runtime.lastError
khi sử dụng lệnh gọi lại hoặc khi Lời hứa bị từ chối. -
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1000000
Không dùng nữaAPI Storage.sync không còn có hạn mức thao tác ghi duy trì.
-
MAX_WRITE_OPERATIONS_PER_HOUR
1800
Số lượng thao tác
set
,remove
hoặcclear
tối đa có thể thực hiện mỗi giờ. Cứ 2 giây là 1 lần, mức trần thấp hơn so với giới hạn ghi trên mỗi phút cao hơn trong thời gian ngắn.Các bản cập nhật sẽ khiến việc vượt quá giới hạn này sẽ không thành công ngay lập tức và đặt
runtime.lastError
khi sử dụng lệnh gọi lại hoặc khi Lời hứa bị từ chối. -
MAX_WRITE_OPERATIONS_PER_MINUTE
120
Số lượng thao tác
set
,remove
hoặcclear
tối đa có thể thực hiện mỗi phút. Tốc độ này là 2/giây, mang lại thông lượng cao hơn so với tốc độ ghi trên mỗi giờ trong một khoảng thời gian ngắn hơn.Các bản cập nhật sẽ khiến việc vượt quá giới hạn này sẽ không thành công ngay lập tức và đặt
runtime.lastError
khi sử dụng lệnh gọi lại hoặc khi Lời hứa bị từ chối. -
QUOTA_BYTES
102400
Tổng dung lượng dữ liệu tối đa (tính bằng byte) có thể lưu trữ trong bộ nhớ đồng bộ hoá, được đo bằng chuỗi JSON của mọi giá trị cộng với độ dài của mỗi khoá. Các bản cập nhật sẽ khiến việc vượt quá giới hạn này sẽ không thành công ngay lập tức và đặt
runtime.lastError
khi sử dụng lệnh gọi lại hoặc khi Lời hứa bị từ chối. -
QUOTA_BYTES_PER_ITEM
8192
Kích thước tối đa (tính bằng byte) của từng mục trong bộ nhớ đồng bộ hoá, được đo bằng chuỗi JSON cộng giá trị của mục đó cộng với độ dài khoá. Các bản cập nhật chứa các mục lớn hơn giới hạn này sẽ không thực hiện được ngay lập tức và đặt giá trị
runtime.lastError
khi sử dụng lệnh gọi lại hoặc khi Lời hứa bị từ chối.
Sự kiện
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
Được kích hoạt khi một hoặc nhiều mục thay đổi.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(changes: object, areaName: string) => void
-
các thay đổi
đối tượng
-
areaName
string
-