Mô tả
Sử dụng API userScripts để thực thi tập lệnh người dùng trong bối cảnh Tập lệnh người dùng.
Quyền
userScriptsĐể sử dụng API Tập lệnh người dùng, browser.userScripts, hãy thêm quyền "userScripts" vào tệp manifest.json và "host_permissions" cho các trang web mà bạn muốn chạy tập lệnh.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
Phạm vi cung cấp
Khái niệm và cách sử dụng
Tập lệnh người dùng là một đoạn mã được chèn vào trang web để sửa đổi giao diện hoặc hành vi của trang web đó. Không giống như các tính năng khác của tiện ích, chẳng hạn như Kịch bản nội dung và API browser.scripting, API Kịch bản người dùng cho phép bạn chạy mã tuỳ ý. API này là bắt buộc đối với các tiện ích chạy tập lệnh do người dùng cung cấp mà không thể được cung cấp trong gói tiện ích của bạn.
Cho phép sử dụng userScripts API
Sau khi tiện ích của bạn nhận được quyền sử dụng API userScripts, người dùng phải bật một nút bật/tắt cụ thể để cho phép tiện ích của bạn sử dụng API. Nút bật/tắt cụ thể cần thiết và hành vi của API khi bị tắt sẽ khác nhau tuỳ theo phiên bản Chrome.
Sử dụng quy trình kiểm tra sau để xác định nút bật/tắt mà người dùng cần bật, ví dụ: trong quá trình làm quen với người dùng mới:
let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
// Allow User Scripts toggle will be used.
} else {
// Developer mode toggle will be used.
}
Các phần sau đây mô tả các nút bật/tắt và cách bật các nút đó.
Các phiên bản Chrome trước phiên bản 138 (Nút bật/tắt Chế độ nhà phát triển)
Là nhà phát triển tiện ích, bạn đã bật Chế độ nhà phát triển trong bản cài đặt Chrome của mình. Người dùng của bạn cũng phải bật Chế độ nhà phát triển.
Bạn có thể sao chép và dán các hướng dẫn sau vào tài liệu của tiện ích cho người dùng
- Chuyển đến trang Tiện ích bằng cách nhập
chrome://extensionsvào một thẻ mới. (Theo thiết kế, bạn không thể liên kết đến URLchrome://.) Bật Chế độ nhà phát triển bằng cách nhấp vào nút bật/tắt bên cạnh Chế độ nhà phát triển.
Trang Tiện ích (chrome://extensions)
Chrome phiên bản 138 trở lên (nút bật/tắt Cho phép tập lệnh của người dùng)
Nút bật tắt Cho phép tập lệnh người dùng nằm trên trang thông tin chi tiết của mỗi tiện ích (ví dụ: chrome://extensions/?id=YOUR_EXTENSION_ID).
Bạn có thể sao chép và dán hướng dẫn sau đây vào tài liệu về tiện ích cho người dùng:
- Chuyển đến trang Tiện ích bằng cách nhập
chrome://extensionsvào một thẻ mới. (Theo thiết kế, bạn không thể liên kết đến URLchrome://.) - Nhấp vào nút "Chi tiết" trên thẻ tiện ích để xem thông tin chi tiết về tiện ích đó.
- Nhấp vào nút bật/tắt bên cạnh mục Cho phép tập lệnh của người dùng.
Kiểm tra xem API có hoạt động không
Bạn nên thực hiện bước kiểm tra sau để xác định xem API userScripts có được bật hay không, vì API này hoạt động trong tất cả phiên bản Chrome. Quá trình kiểm tra này sẽ cố gắng gọi một phương thức browser.userScripts(). Phương thức này sẽ luôn thành công khi API hoạt động. Nếu lệnh gọi này gửi một lỗi, thì API sẽ không hoạt động:
function isUserScriptsAvailable() {
try {
// Method call which throws if API permission or toggle is not enabled.
browser.userScripts.getScripts();
return true;
} catch {
// Not available.
return false;
}
}
Làm việc trong môi trường tách biệt
Cả tập lệnh người dùng và tập lệnh nội dung đều có thể chạy trong một môi trường tách biệt hoặc trong môi trường chính. Môi trường tách biệt là một môi trường thực thi mà trang lưu trữ hoặc các tiện ích khác không thể truy cập được. Điều này cho phép tập lệnh người dùng thay đổi môi trường JavaScript mà không ảnh hưởng đến trang lưu trữ hoặc tập lệnh nội dung và người dùng của các tiện ích khác. Ngược lại, tập lệnh người dùng (và tập lệnh nội dung) không hiển thị với trang lưu trữ hoặc tập lệnh người dùng và nội dung của các tiện ích khác. Các tập lệnh chạy trong môi trường chính có thể truy cập được vào các trang lưu trữ và các tiện ích khác, đồng thời hiển thị với các trang lưu trữ và các tiện ích khác. Để chọn thế giới, hãy truyền "USER_SCRIPT" hoặc "MAIN" khi gọi userScripts.register().
Để định cấu hình chính sách bảo mật nội dung cho thế giới USER_SCRIPT, hãy gọi userScripts.configureWorld():
browser.userScripts.configureWorld({
csp: "script-src 'self'"
});
Nhắn tin
Giống như tập lệnh nội dung và tài liệu ngoài màn hình, tập lệnh người dùng giao tiếp với các phần khác của tiện ích bằng cách sử dụng tính năng nhắn tin (nghĩa là chúng có thể gọi runtime.sendMessage() và runtime.connect() như bất kỳ phần nào khác của tiện ích). Tuy nhiên, các sự kiện này được nhận bằng trình xử lý sự kiện chuyên dụng (nghĩa là không sử dụng onMessage hoặc onConnect). Các trình xử lý này được gọi là runtime.onUserScriptMessage và runtime.onUserScriptConnect. Trình xử lý chuyên dụng giúp bạn dễ dàng xác định thông báo từ tập lệnh người dùng hơn, đây là bối cảnh ít tin cậy hơn.
Trước khi gửi tin nhắn, bạn phải gọi configureWorld() với đối số messaging được đặt thành true. Xin lưu ý rằng bạn có thể truyền cả đối số csp và messaging cùng một lúc.
browser.userScripts.configureWorld({
messaging: true
});
Thông tin cập nhật về tiện ích
Tập lệnh người dùng sẽ bị xoá khi tiện ích cập nhật. Bạn có thể thêm lại các mục này bằng cách chạy mã trong trình xử lý sự kiện runtime.onInstalled trong trình chạy dịch vụ của tiện ích. Chỉ phản hồi "update" lý do được truyền đến lệnh gọi lại sự kiện.
Ví dụ
Ví dụ này được lấy từ mẫu userScript trong kho lưu trữ mẫu của chúng tôi.
Đăng ký tập lệnh
Ví dụ sau đây cho thấy một lệnh gọi cơ bản đến register(). Đối số đầu tiên là một mảng đối tượng xác định các tập lệnh cần đăng ký. Có nhiều lựa chọn hơn so với những lựa chọn được trình bày ở đây.
browser.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Loại
ExecutionWorld
Môi trường JavaScript để tập lệnh người dùng thực thi.
Enum
"MAIN"
Chỉ định môi trường thực thi 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ữ.
"USER_SCRIPT"
Chỉ định môi trường thực thi dành riêng cho tập lệnh người dùng và được miễn trừ khỏi CSP của trang.
InjectionResult
Thuộc tính
-
documentId
chuỗi
Tài liệu liên quan đến việc chèn.
-
error
chuỗi không bắt buộc
Lỗi (nếu có).
errorvàresultloại trừ lẫn nhau. -
frameId
số
Khung liên kết với hoạt động 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
Liệu 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 là true nếu bạn chỉ định
frameIds. -
documentIds
string[] không bắt buộc
Mã của 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 cụ thể cần chèn vào.
-
tabId
số
Mã nhận dạng của thẻ cần chèn.
RegisteredUserScript
Thuộc tính
-
allFrames
boolean không bắt buộc
Nếu đúng, tập lệnh sẽ chèn vào tất cả khung, ngay cả khi khung đó không phải là khung trên cùng trong thẻ. Mỗi khung được kiểm tra độc lập để đảm bảo đáp ứng các yêu cầu về URL; tập lệnh 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ỉ so khớp khung trên cùng.
-
excludeGlobs
string[] không bắt buộc
Chỉ định mẫu ký tự đại diện cho các trang mà tập lệnh người dùng này sẽ KHÔNG được chèn vào.
-
excludeMatches
string[] không bắt buộc
Loại trừ các trang mà tập lệnh người dùng này sẽ được chèn vào. Hãy xem phần Kiể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 người dùng được chỉ định trong lệnh gọi API. Thuộc tính này không được bắt đầu bằng "_" vì đây là tiền tố dành riêng cho mã tập lệnh được tạo.
-
includeGlobs
string[] không bắt buộc
Chỉ định mẫu ký tự đại diện cho các trang mà tập lệnh người dùng này sẽ được chèn vào.
-
js
ScriptSource[] không bắt buộc
Danh sách các đối tượng ScriptSource xác định nguồn của tập lệnh sẽ được chèn vào các trang phù hợp. Bạn phải chỉ định thuộc tính này cho ${ref:register} và khi được chỉ định, thuộc tính này phải là một mảng không trống.
-
khớp với
string[] không bắt buộc
Chỉ định những trang mà tập lệnh người dùng này sẽ được chèn vào. Hãy xem phần Kiể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 thuộc tính này cho ${ref:register}.
-
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ị ưu tiên và mặc định là
document_idle. -
thế giới
ExecutionWorld không bắt buộc
Môi trường thực thi JavaScript để chạy tập lệnh. Mặc định là
`USER_SCRIPT`. -
worldId
chuỗi không bắt buộc
Chrome 133 trở lên browser.* kể từ Chrome 148Chỉ định mã nhận dạng môi trường tập lệnh người dùng để thực thi. Nếu bạn bỏ qua, tập lệnh sẽ thực thi trong môi trường tập lệnh người dùng mặc định. Chỉ hợp lệ nếu
worldbị bỏ qua hoặc làUSER_SCRIPT. Các giá trị có dấu gạch dưới ở đầu (_) được đặt trước.
ScriptSource
Thuộc tính
-
mã
chuỗi không bắt buộc
Một chuỗi chứa mã JavaScript cần chèn. Bạn phải chỉ định chính xác một trong hai thuộc tính
filehoặccode. -
tệp
chuỗi không bắt buộc
Đường dẫn của tệp JavaScript 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
filehoặccode.
UserScriptFilter
Thuộc tính
-
mã nhận dạng
string[] không bắt buộc
getScriptschỉ trả về các tập lệnh có mã nhận dạng được chỉ định trong danh sách này.
UserScriptInjection
Thuộc tính
-
injectImmediately
boolean không bắt buộc
Liệu có nên kích hoạt việc chèn vào 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 việc chèn sẽ diễn ra trước khi tải trang, vì trang có thể đã tải xong khi tập lệnh đến được mục tiêu.
-
js
Danh sách các đối tượng ScriptSource xác định nguồn của tập lệnh cần chèn vào mục tiêu.
-
mục tiêu
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
"Thế giới" JavaScript để chạy tập lệnh. Mặc định là
USER_SCRIPT. -
worldId
chuỗi không bắt buộc
Chỉ định mã nhận dạng môi trường tập lệnh người dùng để thực thi. Nếu bạn bỏ qua, tập lệnh sẽ thực thi trong môi trường tập lệnh người dùng mặc định. Chỉ hợp lệ nếu
worldbị bỏ qua hoặc làUSER_SCRIPT. Các giá trị có dấu gạch dưới ở đầu (_) được đặt trước.
WorldProperties
Thuộc tính
-
csp
chuỗi không bắt buộc
Chỉ định csp chung. Mặc định là CSP thế giới
`ISOLATED`. -
nhắn tin
boolean không bắt buộc
Chỉ định xem API nhắn tin có được hiển thị hay không. Mặc định là
false. -
worldId
chuỗi không bắt buộc
Chrome 133 trở lên browser.* kể từ Chrome 148Chỉ định mã nhận dạng của môi trường tập lệnh người dùng cụ thể cần cập nhật. Nếu không được cung cấp, hãy cập nhật các thuộc tính của môi trường tập lệnh người dùng mặc định. Các giá trị có dấu gạch dưới ở đầu (
_) được đặt trước.
Phương thức
configureWorld()
browser.userScripts.configureWorld(
properties: WorldProperties,
): Promise<void>
Định cấu hình môi trường thực thi `USER_SCRIPT`.
Thông số
-
tài sản
Chứa cấu hình môi trường tập lệnh người dùng.
Giá trị trả về
-
Promise<void>
Lời hứa sẽ được giải quyết sau khi thế giới được định cấu hình.
execute()
browser.userScripts.execute(
injection: UserScriptInjection,
): 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 ngay lập tức nếu trang đã tải xong. 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 lời hứa, trình duyệt sẽ đợi lời hứa đó được giải quyết và trả về giá trị kết quả.
Thông số
-
tiêm
Giá trị trả về
-
Promise<InjectionResult[]>
getScripts()
browser.userScripts.getScripts(
filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>
Trả về tất cả tập lệnh người dùng được đăng ký động cho tiện ích này.
Thông số
-
filter
UserScriptFilter không bắt buộc
Nếu được chỉ định, phương thức này chỉ trả về các tập lệnh người dùng khớp với phương thức đó.
Giá trị trả về
-
Promise<RegisteredUserScript[]>
Lời hứa sẽ giải quyết bằng các tập lệnh đã đăng ký. Lời hứa sẽ bị từ chối nếu xảy ra lỗi.
getWorldConfigurations()
browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>
Truy xuất tất cả cấu hình thế giới đã đăng ký.
Giá trị trả về
-
Promise<WorldProperties[]>
Lời hứa sẽ phân giải bằng các cấu hình môi trường đã đăng ký.
register()
browser.userScripts.register(
scripts: RegisteredUserScript[],
): Promise<void>
Đăng ký một hoặc nhiều tập lệnh người dùng cho tiện ích này.
Thông số
-
các tập lệnh
Chứa danh sách tập lệnh người dùng cần đăng ký.
Giá trị trả về
-
Promise<void>
Lời hứa sẽ giải quyết sau khi tập lệnh được đăng ký đầy đủ. Lời hứa sẽ bị từ chối nếu xảy ra lỗi.
resetWorldConfiguration()
browser.userScripts.resetWorldConfiguration(
worldId?: string,
): Promise<void>
Đặt lại cấu hình cho một môi trường tập lệnh người dùng. Mọi tập lệnh chèn vào môi trường có mã nhận dạng được chỉ định sẽ sử dụng cấu hình môi trường mặc định.
Thông số
-
worldId
chuỗi không bắt buộc
Mã nhận dạng của môi trường tập lệnh người dùng cần đặt lại. Nếu bạn bỏ qua, cấu hình của môi trường mặc định sẽ được đặt lại.
Giá trị trả về
-
Promise<void>
Lời hứa sẽ được thực hiện khi cấu hình được đặt lại.
unregister()
browser.userScripts.unregister(
filter?: UserScriptFilter,
): Promise<void>
Huỷ đăng ký tất cả tập lệnh người dùng được đăng ký linh động cho tiện ích này.
Thông số
-
filter
UserScriptFilter không bắt buộc
Nếu được chỉ định, phương thức này chỉ huỷ đăng ký các tập lệnh người dùng khớp với phương thức đó.
Giá trị trả về
-
Promise<void>
Lời hứa sẽ giải quyết sau khi các tập lệnh đã được huỷ đăng ký hoàn toàn. Lời hứa sẽ bị từ chối nếu xảy ra lỗi.
update()
browser.userScripts.update(
scripts: RegisteredUserScript[],
): Promise<void>
Cập nhật một hoặc nhiều tập lệnh người dùng cho tiện ích này.
Thông số
-
các tập lệnh
Chứa danh sách tập lệnh người dùng 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 thuộc tính đó đượ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ì không có tập lệnh nào được cập nhật.
Giá trị trả về
-
Promise<void>
Lời hứa sẽ được giải quyết sau khi tập lệnh được cập nhật đầy đủ. Lời hứa sẽ bị từ chối nếu xảy ra lỗi.