Nội dung mô tả
Sử dụng API userScripts
để thực thi tập lệnh người dùng trong ngữ cảnh Tập lệnh người dùng.
Quyền
userScripts
Để sử dụng API chrome.userScripts
, hãy thêm quyền "userScripts"
vào 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 một trang web để sửa đổi giao diện hoặc hành vi của trang đó. Các tập lệnh do người dùng tạo hoặc được tải xuống từ kho lưu trữ tập lệnh hoặc tiện ích tập lệnh của người dùng.
Chế độ nhà phát triển dành cho người dùng tiện ích
Là nhà phát triển tiện ích, bạn đ�� b��t Chế độ nhà phát triển trong quá trình cài đặt Chrome. Đối với tiện ích tập lệnh người dùng, người dùng cũng cần bật chế độ nhà phát triển. Sau đây là hướng dẫn mà bạn có thể sao chép và dán vào tài liệu của riêng mình.
- Chuyển đến trang Tiện ích bằng cách nhập
chrome://extensions
vào thẻ mới. (Theo thiết kế,chrome://
URL không thể liên kết.) 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.
Bạn có thể xác định xem chế độ nhà phát triển đã được bật hay chưa bằng cách kiểm tra xem chrome.userScripts
có gửi lỗi hay không. Ví dụ:
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
Làm việc trong các thế giới 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 thế giới riêng biệt hoặc trong môi trường chính. Thế giới riêng biệt là môi trường thực thi không thể truy cập vào trang lưu trữ hoặc các tiện ích khác. Việc 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 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ị cho trang lưu trữ hoặc tập lệnh người dùng và tập lệnh nội dung của các tiện ích khác. Các tập lệnh đang chạy trong phiên bản chính có thể truy cập vào trang lưu trữ và các tiện ích khác, đồng thời hiển thị trên 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 USER_SCRIPT
, hãy gọi userScripts.configureWorld()
:
chrome.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 một tiện ích thông qua tính năng nhắn tin (tức là các tập lệnh đó 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 trình xử lý này được nhận bằng các trình xử lý sự kiện chuyên dụng (có nghĩa là các trình xử lý này 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
. Các 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 của người dùng. Đây là ngữ cảnh ít được 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 cả đối số csp
và messaging
đều có thể được truyền cùng một lúc.
chrome.userScripts.configureWorld({
messaging: true
});
Bản cập nhật 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 trình xử lý 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ụ tiện ích. Chỉ trả lời lý do "update"
được chuyể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 minh hoạ một lệnh gọi cơ bản đến register()
. Đối số đầu tiên là một mảng các đối tượng xác định các tập lệnh cần được đăng ký. Có nhiều lựa chọn hơn những lựa chọn được trình bày ở đây.
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Loại
ExecutionWorld
Thế giới JavaScript để một tập lệnh người dùng thực thi trong đó.
Liệt kê
"MAIN"
Chỉ định môi trường thực thi của DOM, 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 của người dùng và được miễn trừ CSP của trang.
RegisteredUserScript
Thuộc tính
-
allFrames
boolean không bắt buộc
Nếu đúng, thẻ này sẽ được chèn vào tất cả khung hình, ngay cả khi khung hình đó không phải là khung trên cùng trong thẻ. Mỗi khung được kiểm tra độc lập để biết các yêu cầu về URL; khung này sẽ không được chèn vào 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.
-
excludeGlobs
string[] không bắt buộc
Chỉ định mẫu ký tự đại diện cho các trang sẽ KHÔNG chèn tập lệnh người dùng này vào.
-
excludeMatches
string[] không bắt buộc
Không bao gồm các trang mà tập lệnh người dùng 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ã 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ì nó được dùng làm tiền tố cho các 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 sẽ chèn tập lệnh người dùng này.
-
js
Danh sách đối tượng ScriptSource xác định nguồn tập lệnh sẽ được chèn vào các trang phù hợp.
-
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. 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 ${ref:register}.
-
runAt
RunAt không bắt buộc
Chỉ định thời điểm các tệp JavaScript được đưa 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`
.
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. Phải chỉ định chính xác một trong số
file
hoặ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. Phải chỉ định chính xác một trong số
file
hoặccode
.
UserScriptFilter
Thuộc tính
-
ids
string[] không bắt buộc
getScripts
chỉ trả về các tập lệnh có mã được chỉ định trong danh sách này.
WorldProperties
Thuộc tính
-
CSP
chuỗi không bắt buộc
Chỉ định csp thế giới. Mặc định là csp thế giới
`ISOLATED`
. -
nhắn tin
boolean không bắt buộc
Chỉ định xem có hiển thị các API nhắn tin hay không. Mặc định là
false
.
Phương thức
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Định cấu hình môi trường thực thi `USER_SCRIPT`
.
Thông số
-
các tài sản
Chứa cấu hình thế giới của tập lệnh người dù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ề
-
Promise<void>
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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
Trả về tất cả các tập lệnh người dùng đã đăng ký tự động cho phần mở rộng 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 đó.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(scripts: RegisteredUserScript[]) => void
-
các tập lệnh
-
Giá trị trả về
-
Promise<RegisteredUserScript[]>
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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
Đă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 các tập lệnh người dùng cần đă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ề
-
Promise<void>
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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
Huỷ đăng ký tất cả tập lệnh người dùng đã đă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 sẽ chỉ huỷ đăng ký các tập lệnh người dùng khớp với phương thức đó.
-
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ề
-
Promise<void>
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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
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 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 các mã nhận dạng được chỉ định không tương ứng với tập lệnh đã đă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ề
-
Promise<void>
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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.