chrome.storage

Mô tả

Quyền

Để 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"
  ],
  ...
}

Ví dụ

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

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

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

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value is 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:

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

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 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 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.

Tiện ích có thể sử dụng các API bộ nhớ trên web không?

Mặc dù các 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 chúng tôi không khuyến khích bạ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ể sử dụng Web Storage API.
• 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 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 bộ nhớ web sang API bộ nhớ tiện ích từ một worker dịch vụ:

1. Chuẩn bị một trang HTML và tệp kịch bản cho 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.
2. Trong worker dịch vụ của tiện ích, hãy kiểm tra chrome.storage để biết dữ liệu của bạn.
3. Nếu không tìm thấy dữ liệu của bạn, hãy gọi createDocument().
4. Sau khi Promise được trả về phân giải, hãy gọi sendMessage() để 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 hoạt động của các API bộ nhớ trên web trong tiện ích. Tìm hiểu thêm trong bài viết Bộ nhớ và cookie.

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

Storage API có những hạn chế về việc sử dụng:

• Việc lưu trữ dữ liệu có thể ảnh hưởng đến hiệu suất và API này có hạn mức lưu trữ. Lập kế hoạch cho dữ liệu mà bạn dự định lưu trữ để duy trì dung lượng lưu trữ.
• Quá trình lưu trữ có thể mất một chút thời gian để hoàn tất. Cấu trúc mã của bạn để tính đến thời gian đó.

Để biết thông tin chi tiết về các hạn chế đối với dung lượng lưu trữ và những việc sẽ xảy ra khi bạn vượt quá hạn mức, hãy xem thông tin hạn mức của sync, local và session.

Khu vực lưu trữ

Storage API được chia thành các vùng lưu trữ sau:

Địa phương

Dữ liệu được lưu trữ cục bộ và sẽ bị xoá khi bạn xoá tiện ích. Giới hạn bộ nhớ là 10 MB (5 MB trong Chrome 113 trở xuống), nhưng bạn có thể tăng giới hạn này bằng cách yêu cầu quyền "unlimitedStorage". Bạn nên dùng storage.local để lưu trữ lượng dữ liệu lớn hơn. Theo mặc định, API này được cung cấp 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 gọi chrome.storage.local.setAccessLevel().

Được quản lý

Bộ nhớ được quản lý ở chế độ chỉ đọc đối với các tiện ích do chính sách cài đặt. Thư mục này do quản trị viên hệ thống quản lý, sử dụng giản đồ do nhà phát triển xác định và các chính sách của doanh nghiệp. Các chính sách tương tự như các lựa chọn nhưng do quản trị viên hệ thống định cấu hình thay vì người dùng. Nhờ đó, tiện ích có thể được định cấu hình trước cho tất cả người dùng trong một tổ chức.

Theo mặc định, storage.managed sẽ đượ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 gọi chrome.storage.managed.setAccessLevel(). Để 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ề 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ữ.

Phiên

Bộ nhớ phiên lưu trữ dữ liệu trong bộ nhớ trong khi tiện ích được tải. Bộ nhớ sẽ bị xoá nếu tiện ích bị vô hiệu hoá, tải lại, cập nhật và khi trình duyệt khởi động lại. 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 gọi chrome.storage.session.setAccessLevel(). Giới hạn bộ nhớ là 10 MB (1 MB trong Chrome 111 trở xuống).

Giao diện storage.session là một trong số những giao diện mà chúng tôi đề xuất cho các worker dịch vụ.

Đồng bộ hoá

Nếu người dùng bật tính năng đồng bộ hoá, thì dữ liệu sẽ đồ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ó kết nối mạng và tiếp tục đồng bộ hoá khi có kết nối mạng trở lại. Hạn mức là khoảng 100 KB, 8 KB cho mỗi mục.

Bạn nên sử dụng storage.sync để lưu giữ các chế độ cài đặt của người dùng trên các trình duyệt được đồ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ụng storage.session. Theo mặc định, storage.sync sẽ đượ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 gọi chrome.storage.sync.setAccessLevel().

Phương thức và sự kiện

Tất cả các khu vực lưu trữ đều triển khai giao diện StorageArea.

get()

Phương thức get() cho phép bạn đọc một hoặc nhiều khoá từ StorageArea.

getBytesInUse()

Phương thức getBytesInUse() cho phép bạn xem hạn mức mà một StorageArea đã sử dụng.

getKeys()

Phương thức getKeys() cho phép bạn lấy tất cả các khoá được lưu trữ trong StorageArea.

remove()

Phương thức remove() cho phép bạn xoá một mục khỏi StorageArea.

set()

Phương thức set() cho phép bạn đặt một mục trong StorageArea.

setAccessLevel()

Phương thức setAccessLevel() cho phép bạn kiểm soát quyền truy cập vào một StorageArea.

clear()

Phương thức clear() cho phép bạn xoá tất cả dữ liệu khỏi một StorageArea.

onChanged

Sự kiện onChanged cho phép bạn theo dõi các thay đổi đối với StorageArea.

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 thông tin cập nhật về 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 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ể 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 minh hoạ 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ẽ 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 chạy liên tục, 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);
});

Công cụ cho nhà phát triển

Bạn có thể xem và chỉnh sửa dữ liệu được lưu trữ bằng API trong Công cụ cho nhà phát triển. Để tìm hiểu thêm, hãy xem trang Xem và chỉnh sửa bộ nhớ của tiện ích trong tài liệu về Công cụ cho nhà phát triển.

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