browser.devtools.inspectedWindow

Mô tả

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

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

Thuộc tính tabId cung cấp giá trị nhận dạng thẻ mà bạn có thể dùng với các lệnh gọi API browser.tabs.*. Tuy nhiên, API browser.tabs.* không được hiển thị cho các trang tiện ích Công cụ cho nhà phát triển do các yếu tố bảo mật – bạn sẽ cần truyền mã nhận dạng thẻ đến trang nền và gọi các hàm API browser.tabs.* từ đó.

Bạn có thể sử dụng phương thức reload để tải lại trang đang được kiểm tra. Ngoài ra, phương thức gọi có thể chỉ định một cơ chế ghi đè cho chuỗi tác nhân người dùng, một tập lệnh sẽ được chèn sớm khi tải trang hoặc một tuỳ chọn để buộc tải lại tài nguyên đã 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. Bạn có thể sử dụng các phương thức getContent và setContent của lớp Resource cùng với sự kiện onResourceContentCommitted để hỗ trợ việc sửa đổi nội dung tài nguyên, chẳng hạn như bằng một trình chỉnh sửa bên ngoài.

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"

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 của trang được kiểm tra. Phương thức này rất hiệu quả khi được sử dụng trong bối cảnh phù hợp và nguy hiểm khi sử dụng không đúng cách. 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.

Sau đâ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, mã có thể truy cập vào trạng thái JavaScript của cửa sổ được kiểm tra. Hãy sử dụng phương thức này khi bạn cần truy cập vào trạng thái JavaScript của trang được kiểm tra.
  • Bối cảnh thực thi của mã đang được đánh giá bao gồm API bảng điều khiển Công cụ cho nhà phát triển. Ví dụ: mã có thể sử dụng inspect và $0.
  • Mã được đánh giá có thể trả về một giá trị được truyền đến lệnh gọi lại tiện ích. Giá trị được trả về phải là một đối tượng JSON hợp lệ (chỉ có thể chứa các kiểu JavaScript gốc và tham chiếu không tuần hoàn đến các đối tượng JSON khác). Hãy đặc biệt cẩn thận khi xử lý dữ liệu nhận được từ trang được kiểm tra – bối cảnh thực thi về cơ bản 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.

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

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

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

frameURL
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 một ngữ cảnh trong khung đã chỉ định theo nguồn gốc trang web của khung đó.
useContentScriptContext
Nếu đúng, hãy thực thi tập lệnh trong cùng bối cảnh với tập lệnh nội dung của tiện ích. (Tương đương với việc chỉ định nguồn gốc trang web của tiện ích làm nguồn gốc bảo mật bối cảnh.) Bạn có thể dùng tính năng này để trao đổi dữ liệu với tập lệnh nội dung.

Ví dụ

Đoạn mã sau đây kiểm tra phiên bản jQuery mà trang được kiểm tra sử dụng:

browser.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 ví dụ về API công cụ cho nhà phát triển từ kho lưu trữ chrome-extension-samples.

Loại

Resource

Một 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

    chuỗi

    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: 

    () => {...}

    • returns

      <object> hứa hẹn

      Chrome 151 trở lên browser.* kể từ Chrome 152

      Một hàm nhận nội dung tài nguyên khi yêu cầu hoàn tất.

  • setContent

    void

    Đặt nội dung của tài nguyên.

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

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

    • nội dung

      chuỗi

      Nội dung mới của tài nguyên. Hiện chỉ hỗ trợ các tài nguyên có loại văn bản.

    • cam kết

      boolean

      True 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ầ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.

    • returns

      <object> hứa hẹn

      Chrome 151 trở lên browser.* kể từ Chrome 152

      Một hàm được gọi khi hoàn tất yêu cầu.

Thuộc tính

tabId

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

Loại

số

Phương thức

eval()

browser.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
): Promise<object>

Đá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á thành một đối tượng tuân thủ JSON, nếu không, một ngoại lệ sẽ được gửi. 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 xảy ra lỗi phía Công cụ cho nhà phát triển, tham số isException sẽ khác rỗng và có isError được đặt thành true và code được đặt thành mã lỗi. Trong trường hợp xảy ra lỗi JavaScript, isException được đặt thành true và value được đặt thành giá trị chuỗi của đối tượng được gửi.

Thông số

  • biểu thức

    chuỗi

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

  • tùy chọn

    object không bắt buộc

    Tham số options có thể chứa một hoặc nhiều tuỳ 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 browser.* kể từ Chrome 152

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

    • useContentScriptContext

      boolean không bắt buộc

      Đánh giá biểu thức trong ngữ cảnh của 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 sẽ không được đánh giá và lệnh gọi lại sẽ được gọi bằng 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.

Giá trị trả về

  • <object> hứa hẹn

    Chrome 151 trở lên browser.* kể từ Chrome 152

    Một hàm được gọi khi quá trình đánh giá hoàn tất.

getResources()

browser.devtools.inspectedWindow.getResources(): Promise<Resource[]>

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

Giá trị trả về

  • Promise<Resource[]>

    Chrome 151 trở lên browser.* kể từ Chrome 152

    Một hàm nhận danh sách tài nguyên khi yêu cầu hoàn tất.

reload()

browser.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

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

Thông số

  • reloadOptions

    object 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 cho tất cả tài nguyên trang được kiểm tra đã tải trước khi sự kiện load được kích hoạt. Hiệu ứng này tương tự như khi nhấn tổ hợp phím Ctrl+Shift+R trong cửa sổ được kiểm tra hoặc trong cửa sổ Công cụ 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 chèn sau các lần tải lại tiếp theo, chẳng hạn 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 này 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

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

Thông số

  • callback

    hàm

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

    (resource: Resource) => void

onResourceContentCommitted

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

Được kích hoạt khi một 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 đã chỉnh sửa của tài nguyên trong Công cụ cho nhà phát triển).

Thông số

  • callback

    hàm

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

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