chrome.storage

refresh date: 2026-09-25 robots: noindex

Mô tả

Quyền

Tổng quan

Storage API cung cấp một cách thức dành riêng cho tiện ích để duy trì dữ liệu người dùng và trạng thái. 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 số tính năng chính:

• Tất cả các ngữ cảnh 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ị 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 là 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ữ.
• Các chế độ cài đặt đã lưu trữ vẫn được giữ nguyên ngay cả khi bạn sử dụng chế độ ẩn danh chia đôi.
• Bao gồm một vùng lưu trữ được quản lý chỉ đọc dành riêng cho các chính sách của doanh nghiệp.

Mặc dù các 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ố 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ụ của tiện ích không thể truy cập vào Storage.
• Tập lệnh nội dung chia sẻ 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ớ của tiện ích từ một trình chạy dịch vụ:

1. Tạo một tài liệu ngoài màn hình bằng một quy trình chuyển đổi và trình xử lý [onMessage][on-message].
2. Thêm một quy trình chuyển đổi vào tài liệu ngoài màn hình.
3. Trong trình chạy dịch vụ của tiện ích, hãy kiểm tra chrome.storage để biết dữ liệu của bạn.
4. Nếu không tìm thấy dữ liệu của bạn, 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.
5. 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ó một số điểm khác biệt về cách các API lưu trữ trên web hoạt động trong các 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 nhóm ("vùng lưu trữ") sau đây:

storage.local

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

storage.sync

Nếu tính năng đồng bộ hoá được bật, 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ị vô hiệu hoá, nó sẽ hoạt động như storage.local. Chrome lưu trữ dữ liệu cục 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 tính năng này để giữ nguyên chế độ cài đặt của người dùng trên các trình duyệt đã đồng bộ hoá.

storage.session

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

storage.managed

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

Tệp kê khai

Để sử dụng Storage API, hãy khai báo quyền "storage" trong tệp kê khai 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ề vùng lưu trữ managed, hãy xem bài viết Tệp kê khai cho các vùng lưu trữ.

Hạn mức bộ nhớ và hạn mức điều tiết

Đừng nghĩ việc thêm vào Storage API giống như việc đặt đồ vào một chiếc xe tải lớn. Hãy xem việc thêm vào bộ nhớ giống như việc đặt một thứ gì đó vào đường ống. Ống có thể đã có vật liệu bên trong và thậm chí có thể đã đầy. Luôn giả định 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 hạn chế đối với vùng lưu trữ và những việc xảy ra khi vượt quá hạn mức, hãy xem thông tin về hạn mức của 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ộ đối với nội dung cập nhật bộ nhớ

Để theo dõi các thay đổi đối với bộ nhớ, bạn có thể thêm một 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 này:

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ể tiến xa hơn nữa với ý tưởng này. 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" (chưa 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ẽ dùng storage.onChanged để áp dụng chế độ cài đặt này trong thời gian 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ì các worker 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 một trình xử lý sự kiện action.onClicked không đồng bộ, chờ storageCache toàn cục được điền sẵ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ụ 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:

• Tiện ích tìm kiếm toàn cầu.
• Tiện ích cảnh báo nước.

chrome.storage.onChanged.addListener(
  callback: function,
)