Các tiện ích Manifest V2 đã bị gỡ khỏi Cửa hàng Chrome trực tuyến vào ngày 31 tháng 8 năm 2026. Hãy di chuyển tiện ích của bạn sang Manifest V3 để người dùng có thể sử dụng lại tiện ích.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

chrome.storage

refresh date: 2026-09-25 robots: noindex

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

Tổng quan

Storage API cung cấp một cách thức dành riêng cho tiện ích để lưu 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 tiện ích. Sau đây là một số tính năng chính:

Tất cả bối cảnh của tiện ích, bao gồm cả trình chạy dịch vụ của 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ị có thể chuyển đổi tuần tự JSON đượ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 được lưu giữ.
Chế độ cài đặt đã lưu vẫn được giữ nguyên ngay cả khi sử dụng chế độ ẩn danh phân tách.
Bao gồm một vùng lưu trữ được quản lý chỉ có thể đọc dành riêng cho các chính sách của doanh nghiệp.

Mặc dù tiện ích có thể sử dụng giao diện [Storage][mdn-storage] (có thể truy cập từ window.localStorage) trong một số bối 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ụ của tiện ích không thể truy cập vào Storage.
Tập lệnh nội dung dùng chung bộ nhớ với trang lưu trữ.
Dữ liệu được lưu bằng giao diện Storage 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 bộ nhớ web sang API bộ nhớ tiện ích từ một trình chạy dịch vụ:

Tạo một tài liệu ngoài màn hình bằng quy trình chuyển đổi và trình xử lý [onMessage][on-message].
Thêm quy trình chuyển đổi vào tài liệu ngoài màn hình.
Trong trình chạy dịch vụ của 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 [tạo][create-offscreen] một tài liệu ngoài màn hình và gọi [sendMessage()][send-message] để 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 về cách hoạt động của API lưu trữ web trong tiện ích. Tìm hiểu thêm trong bài viết [Bộ nhớ và cookie][storage-and-cookies].

Khu vực lưu trữ

Storage API được chia thành 4 bộ chứa sau ("vùng lưu trữ"):

storage.local: Dữ liệu được lưu trữ cục bộ và sẽ bị xoá khi tiện ích bị xoá. Hạn mức là khoảng 10 MB, nhưng có thể tăng lên bằng cách yêu cầu quyền "unlimitedStorage". Hãy cân nhắc sử dụng Room để lưu trữ lượng dữ liệu lớn hơn.

storage.sync: Nếu bạn bật tính năng đồng bộ hoá, dữ liệu sẽ được đồng bộ hoá với mọi trình duyệt Chrome mà người dùng đã đăng nhập. Nếu bị tắt, chính sách này 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ó mạng và tiếp tục đồng bộ hoá khi có mạng trở lại. Hạn mức là khoảng 100 KB, 8 KB cho mỗi mục. Hãy cân nhắc sử dụng API này để duy trì chế độ cài đặt của người dùng trên các trình duyệt đã đồng bộ hoá.

Cảnh báo: Khu vực lưu trữ cục bộ và đồng bộ hoá không được lưu trữ dữ liệu người dùng bí mật vì chúng không được mã hoá. Khi làm việc với dữ liệu nhạy cảm, hãy cân nhắc sử dụng vùng lưu trữ session để lưu giữ các giá trị trong bộ nhớ cho đến khi trình duyệt tắt.

storage.session: Lưu giữ dữ liệu trong bộ nhớ trong suốt thời gian của một phiên trình duyệt. Theo mặc định, API này không được hiển thị cho 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(). Hạn mức là khoảng 10 MB. Hãy cân nhắc sử dụng API này để lưu trữ các biến toàn cục trong các lần chạy của trình chạy dịch vụ.

storage.managed: Quản trị viên có thể sử dụng giản đồ và chính sách doanh nghiệp để định cấu hình chế độ cài đặt của tiện ích hỗ trợ trong môi trường được quản lý. Khu vực lưu trữ này ở chế độ chỉ đọc.

Tệp kê khai

Để sử dụng API bộ nhớ, hãy khai báo quyền "storage" trong manifest của tiện ích. Ví dụ:

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

Cách sử dụng

Các mẫu sau đây minh hoạ các vùng lưu trữ local, sync và session:

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);
});

Để tìm hiểu thêm về khu vực lưu trữ managed, hãy xem phần Khai báo cho khu vực lưu trữ.

Giới hạn về bộ nhớ và điều tiết

Đừng nghĩ rằng việc thêm vào Storage API giống như việc chất đồ lên một chiếc xe tải lớn. Hãy coi việc thêm vào bộ nhớ giống như việc đưa một thứ gì đó vào đường ống. Ống có thể đã có sẵn vật liệu, thậm chí có thể đã đầy. Luôn giả định rằng có độ trễ giữa thời điểm bạn thêm vào bộ nhớ và thời điểm dữ liệu thực sự được ghi lại.

