Mô tả
Sử dụng API chrome.scripting
để thực thi tập lệnh trong nhiều ngữ cảnh.
Quyền
scripting
Phạm vi cung cấp
Tệp kê khai
Để sử dụng API chrome.scripting
, hãy khai báo quyền "scripting"
trong tệp kê khai cùng với quyền của máy chủ lưu trữ cho các trang chèn tập lệnh vào. Dùng khoá "host_permissions"
hoặc quyền "activeTab"
để cấp quyền tạm thời của máy chủ. Ví dụ sau đây sử dụng quyền activeTab.
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
Khái niệm và cách sử dụng
Bạn có thể sử dụng API chrome.scripting
để chèn JavaScript và CSS vào
của bạn. Điều này tương tự như những gì bạn có thể thực hiện với nội dung
tập lệnh. Tuy nhiên, khi sử dụng không gian tên chrome.scripting
, tiện ích
có thể đưa ra quyết định trong thời gian chạy.
Mục tiêu chèn
Bạn có thể dùng tham số target
để chỉ định một mục tiêu để chèn JavaScript hoặc
CSS vào.
Trường bắt buộc duy nhất là tabId
. Theo mặc định, một thao tác chèn sẽ chạy trong
khung chính của thẻ được chỉ định.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("script injected"));
Để chạy trong tất cả các khung của thẻ đã chỉ định, bạn có thể đặt giá trị boolean allFrames
đến true
.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
Bạn cũng có thể chèn vào các khung hình cụ thể của thẻ bằng cách chỉ định từng khung hình
Mã nhận dạng. Để biết thêm thông tin về mã nhận dạng khung hình, hãy xem chrome.webNavigation
API.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
files : [ "script.js" ],
})
.then(() => console.log("script injected on target frames"));
Mã được chèn
Các tiện ích có thể chỉ định mã để đưa vào thông qua một tệp bên ngoài hoặc một thời gian chạy.
Files
Tệp được chỉ định dưới dạng chuỗi là đường dẫn tương ứng với gốc của tiện ích
thư mục. Đoạn mã sau đây sẽ chèn tệp script.js
vào dữ liệu chính
khung của thẻ.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("injected script file"));
Hàm thời gian chạy
Khi chèn JavaScript bằng scripting.executeScript()
, bạn có thể chỉ định một
được thực thi thay vì một tệp. Hàm này phải là một hàm
biến khả dụng cho ngữ cảnh tiện ích hiện tại.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
})
.then(() => console.log("injected a function"));
Bạn có thể giải quyết vấn đề này bằng cách sử dụng thuộc tính args
:
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
document.body.style.backgroundColor = backgroundColor;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
args : [ getUserColor() ],
})
.then(() => console.log("injected a function"));
Chuỗi thời gian chạy
Nếu chèn CSS trong một trang, bạn cũng có thể chỉ định một chuỗi để sử dụng trong
Thuộc tính css
. Tuỳ chọn này chỉ dành cho scripting.insertCSS()
; bạn
không thể thực thi chuỗi bằng scripting.executeScript()
.
function getTabId() { ... }
const css = "body { background-color: red; }";
chrome.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
Xử lý kết quả
Kết quả thực thi JavaScript sẽ được chuyển sang tiện ích. Một kết quả duy nhất được bao gồm trên mỗi khung hình. Khung chính được đảm bảo là chỉ mục đầu tiên trong mảng kết quả; tất cả các khung hình khác theo thứ tự không xác định.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : getTitle,
})
.then(injectionResults => {
for (const {frameId, result} of injectionResults) {
console.log(`Frame ${frameId} result:`, result);
}
});
scripting.insertCSS()
không trả về kết quả nào.
Lời hứa
Nếu giá trị kết quả của quá trình thực thi tập lệnh là một lời hứa, Chrome sẽ đợi để cam kết thanh toán và trả về giá trị kết quả.
function getTabId() { ... }
async function addIframe() {
const iframe = document.createElement("iframe");
const loadComplete =
new Promise(resolve => iframe.addEventListener("load", resolve));
iframe.src = "https://example.com";
document.body.appendChild(iframe);
await loadComplete;
return iframe.contentWindow.document.title;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : addIframe,
})
.then(injectionResults => {
for (const frameResult of injectionResults) {
const {frameId, result} = frameResult;
console.log(`Frame ${frameId} result:`, result);
}
});
Ví dụ
Huỷ đăng ký tất cả tập lệnh nội dung động
Đoạn mã sau chứa một hàm huỷ đăng ký tất cả nội dung động các tập lệnh mà tiện ích đã đăng ký trước đó.
async function unregisterAllDynamicContentScripts() {
try {
const scripts = await chrome.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return chrome.scripting.unregisterContentScripts(scriptIds);
} catch (error) {
const message = [
"An unexpected error occurred while",
"unregistering dynamic content scripts.",
].join(" ");
throw new Error(message, {cause : error});
}
}
Để dùng thử API chrome.scripting
,
cài đặt mẫu tập lệnh từ mẫu tiện ích của Chrome
kho lưu trữ.
Loại
ContentScriptFilter
Thuộc tính
-
id
string[] không bắt buộc
Nếu được chỉ định,
getRegisteredContentScripts
sẽ chỉ trả về các tập lệnh có mã nhận dạng được chỉ định trong danh sách này.
CSSInjection
Thuộc tính
-
css
chuỗi không bắt buộc
Một chuỗi chứa CSS cần chèn. Bạn phải chỉ định chính xác một trong hai giá trị
files
vàcss
. -
tệp
string[] không bắt buộc
Đường dẫn của các tệp CSS sẽ chèn, tương ứng với thư mục gốc của tiện ích. Bạn phải chỉ định chính xác một trong hai giá trị
files
vàcss
. -
nguồn gốc
StyleOrigin không bắt buộc
Nguồn gốc kiểu cho thao tác chèn. Giá trị mặc định là
'AUTHOR'
. -
mục tiêu
Thông tin chi tiết chỉ định đích đến mà bạn muốn chèn CSS vào.
ExecutionWorld
Thế giới JavaScript để thực thi một tập lệnh bên trong.
Enum
"ISOLATED"
Chỉ định môi trường tách biệt. Đây là môi trường thực thi dành riêng cho tiện ích này.
"MAIN"
Chỉ định môi trường chính của DOM, tức là môi trường thực thi được chia sẻ với JavaScript của trang lưu trữ.
InjectionResult
Thuộc tính
-
documentId
string
Chrome 106 trở lênGiấy tờ liên quan đến thao tác chèn.
-
frameId
số
Chrome 90 trở lênKhung được liên kết với thao tác chèn.
-
kết quả
bất kỳ không bắt buộc
Kết quả thực thi tập lệnh.
InjectionTarget
Thuộc tính
-
allFrames
boolean không bắt buộc
Tập lệnh có nên chèn vào tất cả khung trong thẻ hay không. Giá trị mặc định là false. Giá trị này không được đúng nếu bạn chỉ định
frameIds
. -
documentIds
string[] không bắt buộc
Chrome 106 trở lênMã nhận dạng của documentId cụ thể cần đưa vào. Bạn không được thiết lập giá trị này nếu đã đặt
frameIds
. -
frameIds
number[] không bắt buộc
Mã nhận dạng của các khung cụ thể cần đưa vào.
-
tabId
số
Mã của thẻ cần đưa vào.
RegisteredContentScript
Thuộc tính
-
allFrames
boolean không bắt buộc
Nếu được chỉ định là true, hàm này sẽ chèn vào tất cả các khung hình, ngay cả khi khung hình không phải là khung hình ở trên cùng trong thẻ. Mỗi khung được kiểm tra độc lập để đảm bảo các yêu cầu về URL; sẽ không chèn vào các khung con nếu không đáp ứng các yêu cầu về URL. Giá trị mặc định là false, nghĩa là chỉ khung hình trên cùng được khớp.
-
css
string[] không bắt buộc
Danh sách các tệp CSS sẽ được chèn vào các trang phù hợp. Các phần tử này được chèn theo thứ tự xuất hiện trong mảng này, trước khi bất kỳ DOM nào được xây dựng hoặc hiển thị cho trang.
-
excludeMatches
string[] không bắt buộc
Không bao gồm các trang mà tập lệnh nội dung này sẽ được chèn vào. Xem Mẫu so khớp để biết thêm chi tiết về cú pháp của các chuỗi này.
-
id
string
Mã của tập lệnh nội dung, được chỉ định trong lệnh gọi API. Không được bắt đầu bằng '_' vì mã này được dành riêng làm tiền tố cho các mã tập lệnh được tạo.
-
JavaScript
string[] không bắt buộc
Danh sách tệp JavaScript sẽ được đưa vào các trang phù hợp. Các biến này được chèn theo thứ tự xuất hiện trong mảng này.
-
matchOriginAsFallback
boolean không bắt buộc
Chrome 119 trở lênCho biết liệu tập lệnh có thể được chèn vào các khung có URL chứa lược đồ không được hỗ trợ hay không; cụ thể: about:, data:, blob: hoặc hệ thống tệp:. Trong những trường hợp này, nguồn gốc của URL sẽ được kiểm tra để xác định xem có nên đưa tập lệnh vào hay không. Nếu nguồn gốc là
null
(như trong trường hợp của dữ liệu: URL), thì nguồn gốc được sử dụng là khung đã tạo khung hiện tại hoặc khung đã bắt đầu quá trình điều hướng đến khung này. Lưu ý rằng đây có thể không phải là khung hình chính. -
khớp với
string[] không bắt buộc
Chỉ định những trang mà tập lệnh nội dung này sẽ được chèn vào. Xem Mẫu so khớp để biết thêm chi tiết về cú pháp của các chuỗi này. Bạn phải chỉ định thuộc tính này cho
registerContentScripts
. -
persistAcrossSessions
boolean không bắt buộc
Chỉ định xem tập lệnh nội dung này có duy trì trong các phiên trong tương lai hay không. Giá trị mặc định là "true".
-
runAt
RunAt không bắt buộc
Chỉ định thời điểm chèn tệp JavaScript vào trang web. Giá trị mặc định và được ưu tiên là
document_idle
. -
thế giới
ExecutionWorld không bắt buộc
Chrome 102 trở lên"Thế giới" JavaScript để chạy tập lệnh. Giá trị mặc định là
ISOLATED
.
ScriptInjection
Thuộc tính
-
args
bất kỳ[] không bắt buộc
Chrome 92 trở lênCác đối số cần truyền đến hàm đã cho. Điều này chỉ hợp lệ nếu tham số
func
được chỉ định. Các đối số này phải được chuyển đổi tuần tự JSON. -
tệp
string[] không bắt buộc
Đường dẫn của các tệp JS hoặc CSS cần chèn, tương ứng với thư mục gốc của tiện ích. Bạn phải chỉ định chính xác một trong hai giá trị
files
hoặcfunc
. -
injectImmediately
boolean không bắt buộc
Chrome 102 trở lênLiệu có nên kích hoạt hành động chèn trong mục tiêu trong thời gian sớm nhất có thể hay không. Lưu ý rằng điều này không đảm bảo rằng việc chèn sẽ xảy ra trước khi tải trang, vì trang có thể đã được tải vào thời điểm tập lệnh tiếp cận mục tiêu.
-
mục tiêu
Thông tin chi tiết xác định mục tiêu để chèn tập lệnh vào.
-
thế giới
ExecutionWorld không bắt buộc
Chrome 95 trở lên"Thế giới" JavaScript để chạy tập lệnh. Giá trị mặc định là
ISOLATED
. -
func
khoảng trống không bắt buộc
Chrome 92 trở lênMột hàm JavaScript để chèn. Hàm này sẽ được chuyển đổi tuần tự rồi giải tuần tự để chèn. Điều này có nghĩa là mọi tham số ràng buộc và ngữ cảnh thực thi sẽ bị mất. Bạn phải chỉ định chính xác một trong hai giá trị
files
hoặcfunc
.Hàm
func
có dạng như sau:() => {...}
StyleOrigin
Nguồn gốc của một thay đổi về kiểu. Hãy xem phần nguồn gốc kiểu để biết thêm thông tin.
Enum
"AUTHOR"
"NGƯỜI DÙNG"
Phương thức
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
callback?: function,
)
Chèn một tập lệnh vào một ngữ cảnh mục tiêu. Theo mặc định, tập lệnh sẽ chạy tại document_idle
hoặc ngay lập tức nếu trang đã tải. Nếu bạn đặt thuộc tính injectImmediately
, thì tập lệnh sẽ chèn mà không cần chờ, ngay cả khi trang chưa tải xong. Nếu tập lệnh đánh giá một lời hứa, trình duyệt sẽ chờ lời hứa đó được xử lý và trả về giá trị kết quả.
Tham số
-
tiêm
Thông tin chi tiết về tập lệnh cần chèn.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(results: InjectionResult[]) => void
-
kết quả
-
Giá trị trả về
-
Promise<InjectionResult[]>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Trả về tất cả tập lệnh nội dung đã đăng ký động cho tiện ích này khớp với bộ lọc đã cho.
Tham số
-
filter
ContentScriptFilter không bắt buộc
Đối tượng để lọc các tập lệnh được đăng ký động của tiện ích.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(scripts: RegisteredContentScript[]) => void
-
các tập lệnh
-
Giá trị trả về
-
Promise<RegisteredContentScript[]>
Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
callback?: function,
)
Chèn biểu định kiểu CSS vào ngữ cảnh đích. Nếu bạn chỉ định nhiều khung hình, thì các thao tác chèn không thành công sẽ bị bỏ qua.
Tham số
-
tiêm
Thông tin chi tiết về các kiểu cần chèn.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Lời hứa<vô hiệu>
Chrome 90 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Đăng ký một hoặc nhiều tập lệnh nội dung cho tiện ích này.
Tham số
-
các tập lệnh
Chứa danh sách các tập lệnh cần đăng ký. Nếu xảy ra lỗi trong quá trình phân tích cú pháp tập lệnh/xác thực tệp hoặc nếu mã nhận dạng được chỉ định đã tồn tại, thì sẽ không có tập lệnh nào được đăng ký.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Lời hứa<vô hiệu>
Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
Xoá biểu định kiểu CSS trước đó được tiện ích này chèn vào khỏi ngữ cảnh đích.
Tham số
-
tiêm
Thông tin chi tiết về các kiểu cần xoá. Lưu ý rằng các thuộc tính
css
,files
vàorigin
phải khớp chính xác với biểu định kiểu được chèn thông quainsertCSS
. Việc cố gắng xoá biểu định kiểu không tồn tại sẽ không hoạt động. -
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Lời hứa<vô hiệu>
Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Huỷ đăng ký tập lệnh nội dung cho tiện ích này.
Tham số
-
filter
ContentScriptFilter không bắt buộc
Nếu được chỉ định, chỉ huỷ đăng ký các tập lệnh nội dung động phù hợp với bộ lọc. Nếu không, tất cả tập lệnh nội dung động của tiện ích sẽ bị huỷ đăng ký.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Lời hứa<vô hiệu>
Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Cập nhật một hoặc nhiều tập lệnh nội dung cho phần mở rộng này.
Tham số
-
các tập lệnh
Chứa danh sách các tập lệnh cần cập nhật. Thuộc tính chỉ được cập nhật cho tập lệnh hiện có nếu tập lệnh đó được chỉ định trong đối tượng này. Nếu xảy ra lỗi trong quá trình phân tích cú pháp tập lệnh/xác thực tệp hoặc nếu mã nhận dạng được chỉ định không tương ứng với một tập lệnh được đăng ký đầy đủ, thì sẽ không có tập lệnh nào được cập nhật.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Lời hứa<vô hiệu>
Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.