Trang này được dịch bởi Cloud Translation API.

chrome.devtools.inspectedWindow

Nội dung mô tả

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

Xem thông tin tóm tắt về API DevTools để biết 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ể sử dụng với các lệnh gọi API chrome.tabs.*. Tuy nhiên, xin lưu ý rằng API chrome.tabs.* không hiển thị với các trang tiện ích của Công cụ cho nhà phát triển vì lý do bảo mật. Bạn sẽ cần truyền mã thẻ vào trang nền và gọi các hàm API chrome.tabs.* từ đó.

Bạn có thể 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 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 ngay khi tải trang hoặc một lựa chọn để buộc tải lại các 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 các 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 tiện ích thực thi mã JavaScript trong bối cảnh trang được kiểm tra. Phương thức này hiệu quả khi được sử dụng trong ngữ cảnh phù hợp, nhưng lại nguy hiểm khi được dùng 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 thế giới riêng 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ổ đã kiểm tra. Hãy sử dụng phương thức này khi cần có quyền truy cập vào trạng thái JavaScript của trang được kiểm tra.
Ngữ 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ã 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 của phần mở rộng. Giá trị trả về phải là một đối tượng JSON hợp lệ (giá trị này chỉ có thể chứa các loại JavaScript nguyên gốc và tham chiếu không tuần hoàn đến các đối tượng JSON khác). Vui lòng quan sát kỹ hơn trong 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 là do trang được kiểm tra kiểm soá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 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 từng 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 thực thi trong ngữ 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à mã được đánh giá. Đố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ác với khung chính của trang được kiểm tra.
contextSecurityOrigin: Sử dụng để chọn một ngữ cảnh trong khung đã chỉ định theo nguồn gốc web.
useContentScriptContext: Nếu đúng, 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 phần mở rộng. (Tương đương với việc chỉ định tên gốc của tiện ích làm nguồn gốc bảo mật theo bối cảnh). Bạn có thể dùng tập lệnh này để trao đổi dữ liệu với tập lệnh nội dung.

Ví dụ

Đoạn mã sau đây sẽ kiểm tra phiên bản jQuery mà 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 kho lưu trữ chrome-extension-samples.

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 sẽ 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
```
  - những 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á, hãy mã hoá tên. 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 sẽ có dạng như sau:
```
(content: string,commit: boolean,callback?: function)=> {...}
```
- những 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 thuộc loại văn bản mới được hỗ trợ.
- 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 sẽ đượ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; nếu không thì mô tả lỗi.

Thuộc tính

tabId

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

Loại

number

Phương thức

eval()

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

Đánh giá một 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ẽ trả về một 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 xảy ra lỗi phía Công cụ cho nhà phát triển, tham số isException không phải là giá trị 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.

Tham số

biểu thức

string

Một biểu thức để đánh giá.
tùy chọn

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

Tham số options có thể chứa một hoặc nhiều tùy 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á ở 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 phù hợp với nguồn gố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 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 đượ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 quả
  
  đố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
    
    Thiết lập nếu lỗi xảy ra ở phía Công cụ cho nhà phát triển trước khi đánh giá biểu thức.
  - description
    
    string
    
    Thiết lập nếu lỗi xảy ra ở phía Công cụ cho nhà phát triển trước khi đánh giá biểu thức.
  - chi tiết
    
    bất kỳ[]
    
    Thiết lập nếu lỗi xảy ra ở phía Công cụ cho nhà phát triển trước khi đánh giá biểu thức, chứa mảng các giá trị có thể được thay vào chuỗi mô tả để cung cấp thêm thông tin về nguyên nhân gây ra lỗi.
  - isError
    
    boolean
    
    Thiết lập nếu lỗi xảy ra ở phía Công cụ cho nhà phát triển trước khi đánh giá biểu thức.
  - isException
    
    boolean
    
    Đặt nếu mã được đánh giá tạo ra trường hợp ngoại lệ chưa được xử lý.
  - value
    
    string
    
    Đặt nếu mã được đánh giá tạo ra trường hợp 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[]
  
  Tài nguyên trên trang.

reload()

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

Tải lại trang đã kiểm tra.

Tham số

reloadOptions

đối tượng không bắt buộc
- ignoreCache
  
  boolean không bắt buộc
  
  Khi giá trị này là true, trình tải sẽ bỏ qua bộ nhớ đệm đối với mọi tài nguyên trang đã kiểm tra và được tải trước khi kích hoạt sự kiện load. Hiệu ứng này tương tự như nhấn 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 bất kỳ tập lệnh nào của khung. Tập lệnh sẽ không được chèn sau những lần tải lại tiếp theo – ví dụ: 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

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
```
- tài nguyên
  
  Tài nguyên

onResourceContentCommitted

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

Tham số

số gọi lại

hàm

Tham số callback sẽ có dạng như sau:
```
(resource: Resource,content: string)=>void
```
- tài nguyên
  
  Tài nguyên
- những nội dung
  
  string