Chuyển đổi sang không gian tên trình duyệt

Kể từ Chrome 148, tất cả các API tiện ích của Chrome đều có trong không gian tên browser ngoài không gian tên chrome hiện có. Ví dụ: browser.tabs.create({}) và chrome.tabs.create({}) tương đương nhau.

Không gian tên này có ở bất cứ nơi nào bạn có thể gọi các API tiện ích, bao gồm cả tập lệnh nội dung, worker dịch vụ và tài liệu ngoài màn hình. Nó trỏ đến cùng một đối tượng API như chrome, vì vậy chrome.tabs === browser.tabs.

Vùng chứa tên browser là kết quả của công việc trong WebExtensions Community Group (WECG), một nhóm cộng đồng W3C nơi các nhà cung cấp trình duyệt cộng tác về các tiêu chuẩn mở rộng chung. Vùng chứa tên chrome sẽ không bị xoá; cả hai vùng chứa tên sẽ tiếp tục hoạt động.

Quyết định có nên áp dụng không gian tên trình duyệt hay không

Nếu bạn đang sử dụng webextension-polyfill, hãy bỏ qua và chuyển đến phần Lưu ý dành cho người dùng polyfill trước khi thay đổi bất kỳ nội dung nào khác – câu trả lời sẽ khác đối với bạn.

Nếu bạn đang tạo một tiện ích mới, hãy đặt minimum_chrome_version thành "148" và sử dụng browser vô điều kiện; bạn có thể dừng đọc tại đây. Phần còn lại của phần này dành cho các tiện ích hiện có đang quyết định cách áp dụng.

Kiểm tra xem người dùng của bạn đang dùng phiên bản Chrome nào

Nếu bạn có một tiện ích hiện có, hãy kiểm tra xem người dùng đang chạy phiên bản Chrome nào trước khi chuyển đổi. Chrome tự động cập nhật, nhưng một số người dùng tắt tính năng cập nhật và những người khác dùng các thiết bị cũ không chạy được phiên bản mới nhất. Xác nhận bằng dữ liệu phân tích của riêng bạn. Nếu bạn chưa thiết lập tính năng phân tích, hãy xem bài viết Theo dõi hiệu quả của tiện ích bằng Google Analytics 4 để bắt đầu.

Từ đó, hãy chọn một đường dẫn:

Áp dụng vô điều kiện

Đặt minimum_chrome_version trong tệp kê khai và sử dụng browser vô điều kiện – không cần biện pháp bảo vệ thời gian chạy:

{
  "minimum_chrome_version": "148"
}

Sử dụng tính năng phát hành theo giai đoạn khi tăng minimum_chrome_version. Nếu có vấn đề xảy ra, bạn có thể khôi phục phiên bản cũ của tiện ích trong Cửa hàng Chrome trực tuyến.

Sử dụng cơ chế bảo vệ thời gian chạy

Thêm đoạn mã sau vào đầu mã khởi động của tiện ích trước khi tham chiếu browser ở bất kỳ nơi nào khác:

if (!globalThis.browser) {
  globalThis.browser = chrome;
  // Consider firing an analytics event here to measure how often
  // your users hit this fallback path.
}

Điều này khiến browser trở thành một bí danh cho chrome trên các phiên bản trước, vì vậy, phần còn lại của mã có thể sử dụng browser vô điều kiện.

Lưu ý dành cho người dùng polyfill

Nếu tiện ích của bạn sử dụng webextension-polyfill, thì tiện ích đó sẽ không hoạt động trên Chrome 148 trở lên. Đoạn mã polyfill bỏ qua việc bao bọc khi browser đã được xác định, giả sử trình duyệt lưu trữ đã cung cấp API.

Trước đó, một nỗ lực chuyển không gian tên trong Chrome 136 đã bị huỷ bỏ vì lý do này: khi browser được xác định mới, polyfill đã ngừng bao bọc, nhưng browser.runtime.onMessage của Chrome chưa hỗ trợ các trình nghe trả về lời hứa mà polyfill đã cung cấp. Các tiện ích dựa vào mẫu đó đã bị hỏng. Chrome 148 sẽ cung cấp không gian tên và trình nghe onMessage trả về lời hứa gốc cùng nhau để tránh khoảng trống đó.

Bạn có thể xoá phần phụ thuộc polyfill sau khi cơ sở người dùng chuyển sang Chrome 148.

Tính năng khác

Phản hồi không đồng bộ trong runtime.sendMessage

Trong Chrome 148, các trình nghe runtime.onMessage có thể trả về trực tiếp một Promise để gửi phản hồi không đồng bộ. Điều này có hiệu lực cho dù bạn gọi bằng chrome.* hay browser.*.

Trước đây, cách duy nhất để phản hồi không đồng bộ là trả về một giá trị cố định true từ trình nghe và gọi sendResponse sau:

// Old pattern - requires returning true to keep the channel open
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  fetch('https://example.com')
    .then(response => sendResponse({ statusCode: response.status }));

  return true; // keeps the message channel open for the async response
});

Giờ đây, bạn có thể trả về Promise (hoặc dùng hàm async) trực tiếp:

// New pattern - return a promise or use async/await
browser.runtime.onMessage.addListener(async (message, sender) => {
  const response = await fetch('https://example.com');
  return { statusCode: response.status };
});

Mẫu return true vẫn hoạt động, nên bạn không cần thay đổi mã hiện có.