chrome.webviewTag

說明

使用 webview 標記，透過網路主動從網頁載入即時內容，並將其嵌入 Chrome 應用程式。您的應用程式可以控制 webview 的外觀、與網頁內容互動、在嵌入的網頁中啟動導覽、對其中發生的錯誤事件做出反應等等 (請參閱「用法」)。

權限

webview

類型

ClearDataOptions

決定 clearData 應清除哪些資料的選項。

屬性

  • 開始於

    數字 選填

    清除自這個日期起累積的資料，以自 Epoch 紀元起算的毫秒數表示 (可透過 JavaScript Date 物件的 getTime 方法存取)。如果未提供，預設為 0 (這會移除所有瀏覽資料)。

ClearDataTypeSet

一組資料類型。缺少的屬性會解讀為 false。

屬性

  • appcache

    布林值 選填

    網站的應用程式快取。

  • 快取

    布林值 選填

    Chrome 44 以上版本

    自 Chrome 43 版起。 瀏覽器的快取。注意：移除資料時，系統會清除整個快取，不限於您指定的範圍。

  • Cookie

    布林值 選填

    分區的 Cookie。

  • fileSystems

    布林值 選填

    網站的檔案系統。

  • indexedDB

    布林值 選填

    網站的 IndexedDB 資料。

  • localStorage

    布林值 選填

    網站的本機儲存空間資料。

  • persistentCookies

    布林值 選填

    Chrome 58 以上版本

    分區的永久性 Cookie。

  • sessionCookies

    布林值 選填

    Chrome 58 以上版本

    分區的工作階段 Cookie。

  • webSQL

    布林值 選填

    網站的 WebSQL 資料。

ContentScriptDetails

Chrome 44 以上版本

要插入的內容指令碼詳細資料。詳情請參閱內容指令碼說明文件。

屬性

  • all_frames

    布林值 選填

    如果 all_frames 為 true，表示 JavaScript 或 CSS 應插入目前網頁的所有框架。根據預設，all_frames 為 false，且 JavaScript 或 CSS 只會注入頂端框架。

  • CSS

    InjectionItems 選填

    要插入相符網頁的 CSS 程式碼或 CSS 檔案清單。系統會按照這些標記的顯示順序插入標記，且會在建構或顯示網頁的任何 DOM 之前插入。

  • exclude_globs

    字串陣列 選用

    在比對後套用，排除符合這個 Glob 的網址。旨在模擬 @exclude Greasemonkey 關鍵字。

  • exclude_matches

    字串陣列 選用

    排除這個內容指令碼原本會注入的網頁。

  • include_globs

    字串陣列 選用

    在比對後套用，只納入也符合這個 glob 的網址。用於模擬 @include Greasemonkey 關鍵字。

  • js

    InjectionItems 選填

    要插入相符網頁的 JavaScript 程式碼或 JavaScript 檔案清單。系統會按照顯示順序插入這些項目。

  • match_about_blank

    布林值 選填

    是否要在 about:blank 和 about:srcdoc 上插入內容指令碼。只有當網頁的繼承網址符合「matches」欄位中宣告的其中一個模式時，系統才會在網頁上插入內容指令碼。繼承網址是指建立影格或視窗的文件網址。內容指令碼無法插入沙箱框架。

  • 完全相符

    string[]

    指定要將這個內容指令碼插入哪些網頁。

  • 名稱

    字串

    要插入的內容指令碼名稱。

  • run_at

    RunAt 選填

    JavaScript 或 CSS 最快會注入分頁的時間。預設值為「document_idle」。

ContentWindow

將訊息控制代碼移至邀請對象視窗。

屬性

  • postMessage

    void

    只要嵌入的內容顯示來自目標來源的網頁，就會將訊息發布至嵌入的網頁內容。網頁載入完成後，即可使用這個方法。監聽 contentload 事件，然後呼叫方法。

    受邀者可以將訊息發布至收到的訊息事件中的 event.source，回覆給嵌入者。

    這個 API 與網頁間通訊用的 HTML5 postMessage API 相同。嵌入器可以在自己的影格中新增 message 事件監聽器，藉此監聽回覆。

    postMessage 函式如下所示： 

    (message: any, targetOrigin: string) => {...}

    • 訊息

      不限

      要傳送給邀請對象的訊息物件。

    • targetOrigin

      字串

      指定事件必須來自哪個來源的訪客視窗，才能順利傳送。

ContextMenuCreateProperties

Chrome 44 以上版本

