chrome.devtools.inspectedWindow

說明

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

資訊清單

您必須在資訊清單中宣告下列金鑰，才能使用這個 API。

"devtools_page"

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

如要瞭解如何使用開發人員工具 API，請參閱「開發人員工具 API 摘要」一文。

總覽

tabId 屬性會提供分頁 ID，您可以與 chrome.tabs.* 搭配使用 以及 API 呼叫但請注意，chrome.tabs.* API 不會向開發人員工具公開 基於安全性考量，擴充功能頁面—您必須將分頁 ID 傳遞至背景 並叫用 chrome.tabs.* API 函式。

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

使用 getResources 呼叫和 onResourceContent 事件取得資源清單 (文件、樣式表、指令碼、圖片等)。getContent和 Resource 類別的 setContent 方法和 onResourceContentCommitted 事件 為了支援修改資源內容，例如由外部編輯者修改，

在檢查的視窗中執行程式碼

eval 方法可讓擴充功能在以下項目中執行 JavaScript 程式碼： 這種方式在合適的情境下使用時非常有效，且使用時也能達到危險性 。除非需要特定功能，否則請使用 tabs.executeScript 方法 eval 方法提供的

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 範例 Cloud Storage 也提供目錄同步處理功能

類型

Resource

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

屬性

  • 網址

    字串

    資源的網址。

  • getContent

    void

    取得資源的內容。

    getContent 函式如下所示： 

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

    • 回呼

      函式

      callback 參數如下所示： 

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

      • 內容

        字串

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

      • encoding

        字串

        如果內容未經過編碼，則為空白，否則為編碼名稱。目前僅支援 base64。

  • setContent

    void

    設定資源的內容。

    setContent 函式如下所示： 

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

    • 內容

      字串

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

    • commit

      布林值

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

    • 回呼

      函式 選用

      callback 參數如下所示： 

      (error?: object) => void

      • 錯誤

        物件 optional

        如果已成功設定資源內容，會設為未定義；否則將描述錯誤。

屬性

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 則設為擲回物件的字串值。

參數

  • 運算式

    字串

    要評估的運算式。

  • 選項

    物件 optional

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

    • frameURL

      string optional

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

    • scriptExecutionContext

      string optional

      Chrome 107 以上版本

      評估符合指定來源的擴充功能內容指令碼內容指令碼。如有指定，scriptExecutionContext 會覆寫「true」請使用 ContentScriptContext 設定

    • useContentScriptContext

      布林值 選填

      如果檢查的頁面已插入內容指令碼，則根據呼叫擴充功能的內容指令碼，評估此運算式。如果沒有，則系統不會評估運算式，也不會在物件 (isError) 欄位設為 true 且 code 欄位設為 E_NOTFOUND 的情況下，叫用回呼。

  • 回呼

    函式 選用

    callback 參數如下所示： 

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

    • 結果

      物件

      評估結果。

    • exceptionInfo

      物件

      評估運算式期間發生例外狀況的物件，提供詳細資訊。

      • 程式碼

        字串

        設定「開發人員工具」端是否在評估運算式前發生錯誤。

      • 說明

        字串

        設定「開發人員工具」端是否在評估運算式前發生錯誤。

      • 詳細資料

        任何 []

        設定是否在評估運算式前，開發人員工具端發生錯誤，並加入說明字串中可能取代的值陣列，以針對錯誤原因提供更多資訊。

      • isError

        布林值

        設定「開發人員工具」端是否在評估運算式前發生錯誤。

      • isException

        布林值

        設定評估的程式碼是否產生未處理的例外狀況。

      • 值

        字串

        設定評估的程式碼是否產生未處理的例外狀況。

getResources()

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (resources: Resource[]) => void

    • 資源

      資源[]

      網頁中的資源。

reload()

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

重新載入檢查過的頁面。

參數

  • reloadOptions

    物件 optional

    • ignoreCache

      布林值 選填

      設為 true 時，載入器會在觸發 load 事件前載入所有已檢查的網頁資源的快取。這個效果就像在檢查的視窗或開發人員工具視窗中按下 Ctrl + Shift + R 鍵一樣。

    • injectedScript

      string optional

      如有指定，系統會在載入網頁時，立即將指令碼插入檢查網頁的每個頁框中，插入任何頁框的指令碼之前。即使使用者按下 Ctrl + R 鍵，後續重新載入頁面後，系統不會插入指令碼。

    • userAgent

      string optional

      如有指定，該字串會覆寫系統載入受檢查網頁的資源時所傳送的 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