chrome.webviewTag

说明

使用 webview 标记可通过网络主动加载网络上的实时内容，并将其嵌入您的 Chrome 应用。您的应用可以控制 webview 的外观并与 Web 内容交互、在嵌入式网页中启动导航、对网页中发生的错误事件做出响应等（请参阅使用方式）。

权限

webview

类型

ClearDataOptions

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

属性

  • 开始于

    编号（选填）

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

ClearDataTypeSet

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

属性

  • appcache

    布尔值（可选）

    网站appcaches 等方法。

  • 缓存

    布尔值（可选）

    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 中插入内容脚本。仅当网页的继承网址与 match 字段中声明的模式之一匹配时，内容脚本才会被注入到网页上。继承网址是创建框架或窗口的文档的网址。无法在沙盒化框架中插入内容脚本。

  • 匹配

    字符串[]

    指定要将此内容脚本注入哪些页面。

  • 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

    string |编号（选填）

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

  • targetUrlPatterns

    string[] 选填

    与 documentUrlPatterns 类似，但允许您根据 img/audio/video 标记的 src 属性和锚点标记的 href 进行过滤。

  • 标题

    字符串（可选）

    要在作品中显示的文字；除非 type 为“分隔符”，否则必须执行此操作。当上下文为“selection”时，您可以在字符串中使用 %s 来显示所选文本。例如，如果此参数的值为“Translate '%s”发送给 Pig Latin 式密语”当用户选择了“cool”一词时，可选择的上下文菜单项为“Translate cool”发送给 Pig Latin 式密语。

  • 类型

    ItemType 选填

    菜单项的类型。默认为“normal”（普通）。

  • onClick

    void 可选

    点击菜单项时要回调的函数。

    onclick 函数如下所示： 

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

    • 资讯

      OnClickData

      有关所点击项目的信息以及点击发生的具体环境。

ContextMenus

Chrome 44 及更高版本

属性

  • onShow

    事件<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

    • 返回

      string |号码

      新创建的商品的 ID。

  • 移除

    void

    移除上下文菜单项。

    remove 函数如下所示： 

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

    • menuItemId

      string |号码

      要移除的上下文菜单项的 ID。

    • callback

      函数（可选）

      callback 参数如下所示： 

      () => void

  • 全部移除

    void

    移除添加到此 webview 的所有上下文菜单项。

    removeAll 函数如下所示： 

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

    • callback

      函数（可选）

      callback 参数如下所示： 

      () => void

  • update

    void

    更新之前创建的上下文菜单项。

    update 函数如下所示： 

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

    • id

      string |号码

      要更新的商品的 ID。

    • updateProperties

      对象

      要更新的属性。接受的值与 create 函数相同。

    • callback

      函数（可选）

      callback 参数如下所示： 

      () => void

ContextMenuUpdateProperties

Chrome 44 及更高版本

属性

  • 已勾选

    布尔值（可选）

    复选框或单选项的状态：true 表示选中，false 表示未选中。在指定的一组单选项中，一次只能选择一个单选项。

  • 上下文

    [ContextType, ...ContextType[]] 可选

    显示此菜单项的上下文列表。

  • documentUrlPatterns

    string[] 选填

    可让您将项限制为仅应用于网址与某一给定格式相符的文档。（这也适用于框架）。如需详细了解模式格式，请参阅匹配模式。

  • 已启用

    布尔值（可选）

    此上下文菜单项处于启用状态还是停用状态。

  • parentId

    string |编号（选填）

    父菜单项的 ID；这会使该项成为先前添加的项的子项。注意：您无法将项更改为它自己的某个后代的子级。

  • targetUrlPatterns

    string[] 选填

    与 documentUrlPatterns 类似，但允许您根据 img/audio/video 标记的 src 属性和锚点标记的 href 进行过滤。

  • 标题

    字符串（可选）

    要在作品中显示的文本

  • 类型

    ItemType 选填

    菜单项的类型。

  • onClick

    void 可选

    点击菜单项时要回调的函数。

    onclick 函数如下所示： 

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

    • 资讯

      OnClickData

      有关所点击项目的信息以及点击发生的具体环境。

ContextType

Chrome 44 及更高版本