Để biết thông tin chi tiết về các giới hạn của vùng lưu trữ và những gì xảy ra khi vượt quá giới hạn, 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ộ cho các bản cập nhật bộ nhớ

Để theo dõi các thay đổi đối với bộ nhớ, bạn có thể thêm trình nghe vào sự kiện onChanged của bộ nhớ. Khi có bất kỳ thay đổi nào trong bộ nhớ, sự kiện đó sẽ kích hoạt. Mã mẫu sẽ 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 ta có thể phát triển ý tưởng này hơn nữa. Trong ví dụ này, chúng ta có một trang tuỳ chọn cho phép người dùng bật/tắt "chế độ gỡ lỗi" (không hiển thị cách triển khai ở đây). Trang tuỳ chọn sẽ lưu ngay các chế độ 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 chế độ 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 các tiện ích Manifest V3 cần tải dữ liệu không đồng bộ từ bộ nhớ trước khi thực thi trình xử lý sự kiện. Để thực hiện việc này, đoạn mã sau đây sử dụng trình xử lý sự kiện action.onClicked không đồng bộ, chờ biến toàn cục storageCache được điền sẵn trước khi thực thi logic của biế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ụ về tiện ích

Để xem các bản minh hoạ khác về Storage API, hãy khám phá bất kỳ ví dụ nào sau đây:

Loại

AccessLevel

Chrome 102 trở lên

Cấp truy cập của khu vực kho hàng.

Enum

"TRUSTED_CONTEXTS"
Chỉ định bối cảnh bắt nguồn từ chính tiện ích.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Chỉ định các bối cảnh bắt nguồn từ bên ngoài tiện ích.

StorageChange

Thuộc tính

newValue

bất kỳ không bắt buộc

Giá trị mới của mục, nếu có giá trị mới.
oldValue

bất kỳ không bắt buộc

Giá trị cũ của mục, nếu có giá trị cũ.

Thuộc tính

local

Các mục trong vùng lưu trữ local là cục bộ cho mỗi máy.

Loại

StorageArea và đối tượng

Thuộc tính

QUOTA_BYTES

10485760

Lượng dữ liệu tối đa (tính bằng byte) có thể 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 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à đặt runtime.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 async/await.

managed

Các mục trong vùng lưu trữ managed do chính sách doanh nghiệp mà quản trị viên miền định cấu hình đặt và là mục 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 chính sách, hãy xem phần Tệp kê khai cho vùng lưu trữ.

Loại

StorageArea

sync

Các mục trong vùng lưu trữ sync được đồng bộ hoá bằng tính năng Đồng bộ hoá Chrome.

Loại

StorageArea và đối tượng

Thuộc tính

MAX_ITEMS

512

Số lượng mục tối đa có thể lưu trữ trong bộ nhớ đồng bộ hoá. Các bản cập nhật 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à đặ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_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

1000000

Không dùng nữa

API storage.sync không còn hạn mức hoạt động ghi liên tục nữa.
MAX_WRITE_OPERATIONS_PER_HOUR

1800

Số lượng thao tác set, remove hoặc clear tối đa có thể thực hiện mỗi giờ. Tức là 1 lần mỗi 2 giây, mức trần thấp hơn giới hạn số lượt ghi mỗi phút cao hơn trong thời gian ngắn.

Các bản cập nhật 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à đặ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ặc clear tối đa có thể thực hiện mỗi phút. Tức là 2 lượt ghi mỗi giây, mang lại thông lượng cao hơn so với số lượt ghi mỗi giờ trong một khoảng thời gian ngắn hơn.

Các bản cập nhật 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à đặ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 lượng dữ liệu tối đa (tính bằng byte) có thể được 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 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à đặ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 riêng lẻ trong bộ nhớ đồng bộ hoá, được đo bằng chuỗi JSON của giá trị 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à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.

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.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(changes: object, areaName: string) => void
```
- các thay đổi
  
  đối tượng
- areaName
  
  chuỗi

chrome.storage Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mô tả

Quyền

Tổng quan

Khu vực lưu trữ

Tệp kê khai

Cách sử dụng

storage.local

storage.sync

storage.session

Giới hạn về bộ nhớ và điều tiết

Trường hợp sử dụng

Phản hồi đồng bộ cho các bản cập nhật bộ nhớ

Tải trước không đồng bộ từ bộ nhớ

Ví dụ về tiện ích

Loại

AccessLevel

Enum

StorageChange

Thuộc tính

Thuộc tính

local

Loại

Thuộc tính

managed

Loại

sync

Loại

Thuộc tính

Sự kiện

onChanged

Thông số

chrome.storage