chrome.webviewTag

說明

使用 webview 標記即可在網路上主動載入網路上的直播內容，並嵌入 Chrome 應用程式。應用程式可以控制 webview 的外觀、與網頁內容互動、在內嵌網頁中啟動導覽、對其中的錯誤事件做出回應等等 (請參閱「使用」)。

權限

webview

類型

ClearDataOptions

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

屬性

• 開始於

  編號 選填

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

ClearDataTypeSet

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

屬性

• 應用程式快取

  布林值 選填

  網站應用程式快取。

• 快取

  布林值 選填

  Chrome 44 以上版本

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

• Cookie

  布林值 選填

  分區的 Cookie。

• fileSystems

  布林值 選填

  網站檔案系統

• 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

  string[] 選填

  會在比對後套用，以排除符合此 glob 的網址。用於模擬 @Exclude Greasemonkey 關鍵字。

• exclude_matches

  string[] 選填

  排除會插入這個內容指令碼的網頁。

• include_globs

  string[] 選填

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

• js

  InjectionItems 選用

  要插入到相符網頁的 JavaScript 程式碼或 JavaScript 檔案清單。系統會按照顯示順序插入資料。

• match_about_blank

  布林值 選填

  是否將內容指令碼插入 about:blank 和 about:srcdoc。只有當所繼承的網址與比對欄位中的宣告模式相符時，系統才會在網頁上插入內容指令碼。繼承網址是指建立頁框或視窗的文件網址。無法在沙箱框架中插入內容指令碼。

• 完全相符

  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[]] 選用

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

• documentUrlPatterns

  string[] 選填

  可讓您限制項目僅會套用至網址符合其中一個指定模式的文件。(這也適用於頁框)。如要進一步瞭解模式的格式，請參閱比對模式。

• 已啟用

  布林值 選填

  這個內容選單項目為啟用或停用狀態。預設值為 true。

• id

  string optional

  要指派給這個項目的專屬 ID。活動頁面必須使用這個屬性。不得與這項擴充功能的其他 ID 相同。

• parentId

  string |編號 選填

  父項選單項目的 ID；如此一來，該項目就會成為先前新增項目的子項。

• targetUrlPatterns

  string[] 選填

  與 documentUrlPatterns 類似，但可讓您根據 img/audio/影片標記的 src 屬性和錨定標記的 href 進行篩選。

• title

  string optional

  要在項目中顯示的文字；除非 type 是「分隔符號」，否則此為必填屬性。當結構定義為「選取」時，您可以在字串中使用 %s 來顯示所選文字。例如，如果這個參數的值是「Translate '%s」CANNOT TRANSLATE當使用者選取「cool」一詞時，用於選取項目的內容選單項目是「Translate 'cool'」。Pig Latin 的密語。」

• 類型

  ItemType 選用

  選單項目的類型。預設值為「正常」。

• 點擊

  void optional

  點選選單項目時，系統會呼叫的函式。

  onclick 函式如下所示：

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

  • 資訊

    OnClickData

    與點擊的項目及發生點擊情境相關的資訊。

ContextMenus

Chrome 44 以上版本

屬性

• onShow

  事件<functionvoid>

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

  onShow.addListener 函式如下所示：

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

  • 回呼

    函式

    callback 參數如下所示：

    (event: object) => void

    • 活動

      物件

      • preventDefault

        void

        呼叫此方法即可避免顯示內容選單。

        preventDefault 函式如下所示：

        () => {...}

• create

  void

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

  create 函式如下所示：

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

  • createProperties

    物件

    用於建立商品的屬性

  • 回呼

    函式 選用

    callback 參數如下所示：

    () => void

  • returns

    string |號碼

    新建立項目的 ID。

• 移除

  void

  移除內容選單項目。

  remove 函式如下所示：

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

  • menuItemId

    string |號碼

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

  • 回呼

    函式 選用

    callback 參數如下所示：

    () => void

• 全部移除

  void

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

  removeAll 函式如下所示：

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

  • 回呼

    函式 選用

    callback 參數如下所示：

    () => void

• update

  void

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

  update 函式如下所示：

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

  • id

    string |號碼

    要更新的項目 ID。

  • updateProperties

    物件

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

  • 回呼

    函式 選用

    callback 參數如下所示：

    () => void

ContextMenuUpdateProperties

Chrome 44 以上版本

屬性

• 已勾選

  布林值 選填

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

• 情境

  [ContextType, ...ContextType[]] 選用

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

• documentUrlPatterns

  string[] 選填

  可讓您限制項目僅會套用到網址符合其中一個指定模式的文件。(這也適用於頁框)。如要進一步瞭解模式的格式，請參閱比對模式。

