chrome.storage

Nội dung 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 (API Bộ nhớ) cung cấp một phương thức dành riêng cho tiện ích để lưu 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 tiện ích. Sau đây là một số 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 (API Bộ nhớ) 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 này 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 sử dụng chế độ ẩn danh phân tách.
• Bao gồm khu vực bộ nhớ được quản lý chỉ đọc cho các chính sách 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ố 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 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 sẽ chia sẻ dung lượng lưu trữ 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.

Để di chuyển dữ liệu từ API bộ nhớ trên web sang API bộ nhớ tiện ích từ trình chạy dịch vụ:

1. Tạo tài liệu ngoài màn hình có quy trình chuyển đổi và trình xử lý [onMessage][trên tin nhắn].
2. Thêm 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ụ tiện ích, hãy kiểm tra chrome.storage để xem 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 rồi 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ách hoạt động của API lưu trữ trên web trong tiện ích cũng có một số điểm khác biệt. Hãy tìm hiểu thêm trong bài viết [Bộ nhớ và cookie][bộ nhớ và cookie].

Khu vực lưu trữ

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

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 là khoảng 10 MB, nhưng bạn có thể tăng hạn mức này bằng cách yêu cầu quyền "unlimitedStorage". Hãy cân nhắc sử dụng API 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ậ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ạn tắt chính sách này, mã sẽ hoạt động như storage.local. Chrome lưu trữ dữ liệu cục bộ khi trình duyệt ở chế độ ngoại tuyến 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. Hãy cân nhắc sử dụng API này để lưu giữ 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 nên lưu trữ dữ liệu bí mật của người dùng 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 khu vực 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 một phiên trình duyệt. Theo mặc định, lớp 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 hạn mức là khoảng 10 MB. Hãy cân nhắc sử dụng thuộc tính này để lưu trữ các biến toàn cục trong các lần chạy trình chạy 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ể dùng một giản đồ và chính sách doanh nghiệp để thiết lập các 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ó thể đọc.

Tệp kê khai

Để sử dụng API lưu trữ, 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ạ khu vực 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ữ của managed, hãy xem bài viết Tệp kê khai cho khu vực lưu trữ.

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

Đừng coi việc thêm vào Storage API giống như việc đưa mọi thứ 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ư cho một thứ gì đó vào trong một ống. Đường ống có thể đã có vật liệu trong ống và thậm chí có thể được đổ đầy. Luôn giả định độ trễ tính từ khi bạn thêm vào bộ nhớ cho đến khi thực sự được ghi lại.

Để biết chi tiết về hạn mức bộ nhớ và điều gì 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 (API Bộ nhớ).

Phản hồi đồng bộ cho việc 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 cứ 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 tôi có thể đưa ý tưởng này hơn nữa. Trong ví dụ này, chúng tôi có một trang tuỳ chọn cho phép người dùng bật/tắt "chế độ gỡ lỗi" (cách triển khai không hiển thị ở đâ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 này 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 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ẽ sử dụng trình xử lý sự kiện action.onClicked không đồng bộ để chờ điền toàn bộ storageCache 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 của Storage API, hãy khám phá bất kỳ ví dụ nào sau đây:

• Tiện ích tìm kiếm chung.
• Tiện ích chuông báo nước.

Loại

AccessLevel

Chrome 102 trở lên

Cấp truy cập của khu vực lưu trữ.

Liệt kê

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

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

StorageArea

Thuộc tính

• onChanged

  Sự kiện<functionvoid>

  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 sẽ 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

  Cam kết

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

  Hàm clear sẽ 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

  • giá trị trả về

    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

  Cam kết

  Mua một hoặc nhiều mục từ bộ nhớ.

  Hàm get sẽ có dạng như sau:

  (keys?: string|string[]|object,callback?: function)=> {...}

  • khoá

    string|string[]|object optional

    Một khoá để 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 phần mô tả của đố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 để 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 liên kết khoá-giá trị.

  • giá trị trả về

    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

  Cam kết

  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 sẽ có dạng như sau:

  (keys?: string|string[],callback?: function)=> {...}

  • khoá

    string|string[] optional

    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ề 0. Truyền 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

      number

      Dung lượng đang được sử dụng trong bộ nhớ, tính bằng byte.

  • giá trị trả về

    Hứa hẹn<number>

    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.

• xoá

  void

  Cam kết

  Xoá một hoặc nhiều mục khỏi bộ nhớ.

  Hàm remove sẽ có dạng như sau:

  (keys: string|string[],callback?: function)=> {...}

  • khoá

    chuỗi|chuỗi[]

    Một khoá hoặc danh sách khoá của các mục có thể xoá.

  • số gọi lại

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

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

    ()=>void

  • giá trị trả về

    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.

• set

  void

  Cam kết

  Đặt nhiều mục.

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

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

  • items

    đố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ẽ 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 đại diện String của chúng).

  • số gọi lại

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

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

    ()=>void

  • giá trị trả về

    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

  Cam kết Chrome 102 trở lên

  Đặt cấp truy cập mong muốn cho khu vực lưu trữ. Theo mặc định, chỉ các ngữ cảnh đáng tin cậy.

  Hàm setAccessLevel sẽ có dạng như sau:

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

  • accessOptions

    đối tượng

    • accessLevel

      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

  • giá trị trả về

    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

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

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

• oldValue

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

  Giá trị cũ của mục (nếu từng có giá trị cũ).

Thuộc tính

local

Các mục trong khu vực lưu trữ của local là nội dung cục bộ trên từng máy.

Loại

StorageArea(Khu vực lưu trữ) 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ể đượ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. Những bản cập nhật khiến vượt quá giới hạn này sẽ không hoạt động ngay lập tức và đặt runtime.lastError khi sử dụng lệnh gọi lại hoặc một 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 khu vực lưu trữ managed do quản trị viên miền thiết lập theo 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 chính sách, hãy xem Tệp kê khai cho khu vực lưu trữ.

Loại

StorageArea

session

Chrome 102 trở lên MV3

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(Khu vực lưu trữ) và đố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 của mọi giá trị và khoá. Những bản cập nhật khiế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 một Promise 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(Khu vực lưu trữ) và đối tượng

Thuộc tính

• MAX_ITEMS

  512
  

  Số mục tối đa có thể lưu trữ được trong bộ nhớ đồng bộ hoá. Những bản cập nhật khiến vượt quá giới hạn này sẽ không thực hiện được ngay lập tức và đặt runtime.lastError khi sử dụng lệnh gọi lại hoặc khi một Promise bị từ chối.

• MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

  1000000
  

  Không dùng nữa

  API Storage.sync không còn có hạn mức tác vụ ghi được duy trì.

• MAX_WRITE_OPERATIONS_PER_HOUR

  1800
  

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

  Những bản cập nhật khiế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 một Promise bị từ chối.

• MAX_WRITE_OPERATIONS_PER_MINUTE

  120
  

  Số thao tác tối đa set, remove hoặc clear có thể thực hiện mỗi phút. Tốc độ này là 2 lần/giây, mang lại công suất cao hơn so với số lần ghi mỗi giờ trong khoảng thời gian ngắn hơn.

  Những bản cập nhật khiế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 một Promise 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ể được lưu trữ trong bộ nhớ đồng bộ hoá, được đo bằng cách tạo chuỗi JSON của mọi giá trị cộng với độ dài của mỗi khoá. Những bản cập nhật khiế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 một Promise 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ủa mục đó. Những 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 Promise 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ố

• 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