chrome.devtools.inspectedWindow

說明

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

如需開發人員工具 API 的一般使用簡介，請參閱 DevTools 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 狀態時，請使用這個方法。
  • 所評估程式碼的執行環境包括 Developer Tools Console 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

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

屬性

  • url

    字串

    資源的網址。

  • getContent

    void

    取得資源的內容。

    getContent 函式如下所示：

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

    • 回呼

      功能

      callback 參數如下所示： 

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

      • 內容

        字串

        資源內容 (可能經過編碼)。

      • encoding

        字串

        如果內容未編碼，則為空白，否則編碼名稱會是空白。目前僅支援 Base64。

  • setContent

    void

    設定資源的內容。

    setContent 函式如下所示：

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

    • 內容

      字串

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

    • commit

      boolean

      如果使用者已完成資源編輯，則為「true」，資源的新內容應保留下來；如果是使用者編輯資源正在進行的次要變更，則為「false」。

    • 回呼

      函式選用

      callback 參數如下所示： 

      (error?: object)=>void

      • 錯誤

        物件選用

        如果資源內容已成功設定，請設為未定義；否則，請說明錯誤。

屬性

tabId

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

類型

號碼

方法

eval()

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

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

參數

  • 運算式

    字串

    要評估的運算式。

  • 選項

    物件選用

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

    • frameURL

      字串 選用

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

    • scriptExecutionContext

      字串 選用

      Chrome 107 以上版本

      在符合指定來源的副檔名的內容指令碼中評估運算式。如果指定，scriptExecutionContext 會覆寫 useContentScriptContext 的「true」設定。

    • useContentScriptContext

      布林值 (選用)

      在呼叫的擴充功能內容指令碼中，評估運算式的內容 (前提是該指令碼已插入要檢查的網頁)。如果不使用的話，系統不會評估運算式，並叫用回呼，而例外狀況參數是設為 isError 欄位設為 true 的物件，且 code 欄位則設為 E_NOTFOUND。

  • 回呼

    函式選用

    callback 參數如下所示： 

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

    • 結果

      物件

      評估結果。

    • exceptionInfo

      物件

      如果評估運算式時發生例外狀況，就會提供詳細資料的物件。

      • 代碼

        字串

        設定是否在開發人員工具端發生錯誤，然後再評估運算式。

      • description

        字串

        設定是否在開發人員工具端發生錯誤，然後再評估運算式。

      • 詳細資料

        任何 []

        如果開發人員工具端在評估運算式前發生，設定在開發人員工具端發生錯誤，包含可替換在說明字串中的值陣列，以提供更多與錯誤原因相關的資訊。

      • isError

        boolean

        設定是否在開發人員工具端發生錯誤，然後再評估運算式。

      • isException

        boolean

        如果評估的程式碼產生未處理的例外狀況，請設定該值。

      • 值

        字串

        如果評估的程式碼產生未處理的例外狀況，請設定該值。

getResources()

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

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

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (resources: Resource[])=>void

    • 資源

      資源[]

      頁面中的資源。

reload()

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

重新載入接受檢查的頁面。

參數

  • reloadOptions

    物件選用

    • ignoreCache

      布林值 (選用)

      設為 true 時，載入器會針對 load 事件觸發前載入的所有已檢查網頁資源略過快取。效果相當於在檢查視窗或「開發人員工具」視窗中按下 Ctrl + Shift + R 鍵。

    • injectedScript

      字串 選用

      如有指定，系統會在網頁載入後，立即將指令碼插入至檢查網頁的每個頁框中，接著載入任何頁框的指令碼。後續重新載入後，系統不會插入指令碼 (例如按下 Ctrl+R 鍵)。

    • userAgent

      字串 選用

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

活動

onResourceAdded

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

將新資源新增至已檢查的頁面時就會觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (resource: Resource)=>void

onResourceContentCommitted

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

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

參數

  • 回呼

    功能

    callback 參數如下所示： 

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