Trang này được dịch bởi Cloud Translation API.

chrome.scripting

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

Chrome 88 trở lên MV3 trở lên

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. Sử dụng khoá "host_permissions" hoặc quyền "activeTab" để cấp quyền tạm thời cho 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ể dùng API chrome.scripting để chèn JavaScript và CSS vào các trang web. Điều này tương tự như những gì bạn có thể làm với content scripts. Nhưng bằng cách sử dụng không gian tên chrome.scripting, các tiện ích có thể đưa ra quyết định trong thời gian chạy.

Mục tiêu tiêm

Bạn có thể sử 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 lệnh 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ẻ được chỉ định, bạn có thể đặt giá trị boolean allFrames thành 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 một thẻ bằng cách chỉ định từng mã khung hình. Để biết thêm thông tin về mã khung hình, hãy xem API chrome.webNavigation.

function getTabId() { ... }  chrome.scripting     .executeScript({       target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},       files : [ "script.js" ],     })     .then(() => console.log("script injected on target frames"));

Lưu ý: Bạn không thể chỉ định cả thuộc tính "frameIds" và "allFrames".

Mã được chèn

Tiện ích có thể chỉ định mã cần chèn thông qua tệp bên ngoài hoặc biến thời gian chạy.

Tệp

Các tệp được chỉ định dưới dạng chuỗi là đường dẫn tương ứng với thư mục gốc của tiện ích. Đoạn mã sau đây sẽ chèn tệp script.js vào khung chính 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 hàm sẽ được thực thi thay vì một tệp. Hàm này phải là một biến hàm có sẵn 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ẽ được dùng trong thuộc tính css. Lựa chọn này chỉ dành cho scripting.insertCSS(); bạn không thể thực thi một 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 đến tiện ích. Mỗi khung hình sẽ có một kết quả duy nhất. 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 khác đều theo một 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ị thu được của quá trình thực thi tập lệnh là một promise, Chrome sẽ đợi promise đó hoàn tất và trả về giá trị thu được.

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 đây chứa một hàm huỷ đăng ký tất cả các tập lệnh nội dung động 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({ ids: scriptIds });   } catch (error) {     const message = [       "An unexpected error occurred while",       "unregistering dynamic content scripts.",     ].join(" ");     throw new Error(message, {cause : error});   } }

Để dùng API chrome.scripting, hãy cài đặt mẫu tập lệnh trong kho lưu trữ các mẫu tiện ích của Chrome.

Loại

ContentScriptFilter

Chrome 96 trở lên

Thuộc tính

mã nhận dạng

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 thuộc tính files và css.
tệp

string[] không bắt buộc

Đường dẫn của các tệp 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 thuộc tính files và css.
nguồn gốc

StyleOrigin không bắt buộc

Nguồn gốc của kiểu để chèn. Giá trị mặc định là 'AUTHOR'.
mục tiêu

InjectionTarget

Thông tin chi tiết chỉ định mục tiêu để chèn CSS.

ExecutionWorld

Chrome 95 trở lên

Môi trường JavaScript để một tập lệnh thực thi trong đó.

Enum

"ISOLATED"
Chỉ định thế giới biệt lập, là môi trường thực thi dành riêng cho tiện ích này.

"MAIN"
Chỉ định thế giới chính của DOM, đây 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

chuỗi

Chrome 106 trở lên

Tài liệu liên kết với hoạt động chèn.
frameId

số

Chrome 90 trở lên

Khung liên kết với quá trình chèn.
kết quả

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

Liệu tập lệnh có nên chèn vào tất cả các khung trong thẻ hay không. Giá trị mặc định là false. Giá trị này không được là true nếu bạn chỉ định frameIds.
documentIds

string[] không bắt buộc

Chrome 106 trở lên

Mã nhận dạng của các documentId cụ thể cần chèn vào. Bạn không được đặt 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 hình cụ thể cần chèn vào.
tabId

số

Mã của thẻ cần chèn.

RegisteredContentScript

Chrome 96 trở lên

Thuộc tính

allFrames

boolean không bắt buộc

Nếu được chỉ định là true, thì mã này sẽ được chèn vào tất cả các khung, ngay cả khi khung đó không phải là khung trên cùng trong thẻ. Mỗi khung hình được kiểm tra độc lập theo các yêu cầu về URL; khung hình sẽ không chèn vào các khung hình con nếu không đáp ứng các yêu cầu về URL. Mặc định là false, tức là chỉ khung trên cùng được so 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 đối tượng 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 tạo hoặc hiển thị cho trang.
excludeMatches

string[] không bắt buộc

Loại trừ những trang mà tập lệnh nội dung này sẽ được chèn vào. Hãy xem phần Mẫu khớp để biết thêm thông tin chi tiết về cú pháp của các chuỗi này.
id

chuỗi

Mã nhận dạng 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 dấu "_" vì dấu này được dành riêng làm tiền tố cho các mã tập lệnh được tạo.
js

string[] không bắt buộc

Danh sách các tệp JavaScript sẽ được chèn vào các trang phù hợp. Các đối tượng 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ên