屬性

  • 已勾選

    布林值 選填

    核取方塊或單選按鈕項目的初始狀態：選取時為 true，未選取時為 false。在特定圓形按鈕項目群組中，一次只能選取一個圓形按鈕項目。

  • 情境

    [ContextType, ...ContextType[]] optional

    這個選單項目會顯示的內容清單。如未指定，預設值為 ['page']。

  • documentUrlPatterns

    字串陣列 選用

    您可以限制項目，只套用至網址符合指定模式的文件。(這也適用於影格)。如要瞭解模式格式的詳細資訊，請參閱「比對模式」。

  • 已啟用

    布林值 選填

    這個內容選單項目是否已啟用或停用。預設值為 true。

  • id

    字串 選填

    指派給這個項目的專屬 ID。活動頁面必須提供這項資訊。不得與這個擴充功能的其他 ID 相同。

  • parentId

    字串 | 數字 選填

    父項選單項目的 ID，這會使項目成為先前新增項目的子項。

  • targetUrlPatterns

    字串陣列 選用

    與 documentUrlPatterns 類似，但可根據 img/audio/video 標記的 src 屬性和錨點標記的 href 進行篩選。

  • title

    字串 選填

    要在項目中顯示的文字；除非 type 為「separator」，否則必須提供這項資訊。如果內容為「selection」，您可以在字串中使用 %s 顯示所選文字。舉例來說，如果這個參數的值是「將 '%s' 翻譯成拉丁豬文」，且使用者選取「酷」這個字，選取範圍的內容選單項目就會是「將 '酷' 翻譯成拉丁豬文」。

  • 類型

    ItemType optional

    選單項目的類型。如未指定，預設值為「normal」。

  • onclick

    void 選填

    點選選單項目時要呼叫的回呼函式。

    onclick 函式如下所示： 

    (info: OnClickData) => {...}

    • 資訊

      OnClickData

      使用者點選的項目，以及點選時的背景資訊。

ContextMenus

Chrome 44 以上版本

屬性

  • onShow

    Event<functionvoidvoid>

    在顯示這個 webview 的內容選單之前觸發。呼叫 event.preventDefault() 即可停用這個內容選單。

    onShow.addListener 函式如下所示： 

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

    • callback

      函式

      callback 參數如下： 

      (event: object) => void

      • 活動

        物件

        • preventDefault

          void

          呼叫此函式可防止顯示內容選單。

          preventDefault 函式如下所示： 

          () => {...}

  • create

    void

    建立新的內容選單項目。請注意，如果在建立期間發生錯誤，您可能要等到建立回呼觸發時才會發現 (詳細資料會顯示在 runtime.lastError 中)。

    create 函式如下所示： 

    (createProperties: object, callback?: function) => {...}

    • createProperties

      物件

      用於建立項目的屬性

    • callback

      函式 選填

      callback 參數如下： 

      () => void

    • returns

      字串 | 數字

      新建立項目的 ID。

  • 移除

    void

    移除內容選單項目。

    remove 函式如下所示： 

    (menuItemId: string | number, callback?: function) => {...}

    • menuItemId

      字串 | 數字

      要移除的內容選單項目 ID。

    • callback

      函式 選填

      callback 參數如下： 

      () => void

  • removeAll

    void

    移除新增至這個 webview 的所有內容選單項目。

    removeAll 函式如下所示： 

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

    • callback

      函式 選填

      callback 參數如下： 

      () => void

  • update

    void

    更新先前建立的內容選單項目。

    update 函式如下所示： 

    (id: string | number, updateProperties: object, callback?: function) => {...}

    • id

      字串 | 數字

      要更新的項目 ID。

    • updateProperties

      物件

      要更新的屬性。接受與建立函式相同的值。

    • callback

      函式 選填

      callback 參數如下： 

      () => void

ContextMenuUpdateProperties

Chrome 44 以上版本

屬性

  • 已勾選

    布林值 選填

    核取方塊或單選項目狀態：選取為 true，未選取為 false。在特定圓形按鈕項目群組中，一次只能選取一個圓形按鈕項目。

  • 情境

    [ContextType, ...ContextType[]] optional

    這個選單項目會顯示的內容清單。

  • documentUrlPatterns

    字串陣列 選用

    您可以限制項目，只套用至網址符合指定模式的文件。(這也適用於影格)。如要瞭解模式格式的詳細資訊，請參閱「比對模式」。

  • 已啟用

    布林值 選填

    這個內容選單項目是否已啟用或停用。

  • parentId

    字串 | 數字 選填

    父項選單項目的 ID，這會使項目成為先前新增項目的子項。注意：您無法將項目變更為其後代的子項。

  • targetUrlPatterns

    字串陣列 選用

    與 documentUrlPatterns 類似，但可根據 img/audio/video 標記的 src 屬性和錨點標記的 href 進行篩選。

  • title

    字串 選填

    要在項目中顯示的文字

  • 類型

    ItemType optional

    選單項目的類型。

  • onclick

    void 選填

    點選選單項目時要呼叫的回呼函式。

    onclick 函式如下所示： 

    (info: OnClickData) => {...}

    • 資訊

      OnClickData

      使用者點選的項目，以及點選時的背景資訊。

ContextType

Chrome 44 以上版本

選單可顯示的不同情境。指定「all」等同於所有其他內容的組合。

列舉

「all」

「page」

「frame」

「selection」

「link」

「editable」

「image」

「video」

「audio」

DialogController

附加至 dialog DOM 事件的介面。

屬性

  • 取消

    void

    拒絕對話方塊。相當於在 confirm 或 prompt 對話方塊中點選「取消」。

    cancel 函式如下所示： 

    () => {...}

  • 正常

    void

    接受對話方塊。相當於在 alert、confirm 或 prompt 對話方塊中按一下「確定」。

    ok 函式如下所示： 

    (response?: string) => {...}

    • 回應

      字串 選填

      接受 prompt 對話方塊時，要提供給訪客的回覆字串。