• 已啟用

  布林值 選填

  這個內容選單項目為啟用或停用狀態。

• parentId

  string |編號 選填

  父項選單項目的 ID；如此一來，該項目就會成為先前新增項目的子項。注意：您無法將項目變更為其他子系的子項。

• targetUrlPatterns

  string[] 選填

  與 documentUrlPatterns 類似，但可讓您根據 img/audio/影片標記的 src 屬性和錨定標記的 href 進行篩選。

• title

  string optional

  要在商品中顯示的文字

• 類型

  ItemType 選用

  選單項目的類型。

• 點擊

  void optional

  點選選單項目時，系統會呼叫的函式。

  onclick 函式如下所示：

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

  • 資訊

    OnClickData

    與點擊的項目及發生點擊情境相關的資訊。

ContextType

Chrome 44 以上版本

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

列舉

"all"

"網頁"

"框"

"selection"

"連結"

"editable"

"圖片"

"影片"

"音訊"

DialogController

附加至 dialog DOM 事件的介面。

屬性

• 取消

  void

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

  cancel 函式如下所示：

  () => {...}

• 正常

  void

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

  ok 函式如下所示：

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

  • 回應

    string optional

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

DownloadPermissionRequest

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

屬性

• requestMethod

  字串

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

• 網址

  字串

  要求的下載網址。

• allow

  void

  授予權限。

  allow 函式如下所示：

  () => {...}

• deny

  void

  拒絕權限要求。如果未呼叫 allow，這會是預設行為。

  deny 函式如下所示：

  () => {...}

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 物件類型。

屬性

• 起源

  字串

  啟動全螢幕要求的 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 的詳細資料。您必須設定程式碼或檔案屬性，但兩者不能同時設定。

屬性

• 程式碼

  string optional

  要插入的 JavaScript 或 CSS 程式碼。

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

• 檔案

  string optional

  要插入的 JavaScript 或 CSS 檔案

InjectionItems

Chrome 44 以上版本

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

屬性

• 程式碼

  string optional

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

• 檔案

  string[] 選填

  要插入相符網頁的 JavaScript 或 CSS 檔案清單。系統會按照此陣列中的顯示順序插入這些元素。

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 函式如下所示：

  () => {...}

PointerLockPermissionRequest

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

屬性

• lastUnlockedBySelf

  布林值

  要求框架是否為最新保留指標鎖定的用戶端。

• 網址

  字串

  要求指標鎖定的頁框網址。

• userGesture

  布林值

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

• allow

  void

  授予權限。

  allow 函式如下所示：

  () => {...}

• deny

  void

  拒絕權限要求。如果未呼叫 allow，這會是預設行為。

  deny 函式如下所示：

  () => {...}

SelectionRect

說明螢幕座標中的矩形。

包含語意類似於陣列；也就是說，矩形會認定座標 (left, top)，但座標 (left + width, top) 則不包含在內。

屬性

• 高度

  數字

  矩形的高度。

• 左側

  數字

  與畫面左側邊緣到矩形左側邊緣的距離。

• 頂端

  數字

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

• 寬度

  數字

  矩形的寬度。

WebRequestEventInterface

Chrome 44 以上版本

這個介面可在訪客頁面上存取 webRequest 事件。如要進一步瞭解 webRequest 生命週期和相關概念，請參閱 chrome.webRequest 擴充功能 API。注意：Webview 不支援 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.* 對應項目例項化。下列程式碼範例會在 WebView myWebview 上以宣告方式封鎖所有傳送至 "example.com" 的要求：

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

ZoomMode

Chrome 43 以上版本

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

列舉

"per-origin"
縮放變更會保留在經過縮放的網頁來源中，亦即同一個分區中前往同一來源的所有其他 WebView 也都會縮放。此外，per-origin 縮放變更會與來源儲存，也就是說，瀏覽相同來源的其他頁面時，所有頁面都會縮放至相同的縮放比例係數。

「每個畫面」
變更縮放設定只會套用至這個 WebView，而在其他 WebView 中進行縮放變更不會影響此 WebView 的縮放比例。此外，瀏覽時也會重設 per-view 縮放變更。瀏覽 WebView 時，系統一律會以個別來源的縮放因素 (在分區範圍內) 載入網頁。

"disabled"
停用 WebView 的所有縮放功能。內容會還原為預設的縮放等級，且會忽略所有嘗試的縮放變更。

屬性

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[]],
)

將內容指令碼插入規則新增至 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';

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

下例顯示如何覆寫現有規則。

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 為父項，系統仍會保留規則。

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

參數

