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 Video nhạc 3 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. 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

Chrome 96 trở lên

Thuộc tính

  • id [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 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

    InjectionTarget

    Thông tin chi tiết chỉ định đích đến mà bạn muốn chèn CSS vào.

ExecutionWorld

Chrome 95 trở lên

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ên

    Giấy tờ liên quan đến thao tác chèn.

  • frameId

    số

    Chrome 90 trở lên

    Khung đượ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ên

    Mã 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

Chrome 96 trở lên

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ên

    Cho 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ên

    Cá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ặc func.

  • injectImmediately

    boolean không bắt buộc

    Chrome 102 trở lên

    Liệ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

    InjectionTarget

    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ên

    Mộ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ặ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 kiểu để biết thêm thông tin.

Enum

"AUTHOR"

"NGƯỜI DÙNG"

Phương thức

executeScript()

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

  • 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

Giá trị trả về

  • Promise<InjectionResult[]>

    Chrome 90 trở lên

    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.

getRegisteredContentScripts()

Lời hứa Chrome 96 trở lên 
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ố

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()

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

    CSSInjection

    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ên

    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.

registerContentScripts()

Lời hứa Chrome 96 trở lên 
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

    RegisteredContentScript[]

    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()

Lời hứa Chrome 90 trở lên 
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

    CSSInjection

    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 qua insertCSS. 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()

Lời hứa Chrome 96 trở lên 
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()

Lời hứa Chrome 96 trở lên 
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

    RegisteredContentScript[]

    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.