DialogMessageType

待處理

訪客要求顯示的模式對話方塊類型。

列舉

「alert」

「confirm」

「提示」

DownloadPermissionRequest

伴隨 download permissionrequest DOM 事件的 request 物件類型。

屬性

  • requestMethod

    字串

    與下載要求相關聯的 HTTP 要求類型 (例如 GET)。

  • 網址

    字串

    要求的下載網址。

  • allow

    void

    允許權限要求。

    allow 函式如下所示： 

    () => {...}

  • deny

    void

    拒絕權限要求。如果未呼叫 allow，系統會預設採用這項行為。

    deny 函式如下所示： 

    () => {...}

ExitReason

待處理

指出退出原因的字串。

列舉

「normal」

「abnormal」

「crashed」

「killed」

「oom killed」

"oom"

「無法啟動」

「完整性失敗」

FileSystemPermissionRequest

伴隨 filesystem permissionrequest DOM 事件的 request 物件類型。

屬性

  • 網址

    字串

    要求存取本機檔案系統的影格網址。

  • allow

    void

    允許權限要求。

    allow 函式如下所示： 

    () => {...}

  • deny

    void

    拒絕權限要求。

    deny 函式如下所示： 

    () => {...}

FindCallbackResults

內含所有尋找要求的結果。

屬性

  • activeMatchOrdinal

    數字

    目前賽事的序號。

  • 已取消

    布林值

    指出這項尋找要求是否已取消。

  • numberOfMatches

    數字

    頁面上 searchText 的比對次數。

  • selectionRect

    SelectionRect

    說明以螢幕座標表示的矩形，該矩形會圍住有效比對。

FindOptions

尋找要求的選項。

屬性

  • 向後

    布林值 選填

    旗標，以反向順序尋找相符項目。預設值為 false。

  • matchCase

    布林值 選填

    這個標記可決定比對時是否要區分大小寫。預設值為 false。

FullscreenPermissionRequest

Chrome 43 以上版本

伴隨 fullscreen permissionrequest DOM 事件的 request 物件類型。

屬性

  • origin

    字串

    發起全螢幕要求時，webview 內影格的來源。

  • allow

    void

    允許權限要求。

    allow 函式如下所示： 

    () => {...}

  • deny

    void

    拒絕權限要求。

    deny 函式如下所示： 

    () => {...}

GeolocationPermissionRequest

伴隨 geolocation permissionrequest DOM 事件的 request 物件類型。

屬性

  • 網址

    字串

    要求存取地理位置資料的框架網址。

  • allow

    void

    允許權限要求。

    allow 函式如下所示： 

    () => {...}

  • deny

    void

    拒絕權限要求。如果未呼叫 allow，系統會預設採用這項行為。

    deny 函式如下所示： 

    () => {...}

HidPermissionRequest

Chrome 125 以上版本

與 hid permissionrequest DOM 事件一併傳送的 request 物件類型。

屬性

  • 網址

    字串

    要求存取 HID API 的影格網址。

  • allow

    void

    允許權限要求。

    allow 函式如下所示： 

    () => {...}

  • deny

    void

    拒絕權限要求。如果未呼叫 allow，系統會預設採用這項行為。

    deny 函式如下所示： 

    () => {...}

InjectDetails

要插入的指令碼或 CSS 詳細資料。必須設定程式碼或檔案屬性，但不能同時設定兩者。

屬性

  • 程式碼

    字串 選填

    要插入的 JavaScript 或 CSS 程式碼。

    警告： 請謹慎使用 code 參數。如果使用不當，應用程式可能會遭受跨網站指令碼攻擊。

  • 檔案

    字串 選填

    要插入的 JavaScript 或 CSS 檔案。

InjectionItems

Chrome 44 以上版本

插入項目的類型：程式碼或一組檔案。

屬性

  • 程式碼

    字串 選填

    要插入相符網頁的 JavaScript 程式碼或 CSS。

  • 檔案

    字串陣列 選用

    要插入相符網頁的 JavaScript 或 CSS 檔案清單。系統會按照這個陣列中的順序插入這些項目。

LoadAbortReason

待處理

指出發生哪種中止情況的字串。我們無法保證這個字串在各版本之間維持回溯相容性。您不得剖析並根據其內容採取行動。此外，在某些情況下，系統也可能會回報未列於此處的錯誤。

列舉

「ERR_ABORTED」

「ERR_INVALID_URL」

"ERR_DISALLOWED_URL_SCHEME"

"ERR_BLOCKED_BY_CLIENT"

「ERR_ADDRESS_UNREACHABLE」

「ERR_EMPTY_RESPONSE」

"ERR_FILE_NOT_FOUND"

"ERR_UNKNOWN_URL_SCHEME"

LoadPluginPermissionRequest

伴隨 loadplugin permissionrequest DOM 事件的 request 物件類型。

屬性

  • ID

    字串

    外掛程式的 ID 字串。

  • 名稱

    字串

    外掛程式的顯示名稱。

  • allow

    void

    允許權限要求。如果未呼叫 deny，這是預設行為。

    allow 函式如下所示： 

    () => {...}

  • deny

    void

    拒絕權限要求。

    deny 函式如下所示： 

    () => {...}