• contentScriptList

  [ContentScriptDetails, ...ContentScriptDetails[]]

  要新增的內容指令碼詳細資料。

back()

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

在可能的情況下，返回上一個記錄項目。等同於 go(-1)。

參數

• 回呼

  函式 選用

  Chrome 44 以上版本

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    布林值

    指出導覽是否成功。

canGoBack()

chrome.webviewTag.canGoBack()

指出是否可向先前瀏覽歷史記錄。系統會快取此函式的狀態，並在每個 loadcommit 之前更新，因此呼叫此函式的最佳位置是在 loadcommit 上。

傳回

• 布林值

canGoForward()

chrome.webviewTag.canGoForward()

指出是否可向前瀏覽歷程記錄。系統會快取此函式的狀態，並在每個 loadcommit 之前更新，因此呼叫此函式的最佳位置是在 loadcommit 上。

傳回

• 布林值

captureVisibleRegion()

Chrome 50 以上版本

chrome.webviewTag.captureVisibleRegion(
  options?: ImageDetails,
  callback: function,
)

擷取 WebView 的可見區域。

參數

• 選項

  ImageDetails 選用

• 回呼

  函式

  callback 參數如下所示：

  (dataUrl: string) => void

  • dataUrl

    字串

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

clearData()

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

清除 webview 分區的瀏覽資料。

參數

• 選項

  ClearDataOptions

  決定要清除哪些資料。

• 類型

  ClearDataTypeSet

  要清除的資料類型。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

executeScript()

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

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

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

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

參數

• 詳細資料

  InjectDetails

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (result?: any[]) => void

  • 結果

    Any[] 選填

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

find()

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

啟動「網頁內找」要求。

參數

• searchText

  字串

  要在網頁中尋找的字串。

• 選項

  FindOptions 選用

  尋找要求的選項。

• 回呼

  函式 選用

  callback 參數如下所示：

  (results?: FindCallbackResults) => void

  • 結果

    FindCallbackResults 選用

    包含尋找要求的所有結果。如果 results 未在回呼函式主體中使用，則可省略；例如，如果回呼只用於識別搜尋要求完成的時間。

forward()

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

在可能的情況下，前往下一個記錄項目。等同於 go(1)。

參數

• 回呼

  函式 選用

  Chrome 44 以上版本

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    布林值

    指出導覽是否成功。

getAudioState()

Chrome 62 以上版本

chrome.webviewTag.getAudioState(
  callback: function,
)

查詢音訊狀態。

參數

• 回呼

  函式

  callback 參數如下所示：

  (audible: boolean) => void

  • audible

    布林值

getProcessId()

chrome.webviewTag.getProcessId()

針對訪客網頁目前的處理程序傳回 Chrome 的內部程序 ID，讓嵌入者知道終止處理程序會影響多少邀請對象。只有兩名訪客屬於同一個應用程式，並使用相同的儲存空間分區 ID，才能共用處理程序。此呼叫為同步性質，會傳回嵌入器目前程序 ID 的快取標記。程序 ID 與作業系統的程序 ID 不同。

傳回

• 數字

getUserAgent()

chrome.webviewTag.getUserAgent()

傳回 webview 用於訪客頁面要求的使用者代理程式字串。

傳回

• 字串

getZoom()

chrome.webviewTag.getZoom(
  callback: function,
)

取得目前的變焦係數。

參數

• 回呼

  函式

  callback 參數如下所示：

  (zoomFactor: number) => void

  • zoomFactor

    數字

    目前的縮放係數。

getZoomMode()

Chrome 43 以上版本

chrome.webviewTag.getZoomMode(
  callback: function,
)

取得目前的縮放模式。

參數

• 回呼

  函式

  callback 參數如下所示：

  (ZoomMode: ZoomMode) => void

  • ZoomMode

    ZoomMode

    webview 目前的縮放模式。

go()

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

使用相對於目前導覽的記錄索引，前往記錄項目。如果無法使用要求的導覽功能，此方法就不會有任何作用。

參數

• relativeIndex

  數字

  應前往 webview 的相對記錄索引。舉例來說，如果值為 2，系統會盡可能往前瀏覽 2 個記錄項目；如果值為 -3，則會瀏覽 3 個項目。

• 回呼

  函式 選用

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    布林值

    指出導覽是否成功。

insertCSS()

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

將 CSS 插入訪客頁面。

參數

• 詳細資料

  InjectDetails

  要插入的 CSS 詳細資料。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

isAudioMuted()

Chrome 62 以上版本

chrome.webviewTag.isAudioMuted(
  callback: function,
)

查詢音訊是否設為靜音。

