Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

chrome.devtools.inspectedWindow

說明

使用 chrome.devtools.inspectedWindow API 與檢查的視窗互動：取得檢查頁面的分頁 ID、評估檢查視窗環境中的程式碼、重新載入頁面，或取得頁面中的資源清單。

如需開發人員工具 API 的一般簡介，請參閱開發人員工具 API 摘要。

tabId 屬性提供分頁 ID，可用於 chrome.tabs.* API 呼叫。不過請注意，基於安全考量，chrome.tabs.* API 不會公開給開發人員工具擴充功能頁面，您必須將分頁 ID 傳遞至背景頁面，並從該處叫用 chrome.tabs.* API 函式。

reload 方法可用於重新載入檢查的網頁。此外，呼叫端可以指定使用者代理程式字串的覆寫項目、在載入網頁時提早插入的指令碼，或強制重新載入快取資源的選項。

使用 getResources 呼叫和 onResourceContent 事件，取得檢查頁面中的資源清單 (文件、樣式表、指令碼、圖片等)。Resource 類別的 getContent 和 setContent 方法以及 onResourceContentCommitted 事件可用於支援修改資源內容，例如透過外部編輯器。

資訊清單

如要使用這項 API，必須在資訊清單中宣告下列鍵。

"devtools_page"

在檢查視窗中執行程式碼

擴充功能可透過 eval 方法，在檢查的網頁環境中執行 JavaScript 程式碼。這個方法在適當情況下使用非常強大，但若使用不當則很危險。除非需要 eval 方法提供的特定功能，否則請使用 tabs.executeScript 方法。

eval 和 tabs.executeScript 方法的主要差異如下：

eval 方法不會為評估的程式碼使用獨立世界，因此程式碼可存取檢查視窗的 JavaScript 狀態。如要存取檢查網頁的 JavaScript 狀態，請使用這個方法。
程式碼的評估執行環境包含開發人員工具控制台 API。舉例來說，程式碼可以使用 inspect 和 $0。
評估的程式碼可能會傳回值，並傳遞至擴充功能回呼。傳回的值必須是有效的 JSON 物件 (可能只包含原始 JavaScript 型別，以及對其他 JSON 物件的非循環參照)。處理從檢查頁面收到的資料時，請格外謹慎，因為執行環境基本上是由檢查頁面控管；惡意網頁可能會影響傳回擴充功能的資料。

請注意，網頁可以包含多個不同的 JavaScript 執行環境。每個頁框都有自己的內容，以及每個擴充功能在該頁框中執行的內容指令碼的額外內容。

根據預設，eval 方法會在檢查頁面的主要框架環境中執行。

eval 方法會採用選用的第二個引數，您可以用來指定評估程式碼的環境。這個 options 物件可包含下列一或多個鍵：

frameURL: 用來指定檢查網頁主頁框以外的頁框。
contextSecurityOrigin: 根據指定框架的網路來源，選取該框架內的環境。
useContentScriptContext: 如果為 true，則會在與擴充功能內容指令碼相同的環境中執行指令碼。(相當於將擴充功能的自有網路來源指定為內容安全性來源)。這可用於與內容指令碼交換資料。

範例

下列程式碼會檢查所檢查網頁使用的 jQuery 版本：

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);
    }
  }
);

如要試用這個 API，請從 chrome-extension-samples 存放區安裝 devtools API 範例。

類型

Resource

受檢查網頁中的資源，例如文件、指令碼或圖片。

屬性

網址

字串

資源的網址。
getContent

void

取得資源內容。

getContent 函式如下所示：
```
(callback: function) => {...}
```
- callback
  
  函式
  
  callback 參數如下：
```
(content: string, encoding: string) => void
```
  - 內容
    
    字串
    
    資源內容 (可能經過編碼)。
  - encoding
    
    字串
    
    如果內容未經過編碼，則為空白；否則為編碼名稱。目前僅支援 base64。
setContent

void

設定資源的內容。

setContent 函式如下所示：
```
(content: string, commit: boolean, callback?: function) => {...}
```
- 內容
  
  字串
  
  資源的新內容。目前僅支援文字類型的資源。
- commit
  
  布林值
  
  如果使用者已完成編輯資源，且應保留資源的新內容，則為 True；如果這是使用者編輯資源時傳送的次要變更，則為 False。
- callback
  
  函式選填
  
  callback 參數如下：