MediaPermissionRequest

伴隨 media permissionrequest DOM 事件的 request 物件類型。

屬性

  • 網址

    字串

    要求存取使用者媒體的影格網址。

  • allow

    void

    允許權限要求。

    allow 函式如下所示： 

    () => {...}

  • deny

    void

    拒絕權限要求。如果未呼叫 allow，系統會預設採用這項行為。

    deny 函式如下所示： 

    () => {...}

NewWindow

附加至 newwindow DOM 事件的介面。

屬性

  • 附加

    void

    將要求的目標網頁附加至現有的 webview 元素。

    attach 函式如下所示： 

    (webview: object) => {...}

    • webview

      物件

      目標網頁應附加的 webview 元素。

  • 捨棄

    void

    取消新視窗要求。

    discard 函式如下所示： 

    () => {...}

PermissionType

待處理

要求的權限類型。

列舉

「media」

「geolocation」

「pointerLock」

「download」

"loadplugin"

"filesystem"

「fullscreen」

「hid」

PointerLockPermissionRequest

伴隨 pointerLock permissionrequest DOM 事件的 request 物件類型。

屬性

  • lastUnlockedBySelf

    布林值

    要求影格是否為最近一個保留指標鎖定的用戶端。

  • 網址

    字串

    要求游標鎖定的影格網址。

  • userGesture

    布林值

    是否因使用者輸入手勢而要求指標鎖定。

  • allow

    void

    允許權限要求。

    allow 函式如下所示： 

    () => {...}

  • deny

    void

    拒絕權限要求。如果未呼叫 allow，系統會預設採用這項行為。

    deny 函式如下所示： 

    () => {...}

SelectionRect

說明螢幕座標中的矩形。

容器語意類似陣列，也就是說，座標 (left, top) 會視為包含在矩形中，但座標 (left + width, top) 則不會。

屬性

  • 高度

    數字

    矩形的高度。

  • 左

    數字

    從螢幕左側邊緣到矩形左側邊緣的距離。

  • 頂端

    數字

    從螢幕頂端到矩形頂端的距離。

  • 寬度

    數字

    矩形的寬度。

StopFindingAction

待處理

決定在尋找工作階段結束後，如何處理有效比對。clear 會清除醒目顯示的相符項目；keep 會保留醒目顯示的相符項目；activate 會保留醒目顯示的相符項目，並模擬使用者點選該相符項目。預設動作為 keep。

列舉

「clear」

「keep」

「activate」

WebRequestEventInterface

Chrome 44 以上版本

這個介面可存取訪客網頁上的 webRequest 事件。如要瞭解 webRequest 生命週期和相關概念，請參閱 chrome.webRequest 擴充功能 API。注意：網頁檢視區塊不支援 chrome.webRequest.onActionIgnored 事件。

為說明使用方式與擴充功能的 webRequest API 有何不同，請參考下列程式碼範例，該程式碼會封鎖與 *://www.evil.com/* 相符的任何訪客網址要求：

webview.request.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]);

此外，這個介面也透過 onRequest 和 onMessage 事件，支援宣告式 webRequest 規則。如需 API 詳細資料，請參閱 declarativeWebRequest。

請注意，宣告式 WebView webRequest 的條件和動作應從對應的 chrome.webViewRequest.* 例項化。以下程式碼範例會以宣告方式，封鎖網頁檢視區塊 myWebview 上對 "example.com" 的所有要求：

var rule = {
  conditions: [
    new chrome.webViewRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } })
  ],
  actions: [ new chrome.webViewRequest.CancelRequest() ]
};
myWebview.request.onRequest.addRules([rule]);

WindowOpenDisposition

待處理

新視窗的所需處置方式。

列舉

「ignore」

「save_to_disk」

「current_tab」

「new_background_tab」

「new_foreground_tab」

「new_window」

「new_popup」

ZoomMode

Chrome 43 以上版本

定義 webview 中的縮放處理方式。

列舉

「per-origin」
縮放變更會保留在縮放網頁的來源中，也就是說，導向相同來源的相同分割區中，所有其他 WebView 也會縮放。此外，per-origin縮放變更會與來源一併儲存，也就是說，瀏覽同一來源的其他頁面時，這些頁面都會套用相同的縮放比例。

「每次檢視」
縮放比例變更只會在這個 WebView 中生效，其他 WebView 的縮放比例變更不會影響這個 WebView。此外，per-view縮放比例會在導覽時重設；導覽網頁檢視區塊時，系統一律會載入具有來源專屬縮放比例的網頁 (在分割區範圍內)。

「disabled」
：停用網頁檢視區塊中的所有縮放功能。內容會還原為預設縮放比例，所有嘗試變更縮放比例的操作都會遭到忽略。

屬性

contentWindow

物件參照，可用於將訊息發布至訪客頁面。

類型

ContentWindow

contextMenus

Chrome 44 以上版本

與 chrome 的 ContextMenus API 類似，但適用於 webview，而非瀏覽器。使用 webview.contextMenus API 將項目新增至 webview 的內容選單。您可以選擇內容選單增項適用的物件類型，例如圖片、超連結和網頁。