菜单可显示的不同上下文。指定“all”等同于所有其他上下文的组合。

枚举

“全部”

“页面”

"框架"

“selection”

“链接”

"可修改"

“图片”

“视频”

"audio"

DialogController

附加到 dialog DOM 事件的接口。

属性

  • 取消

    void

    拒绝该对话框。相当于在 confirm 或 prompt 对话框中点击“取消”。

    cancel 函数如下所示： 

    () => {...}

  • 确定

    void

    接受对话框。相当于在 alert、confirm 或 prompt 对话框中点击“OK”。

    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

    number

    当前匹配项的序数。

  • 已取消

    布尔值

    指示此查找请求是否已取消。

  • numberOfMatches

    number

    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) 则不包含。

属性

  • 高度

    number

    矩形的高度。

  • 左侧

    number

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

  • 顶部

    number

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

  • width

    number

    矩形的宽度。

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 缩放更改会与原点一起保存，这意味着当导航到同一原点的其他网页时，它们都将按照相同的缩放比例进行缩放。

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

向 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

      字符串

      一个数据网址，用于对所截取标签页的可见区域的图片进行编码。可能会分配给“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，则可以省略它；例如，如果回调仅用于在查找请求完成时进行识别。

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 不同。

返回

  • number

getUserAgent()

chrome.webviewTag.getUserAgent()

返回 webview 用于访客页面请求的用户代理字符串。

返回

  • 字符串

getZoom()

chrome.webviewTag.getZoom(
  callback: function,
)

获取当前的缩放比例。

参数

  • callback

    函数

    callback 参数如下所示： 

    (zoomFactor: number) => void

    • zoomFactor

      number

      当前缩放比例。

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

    number

    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 针对访客页面请求使用的用户代理字符串。如果替换，对于应用了此替换值的访客页面请求，替换后，用户代理客户端提示标头值以及 navigator.userAgentData 返回的值将为空。

参数

  • userAgent

    字符串

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

setZoom()

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

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

参数

  • zoomFactor

    number

    新的缩放比例。

  • 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

    "清除"
     |"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

      number

    • 消息

      字符串

    • line

      number

    • 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

      "提醒"
       |"确认"
       |“提示”

    • messageText

      字符串

    • 对话框

      DialogController

exit

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

在呈现访客 Web 内容的进程退出时触发。

以下示例代码会在访客页面崩溃时显示告别消息：

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

      number

    • 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

      number

    • activeMatchOrdinal

      number

    • selectionRect

      SelectionRect

    • 已取消

      布尔值

    • finalUpdate

      字符串

loadabort

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

顶级加载已取消且未提交时触发。除非活动默认被阻止，否则系统会在控制台中输出错误消息。

注意：取消资源加载后，即使有自上次 loadstop 事件（如有）以来所有已提交的加载被中止，loadabort 事件最终也会跟随 loadstop 事件。

注意：如果取消加载 about 网址或 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

      布尔值

    • 代码

      number

    • reason

      "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

    函数

    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。这种模式通常在加载广告的网页上出现。

注意：如果取消提交的加载，则 loadstop 事件最终将发生在 loadabort 事件之后，即使自上次 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

      number

    • initialHeight

      number

    • name

      字符串

    • 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

    函数

    callback 参数如下所示： 

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

    • 权限

      "media"
       |"geolocation"
       |"pointerLock"
       |"下载"
       |"loadplugin"
       |"filesystem"
       |"全屏"
       |“隐藏”

    • request

      对象

responsive

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

在呈现访客 Web 内容的进程在无响应后又恢复响应时触发。

以下示例代码会在 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

      number

sizechanged

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

在通过 autosize 调整嵌入的 Web 内容的大小时触发。仅在 autosize 处于启用状态时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • oldWidth

      number

    • oldHeight

      number

    • newWidth

      number

    • newHeight

      number

unresponsive

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

在呈现访客 Web 内容的进程无响应时触发。如果邀请对象开始再次回复，此事件将与匹配的自适应事件一起生成一次。

参数

  • callback

    函数

    callback 参数如下所示： 

    (processID: number) => void

    • processID

      number

zoomchange

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

在网页的缩放比例发生变化时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • oldZoomFactor

      number

    • newZoomFactor

      number