```
(error?: object) => void
```
  - 錯誤
    
    object 選填
    
    如果資源內容設定成功，請設為未定義；否則請說明錯誤。

屬性

tabId

正在檢查的分頁 ID。這個 ID 可與 chrome.tabs.* 搭配使用API。

類型

數字

方法

eval()

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

在檢查網頁的主要框架中評估 JavaScript 運算式。運算式必須評估為符合 JSON 規範的物件，否則會擲回例外狀況。eval 函式可以回報 DevTools 端的錯誤，或評估期間發生的 JavaScript 例外狀況。無論是哪種情況，回呼的 result 參數都是 undefined。如果是開發人員工具端的錯誤，isException 參數會是非空值，且 isError 會設為 true，而 code 會設為錯誤代碼。如果發生 JavaScript 錯誤，isException 會設為 true，而 value 會設為擲回物件的字串值。

參數

運算式

字串

要評估的運算式。
選項

object 選填

options 參數可以包含一或多個選項。
- frameURL
  
  字串選填
  
  如果指定，系統會在網址與指定網址相符的 iframe 上評估運算式。根據預設，系統會在檢查網頁的頂端框架中評估運算式。
- scriptExecutionContext
  
  字串選填
  
  Chrome 107 以上版本
  
  在擴充功能內容指令碼的環境中評估運算式，該指令碼與指定的來源相符。如果提供 scriptExecutionContext，系統會覆寫 useContentScriptContext 的「true」設定。
- useContentScriptContext
  
  布林值選填
  
  在呼叫擴充功能的內容指令碼環境中評估運算式，前提是內容指令碼已插入檢查的網頁。如果不是，系統不會評估運算式，並會叫用回呼，且例外狀況參數會設為 isError 欄位設為 true，而 code 欄位設為 E_NOTFOUND 的物件。
callback

函式選填

callback 參數如下：
```
(result: object, exceptionInfo: object) => void
```
- 結果
  
  物件
  
  評估結果。
- exceptionInfo
  
  物件
  
  如果評估運算式時發生例外狀況，則提供詳細資料的物件。
  - 程式碼
    
    字串
    
    設定錯誤是否在運算式評估前發生於開發人員工具端。
  - 說明
    
    字串
    
    設定錯誤是否在運算式評估前發生於開發人員工具端。
  - 詳細資料
    
    不限 []
    
    設定錯誤是否在運算式評估前發生於開發人員工具端，包含可能代入說明字串的值陣列，以提供錯誤原因的詳細資訊。
  - isError
    
    布林值
    
    設定錯誤是否在運算式評估前發生於開發人員工具端。
  - isException
    
    布林值
    
    設定評估的程式碼是否會產生未處理的例外狀況。
  - 值
    
    字串
    
    設定評估的程式碼是否會產生未處理的例外狀況。

getResources()

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

從檢查的頁面擷取資源清單。

參數

callback

函式

callback 參數如下：
```
(resources: Resource[]) => void
```
- 資源
  
  資源[]
  
  網頁中的資源。

reload()

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

重新載入檢查的網頁。

參數

reloadOptions

object 選填
- ignoreCache
  
  布林值選填
  
  如果為 true，載入器會略過所有檢查過的網頁資源的快取，這些資源會在 load 事件觸發前載入。效果類似於在檢查視窗或開發人員工具視窗中按下 Ctrl+Shift+R 鍵。
- injectedScript
  
  字串選填
  
  如果指定，系統會在載入檢查的網頁後，立即將指令碼插入每個框架，且會先於任何框架的指令碼。後續重新載入時 (例如使用者按下 Ctrl+R 鍵)，系統不會再注入指令碼。
- userAgent
  
  字串選填
  
  如果指定字串，系統會在載入檢查網頁的資源時，覆寫傳送的 User-Agent HTTP 標頭值。這個字串也會覆寫傳回給檢查頁面中任何執行指令碼的 navigator.userAgent 屬性值。

事件

onResourceAdded

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

當新資源新增至檢查的頁面時，就會觸發這個事件。

參數

callback

函式

callback 參數如下：
```
(resource: Resource) => void
```
- 資源
  
  資源

onResourceContentCommitted

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

在提交資源的新修訂版本時觸發 (例如使用者在開發人員工具中儲存資源的編輯版本)。

參數

callback

函式

callback 參數如下：
```
(resource: Resource, content: string) => void
```
- 資源
  
  資源
- 內容
  
  字串