類型

ContextMenus

request

這個介面可讓您存取訪客網頁上的 webRequest 事件。

類型

WebRequestEventInterface

方法

addContentScripts()

Chrome 44 以上版本 
chrome.webviewTag.addContentScripts(
  contentScriptList: [ContentScriptDetails, ...ContentScriptDetails[]],
): void

將內容指令碼插入規則新增至 webview。當 webview 導向符合一或多項規則的網頁時，系統會注入相關聯的指令碼。您可以透過程式輔助方式新增規則或更新現有規則。

以下範例會將兩項規則新增至 webview：「myRule」和「anotherRule」。

webview.addContentScripts([
  {
    name: 'myRule',
    matches: ['http://www.foo.com/*'],
    css: { files: ['mystyles.css'] },
    js: { files: ['jquery.js', 'myscript.js'] },
    run_at: 'document_start'
  },
  {
    name: 'anotherRule',
    matches: ['http://www.bar.com/*'],
    js: { code: "document.body.style.backgroundColor = 'red';" },
    run_at: 'document_end'
  }]);
 ...

// Navigates webview.
webview.src = 'http://www.foo.com';

您可以延後 addContentScripts 呼叫，直到需要插入指令碼為止。

以下範例說明如何覆寫現有規則。

webview.addContentScripts([{
    name: 'rule',
    matches: ['http://www.foo.com/*'],
    js: { files: ['scriptA.js'] },
    run_at: 'document_start'}]);

// Do something.
webview.src = 'http://www.foo.com/*';
 ...
// Overwrite 'rule' defined before.
webview.addContentScripts([{
    name: 'rule',
    matches: ['http://www.bar.com/*'],
    js: { files: ['scriptB.js'] },
    run_at: 'document_end'}]);

如果 webview 已導覽至來源 (例如 foo.com) 並呼叫 webview.addContentScripts 來新增「myRule」，您必須等待下一次導覽，才能注入指令碼。如要立即注入，executeScript 會採取適當行動。

即使訪客程序當機或終止，甚至是 webview 重新設定父項，規則仍會保留。

詳情請參閱內容指令碼說明文件。

參數

back()

chrome.webviewTag.back(
  callback?: function,
): void

如果可以，會向後瀏覽一個記錄項目。等同於 go(-1)。

參數

  • callback

    函式 選填

    Chrome 44 以上版本

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

      指出導覽是否成功。

canGoBack()

chrome.webviewTag.canGoBack(): boolean

指出是否可以透過記錄向後瀏覽。這個函式的狀態會經過快取，並在每次 loadcommit 前更新，因此呼叫函式的最佳位置是 loadcommit。

傳回

  • 布林值

canGoForward()

chrome.webviewTag.canGoForward(): boolean

指出是否可以透過記錄向前瀏覽。這個函式的狀態會經過快取，並在每次 loadcommit 前更新，因此呼叫函式的最佳位置是 loadcommit。

傳回

  • 布林值

captureVisibleRegion()

Chrome 50 以上版本 
chrome.webviewTag.captureVisibleRegion(
  options?: ImageDetails,
  callback: function,
): void

擷取網頁檢視區塊的可見區域。

參數

  • 選項

    ImageDetails 選填

  • callback

    函式

    callback 參數如下： 

    (dataUrl: string) => void

    • dataUrl

      字串

      資料網址，可編碼擷取分頁可見區域的圖片。可指派給 HTML 圖片元素的「src」屬性以供顯示。

clearData()

chrome.webviewTag.clearData(
  options: ClearDataOptions,
  types: ClearDataTypeSet,
  callback?: function,
): void

清除 webview 分區的瀏覽資料。

參數

  • 決定要清除哪些資料的選項。

  • 要清除的資料類型。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

executeScript()

chrome.webviewTag.executeScript(
  details: InjectDetails,
  callback?: function,
): void

將 JavaScript 程式碼插入訪客頁面。

下列程式碼範例會使用指令碼插入功能，將訪客網頁的背景顏色設為紅色：

webview.executeScript({ code: "document.body.style.backgroundColor = 'red'" });

參數

  • 詳細資料

    InjectDetails

    要執行的指令碼詳細資料。

  • callback

    函式 選填

    callback 參數如下： 

    (result?: any[]) => void

    • 結果

      any[] 選填

      每個插入影格中的指令碼結果。

find()

chrome.webviewTag.find(
  searchText: string,
  options?: FindOptions,
  callback?: function,
): void

發起網頁內搜尋要求。

參數

  • searchText

    字串

    要在頁面中尋找的字串。

  • 選項

    FindOptions 選用

    尋找要求的選項。

  • callback

    函式 選填

    callback 參數如下： 

    (results?: FindCallbackResults) => void

    • 結果

      FindCallbackResults optional

      內含所有尋找要求的結果。如果回呼函式主體中未使用 results，則可以省略，例如回呼僅用於判斷尋找要求何時完成。

forward()

chrome.webviewTag.forward(
  callback?: function,
): void

盡可能往前瀏覽一個歷史記錄項目。等同於 go(1)。

參數

  • callback

    函式 選填

    Chrome 44 以上版本

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

      指出導覽是否成功。

