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ố 3 phần mô tả những thay đổi cần thiết cho 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 sẽ đề cập đến việc thay thế các yêu cầu chặn trên web và cải thiện tính bảo mật.

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

Trong Manifest V3, executeScript() sẽ chuyển từ API tabs sang API scripting. Ngoài những thay đổi thực tế về mã, bạn cũng cần thay đổi các quyền trong tệp kê khai.

Đố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 của phương thức này với tabs.executeScript(). Có một số điểm khác biệt.

• Trong khi phương thức cũ chỉ có thể lấy một tệp, thì 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 phần của ScriptInjection.target thay vì dưới dạng một đối số phương thức.

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

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

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

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

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

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

Trong Manifest V3, insertCSS() và removeCSS() sẽ chuyển từ API tabs sang API scripting. Việc này yêu cầu thay đổi các quyền trong tệp kê khai ngoài các thay đổi về 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 số điểm khác biệt.

• Khi gọi các phương thức này, bạn sẽ 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 phần của CSSInjection.target thay vì dưới dạng một đố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ự.

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

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

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à hai khái niệm riêng biệt trong Manifest V2. Mặc dù bắt đầu với các vai trò riêng biệt, nhưng sự khác biệt giữa các 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 thành API Action. Việc này đòi hỏi bạn phải thay đổi manifest.json và mã 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 giống với các thao tác trên trình duyệt nhất; tuy nhiên, API action không cung cấp hide() và show() như pageAction. 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 nội dung khai báo hoặc gọi enable() hoặc disable() bằng mã nhận dạng 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 thông tin về trường "action".

{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}

{
  ...
  "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 các API browserAction và pageAction, thì giờ đây, bạn nên sử dụng API action.

browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });

browser.action.onClicked.addListener(tab => { ... });

Thay thế lệnh gọi lại bằng promise

Trong Manifest V3, nhiều phương thức API tiện ích sẽ trả về các promise. Promise là một proxy hoặc phần giữ chỗ cho giá trị do một phương thức không đồng bộ trả về. Nếu chưa từng sử dụng Promises, bạn có thể đọc về chúng 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 thêm tính năng hỗ trợ promise. Xin lưu ý rằng bạn không thể sử dụng cả hai 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ề một promise và nếu bạn muốn hàm trả về một promise, đừng truyền 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 lệnh gọi lại. Để kiểm tra xem một phương thức có hỗ trợ promise 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ừ một lệnh gọi lại sang một promise, hãy xoá lệnh gọi lại và xử lý promise được trả về. Ví dụ bên dưới được lấy từ mẫu quyền không bắt buộc, cụ thể là newtab.js. Phiên bản gọi lại cho biết lệnh gọi của mẫu đến request() sẽ có dạng như thế nào khi có lệnh gọi lại. Xin lưu ý rằng bạn có thể viết lại phiên bản promise bằng async và await.

browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

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 dự kiến có bối cảnh nền Manifest V2

Các bối cảnh tiện ích khác chỉ có thể tương tác với các worker dịch vụ của tiện ích bằng cách sử dụng truyền thông báo. Do đó, bạn sẽ cần thay thế các lệnh gọi dự kiến có một bối cảnh nền, cụ thể là:

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

Các tập lệnh tiện ích của bạn 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 trong 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.