chrome.webviewTag

说明

使用 webview 标记可通过网络主动加载来自网络的直播内容，并将其嵌入到 Chrome 应用中。您的应用可以控制 webview 的外观，与网络内容互动，在嵌入的网页中发起导航，对其中发生的错误事件做出响应，等等（请参阅用法）。

权限

webview

类型

ClearDataOptions

用于确定 clearData 应清除哪些数据的选项。

属性

  • 开始于

    number 可选

    清除在此日期当天或之后累积的数据，以从公元纪年起算的毫秒数表示（可通过 JavaScript Date 对象的 getTime 方法访问）。如果不存在，则默认为 0（这会移除所有浏览数据）。

ClearDataTypeSet

一组数据类型。缺少的属性会被解释为 false。

属性

  • appcache

    布尔值（可选）

    网站的 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[] 可选

    在匹配后应用，用于排除与此正则表达式匹配的网址。旨在模拟 Greasemonkey 中的 @exclude 关键字。

  • exclude_matches

    string[] 可选

    排除本应注入此内容脚本的网页。

  • include_globs

    string[] 可选

    在匹配后应用，以便仅包含也与此正则表达式匹配的网址。旨在模拟 @include Greasemonkey 关键字。

  • js

    InjectionItems 可选

    要注入到匹配网页中的 JavaScript 代码或 JavaScript 文件列表。这些内容会按照显示的顺序注入。

  • match_about_blank

    布尔值（可选）

    是否在 about:blank 和 about:srcdoc 中插入内容脚本。只有当网页的继承网址与 matches 字段中声明的某个模式匹配时，系统才会在该网页上注入内容脚本。继承网址是创建框架或窗口的文档的网址。内容脚本无法插入沙盒化框架中。

  • 匹配

    字符串[]

    指定将向哪些网页注入此内容脚本。

  • name

    字符串

    要注入的内容脚本的名称。

  • run_at

    RunAt（可选）

    JavaScript 或 CSS 最早会注入到标签页中的时间。默认为“document_idle”。

ContentWindow

与访客窗口通信的句柄。

属性

  • postMessage

    void

    只要嵌入式内容正在显示目标来源中的网页，便会向嵌入式 Web 内容发布消息。页面加载完毕后，此方法才可用。监听 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

    字符串（选填）

    要分配给此项的唯一 ID。对于活动页面，此属性为必填项。不能与此扩展程序的其他 ID 相同。

  • parentId

    字符串 | 数字（可选）

    父级菜单项的 ID；这会使该项成为之前添加的项的子项。

  • targetUrlPatterns

    string[] 可选

    与 documentUrlPatterns 类似，但可让您根据 img/audio/video 标记的 src 属性和锚链接标记的 href 进行过滤。

  • title

    字符串（选填）

    要在项中显示的文本；除非 type 为“分隔符”，否则此属性为必需属性。当上下文为“selection”时，您可以在字符串中使用 %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

    • 返回

      字符串 | 数字

      新创建的项的 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

      对象

      要更新的媒体资源。接受与 create 函数相同的值。

    • callback

      函数（可选）

      callback 参数如下所示： 

      () => void

ContextMenuUpdateProperties

Chrome 44 及更高版本

属性

  • 已勾选

    布尔值（可选）

    复选框或单选按钮项的状态：如果处于选中状态，则为 true；如果处于未选中状态，则为 false。在给定的一组单选项中，一次只能选择一个单选项。

  • 上下文

    [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) => {...}

    • Response

      字符串（选填）

      接受 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 的详细信息。必须设置代码或文件属性，但不能同时设置这两者。

属性

  • 代码

    字符串（选填）

    要注入的 JavaScript 或 CSS 代码。

    警告：请谨慎使用 code 参数。如果使用不当，可能会使您的应用受到跨站脚本攻击。

  • 文件

    字符串（选填）

    要注入的 JavaScript 或 CSS 文件。

InjectionItems

Chrome 44 及更高版本

注入项的类型：代码或一组文件。

