chrome.storage

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

API Bộ nhớ cung cấp một cách 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 bộ nhớ của nền tảng web (IndexedDB và Bộ nhớ), 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ả 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 API Bộ nhớ.
• 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ữ vẫn tồn tại ngay cả khi bạn sử dụng chế độ chia chế độ ẩn danh.
• Bao gồm một khu vực bộ nhớ đượ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ù 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:

• Worker 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ớ tiện ích từ một worker 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 worker dịch vụ 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, 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. 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 bộ nhớ web 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ữ

API Bộ nhớ được chia thành 4 nhóm ("khu vực bộ nhớ") sau:

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 hạn mức là khoảng 10 MB, nhưng bạn có thể tăng hạn mức bằng cách yêu cầu quyền "unlimitedStorage". Hãy cân nhắc sử dụng phương thức này để lưu trữ lượng dữ liệu lớn hơn.

Thận trọng: Trước Chrome 114, hạn mức là khoảng 5 MB.

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, thuộc tính 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ó 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 hạn mức là khoảng 100 KB, 8 KB cho mỗi mặt hàng. Hãy cân nhắc sử dụng tính năng này để duy trì chế độ cài đặt của người dùng trên các trình duyệt được đồng bộ hoá.

Cảnh báo: Bộ nhớ đồng bộ hoá và bộ nhớ cục bộ không được lưu trữ dữ liệu người dùng bảo mật vì các bộ nhớ này không được mã hoá. Khi xử lý 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

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, phần tử này không hiển thị với 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 là khoảng 10 MB. Hãy cân nhắc sử dụng phương thức này để lưu trữ các biến toàn cục trên các lần chạy worker dịch vụ.

Cảnh báo: Trước Chrome 112, hạn mức là khoảng 1 MB.

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 bộ nhớ này ở chế độ chỉ đọc.

Tệp kê khai

Để sử dụng API bộ nhớ, 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 phần Tệp kê khai cho vùng lưu trữ.

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

Đừng nghĩ việc thêm vào API Bộ nhớ giống như việc đặt đồ đạc vào 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 đặt một vật gì đó vào một ống. Ống có thể đã chứa vật liệu và thậm chí có thể đã được lấp đầ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 giới hạn về vùng bộ nhớ và những việc sẽ 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 của API Bộ nhớ.

Phản hồi đồng bộ đối với nội dung cập nhật về 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. 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 hiển thị cách triển khai tại đây). Trang tuỳ chọn sẽ lưu ngay chế độ cài đặt mới vào storage.sync và worker 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ì worker dịch vụ không phải lúc nào cũng chạy, nên các tiện ích Manifest V3 đôi khi 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ờ điền sẵn storageCache toàn cục trước khi thực thi logic của trình xử lý đó.

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ề phần mở rộng

Để xem các bản minh hoạ khác về API Bộ nhớ, 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 chuông báo ngập nước.

Loại

AccessLevel

Chrome 102 trở lên

Cấp truy cập của vùng 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

  Event<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) => {...}

  • lệnh gọi lại

    hàm

    Tham số callback có dạng như sau:

    (changes: object) => void

    • các thay đổi

      đối tượng

• xóa

  void

  Promise

  Xoá tất cả các mục khỏi bộ nhớ.

  Hàm clear có dạng như sau:

  (callback?: function) => {...}

  • lệnh gọi lại

    hàm không bắt buộc

    Tham số callback có dạng như sau:

    () => void

  • returns

    Promise<void>

    Chrome 88 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

• get

  void

  Promise

  Lấ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[] | object không bắt buộc

    Một khoá duy nhất cần lấy, danh sách khoá cần lấy hoặc một 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 vào null để lấy toàn bộ nội dung của bộ nhớ.

  • lệnh gọi lại

    hàm không bắt buộc

    Tham số callback có dạng như sau:

    (items: object) => void

    • mục

      đố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ên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

• getBytesInUse

  void

  Promise

  Lấ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 khoá để biết tổng mức sử dụng. Danh sách trống sẽ trả về giá trị 0. Truyền vào null để nhận tổng mức sử dụng của tất cả bộ nhớ.

  • lệnh gọi lại

    hàm không bắt buộc

    Tham số callback 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<số>

    Chrome 88 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

• getKeys

  void

  Lời hứa Chrome 130 trở lên

  Lấy tất cả khoá từ bộ nhớ.

  Hàm getKeys có dạng như sau:

  (callback?: function) => {...}

  • lệnh gọi lại

    hàm không bắt buộc

    Tham số callback có dạng như sau:

    (keys: string[]) => void

    • khoá

      string[]

      Mảng có các khoá được đọc từ bộ nhớ.

  • returns

    Promise<string[]>

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

• xoá

  void

  Promise

  Xoá 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 | string[]

    Một khoá hoặc danh sách khoá cho các mục cần xoá.

  • lệnh gọi lại

    hàm không bắt buộc

    Tham số callback có dạng như sau:

    () => void

  • returns

    Promise<void>

    Chrome 88 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

• đặt

  void

  Promise

  Đặt nhiều mục.

  Hàm set có dạng như sau:

  (items: object, callback?: function) => {...}

  • mục

    đối tượng

    Một đối tượng cung cấp cho mỗi cặp khoá/giá trị để cập nhật bộ nhớ. Mọi cặp khoá/giá trị khác trong bộ nhớ sẽ không bị ảnh hưởng.

    Các giá trị gốc 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 bản trình bày String).

  • lệnh gọi lại

    hàm không bắt buộc

    Tham số callback có dạng như sau:

    () => void

  • returns

    Promise<void>

    Chrome 88 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng 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 vùng bộ nhớ. Chế độ 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

      AccessLevel

      Cấp truy cập của vùng bộ nhớ.

  • lệnh gọi lại

    hàm không bắt buộc

    Tham số callback có dạng như sau:

    () => void

  • returns

    Promise<void>

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

StorageChange

Thuộc tính

• newValue

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

  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 nào

  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
  

  Số 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 việc chuyển đổi 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ẽ ngay lập tức không thành công 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 chế độ không đồng bộ/chờ.

managed

Các mục trong vùng bộ nhớ managed được đặt theo chính sách doanh nghiệp do quản trị viên miền định cấu hình và 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 bộ nhớ.

Loại

StorageArea

sync

Các mục trong vùng lưu trữ sync được đồng bộ hoá bằng Chrome Sync.

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 bạn 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_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.

• MAX_WRITE_OPERATIONS_PER_HOUR

  1800
  

  Số lượng tối đa các thao tác set, remove hoặc clear có thể thực hiện mỗi giờ. Tức là 1 lần mỗi 2 giây, thấp hơn giới hạn số lượt ghi mỗi phút 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ẽ ngay lập tức không thành công 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 tối đa các thao tác set, remove hoặc clear có thể thực hiện mỗi phút. Tốc độ này là 2 lượt/giây, mang lại băng thông cao hơn so với số lượt ghi/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ẽ ngay lập tức không thành công 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 việc chuyển đổi 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 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 cách chuyển đổi giá trị của mục đó thành chuỗi JSON cộng với độ dài khoá của mục đó. 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 một 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ố

• lệnh gọi lại

  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