getAudioState()

Chrome 62 以上版本 
chrome.webviewTag.getAudioState(
  callback: function,
): void

查詢音訊狀態。

參數

  • callback

    函式

    callback 參數如下： 

    (audible: boolean) => void

    • audible

      布林值

getProcessId()

chrome.webviewTag.getProcessId(): number

傳回訪客網頁目前程序的 Chrome 內部程序 ID，讓嵌入者瞭解終止程序會影響多少訪客。只有當兩位訪客屬於同一個應用程式，且具有相同的儲存空間分割區 ID 時，才會共用程序。此呼叫是同步呼叫，會傳回嵌入器的快取概念，也就是目前的程序 ID。程序 ID 與作業系統的程序 ID 不同。

傳回

  • 數字

getUserAgent()

chrome.webviewTag.getUserAgent(): string

傳回 webview 用於訪客網頁要求的 User-Agent 字串。

傳回

  • 字串

getZoom()

chrome.webviewTag.getZoom(
  callback: function,
): void

取得目前的縮放係數。

參數

  • callback

    函式

    callback 參數如下： 

    (zoomFactor: number) => void

    • zoomFactor

      數字

      目前的縮放比例。

getZoomMode()

Chrome 43 以上版本 
chrome.webviewTag.getZoomMode(
  callback: function,
): void

取得目前的縮放模式。

參數

  • callback

    函式

    callback 參數如下： 

    (ZoomMode: ZoomMode) => void

    • ZoomMode

      ZoomMode

      webview目前的縮放模式。

go()

chrome.webviewTag.go(
  relativeIndex: number,
  callback?: function,
): void

使用相對於目前導覽的記錄索引，導覽至記錄項目。如果無法完成要求的導覽，這個方法就不會有任何作用。

參數

  • relativeIndex

    數字

    應導覽至的相對記錄索引。webview舉例來說，如果可能，值為 2 會向前瀏覽 2 個歷史記錄項目；值為 -3 則會向後瀏覽 3 個項目。

  • callback

    函式 選填

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

      指出導覽是否成功。

insertCSS()

chrome.webviewTag.insertCSS(
  details: InjectDetails,
  callback?: function,
): void

將 CSS 導入訪客頁面。

參數

  • 詳細資料

    InjectDetails

    要插入的 CSS 詳細資料。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

isAudioMuted()

Chrome 62 以上版本 
chrome.webviewTag.isAudioMuted(
  callback: function,
): void

查詢音訊是否設為靜音。

參數

  • callback

    函式

    callback 參數如下： 

    (muted: boolean) => void

    • 已設為靜音。

      布林值

isSpatialNavigationEnabled()

Chrome 71 以上版本 
chrome.webviewTag.isSpatialNavigationEnabled(
  callback: function,
): void

查詢是否已為 WebView 啟用空間導覽。

參數

  • callback

    函式

    callback 參數如下： 

    (enabled: boolean) => void

    • 已啟用

      布林值

isUserAgentOverridden()

chrome.webviewTag.isUserAgentOverridden(): void

指出 webview 的使用者代理程式字串是否已遭 webviewTag.setUserAgentOverride 覆寫。

loadDataWithBaseUrl()

chrome.webviewTag.loadDataWithBaseUrl(
  dataUrl: string,
  baseUrl: string,
  virtualUrl?: string,
): void

載入資料網址，並指定用於相對連結的基底網址。如有需要，可以提供虛擬網址，供使用者查看，而非資料網址。

參數

  • dataUrl

    字串

    要載入的資料網址。

  • baseUrl

    字串

    用於相對連結的基本網址。

  • virtualUrl

    字串 選填

    向使用者顯示的網址 (位於網址列中)。

print()

chrome.webviewTag.print(): void

列印 webview 的內容。這等同於從 webview 本身呼叫指令碼列印函式。

reload()

chrome.webviewTag.reload(): void

重新載入目前的頂層頁面。

removeContentScripts()

Chrome 44 以上版本 
chrome.webviewTag.removeContentScripts(
  scriptNameList?: string[],
): void

從 webview 移除內容指令碼。

以下範例會移除先前新增的「myRule」。

webview.removeContentScripts(['myRule']);

您可以呼叫下列項目移除所有規則：

webview.removeContentScripts();

參數

  • scriptNameList

    字串陣列 選用

    要移除的內容指令碼名稱清單。如果清單為空白，系統會移除所有新增至 webview 的內容指令碼。

setAudioMuted()

Chrome 62 以上版本 
chrome.webviewTag.setAudioMuted(
  mute: boolean,
): void

設定網頁檢視區塊的音訊靜音狀態。

參數

  • 靜音

    布林值

    音訊靜音值

setSpatialNavigationEnabled()

Chrome 71 以上版本 
chrome.webviewTag.setSpatialNavigationEnabled(
  enabled: boolean,
): void

設定 WebView 的空間導覽狀態。

參數

  • 已啟用

    布林值

    空間導覽狀態值。

setUserAgentOverride()

chrome.webviewTag.setUserAgentOverride(
  userAgent: string,
): void