參數

• 回呼

  函式

  callback 參數如下所示：

  (muted: boolean) => void

  • 已設為靜音。

    布林值

isSpatialNavigationEnabled()

Chrome 71 以上版本

chrome.webviewTag.isSpatialNavigationEnabled(
  callback: function,
)

查詢是否已啟用 WebView 的空間導覽功能。

參數

• 回呼

  函式

  callback 參數如下所示：

  (enabled: boolean) => void

  • 已啟用

    布林值

isUserAgentOverridden()

chrome.webviewTag.isUserAgentOverridden()

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

loadDataWithBaseUrl()

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

以用於相對連結的指定基準網址載入資料網址。您也可以視需要提供虛擬網址給使用者，而非資料網址。

參數

• dataUrl

  字串

  要載入的資料網址。

• baseUrl

  字串

  要用於相關連結的基準網址。

• virtualUrl

  string optional

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

print()

chrome.webviewTag.print()

顯示 webview 的內容。這相當於從 webview 本身呼叫已編寫指令碼的列印函式。

reload()

chrome.webviewTag.reload()

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

removeContentScripts()

Chrome 44 以上版本

chrome.webviewTag.removeContentScripts(
  scriptNameList?: string[],
)

從 webview 中移除內容指令碼。

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

webview.removeContentScripts(['myRule']);

如要移除所有規則，請呼叫：

webview.removeContentScripts();

參數

• scriptNameList

  string[] 選填

  一份清單，列出即將移除的內容指令碼。如果清單空白，所有新增至 webview 的內容指令碼都會移除。

setAudioMuted()

Chrome 62 以上版本

chrome.webviewTag.setAudioMuted(
  mute: boolean,
)

設定 WebView 的音訊靜音狀態。

參數

• 靜音

  布林值

  將音訊設為靜音值

setSpatialNavigationEnabled()

Chrome 71 以上版本

chrome.webviewTag.setSpatialNavigationEnabled(
  enabled: boolean,
)

設定 WebView 的空間導覽狀態。

參數

• 已啟用

  布林值

  空間導覽狀態值。

setUserAgentOverride()

chrome.webviewTag.setUserAgentOverride(
  userAgent: string,
)

覆寫 webview 用於訪客頁面要求使用的使用者代理程式字串。覆寫會造成 User-Agent Client Hint 標頭值，以及套用此覆寫值的訪客網頁要求時，navigator.userAgentData 傳回的值將為空白。

參數

• userAgent

  字串

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

setZoom()

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

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

參數

• zoomFactor

  數字

  新的縮放係數。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

setZoomMode()

Chrome 43 以上版本

chrome.webviewTag.setZoomMode(
  ZoomMode: ZoomMode,
  callback?: function,
)

設定 webview 的縮放模式。

參數

• ZoomMode

  ZoomMode

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

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

stop()

chrome.webviewTag.stop()

如果進行中，系統會停止載入目前的 webview 導覽。

stopFinding()

chrome.webviewTag.stopFinding(
  action?: "clear" 
  | "keep" 
  | "activate" 
 ,
)

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

參數

• 動作

  "清除"
   |"keep"
   |"activate"
   選用

  決定在尋找工作階段結束後如何處理有效比對。clear 會清除正在置頂的相符項目。keep 會維持醒目顯示目前的相符結果；activate 會醒目顯示使用中的相符項目，並模擬使用者點擊相符結果。預設動作為 keep。

terminate()

chrome.webviewTag.terminate()

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

活動

close

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

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

下列範例程式碼會在訪客嘗試自行關閉時導覽 webview 到 about:blank。

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

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void

consolemessage

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

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

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

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

參數

• 回呼

  函式

  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 參數如下所示：

  () => void

dialog

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

在訪客視窗嘗試透過 window.alert、window.confirm 或 window.prompt 開啟強制回應對話方塊時觸發。

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

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

參數

• 回呼

  函式

  callback 參數如下所示：

  (messageType: "alert" 
    | "confirm" 
    | "prompt" 
   , messageText: string, dialog: DialogController) => void

  • messageType

    "alert"
     |"確認"
     |"提示"
    

  • messageText

    字串

  • 對話方塊

    DialogController

exit

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

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

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

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

參數

• 回呼

  函式

  callback 參數如下所示：

  (processID: number, reason: "normal" 
    | "abnormal" 
    | "crash" 
    | "kill" 
   ) => void

  • processID

    數字

  • 原因

    "一般"
     |"異常"
     |"當機"
     |「kill」
    

findupdate

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

有效尋找要求有新的發現項目時，就會觸發。針對單一尋找要求找到相符項目，可能會多次發生這種情形。