属性

  • 代码

    字符串（选填）

    要注入到匹配网页中的 JavaScript 代码或 CSS。

  • 文件

    string[] 可选

    要注入到匹配网页中的 JavaScript 或 CSS 文件的列表。这些参数会按照此数组中的显示顺序注入。

LoadPluginPermissionRequest

与 loadplugin permissionrequest DOM 事件一起出现的 request 对象的类型。

属性

  • 标识符

    字符串

    插件的标识符字符串。

  • name

    字符串

    插件的显示名称。

  • 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) 不包含在矩形中。

属性

  • 高度

    数值

    矩形的高度。

  • 左侧

    数值

    从屏幕左侧边缘到矩形左侧边缘的距离。

  • 顶部

    数值

    从屏幕顶边到矩形顶边的距离。

  • width

    数值

    矩形的宽度。

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 中处理缩放。

枚举

“按源”
缩放更改将保留在经过缩放的网页的源中，即同一分区中导航到同一源的所有其他 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';

您可以推迟 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,
)

向后浏览一个历史记录条目（如果可能）。等同于 go(-1)。

参数

  • callback

    函数（可选）

    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

    函数

    callback 参数如下所示： 

    (dataUrl: string) => void

    • dataUrl

      字符串

      用于编码所截取标签页可见区域的图片的数据网址。可分配给 HTML 图片元素的“src”属性以进行显示。

clearData()

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

清除 webview 分区的浏览数据。

参数

  • 用于确定要清除哪些数据的选项。

  • 要清除的数据类型。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

executeScript()

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

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

发起页面内搜索请求。

参数

  • searchText

    字符串

    要在网页中查找的字符串。

  • 选项

    FindOptions（可选）

    查找请求的选项。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (results?: FindCallbackResults) => void

    • 结果

      FindCallbackResults（可选）

      包含查找请求的所有结果。如果回调函数正文中未使用 results，则可以省略 results；例如，如果回调仅用于确定查找请求何时完成。

forward()

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

向前浏览一个历史记录条目（如果可能）。等同于 go(1)。

参数

  • callback

    函数（可选）

    Chrome 44 及更高版本

    callback 参数如下所示： 

    (success: boolean) => void

    • 成功

      布尔值

      指示导航是否成功。

getAudioState()

Chrome 62 及更高版本 
chrome.webviewTag.getAudioState(
  callback: function,
)

查询音频状态。

参数

  • callback

    函数

    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

    函数

    callback 参数如下所示： 

    (zoomFactor: number) => void

    • zoomFactor

      数值

      当前缩放比例。

getZoomMode()

Chrome 43 及更高版本 
chrome.webviewTag.getZoomMode(
  callback: function,
)

获取当前的缩放模式。

参数

  • callback

    函数

    callback 参数如下所示： 

    (ZoomMode: ZoomMode) => void

    • ZoomMode

      ZoomMode

      webview 的当前缩放模式。

go()

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

使用相对于当前导航的导航历史记录索引导航到导航历史记录条目。如果无法执行请求的导航，此方法将不会产生任何影响。

参数

  • relativeIndex

    数值

    应将 webview 导航到的相对历史记录索引。例如，如果可能，值 2 会向前导航 2 个历史记录条目；值 -3 会向后导航 3 个条目。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (success: boolean) => void

    • 成功

      布尔值

      指示导航是否成功。

insertCSS()

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

将 CSS 注入到访客页面。

参数

  • 详细信息

    InjectDetails

    要插入的 CSS 的详细信息。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

isAudioMuted()

Chrome 62 及更高版本 
chrome.webviewTag.isAudioMuted(
  callback: function,
)

查询音频是否处于静音状态。

参数

  • callback

    函数

    callback 参数如下所示： 

    (muted: boolean) => void

    • 已设为静音

      布尔值

isSpatialNavigationEnabled()

Chrome 71 及更高版本 
chrome.webviewTag.isSpatialNavigationEnabled(
  callback: function,
)

查询是否为 WebView 启用了空间导航。

参数

  • callback

    函数

    callback 参数如下所示： 

    (enabled: boolean) => void

    • 已启用

      布尔值

