chrome.webviewTag

重要事項： 這個 API 僅適用於 ChromeOS。

說明

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

權限

webview

可用性

僅適用於 ChromeOS

類型

ClearDataOptions

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

屬性

• 開始於

  數字 選填

  清除這個日期當天或之後累積的資料，以自紀元起算的毫秒數表示 (可透過 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

  string[] 選填

  比對後套用，排除與這個 glob 相符的網址。用於模擬 @exclude Greasemonkey 關鍵字。

• exclude_matches

  string[] 選填

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

• include_globs

  string[] 選填

  在比對後套用，僅納入同時符合這個 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 表示未選取。在指定的圓形按鈕項目群組中，一次只能選取一個圓形按鈕項目。

• contexts

  [ContextType, ...ContextType[]] 選填

  這個選單項目會顯示在哪些情境。如未指定，預設為 ['page']。

• documentUrlPatterns

  string[] 選填

  限制項目只能套用至網址符合指定模式的文件。(鏡框也適用)。如要進一步瞭解模式格式，請參閱「比對模式」。

• 已啟用

  布林值 選填

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

• id

  字串 選填

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

• parentId

  字串 | 數字 選填

  上層選單項目的 ID；這會使該項目成為先前新增項目的子項。

• targetUrlPatterns

  string[] 選填

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

• title

  字串 選填

  項目中要顯示的文字；除非 type 為「separator」，否則這是必要屬性。如果情境是「選取項目」，您可以在字串中使用 %s 顯示所選文字。舉例來說，如果這個參數的值是「將『%s』翻譯成兒童黑話」，而使用者選取了「cool」這個字，則所選內容的內容選單項目會是「將『cool』翻譯成兒童黑話」。

• 類型

  ItemType 選填

  選單項目類型。如未指定，預設為「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

    string | number

    新建立項目的 ID。

• 移除

  void

  移除內容選單項目。

  remove 函式如下所示：

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

  • menuItemId

    string | number

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

  • callback

    函式 選填

    callback 參數如下：

    () => void

• removeAll

  void

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

  removeAll 函式如下所示：

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

  • callback

    函式 選填

    callback 參數如下：

    () => void

• update

  void

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

  update 函式如下所示：

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

  • id

    string | number

    要更新的項目 ID。

  • updateProperties

    物件

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

  • callback

    函式 選填

    callback 參數如下：

    () => void

ContextMenuUpdateProperties

Chrome 44 以上版本

屬性

• 已勾選

  布林值 選填

  核取方塊或圓形按鈕項目的狀態：true 代表已選取，false 代表未選取。在指定的圓形按鈕項目群組中，一次只能選取一個圓形按鈕項目。

• contexts

  [ContextType, ...ContextType[]] 選填

  這個選單項目會顯示在哪些情境。

• documentUrlPatterns

  string[] 選填

  限制項目僅套用至網址符合指定模式的文件。(這也適用於鏡框)。如要進一步瞭解模式格式，請參閱「比對模式」。

• 已啟用

  布林值 選填

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

• parentId

  字串 | 數字 選填

  上層選單項目的 ID；這會使該項目成為先前新增項目的子項。注意：您無法將項目變更為其子項的子項。

• targetUrlPatterns

  string[] 選填

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

• title

  字串 選填

  項目中要顯示的文字

• 類型

  ItemType 選填

  選單項目類型。

• 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

Chrome 141 以上版本

訪客要求的互動視窗對話方塊類型。

列舉

"alert"

"confirm"

"prompt"

DownloadPermissionRequest

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

屬性

• requestMethod

  字串

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

• 網址

  字串

  要求的下載網址。

• allow

  void

  允許權限要求。

  allow 函式如下所示：

  () => {...}

• deny

  void

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

  deny 函式如下所示：

  () => {...}

ExitReason

Chrome 141 以上版本

表示退出原因的字串。

列舉

"normal"

「異常」

「當機」

"killed"

「oom killed」

"oom"

「無法啟動」

「integrity failure」

FileSystemPermissionRequest

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

屬性

• 網址

  字串

  要求存取本機檔案系統的頁框網址。

• allow

  void

  允許權限要求。

  allow 函式如下所示：

  () => {...}

• deny

  void

  拒絕權限要求。

  deny 函式如下所示：

  () => {...}

FindCallbackResults

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

屬性

• activeMatchOrdinal

  數字

  目前相符項目的序數。

• 已取消

  布林值

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

• numberOfMatches

  數字

  網頁上與「searchText」相符的次數。

• selectionRect

  SelectionRect

  以螢幕座標描述目前相符項目周圍的矩形。

FindOptions

尋找要求的選項。

屬性

• backward

  布林值 選填

  這個標記會以反向順序尋找相符項目。預設值為 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。

• 檔案

  string[] 選填

  要插入相符網頁的 JavaScript 或 CSS 檔案清單。系統會按照這些指令碼在陣列中的顯示順序，依序插入指令碼。

LoadAbortReason

Chrome 141 以上版本

指出發生何種中斷情形的字串。我們不保證這個字串在不同版本之間能維持回溯相容性。請勿剖析內容並據此採取行動。在某些情況下，系統也可能回報未列於此處的錯誤。

列舉

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

屬性

• identifier

  字串

  外掛程式的 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

Chrome 141 以上版本

要求的權限類型。

列舉

"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

Chrome 141 以上版本

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

列舉

「clear」

"keep"

「啟用」

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.* 例項化。以下程式碼範例會以宣告方式，封鎖 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]);

