chrome.userScripts

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 chrome.userScripts, hãy thêm quyền "userScripts" vào manifest.json và "host_permissions" cho các trang web 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

Chrome 120 trở lên Video nhạc 3 trở lên

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. Tập lệnh là 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 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ủa bạn cũng sẽ 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.

  1. 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.)

  2. Bật Chế độ nhà phát triển bằng cách nhấp vào nút chuyển bên cạnh Chế độ nhà phát triển.

    Trang Phần mở rộng

    Trang Tiện ích (chrome://extensions)

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 những thế giới tách biệt

Cả tập lệnh người dùng và nội dung đều có thể chạy trong một môi trường tách biệt hoặc trong thế giới chính. Môi trường tách 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. Điều này cho phép tập lệnh người dùng thay đổi môi trường JavaScript của tập lệnh mà không ảnh hưởng đến trang lưu trữ hoặc các tiện ích khác' tập lệnh nội dung và tập lệnh người dùng. 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 thế giới chính có thể truy cập được vào trang lưu trữ và các tiện ích mở rộng khác, đồng thời hiển thị cho trang lưu trữ và các tiện ích mở rộng khác. Để chọn cả 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():

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 tiện ích thông qua tính năng nhắn tin (tức là họ có thể gọi runtime.sendMessage() và runtime.connect() như mọi phần khác của tiện ích). Tuy nhiên, bạn nhận được các sự kiện này thông qua các trình xử lý sự kiện chuyên dụng (có nghĩa là các trình xử lý sự kiện không sử dụng onMessage hoặc onConnect). Những 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 người dùng (đây là một ngữ cảnh ít tin cậy hơn).

Trước khi gửi tin nhắn, bạn phải gọi hàm configureWorld() với đối số messaging được thiết lập thành true. Xin lưu ý rằng cả hai đối số csp và messaging đều có thể được truyền cùng 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 một tiện ích cập nhật. Bạn có thể thêm lại tiện ích 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ỉ phản hồi lý do "update" được chuyển đến lệnh gọi lại sự kiện.

Ví dụ:

Ví dụ này lấy từ mẫu userScript trong kho lưu trữ mẫu của chúng tôi.

Đăng ký một tập lệnh

Ví dụ sau đây trình bày 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 đăng ký. Có nhiều lựa chọn hơn số lượng hiển thị ở đây.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Loại

ExecutionWorld

Thế giới JavaScript để tập lệnh người dùng thực thi bên trong.

Enum

"MAIN"
Chỉ định môi trường thực thi của DOM. Đây 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.

RegisteredUserScript

Thuộc tính

  • allFrames

    boolean không bắt buộc

    Nếu 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.

  • excludeGlobs

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

    Chỉ định các 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 đưa 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 đưa 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ã 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ì mã này được dành riê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 các mẫu ký tự đại diện cho các trang sẽ chèn tập lệnh người dùng này.

  • JavaScript

    ScriptSource[]

    Danh sách đối tượng ScriptSource xác định các 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 đưa 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 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

    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 để chèn. Bạn phải chỉ định chính xác một trong hai giá trị file hoặc code.

  • 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 giá trị file hoặc code.

UserScriptFilter

Thuộc tính

  • id

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

    getScripts chỉ trả về các tập lệnh có mã nhận dạng đượ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. Giá trị 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.

Phương thức

configureWorld()

Lời hứa 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Định cấu hình môi trường thực thi `USER_SCRIPT`.

Tham số

  • các tài sản

    WorldProperties

    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ề

  • 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.

getScripts()

Lời hứa 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Trả về tất cả tập lệnh người dùng đã đăng ký động cho tiện ích này.

Tham 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 nó.

  • 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

Giá trị trả về

  • Promise&lt;RegisteredUserScript[]&gt;

    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.

register()

Lời hứa 
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.

Tham số

  • các tập lệnh

    RegisteredUserScript[]

    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ề

  • 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.

unregister()

Lời hứa 
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.

Tham 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 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>

    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.

update()

Lời hứa 
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.

Tham số

  • các tập lệnh

    RegisteredUserScript[]

    Chứa danh sách tập lệnh người dùng 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.