Cập nhật mã

Nội dung cập nhật không liên quan đến các vấn đề khác

Đây là phần đầu tiên trong ba phần mô tả các thay đổi cần thiết đối với mã không phải là một phần của worker mở rộng. Phần này dành cho các thay đổi bắt buộc về mã mà không liên quan đến các vấn đề khác. Hai phần tiếp theo đề cập đến việc thay thế cho yêu cầu web và cách cải thiện tính bảo mật.

Thay thế tab.ExecScript() bằng Scripts.ExecutionScript()

Trong Manifest V3, executeScript() chuyển từ API tabs sang API scripting. Việc này yêu cầu thay đổi quyền trong tệp kê khai ngoài những thay đổi thực tế về mã.

Đối với phương thức executeScript(), bạn cần:

  • Quyền "scripting".
  • Quyền của máy chủ hoặc quyền "activeTab".

Phương thức scripting.executeScript() tương tự như cách đã hoạt động với tabs.executeScript(). Có một số điểm khác biệt.

  • Mặc dù phương thức cũ chỉ có thể lấy một tệp, nhưng phương thức mới có thể lấy một mảng tệp.
  • Bạn cũng truyền đối tượng ScriptInjection thay vì InjectDetails. Có nhiều điểm khác biệt giữa hai công cụ này. Ví dụ: tabId hiện được chuyển dưới dạng thành phần của ScriptInjection.target thay vì dưới dạng đối số phương thức.

Ví dụ cho thấy cách thực hiện việc này.

Tệp kê khai V2
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

chrome.tabs.executeScript(
  tab.id,
  {
    file: 'content-script.js'
  }
);

Trong tệp tập lệnh nền.

Tệp kê khai V3
async function getCurrentTab()
let tab = await getCurrentTab();

chrome.scripting.executeScript({
  target: {tabId: tab.id},
  files: ['content-script.js']
});

Trong trình chạy dịch vụ tiện ích.

Thay thế tab.insertCSS() và tab.removeCSS() bằng Script.insertCSS() và−script.removeCSS()

Trong Manifest V3, insertCSS() và removeCSS() di chuyển từ API tabs sang API scripting. Việc này yêu cầu thay đổi quyền trong tệp kê khai ngoài việc thay đổi mã:

  • Quyền "scripting".
  • Quyền của máy chủ hoặc quyền "activeTab".

Các hàm trên API scripting tương tự như các hàm trên tabs. Có một số điểm khác biệt.

  • Khi gọi các phương thức này, bạn sẽ truyền đối tượng CSSInjection thay vì InjectDetails.
  • tabId hiện được truyền dưới dạng thành phần của CSSInjection.target thay vì dưới dạng đối số phương thức.

Ví dụ cho thấy cách thực hiện việc này đối với insertCSS(). Quy trình cho removeCSS() cũng tương tự.

Tệp kê khai V2
chrome.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

Trong tệp tập lệnh nền.

Tệp kê khai V3
const insertPromise = await chrome.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code.

Trong trình chạy dịch vụ tiện ích.

Thay thế Hành động trên trình duyệt và Hành động trên trang bằng Hành động

Các thao tác trên trình duyệt và thao tác trên trang là hai khái niệm riêng biệt trong Manifest V2. Mặc dù họ bắt đầu với những vai trò riêng biệt, nhưng sự khác biệt giữa hai vai trò này đã giảm dần theo thời gian. Trong Manifest V3, các khái niệm này được hợp nhất vào API Action. Để thực hiện thao tác này, bạn phải thay đổi manifest.json và mã tiện ích khác với mã bạn đã đặt trong tập lệnh nền Manifest V2.

Các thao tác trong Manifest V3 giống với các thao tác trên trình duyệt nhất; tuy nhiên, action API không cung cấp hide() và show() như pageAction đã làm. Nếu vẫn cần các thao tác trên trang, bạn có thể mô phỏng các thao tác đó bằng cách sử dụng nội dung khai báo hoặc gọi enable() hoặc disable() bằng mã thẻ.

Thay thế "browser_action" và "page_action" bằng "action"

Trong manifest.json, hãy thay thế các trường "browser_action" và "page_action" bằng trường "action". Hãy tham khảo thông tin về trường "action".