WindowOpenDisposition

Chrome 141 以上版本

新視窗要求的配置。

列舉

"ignore"

"save_to_disk"

"current_tab"

"new_background_tab"

"new_foreground_tab"

"new_window"

"new_popup"

ZoomMode

Chrome 43 以上版本

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

列舉

「per-origin」
縮放變更會保留在縮放頁面的來源中，也就是說，同一分區中所有其他前往相同來源的網頁檢視也會縮放。此外，per-origin縮放變更會與來源一起儲存，也就是說，當使用者前往相同來源的其他頁面時，這些頁面都會縮放到相同的縮放係數。

「per-view」
縮放變更只會在這個 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[]],
): 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 重新建立父項，規則仍會保留。

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

參數

• contentScriptList

  [ContentScriptDetails, ...ContentScriptDetails[]]

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

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 分區的瀏覽資料。

參數

• 選項

  ClearDataOptions

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

• 類型

  ClearDataTypeSet

  要清除的資料類型。

• 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 選用

    包含尋找要求的所有結果。如果回呼函式主體中未使用 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 用於訪客頁面要求的使用者代理程式字串。

傳回

• 字串

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

查詢是否為網頁檢視啟用空間導覽功能。

參數

• 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

  string[] 選填

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

setAudioMuted()

Chrome 62 以上版本

chrome.webviewTag.setAudioMuted(
  mute: boolean,
): void

設定 WebView 的音訊靜音狀態。

參數

• 靜音

  布林值

  靜音音訊值

setSpatialNavigationEnabled()

Chrome 71 以上版本

chrome.webviewTag.setSpatialNavigationEnabled(
  enabled: boolean,
): void

設定 WebView 的空間導覽狀態。

參數

• 已啟用

  布林值

  空間導覽狀態值。

setUserAgentOverride()

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

覆寫 webview 用於訪客頁面要求的使用者代理程式字串。覆寫後，如果訪客頁面要求套用這項覆寫設定，使用者代理程式用戶端提示標頭值和 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

  • 等級

    數字

  • 訊息

    字串

  • 行

    數字

  • 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())。

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

參數

• callback

  函式

  callback 參數如下：

  (messageType: DialogMessageType, messageText: string, dialog: DialogController) => void

  • messageType

    DialogMessageType

  • messageText

    字串

  • 對話方塊

    DialogController

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。

    • reason

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

頂層載入作業在未提交的情況下中止時，就會觸發這個事件。除非事件已預設為禁止，否則控制台會顯示錯誤訊息。

注意：資源載入作業取消時，系統最終會在 loadabort 事件後觸發 loadstop 事件，即使自上次 loadstop 事件 (如有) 以來的所有已提交載入作業都已取消，也是如此。

注意：如果 about 網址或 JavaScript 網址載入作業遭到中止，系統會觸發 loadabort，然後將 webview 導向「about:blank」。

參數

• callback

  函式

  callback 參數如下：

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

  • 網址

    字串

  • isTopLevel

    布林值

  • 程式碼

    數字

  • reason

    LoadAbortReason

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 來載入網頁，則第二個 loadstop 會在 iframe 網頁載入完成時觸發。這種模式常見於載入廣告的網頁。

注意：如果已提交的載入作業遭到取消，系統最終會在 loadabort 事件後觸發 loadstop 事件，即使自上次 loadstop 事件 (如有) 以來的所有已提交載入作業都遭到取消，也是如此。

參數

• 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

  • 窗戶

    NewWindow

  • targetUrl

    字串

  • initialWidth

    數字

  • initialHeight

    數字

  • 名稱

    字串

  • windowOpenDisposition

    WindowOpenDisposition

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

  • 權限

    PermissionType

  • 申請。

    物件

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

    數字