Cập nhật mã

Thông tin cập nhật không liên quan đến các vấn đề khác

Đây là phần đầu tiên trong số ba phần mô tả những thay đổi cần thiết đối với mã không thuộc trình chạy dịch vụ của tiện ích. Phần này dành cho những thay đổi bắt buộc về 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ế các yêu cầu web bị chặn và cải thiện tính bảo mật.

Thay thế tabs.executeScript() bằng scripting.executeScript()

Trong Manifest V3, executeScript() chuyển từ API tabs sang API scripting. Điều này đòi hỏi bạn phải thay đổi các quyền trong tệp kê khai ngoài việc thay đổi mã thực tế.

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

  • Quyền "scripting".
  • Quyền của máy chủ lưu trữ 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 vài đ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 một đối tượng ScriptInjection thay vì InjectDetails. Có nhiều điểm khác biệt giữa hai loại này. Ví dụ: tabId hiện được truyền dưới dạng một thành viên của ScriptInjection.target thay vì dưới dạng đối số phương thức.

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

Manifest V2
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

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

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

Manifest V3
async function getCurrentTab()
let tab = await getCurrentTab();

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

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

Thay thế tabs.insertCSS() và tabs.removeCSS() bằng scripting.insertCSS() và scripting.removeCSS()

Trong Manifest V3, insertCSS() và removeCSS() 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ủ lưu trữ 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 vài điểm khác biệt.

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

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

Manifest V2
browser.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

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

Manifest V3
const insertPromise = await browser.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code.

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

Thay thế Thao tác trên trình duyệt và Thao tác trên trang bằng Thao tác

Thao tác trên trình duyệt và thao tác trên trang là các khái niệm riêng biệt trong Manifest V2. Mặc dù ban đầu có 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. Việc này đòi hỏi bạn phải thay đổi mã trong manifest.json và tiện ích, khác với những gì bạn đã đưa vào tập lệnh nền Manifest V2.

Các thao tác trong Manifest V3 gần giống nhất với các thao tác trên trình duyệt; tuy nhiên, API action không cung cấp hide() và show() như pageAction. Nếu vẫn cần thao tác trên trang, bạn có thể mô phỏng thao tác đó bằ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". Tham khảo tài liệu tham khảo để biết thông tin về trường "action".

Manifest V2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
Manifest V3
{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

Thay thế API browserAction và pageAction bằng API action

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.

Manifest V2
browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });
Manifest V3
browser.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 trả về bằng phương thức không đồng bộ. Nếu chưa từng sử dụng Promise, bạn có thể đọc về Promise trên MDN. Trang này mô tả những điều bạn cần biết để sử dụng các API này trong một tiện ích Chrome.

Để đảm bảo khả năng tương thích ngược, nhiều phương thức vẫn tiếp tục hỗ trợ lệnh gọi lại sau khi tính năng hỗ trợ lời hứa được thêm vào. Xin lưu ý rằng bạn không thể sử dụng cả hai tham số này trên cùng một lệnh gọi hàm. Nếu bạn truyền một lệnh gọi lại, hàm sẽ không trả về lời hứa và nếu bạn muốn trả về lời hứa, đừng truyền lệnh gọi lại. Một số tính năng của API, chẳng hạn như trình nghe sự kiện, sẽ tiếp tục yêu cầu lệnh 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 "Lời hứa" 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 sang 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ụ dưới đây được lấy từ mẫu quyền không bắt buộc, cụ thể là newtab.js. Phiên bản lệnh gọi lại cho thấy lệnh gọi của mẫu đến request() sẽ trông như thế nào khi có lệnh gọi lại. Xin lưu ý rằng phiên bản hứa hẹn có thể được viết lại bằng async và await.

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

Thay thế các hàm cần có bối cảnh nền của Manifest V2

Các bối cảnh tiện ích khác chỉ có thể tương tác với trình chạy 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 cần thay thế các lệnh gọi yêu cầu bối cảnh nền, cụ thể là:

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

Tập lệnh tiện ích của bạn nên sử dụng tính năng truyền thông báo để giao tiếp giữa 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 có thể thực hiện việc này bằng cách sử dụng sendMessage() và triển khai browser.runtime.onMessage trong trình chạy dịch vụ của 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 thông báo 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 được liệt kê dưới đây cần thay đổi trong Manifest V3.

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