browser.devtools.inspectedWindow

說明

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

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

tabId 屬性提供分頁 ID，可與 browser.tabs.* API 呼叫搭配使用。不過，基於安全考量，browser.tabs.* API 不會向開發人員工具擴充功能頁面公開，您必須將分頁 ID 傳遞至背景頁面，並從該頁面叫用 browser.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 版本：

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

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

類型

Resource

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

屬性

  • 網址

    字串

    資源的網址。

  • getContent

    void

    取得資源內容。

    getContent 函式如下所示： 

    () => {...}

    • returns

      Promise<object>

      Chrome 151 以上版本 瀏覽器。*自 Chrome 152 起

      在要求完成時接收資源內容的函式。

  • setContent

    void

    設定資源內容。

    setContent 函式如下所示： 

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

    • 內容

      字串

      資源的新內容。目前僅支援文字類型的資源。

    • commit

      布林值

      如果使用者已完成資源編輯，且應保留資源的新內容，則為 True；如果這是使用者編輯資源時傳送的小幅變更，則為 False。

    • returns

      Promise<object>

      Chrome 151 以上版本 瀏覽器。*自 Chrome 152 起

      要求完成時呼叫的函式。

屬性

tabId

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

類型

數字

方法

eval()

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

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

參數

  • 運算式

    字串

    要評估的運算式。

  • 選項

    物件 選填

    options 參數可包含一或多個選項。

    • frameURL

      字串 選填

      如果指定，系統會對網址與指定網址相符的 iframe 評估運算式。根據預設，系統會在受檢查網頁的頂端框架中評估運算式。

    • scriptExecutionContext

      字串 選填

      Chrome 107 以上版本 瀏覽器。*自 Chrome 152 起

      在與指定來源相符的擴充功能內容指令碼中，評估運算式。如果提供 scriptExecutionContext，則會覆寫 useContentScriptContext 的「true」設定。

    • useContentScriptContext

      布林值 選填

      在呼叫擴充功能的內容指令碼情境中評估運算式，前提是內容指令碼已插入受檢查的頁面。如果沒有，系統就不會評估運算式，並叫用回呼，將例外狀況參數設為物件，其中 isError 欄位設為 true，code 欄位設為 E_NOTFOUND。

傳回

  • Promise<object>

    Chrome 151 以上版本 瀏覽器。*自 Chrome 152 起

    評估完成時呼叫的函式。

getResources()

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

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

傳回

  • Promise<Resource[]>

    Chrome 151 以上版本 瀏覽器。*自 Chrome 152 起

    在要求完成時接收資源清單的函式。

reload()

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

重新載入檢查的網頁。

參數

  • reloadOptions

    物件 選填

    • ignoreCache

      布林值 選填

      如果設為 true，載入器會略過快取，處理在 load 事件觸發前載入的所有受檢網頁資源。效果類似於在檢查視窗或開發人員工具視窗中按下 Ctrl+Shift+R 鍵。

    • injectedScript

      字串 選填

      如果指定，系統會在載入受檢網頁時，立即將指令碼插入每個頁框，並在頁框的任何指令碼之前執行。後續重新載入 (例如使用者按下 Ctrl+R 鍵) 後，系統不會插入指令碼。

    • userAgent

      字串 選填

      如果指定，這個字串會覆寫載入受檢網頁資源時傳送的 User-Agent HTTP 標頭值。這個字串也會覆寫 navigator.userAgent 屬性的值，並傳回給在受檢查網頁中執行的任何指令碼。

事件

onResourceAdded

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

在受檢查頁面中新增資源時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (resource: Resource) => void

onResourceContentCommitted

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

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

參數

  • callback

    函式

    callback 參數如下： 

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