覆寫 webview 用於訪客網頁要求的 User-Agent 字串。覆寫後，系統會將套用此覆寫的訪客網頁要求，其 User-Agent 用戶端提示標頭值和 navigator.userAgentData 傳回的值設為空白。

參數

  • userAgent

    字串

    要使用的使用者代理程式字串。

setZoom()

chrome.webviewTag.setZoom(
  zoomFactor: number,
  callback?: function,
): void

變更網頁的縮放比例。這項變更的範圍和持續性取決於 WebView 目前的縮放模式 (請參閱 webviewTag.ZoomMode)。

參數

  • zoomFactor

    數字

    新的縮放係數。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

setZoomMode()

Chrome 43 以上版本 
chrome.webviewTag.setZoomMode(
  ZoomMode: ZoomMode,
  callback?: function,
): void

設定 webview 的縮放模式。

參數

  • ZoomMode

    ZoomMode

    定義 webview 中的縮放處理方式。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

stop()

chrome.webviewTag.stop(): void

如果目前正在載入 webview 導覽，則停止載入。

stopFinding()

chrome.webviewTag.stopFinding(
  action?: StopFindingAction,
): void

結束目前的尋找工作階段 (清除所有醒目顯示)，並取消所有進行中的尋找要求。

參數

  • 動作

    StopFindingAction 選填

    決定在尋找工作階段結束後，如何處理有效比對。clear 會清除醒目顯示的相符項目；keep 會保留醒目顯示的相符項目；activate 會保留醒目顯示的相符項目，並模擬使用者點選該相符項目。預設動作為 keep。

terminate()

chrome.webviewTag.terminate(): void

強制終止訪客網頁的轉譯器程序。如果目前應用程式中的多個 webview 標記共用相同程序，這項變更可能會影響這些標記，但不會影響其他應用程式中的 webview 標記。

事件

close

chrome.webviewTag.close.addListener(
  callback: function,
)

當訪客視窗嘗試自行關閉時觸發。

以下範例程式碼會在訪客嘗試關閉自身時，將 webview 導覽至 about:blank。

webview.addEventListener('close', function() {
  webview.src = 'about:blank';
});

參數

  • callback

    函式

    callback 參數如下： 

    () => void

consolemessage

chrome.webviewTag.consolemessage.addListener(
  callback: function,
)

當訪客視窗記錄主控台訊息時觸發。

以下程式碼範例會將所有記錄訊息轉送至嵌入器的控制台，不考慮記錄層級或其他屬性。

webview.addEventListener('consolemessage', function(e) {
  console.log('Guest page logged a message: ', e.message);
});

參數

  • callback

    函式

    callback 參數如下： 

    (level: number, message: string, line: number, sourceId: string) => void

    • level

      數字

    • 訊息

      字串

    • 行

      數字

    • sourceId

      字串

contentload

chrome.webviewTag.contentload.addListener(
  callback: function,
)

當訪客視窗觸發 load 事件 (即載入新文件時)，就會觸發此事件。這不包括目前文件中的網頁導覽或非同步資源載入。

下列程式碼範例會在網頁載入後，修改訪客 body 元素的預設字型大小：

webview.addEventListener('contentload', function() {
  webview.executeScript({ code: 'document.body.style.fontSize = "42px"' });
});

參數

  • callback

    函式

    callback 參數如下： 

    () => void

dialog

chrome.webviewTag.dialog.addListener(
  callback: function,
)

當訪客視窗嘗試透過 window.alert、window.confirm 或 window.prompt 開啟無模式對話方塊時，系統會觸發這個事件。

處理這個事件會封鎖訪客程序，直到每個事件監聽器傳回或 dialog 物件無法連線為止 (如果呼叫了 preventDefault())。

預設行為是取消對話方塊。

參數

exit

chrome.webviewTag.exit.addListener(
  callback: function,
)

在呈現訪客網頁內容的程序結束時觸發。

以下範例程式碼會在訪客頁面當機時顯示告別訊息：

webview.addEventListener('exit', function(e) {
  if (e.reason === 'crash') {
    webview.src = 'data:text/plain,Goodbye, world!';
  }
});

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • processID

        數字

        已結束程序的 Chrome 內部 ID。

      • 原因

        ExitReason

        指出退出原因的字串。

findupdate

chrome.webviewTag.findupdate.addListener(
  callback: function,
)

當有效尋找要求有新的尋找結果時，系統會觸發這個事件。找到相符項目時，單一搜尋要求可能會多次觸發這項事件。

參數

  • callback

    函式

    callback 參數如下： 

    (searchText: string, numberOfMatches: number, activeMatchOrdinal: number, selectionRect: SelectionRect, canceled: boolean, finalUpdate: string) => void

    • searchText

      字串

    • numberOfMatches

      數字

    • activeMatchOrdinal

      數字

    • selectionRect

      SelectionRect

    • 已取消

      布林值

    • finalUpdate

      字串

loadabort

chrome.webviewTag.loadabort.addListener(
  callback: function,
)

當頂層載入作業在未提交的情況下中止時，系統會觸發此事件。除非事件已預防預設行為，否則系統會在控制台中列印錯誤訊息。

注意：資源載入作業中止後，即使自上次 loadstop 事件以來的所有已確認載入作業 (如有) 都已中止，最終仍會發生 loadabort 事件，接著發生 loadstop 事件。