Tệp kê khai V2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
Tệp kê khai V3
{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

Thay thế các API browserAction và pageAction bằng API hành động

Nếu Manifest V2 của bạn sử dụng API browserAction và pageAction thì giờ đây bạn nên sử dụng API action.

Tệp kê khai V2
chrome.browserAction.onClicked.addListener(tab => { ... });
chrome.pageAction.onClicked.addListener(tab => { ... });
Tệp kê khai V3
chrome.action.onClicked.addListener(tab => { ... });

Thay thế lệnh gọi lại bằng lời hứa

Trong Manifest V3, nhiều phương thức API tiện ích trả về lời hứa. Promise là một proxy hoặc phần giữ chỗ cho một giá trị được phương thức không đồng bộ trả về. Nếu chưa từng sử dụng Lời hứa, bạn có thể đọc về Lời hứa trên MDN. Trang này mô tả những điều bạn cần biết để sử dụng tiện ích trong tiện ích của Chrome.

Để có khả năng tương thích ngược, nhiều phương thức tiếp tục hỗ trợ lệnh gọi lại sau khi thêm tính năng hỗ trợ cam kết. Xin lưu ý rằng bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Nếu bạn truyền một hàm gọi lại, hàm sẽ không trả về một lời hứa và nếu bạn muốn một lời hứa được trả về thì không truyền một lệnh gọi lại. Một số tính năng API, chẳng hạn như trình nghe sự kiện, sẽ tiếp tục yêu cầu gọi lại. Để kiểm tra xem một phương thức có hỗ trợ lời hứa hay không, hãy tìm nhãn "Promise" trong tài liệu tham khảo API của phương thức đó.

Để chuyển đổi từ lệnh gọi lại thành lời hứa, hãy xoá lệnh gọi lại và xử lý lời hứa được trả về. Ví dụ bên dưới được lấy từ mẫu cấp quyền không bắt buộc, cụ thể là newtab.js. Phiên bản gọi lại cho thấy lệnh gọi của mẫu tới request() sẽ trông như thế nào khi sử dụng một lệnh gọi lại. Lưu ý rằng bạn có thể viết lại phiên bản lời hứa bằng chế độ không đồng bộ và chờ.

Số nhận cuộc gọi lại
chrome.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Lời hứa
const newPerms = { permissions: ['topSites'] };
chrome.permissions.request(newPerms)
.then((granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

Thay thế các hàm yêu cầu ngữ cảnh nền Manifest V2

Các ngữ cảnh tiện ích khác chỉ có thể tương tác với trình thực thi dịch vụ tiện ích bằng cách sử dụng tính năng truyền thông báo. Do đó, bạn sẽ cần thay thế các lệnh gọi yêu cầu ngữ cảnh ở chế độ nền, cụ thể là:

  • chrome.runtime.getBackgroundPage()
  • chrome.extension.getBackgroundPage()
  • chrome.extension.getExtensionTabs()

Tập lệnh tiện ích phải sử dụng tính năng truyền thông báo để giao tiếp giữa một trình chạy dịch vụ và các phần khác của tiện ích. Hiện tại, bạn phải sử dụng sendMessage() và triển khai chrome.runtime.onMessage trong trình chạy dịch vụ tiện ích. Về lâu dài, bạn nên lên kế hoạch thay thế các lệnh gọi này bằng postMessage() và trình xử lý sự kiện tin nhắn của trình chạy dịch vụ.

Thay thế các API không được hỗ trợ

Các phương thức và thuộc tính nêu dưới đây cần phải thay đổi trong Manifest V3.

Phương thức hoặc thuộc tính của Manifest V2 Thay thế bằng
chrome.extension.connect() chrome.runtime.connect()
chrome.extension.connectNative() chrome.runtime.connectNative()
chrome.extension.getExtensionTabs() chrome.extension.getViews()
chrome.extension.getURL() chrome.runtime.getURL()
chrome.extension.lastError Khi các phương thức trả về lời hứa, hãy sử dụng promise.catch()
chrome.extension.onConnect chrome.runtime.onConnect
chrome.extension.onConnectExternal chrome.runtime.onConnectExternal
chrome.extension.onMessage chrome.runtime.onMessage
chrome.extension.onRequest chrome.runtime.onMessage
chrome.extension.onRequestExternal chrome.runtime.onMessageExternal
chrome.extension.sendMessage() chrome.runtime.sendMessage()
chrome.extension.sendNativeMessage() chrome.runtime.sendNativeMessage()
chrome.extension.sendRequest() chrome.runtime.sendMessage()
chrome.runtime.onSuspend (tập lệnh nền) Không được hỗ trợ trong trình chạy dịch vụ tiện ích. Thay vào đó, hãy sử dụng sự kiện tài liệu beforeunload.
chrome.tabs.getAllInWindow() chrome.tabs.query()
chrome.tabs.getSelected() chrome.tabs.query()
chrome.tabs.onActiveChanged chrome.tabs.onActivated
chrome.tabs.onHighlightChanged chrome.tabs.onHighlighted
chrome.tabs.onSelectionChanged chrome.tabs.onActivated
chrome.tabs.sendRequest() chrome.runtime.sendMessage()
chrome.tabs.Tab.selected chrome.tabs.Tab.highlighted