isUserAgentOverridden()

chrome.webviewTag.isUserAgentOverridden()

指明 webview 的用户代理字符串是否已被 webviewTag.setUserAgentOverride 替换。

loadDataWithBaseUrl()

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

使用用于相对链接的指定基本网址加载数据网址。（可选）您可以提供虚拟网址（而不是数据网址）来向用户显示。

参数

  • dataUrl

    字符串

    要加载的数据网址。

  • baseUrl

    字符串

    将用于相对链接的基准网址。

  • virtualUrl

    字符串（选填）

    将向用户显示的网址（在地址栏中）。

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 客户端提示标头值和 navigator.userAgentData 返回的值为空。

参数

  • userAgent

    字符串

    要使用的用户代理字符串。

setZoom()

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

更改网页的缩放比例。此更改的范围和持久性取决于 WebView 的当前缩放模式（请参阅 webviewTag.ZoomMode）。

参数

  • zoomFactor

    数值

    新的缩放比例。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

setZoomMode()

Chrome 43 及更高版本 
chrome.webviewTag.setZoomMode(
  ZoomMode: ZoomMode,
  callback?: function,
)

设置 webview 的缩放模式。

参数

  • ZoomMode

    ZoomMode

    定义如何在 webview 中处理缩放。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

stop()

chrome.webviewTag.stop()

停止加载当前的 webview 导航（如果正在进行）。

stopFinding()

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

结束当前查找会话（清除所有突出显示内容），并取消所有正在进行的查找请求。

参数

  • action

    "clear"
     | "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

    函数

    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

      数值

    • 消息

      字符串

    • line

      数值

    • 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: "alert" 
      | "confirm" 
      | "prompt" 
     , messageText: string, dialog: DialogController) => void

    • messageType

      "alert"
       | "confirm"
       | "prompt"

    • 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 参数如下所示： 

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

    • processID

      数值

    • reason

      "normal"
       | "abnormal"
       | "crash"
       | "kill"

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 事件（如果有）以来所有已提交的加载都被中止也是如此。

注意：当“关于”网址或 JavaScript 网址的加载被中止时，系统会触发 loadabort，然后将 webview 导航到“about:blank”。

参数

  • callback

    函数

    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

      布尔值

    • 代码

      数值

    • reason

      "ERR_ABORTED"
       | "ERR_INVALID_网址"
       | "ERR_DISALLOWED_网址_SCHEME"
       | "ERR_BLOCKED_BY_CLIENT"
       | "ERR_ADDRESS_UNREACHABLE"
       | "ERR_EMPTY_RESPONSE"
       | "ERR_FILE_NOT_FOUND"
       | "ERR_UNKNOWN_网址_SCHEME"

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

当访客页面中的所有帧级加载（包括其所有子帧）都完成时触发。这包括在当前文档中导航以及子帧文档级加载，但不包括异步资源加载。每当文档级加载次数从 1（或更多）变为 0 时，系统都会触发此事件。例如，如果某个网页已完成加载（即loadstop 已触发一次）会创建一个用于加载页面的新 iframe，然后在 iframe 页面加载完成时触发第二个 loadstop。这种模式通常出现在加载广告的网页上。

注意：当已提交的加载被中止时，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: "ignore" 
      | "save_to_disk" 
      | "current_tab" 
      | "new_background_tab" 
      | "new_foreground_tab" 
      | "new_window" 
      | "new_popup" 
     ) => void

    • 窗口

      NewWindow

    • targetUrl

      字符串

    • initialWidth

      数值

    • initialHeight

      数值

    • name

      字符串

    • windowOpenDisposition

      "ignore"
       | "save_to_disk"
       | "current_tab"
       | "new_background_tab"
       | "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

    函数

    callback 参数如下所示： 

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

    • 权限

      "media"
       | "geolocation"
       | "pointerLock"
       | "download"
       | "loadplugin"
       | "filesystem"
       | "fullscreen"
       | "hid"

    • request

      对象

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

当嵌入的 Web 内容通过 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

      数值