chrome.devtools.inspectedWindow

Mô tả

Sử dụng chrome.devtools.inspectedWindow API để tương tác với cửa sổ được kiểm tra: lấy mã thẻ cho trang được kiểm tra, đánh giá mã trong bối cảnh cửa sổ được kiểm tra, tải lại trang hoặc lấy danh sách tài nguyên trên trang.

Tệp kê khai

Bạn phải khai báo các khoá sau trong tệp kê khai để sử dụng API này.

"devtools_page"

Sử dụng chrome.devtools.inspectedWindow để tương tác với cửa sổ đã kiểm tra: lấy mã thẻ cho trang được kiểm tra, đánh giá mã trong bối cảnh cửa sổ được kiểm tra, tải lại trang hoặc lấy danh sách tài nguyên trên trang.

Xem Tóm tắt API Công cụ cho nhà phát triển để biết giới thiệu chung về cách sử dụng API Công cụ dành cho nhà phát triển.

Tổng quan

Thuộc tính tabId cung cấp giá trị nhận dạng thẻ mà bạn có thể sử dụng cùng với chrome.tabs.* Lệnh gọi API. Tuy nhiên, xin lưu ý rằng API chrome.tabs.* không được cung cấp cho Công cụ cho nhà phát triển do các cân nhắc về bảo mật—bạn sẽ cần chuyển ID thẻ vào chế độ nền trang và gọi các hàm API chrome.tabs.* từ đó.

Bạn có thể sử dụng phương thức reload để tải lại trang đã kiểm tra. Ngoài ra, phương thức gọi có thể chỉ định cơ chế ghi đè chuỗi tác nhân người dùng, một tập lệnh sẽ được đưa vào ngay khi tải trang hoặc một để buộc tải lại các tài nguyên được lưu vào bộ nhớ đệm.

Sử dụng lệnh gọi getResources và sự kiện onResourceContent để lấy danh sách tài nguyên (tài liệu, biểu định kiểu, tập lệnh, hình ảnh, v.v.) trong trang được kiểm tra. getContent và Các phương thức setContent của lớp Resource cùng với sự kiện onResourceContentCommitted có thể được sử dụng để hỗ trợ việc sửa đổi nội dung tài nguyên, chẳng hạn như trình chỉnh sửa bên ngoài.

Thực thi mã trong cửa sổ được kiểm tra

Phương thức eval cho phép các tiện ích thực thi mã JavaScript trong bối cảnh trang được kiểm tra. Phương pháp này phát huy hiệu quả nếu dùng trong bối cảnh phù hợp và nguy hiểm nếu dùng trong bối cảnh phù hợp không phù hợp. Sử dụng phương thức tabs.executeScript trừ phi bạn cần chức năng cụ thể mà phương thức eval cung cấp.

Dưới đây là những điểm khác biệt chính giữa phương thức eval và tabs.executeScript:

  • Phương thức eval không sử dụng một môi trường tách biệt cho mã đang được đánh giá, vì vậy, JavaScript Mã có thể truy cập vào trạng thái của cửa sổ được kiểm tra. Hãy sử dụng phương thức này khi truy cập vào Bạn phải nhập trạng thái JavaScript của trang được kiểm tra.
  • Ngữ cảnh thực thi mã đang được đánh giá bao gồm API Bảng điều khiển của công cụ dành cho nhà phát triển. Ví dụ: mã này có thể sử dụng inspect và $0.
  • Mã được đánh giá có thể trả về một giá trị được chuyển đến lệnh gọi lại tiện ích. Giá trị trả về phải là một đối tượng JSON hợp lệ (chỉ có thể chứa các loại JavaScript gốc và không tuần hoàn tham chiếu đến các đối tượng JSON khác). Hãy thận trọng hơn khi xử lý dữ liệu nhận được từ trang được kiểm tra – ngữ cảnh thực thi về cơ bản đều do trang được kiểm tra kiểm soát; một trang độc hại có thể ảnh hưởng đến dữ liệu được trả về tiện ích.

Lưu ý rằng một trang có thể bao gồm nhiều ngữ cảnh thực thi JavaScript khác nhau. Mỗi khung có ngữ cảnh riêng, cùng với ngữ cảnh bổ sung cho mỗi tiện ích có tập lệnh nội dung chạy trong ngữ cảnh đó khung.

Theo mặc định, phương thức eval sẽ thực thi trong bối cảnh khung chính của trang được kiểm tra.