注意：如果系統中止載入「關於」網址或 JavaScript 網址，就會觸發 loadabort，然後 webview 會導向「about:blank」。

參數

  • callback

    函式

    callback 參數如下： 

    (url: string, isTopLevel: boolean, code: number, reason: LoadAbortReason) => void

    • 網址

      字串

    • isTopLevel

      布林值

    • 程式碼

      數字

loadcommit

chrome.webviewTag.loadcommit.addListener(
  callback: function,
)

載入作業完成時觸發。這包括目前文件中的導覽，以及子框架文件層級的載入，但不包括非同步資源載入。

參數

  • callback

    函式

    callback 參數如下： 

    (url: string, isTopLevel: boolean) => void

    • 網址

      字串

    • isTopLevel

      布林值

loadredirect

chrome.webviewTag.loadredirect.addListener(
  callback: function,
)

當頂層載入要求已重新導向至其他網址時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (oldUrl: string, newUrl: string, isTopLevel: boolean) => void

    • oldUrl

      字串

    • newUrl

      字串

    • isTopLevel

      布林值

loadstart

chrome.webviewTag.loadstart.addListener(
  callback: function,
)

載入開始時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (url: string, isTopLevel: boolean) => void

    • 網址

      字串

    • isTopLevel

      布林值

loadstop

chrome.webviewTag.loadstop.addListener(
  callback: function,
)

當訪客網頁中的所有影格層級載入 (包括所有子影格) 都已完成時，就會觸發這個事件。這包括目前文件中的導覽，以及子框架文件層級的載入，但不包括非同步資源載入。每當文件層級的載入次數從一 (或以上) 變為零時，系統就會觸發這個事件。舉例來說，如果網頁已載入完畢 (即 loadstop 已觸發一次)，系統會建立新的 iframe 並載入網頁，然後在 iframe 網頁載入完成時觸發第二次 loadstop。載入廣告的網頁通常會出現這種模式。

注意：如果已確認的載入作業遭到中止，即使自上次 loadstop 事件以來的所有已確認載入作業 (如有) 都遭到中止，loadstop 事件最終仍會接在 loadabort 事件之後。

參數

  • callback

    函式

    callback 參數如下： 

    () => void

newwindow

chrome.webviewTag.newwindow.addListener(
  callback: function,
)

當訪客頁面嘗試開啟新的瀏覽器視窗時觸發。

下列程式碼範例會為每個要求的新視窗，在嵌入器中建立並導覽新的 webview：

webview.addEventListener('newwindow', function(e) {
  var newWebview = document.createElement('webview');
  document.body.appendChild(newWebview);
  e.window.attach(newWebview);
});

參數

  • callback

    函式

    callback 參數如下： 

    (window: NewWindow, targetUrl: string, initialWidth: number, initialHeight: number, name: string, windowOpenDisposition: WindowOpenDisposition) => void

permissionrequest

chrome.webviewTag.permissionrequest.addListener(
  callback: function,
)

當訪客網頁需要向嵌入器要求特殊權限時，系統會觸發這個事件。

下列程式碼範例會授予訪客頁面 webkitGetUserMedia API 的存取權。請注意，使用這個範例程式碼的應用程式本身必須指定 audioCapture 和/或 videoCapture 資訊清單權限：

webview.addEventListener('permissionrequest', function(e) {
  if (e.permission === 'media') {
    e.request.allow();
  }
});

參數

  • callback

    函式

    callback 參數如下： 

    (permission: PermissionType, request: object) => void

responsive

chrome.webviewTag.responsive.addListener(
  callback: function,
)

當呈現訪客網頁內容的程序在無回應後再次回應時，就會觸發此事件。

以下程式碼範例會在 webview 元素變成回應式或無回應時，淡入或淡出該元素：

webview.style.webkitTransition = 'opacity 250ms';
webview.addEventListener('unresponsive', function() {
  webview.style.opacity = '0.5';
});
webview.addEventListener('responsive', function() {
  webview.style.opacity = '1';
});

參數

  • callback

    函式

    callback 參數如下： 

    (processID: number) => void

    • processID

      數字

sizechanged

chrome.webviewTag.sizechanged.addListener(
  callback: function,
)

當透過 autosize 調整內嵌網頁內容大小時，系統會觸發這個事件。只有在啟用 autosize 時才會觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (oldWidth: number, oldHeight: number, newWidth: number, newHeight: number) => void

    • oldWidth

      數字

    • oldHeight

      數字

    • newWidth

      數字

    • newHeight

      數字

unresponsive

chrome.webviewTag.unresponsive.addListener(
  callback: function,
)

當轉譯訪客網頁內容的程序沒有回應時，系統會觸發這個事件。如果訪客再次開始回應，系統就會產生這個事件，並搭配相應的回應事件。

參數

  • callback

    函式

    callback 參數如下： 

    (processID: number) => void

    • processID

      數字

zoomchange

chrome.webviewTag.zoomchange.addListener(
  callback: function,
)

網頁縮放比例變更時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (oldZoomFactor: number, newZoomFactor: number) => void

    • oldZoomFactor

      數字

    • newZoomFactor

      數字