Cho biết liệu tập lệnh có thể được chèn vào các khung hình mà URL chứa một lược đồ không được hỗ trợ hay không; cụ thể là: about:, data:, blob: hoặc filesystem:. 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 chèn tập lệnh hay không. Nếu nguồn gốc là null (như trong trường hợp đối với 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 thao tác điều hướng đến khung này. Xin lưu ý rằng đây có thể không phải là khung mẹ.
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. Hãy xem phần Mẫu khớp để biết thêm thông tin chi tiết về cú pháp của các chuỗi này. Bạn phải chỉ định cho registerContentScripts.
persistAcrossSessions

boolean không bắt buộc

Chỉ định xem tập lệnh nội dung này có tiếp tục hoạt động trong các phiên sau này hay không. Giá trị mặc định là "true".
runAt

RunAt không bắt buộc

Chỉ định thời điểm các tệp JavaScript được chèn vào trang web. Giá trị ưu tiên và mặc định 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

any[] không bắt buộc

Chrome 92 trở lên

Các đối số cần truyền vào hàm đã cho. Điều này chỉ hợp lệ nếu bạn chỉ định tham số func. Các đối số này phải có thể chuyển đổi tuần tự thành 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 thuộc tính files hoặc func.
injectImmediately

boolean không bắt buộc

Chrome 102 trở lên

Liệu quá trình chèn có nên được kích hoạt trong mục tiêu càng sớm càng tốt hay không. Xin lưu ý rằng điều này không đảm bảo rằng quá trình chèn sẽ diễn ra trước khi tải trang, vì trang có thể đã tải xong vào thời điểm tập lệnh đạt đến mục tiêu.
mục tiêu

InjectionTarget

Thông tin chi tiết chỉ định mục tiêu để chèn tập lệnh.
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

void optional

Chrome 92 trở lên

Một hàm JavaScript để chèn. Hàm này sẽ được chuyển đổi tuần tự, sau đó chuyển đổi ngược tuần tự để chèn. Điều này có nghĩa là mọi thông số liên kết và bối cảnh thực thi sẽ bị mất. Bạn phải chỉ định chính xác một trong hai thuộc tính files hoặc func.

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 của kiểu để biết thêm thông tin.

Enum

"TÁC GIẢ"

"USER"

Phương thức

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

Chèn một tập lệnh vào ngữ cảnh mục tiêu. Theo mặc định, tập lệnh sẽ chạy tại document_idle hoặc chạy ngay lập tức nếu trang đã tải. Nếu bạn đặt thuộc tính injectImmediately, 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 promise, trình duyệt sẽ đợi promise hoàn tất và trả về giá trị kết quả.

Thông số

tiêm

ScriptInjection

Thông tin chi tiết về tập lệnh cần chèn.

Giá trị trả về

Promise<InjectionResult[]>

Chrome 90 trở lên

getRegisteredContentScripts()

Chrome 96 trở lên

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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.

Thông số

filter

ContentScriptFilter không bắt buộc

Một đối tượng để lọc các tập lệnh đã đăng ký động của tiện ích.

Giá trị trả về

Promise<RegisteredContentScript[]>

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

Chèn một biểu định kiểu CSS vào một ngữ cảnh mục tiêu. Nếu bạn chỉ định nhiều khung, thì các lần chèn không thành công sẽ bị bỏ qua.

Thông số

tiêm

CSSInjection

Thông tin chi tiết về các kiểu cần chèn.

Giá trị trả về

Promise<void>

Chrome 90 trở lên

registerContentScripts()

Chrome 96 trở lên

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Đăng ký một hoặc nhiều tập lệnh nội dung cho tiện ích này.

Thông số

các tập lệnh

RegisteredContentScript[]

Chứa danh sách các tập lệnh cần đăng ký. Nếu có 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 các mã nhận dạng được chỉ định đã tồn tại, thì không có tập lệnh nào được đăng ký.

Giá trị trả về

Promise<void>

removeCSS()

Chrome 90 trở lên

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Xoá một biểu định kiểu CSS mà tiện ích này đã chèn trước đó khỏi một ngữ cảnh mục tiêu.

Thông số

tiêm

CSSInjection

Thông tin chi tiết về các kiểu cần xoá. Xin 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 qua insertCSS. Việc cố gắng xoá một biểu định kiểu không tồn tại sẽ không có tác dụng.

Giá trị trả về

Promise<void>

unregisterContentScripts()

Chrome 96 trở lên

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Huỷ đăng ký tập lệnh nội dung cho tiện ích này.

Thông 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 khớ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ý.

Giá trị trả về

Promise<void>

updateContentScripts()

Chrome 96 trở lên

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Cập nhật một hoặc nhiều tập lệnh nội dung cho tiện ích này.

Thông số

các tập lệnh

RegisteredContentScript[]

Chứa danh sách các tập lệnh cần cập nhật. Một thuộc tính chỉ được cập nhật cho tập lệnh hiện có nếu được chỉ định trong đối tượng này. Nếu có 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 đã đăng ký đầy đủ, thì sẽ không có tập lệnh nào được cập nhật.

Giá trị trả về

Promise<void>

chrome.scripting Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mô tả

Quyền

Phạm vi cung cấp

Tệp kê khai

Khái niệm và cách sử dụng

Mục tiêu tiêm

Mã được chèn

Tệp

Hàm thời gian chạy

Chuỗi thời gian chạy

Xử lý kết quả

Lời hứa

Ví dụ

Huỷ đăng ký tất cả tập lệnh nội dung động

Loại

ContentScriptFilter

Thuộc tính

CSSInjection

Thuộc tính

ExecutionWorld

Enum

InjectionResult

Thuộc tính

InjectionTarget

Thuộc tính

RegisteredContentScript

Thuộc tính

ScriptInjection

Thuộc tính

StyleOrigin

Enum

Phương thức

executeScript()

Thông số

Giá trị trả về

getRegisteredContentScripts()

Thông số

Giá trị trả về

insertCSS()

Thông số

Giá trị trả về

registerContentScripts()

Thông số

Giá trị trả về

removeCSS()

Thông số

Giá trị trả về

unregisterContentScripts()

Thông số

Giá trị trả về

updateContentScripts()

Thông số

Giá trị trả về

chrome.scripting