Phương thức eval lấy một đối số thứ hai (không bắt buộc) mà bạn có thể dùng để chỉ định ngữ cảnh mã được đánh giá. Đối tượng options này có thể chứa một hoặc nhiều khoá sau:

frameURL
Sử dụng để chỉ định một khung không phải khung chính của trang được kiểm tra.
contextSecurityOrigin
Dùng để chọn bối cảnh trong khung hình được chỉ định theo nguồn gốc web.
useContentScriptContext
Nếu giá trị là true, hãy thực thi tập lệnh trong cùng ngữ cảnh với tập lệnh nội dung của tiện ích. (Tương đương với chỉ định nguồn gốc web riêng của tiện ích là nguồn gốc bảo mật theo bối cảnh). Bạn có thể dùng thông tin này để trao đổi dữ liệu với tập lệnh nội dung.

Ví dụ

Các mã sau đây sẽ kiểm tra phiên bản jQuery được trang được kiểm tra sử dụng:

chrome.devtools.inspectedWindow.eval(
  "jQuery.fn.jquery",
  function(result, isException) {
    if (isException) {
      console.log("the page is not using jQuery");
    } else {
      console.log("The page is using jQuery v" + result);
    }
  }
);

Để dùng thử API này, hãy cài đặt các ví dụ về API cho nhà phát triển trong chrome-extension-samples kho lưu trữ.

Loại

Resource

Tài nguyên trong trang được kiểm tra, chẳng hạn như tài liệu, tập lệnh hoặc hình ảnh.

Thuộc tính

  • url

    string

    URL của tài nguyên.

  • getContent

    void

    Lấy nội dung của tài nguyên.

    Hàm getContent có dạng như sau: 

    (callback: function) => {...}

    • số gọi lại

      hàm

      Tham số callback sẽ có dạng như sau: 

      (content: string, encoding: string) => void

      • nội dung

        string

        Nội dung của tài nguyên (có thể đã được mã hoá).

      • mã hoá

        string

        Để trống nếu nội dung không được mã hoá, nếu không thì tên mã hoá. Hiện tại, chúng tôi chỉ hỗ trợ base64.

  • setContent

    void

    Thiết lập nội dung của tài nguyên.

    Hàm setContent có dạng như sau: 

    (content: string, commit: boolean, callback?: function) => {...}

    • nội dung

      string

      Nội dung mới của tài nguyên. Hiện tại, chỉ những tài nguyên có loại văn bản này mới được hỗ trợ.

    • cam kết

      boolean

      Đúng nếu người dùng đã chỉnh sửa xong tài nguyên và nội dung mới của tài nguyên đó được duy trì; false nếu đây là một thay đổi nhỏ được gửi trong quá trình người dùng chỉnh sửa tài nguyên.

    • số gọi lại

      hàm không bắt buộc

      Tham số callback sẽ có dạng như sau: 

      (error?: object) => void

      • error

        đối tượng không bắt buộc

        Đặt thành không xác định nếu nội dung tài nguyên đã được đặt thành công; lại mô tả lỗi.

Thuộc tính

tabId

Mã của thẻ đang được kiểm tra. Bạn có thể dùng mã nhận dạng này với chrome.tabs.* API.

Loại

số

Phương thức

eval()

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
)

Đánh giá biểu thức JavaScript trong ngữ cảnh của khung chính của trang được kiểm tra. Biểu thức phải đánh giá cho một đối tượng tuân thủ JSON, nếu không thì hệ thống sẽ gửi một trường hợp ngoại lệ. Hàm eval có thể báo cáo lỗi phía Công cụ cho nhà phát triển hoặc ngoại lệ JavaScript xảy ra trong quá trình đánh giá. Trong cả hai trường hợp, tham số result của lệnh gọi lại là undefined. Trong trường hợp lỗi phía Công cụ cho nhà phát triển, tham số isException không rỗng và đã đặt isError thành true còn code được đặt thành mã lỗi. Trong trường hợp lỗi JavaScript, isException được thiết lập thành true và value được đặt thành giá trị chuỗi của đối tượng được gửi.