參數

• 回呼

  函式

  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,
)

在取消頂層載入且未提交的情況下啟動。除非預設禁止活動，否則控制台會顯示錯誤訊息。

注意：取消資源載入時，loadabort 事件最終後面會接 loadstop 事件，即使在上次 loadstop 事件 (如有) 之後取消的所有修訂的載入作業也取消也一樣。

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

參數

• 回呼

  函式

  callback 參數如下所示：

  (url: string, isTopLevel: boolean, code: number, reason: "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" 
   ) => void

  • 網址

    字串

  • isTopLevel

    布林值

  • 程式碼

    數字

  • 原因

    "ERR_ABORTED"
     |&quot;ERR_INVALID_URL&quot;
     |&quot;ERR_DISALLOWED_URL_SCHEME&quot;
     |&quot;ERR_BLOCKED_BY_CLIENT&quot;
     |"ERR_ADDRESS_UNREACHABLE"
     |&quot;ERR_EMPTY_RESPONSE&quot;
     |&quot;ERR_FILE_NOT_FOUND&quot;
     |&quot;ERR_UNKNOWN_URL_SCHEME&quot;
    

loadcommit

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

已提交負載時觸發。這包括在目前文件中瀏覽內容，以及子頁框文件層級載入作業，但「不」包含非同步資源載入。

參數

• 回呼

  函式

  callback 參數如下所示：

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

  • 網址

    字串

  • isTopLevel

    布林值

loadredirect

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

當頂層載入要求重新導向至不同的網址時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

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

  • oldUrl

    字串

  • newUrl

    字串

  • isTopLevel

    布林值

loadstart

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

在載入開始時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

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

  • 網址

    字串

  • isTopLevel

    布林值

loadstop

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

完成訪客頁面 (包括其所有子頁框) 中的所有頁框層級載入時，便會觸發。這包括在目前文件中瀏覽內容，以及子頁框文件層級載入作業，但「不」包括非同步資源載入。每當文件層級的載入次數從 1 (或多個) 變更為零時，就會觸發這個事件。舉例來說，如果網頁已完成載入 (例如loadstop 已觸發一次) 會建立新的 iframe 來載入網頁，然後第二個 loadstop 會在 iframe 網頁載入完成時觸發。這種模式通常會在載入廣告的網頁上發現。

注意：取消已提交的載入時，loadstop 事件最終將遵循 loadabort 事件，即使自上次 loadstop 事件 (如有) 以來的所有修訂的載入作業已取消也一樣。

參數

• 回呼

  函式

  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 參數如下所示：

  (window: NewWindow, targetUrl: string, initialWidth: number, initialHeight: number, name: string, windowOpenDisposition: "ignore" 
    | "save_to_disk" 
    | "current_tab" 
    | "new_background_tab" 
    | "new_foreground_tab" 
    | "new_window" 
    | "new_popup" 
   ) => void

  • 窗戶

    NewWindow

  • targetUrl

    字串

  • initialWidth

    數字

  • initialHeight

    數字

  • 名稱

    字串

  • windowOpenDisposition

    "略過"
     |"save_to_disk"
     |"current_tab"
     |&quot;new_background_tab&quot;
     |"new_foreground_tab"
     |"new_window"
     |"new_popup"
    

permissionrequest

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

訪客頁面需要向嵌入程式要求特殊權限時觸發。

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

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

參數

• 回呼

  函式

  callback 參數如下所示：

  (permission: "media" 
    | "geolocation" 
    | "pointerLock" 
    | "download" 
    | "loadplugin" 
    | "filesystem" 
    | "fullscreen" 
    | "hid" 
   , request: object) => void

  • 權限

    "媒體"
     |"地理位置"
     |"pointerLock"
     |「下載」
     |"loadplugin"
     |"檔案系統"
     |"全螢幕"
     |"hid"
    

  • 申請。

    物件

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 參數如下所示：

  (processID: number) => void

  • processID

    數字

sizechanged

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

透過 autosize 調整嵌入網頁內容的大小時觸發。只有在啟用 autosize 時才會觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

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

  • oldWidth

    數字

  • oldHeight

    數字

  • newWidth

    數字

  • newHeight

    數字

unresponsive

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

在轉譯訪客網頁內容的程序沒有回應時觸發。只要邀請對象再次開始回應，系統就會透過相符的回應式活動產生這個活動一次。

參數

• 回呼

  函式

  callback 參數如下所示：

  (processID: number) => void

  • processID

    數字

zoomchange

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

頁面縮放變更時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

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

  • oldZoomFactor

    數字

  • newZoomFactor

    數字