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

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

Trong Tệp kê khai V3, executeScript() sẽ chuyển từ API tabs sang API scripting. Việc này đòi hỏi phải 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ố 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 công cụ 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ì một đối số phương thức.

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

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

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

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

chrome.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 Tệp kê khai V3, insertCSS() và removeCSS() sẽ chuyển từ API tabs sang API scripting. Việc 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ã:

• 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 sẽ truyền một đối tượng CSSInjection thay vì InjectDetails.
• tabId hiện được truyền dưới dạng thành viên của CSSInjection.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 việc này cho insertCSS(). Quy trình cho removeCSS() giống nhau.

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

const insertPromise = await chrome.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 những vai trò khác nhau, nhưng sự khác biệt giữa hai công cụ 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 Action API. Điều 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 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 đã cung cấp. 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() hay 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 tài liệu tham khảo để biết 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 hành động

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

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

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

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

Trong Tệp kê khai V3, nhiều phương thức API tiện ích trả về các lời hứa. Promise (Lời hứa) là một proxy hoặc phần giữ chỗ cho một giá trị do phương thức không đồng bộ trả về. Nếu chưa từng 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 chúng tôi thêm tính năng hỗ trợ lời hứa. 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 lời hứa và nếu bạn muốn lời hứa được trả về, đừ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 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 thành một 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 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 đến request() sẽ trông như thế nào với lệnh gọi lại. Lưu ý rằng phiên bản hứa hẹn có thể được viết lại bằng chế độ không đồng bộ và đang chờ.

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

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 dự kiến 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 chạy dịch vụ tiện ích bằng cách sử dụng tính năng truyền tin nhắn. Do đó, bạn cần thay thế các lệnh gọi dự kiến ngữ cảnh ở chế độ nền, cụ thể:

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

Tập lệnh tiện ích của bạn phải sử dụng tính năng truyền tin nhắn để giao tiếp giữa worker 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 chrome.runtime.onMessage trong worker 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 thông báo của worker 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ê bên dưới cần thay đổi trong Tệp kê khai phiên bản 3.