Tham số

  • biểu thức

    string

    Biểu thức để đánh giá.

  • tùy chọn

    đối tượng không bắt buộc

    Tham số options có thể chứa một hoặc nhiều lựa chọn.

    • frameURL

      chuỗi không bắt buộc

      Nếu được chỉ định, biểu thức sẽ được đánh giá trên iframe có URL khớp với URL được chỉ định. Theo mặc định, biểu thức được đánh giá trong khung trên cùng của trang được kiểm tra.

    • scriptExecutionContext

      chuỗi không bắt buộc

      Chrome 107 trở lên

      Đánh giá biểu thức trong ngữ cảnh tập lệnh nội dung của một tiện ích khớp với nguồn gốc đã chỉ định. Nếu được cung cấp, scriptExecutionContext sẽ ghi đè giá trị "true" sử dụng useContentScriptContext.

    • useContentScriptContext

      boolean không bắt buộc

      Đánh giá biểu thức trong ngữ cảnh tập lệnh nội dung của tiện ích gọi, miễn là tập lệnh nội dung đã được chèn vào trang được kiểm tra. Nếu không, biểu thức không được đánh giá và lệnh gọi lại sẽ được gọi với tham số ngoại lệ được đặt thành một đối tượng có trường isError được đặt thành true và trường code được đặt thành E_NOTFOUND.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (result: object, exceptionInfo: object) => void

    • kết quả

      đối tượng

      Kết quả đánh giá.

    • exceptionInfo

      đối tượng

      Một đối tượng cung cấp thông tin chi tiết nếu có ngoại lệ xảy ra trong khi đánh giá biểu thức.

      • mã

        string

        Đặt xem lỗi có xảy ra ở phía Công cụ cho nhà phát triển hay không trước khi biểu thức được đánh giá.

      • description

        string

        Đặt xem lỗi có xảy ra ở phía Công cụ cho nhà phát triển hay không trước khi biểu thức được đánh giá.

      • chi tiết

        bất kỳ[]

        Đặt nếu lỗi xảy ra ở phía Công cụ cho nhà phát triển trước khi biểu thức được đánh giá, hàm này chứa mảng các giá trị có thể được thay thế vào chuỗi mô tả để cung cấp thêm thông tin về nguyên nhân lỗi.

      • isError

        boolean

        Đặt xem lỗi có xảy ra ở phía Công cụ cho nhà phát triển hay không trước khi biểu thức được đánh giá.

      • isException

        boolean

        Đặt nếu mã được đánh giá tạo ra ngoại lệ chưa được xử lý.

      • value

        string

        Đặt nếu mã được đánh giá tạo ra ngoại lệ chưa được xử lý.

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
)

Truy xuất danh sách tài nguyên từ trang đã kiểm tra.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (resources: Resource[]) => void

    • các tài nguyên

      Tài nguyên[]

      Các tài nguyên trong trang.

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
)

Tải lại trang được kiểm tra.

Tham số

  • reloadOptions

    đối tượng không bắt buộc

    • ignoreCache

      boolean không bắt buộc

      Khi đúng, trình tải sẽ bỏ qua bộ nhớ đệm đối với mọi tài nguyên trang được kiểm tra và tải trước khi sự kiện load được kích hoạt. Hiệu ứng này tương tự như việc nhấn Ctrl+Shift+R trong cửa sổ được kiểm tra hoặc trong cửa sổ Công cụ dành cho nhà phát triển.

    • injectedScript

      chuỗi không bắt buộc

      Nếu được chỉ định, tập lệnh sẽ được chèn vào mọi khung của trang được kiểm tra ngay khi tải, trước mọi tập lệnh của khung đó. Tập lệnh sẽ không được đưa vào sau những lần tải lại tiếp theo, ví dụ như nếu người dùng nhấn tổ hợp phím Ctrl+R.

    • userAgent

      chuỗi không bắt buộc

      Nếu được chỉ định, chuỗi sẽ ghi đè giá trị của tiêu đề HTTP User-Agent được gửi trong khi tải tài nguyên của trang được kiểm tra. Chuỗi này cũng sẽ ghi đè giá trị của thuộc tính navigator.userAgent được trả về cho mọi tập lệnh đang chạy trong trang được kiểm tra.

Sự kiện

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

Được kích hoạt khi một tài nguyên mới được thêm vào trang được kiểm tra.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (resource: Resource) => void

onResourceContentCommitted

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

Được kích hoạt khi bản sửa đổi mới của tài nguyên được cam kết (ví dụ: người dùng lưu phiên bản tài nguyên đã chỉnh sửa trong Công cụ cho nhà phát triển).

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (resource: Resource, content: string) => void