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 事件取得資源清單 (文件、樣式表、指令碼、圖片等)。getContentResource 類別的 setContent 方法和 onResourceContentCommitted 事件 為了支援修改資源內容,例如由外部編輯者修改,

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

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

evaltabs.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