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 đối với mã không phải là một phần của trình chạy dịch vụ tiện ích. Phần này dành cho những 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 trình bày về cách thay thế việc chặn yêu cầu web và cải thiện khả năng bảo mật.
Thay thế tab.ExecutionScript() bằng tập lệnh.exeScript()
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 bên cạnh 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 từ 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 vài điểm khác biệt.
- Mặc dù phương thức cũ chỉ có thể nhận một tệp duy nhất, 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 loại thông báo này. Ví dụ:tabId
hiện được truyền dưới dạng thành phần củaScriptInjection.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.
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ế tab.insertCSS() và tab.removeCSS() bằng kịch bản.insertCSS() và tập lệnh.removeCSS()
Trong Manifest V3, insertCSS()
và removeCSS()
di chuyển từ API tabs
sang scripting
API. Để thực hiện việc này, ngoài việc thay đổi mã, bạn còn phải thay đổi các quyền trong tệp kê khai:
- Quyền
"scripting"
. - Quyền từ 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 vài đ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ủaCSSInjection.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 cho insertCSS()
. Quy trình thực hiện removeCSS()
tương tự.
chrome.tabs.insertCSS(tabId, injectDetails, () => { // callback code });
const insertPromise = await chrome.scripting.insertCSS({ files: ["style.css"], target: { tabId: tab.id } }); // Remaining code.
Thay thế Tác vụ trên trình duyệt và Tác vụ trên trang bằng Tác vụ
Các thao tác trên trình duyệt và trên trang là các 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 thành API Action. Để này, bạn phải thay đổi manifest.json
và mã tiện ích khác với mã mà 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, action
API 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()
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 xem 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ế các API browserAction và pageAction bằng API hành động
Khi Manifest V2 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 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 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 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ợ lời hứa. 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ề, không truyền một 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 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ừ mộ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 lời hứa có thể được viết lại bằng chế độ không đồng bộ và 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 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 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 phải thay thế các lệnh gọi mong đợi ngữ cảnh 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 cách 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, việc này đòi hỏi 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 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 đượ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 |
---|---|
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 |
Trong trường hợp 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.onRequest |
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 |