WebView
提供创建 webview、与其他 webview 通信以及操作当前 webview 的 API。
Webview 事件
可以使用 Webview.listen 监听事件
import { getCurrentWebview } from "@tauri-apps/api/webview";getCurrentWebview().listen("my-webview-event", ({ event, payload }) => { });
类
Webview
创建新的 webview 或获取现有 webview 的句柄
Webview 使用 标签 进行识别,标签是一个唯一的标识符,可以在以后引用它。它可能只能包含以下字符:字母数字字符 a-zA-Z
以及以下特殊字符 -
、/
、:
和 _
。
例子
import { Window } from "@tauri-apps/api/window"import { Webview } from "@tauri-apps/api/webview"
const appWindow = new Window('uniqueLabel');
// loading embedded asset:const webview = new Webview(appWindow, 'theUniqueLabel', { url: 'path/to/page.html'});// alternatively, load a remote URL:const webview = new Webview(appWindow, 'theUniqueLabel', { url: 'https://github.com/tauri-apps/tauri'});
webview.once('tauri://created', function () { // webview successfully created});webview.once('tauri://error', function (e) { // an error happened creating the webview});
// emit an event to the backendawait webview.emit("some-event", "data");// listen to an event from the backendconst unlisten = await webview.listen("event-name", e => {});unlisten();
从
2.0.0
扩展自
构造函数
new Webview()
new Webview( window, label, options): Webview
创建一个新的 Webview。
参数
参数 | 类型 | 描述 |
---|---|---|
窗口 | Window | 要添加此 webview 的窗口。 |
label | 字符串 | 唯一的 webview 标签。必须是字母数字:a-zA-Z-/:_ 。 |
options | WebviewOptions | - |
返回
与 webview 通信的 Webview 实例。
例子
import { Window } from '@tauri-apps/api/window'import { Webview } from '@tauri-apps/api/webview'const appWindow = new Window('my-label')const webview = new Webview(appWindow, 'my-label', { url: 'https://github.com/tauri-apps/tauri'});webview.once('tauri://created', function () { // webview successfully created});webview.once('tauri://error', function (e) { // an error happened creating the webview});
来源:https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L160
属性
属性 | 类型 | 描述 | 定义在 |
---|---|---|---|
label | 字符串 | webview 标签。它是 webview 的唯一标识符,可以在以后引用。 | 来源:https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L131 |
listeners | Record <string , EventCallback <any >[]> | 本地事件监听器。 | 来源:https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L136 |
window | Window | 承载此webview的窗口。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L133 |
方法
clearAllBrowsingData()
clearAllBrowsingData(): Promise<void>
清除此webview的所有浏览数据。
返回
Promise
<void
>
表示操作成功或失败的Promise。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().clearAllBrowsingData();
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L536
close()
close(): Promise<void>
关闭webview。
返回
Promise
<void
>
表示操作成功或失败的Promise。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().close();
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L400
emit()
emit(event, payload?): Promise<void>
向所有目标发出事件。
参数
参数 | 类型 | 描述 |
---|---|---|
事件 | 字符串 | 事件名称。只能包括字母数字字符,- ,/ ,: 和 _ 。 |
负载 ? | 未知 | 事件负载。 |
返回
Promise
<void
>
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().emit('webview-loaded', { loggedIn: true, token: 'authToken' });
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L289
emitTo()
emitTo( target, event,payload?): Promise<void>
向匹配给定目标的所有目标发出事件。
参数
参数 | 类型 | 描述 |
---|---|---|
目标 | string | EventTarget | 目标窗口/Webview/WebviewWindow的标签或原始 EventTarget 对象。 |
事件 | 字符串 | 事件名称。只能包括字母数字字符,- ,/ ,: 和 _ 。 |
负载 ? | 未知 | 事件负载。 |
返回
Promise
<void
>
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().emitTo('main', 'webview-loaded', { loggedIn: true, token: 'authToken' });
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L317
hide()
hide(): Promise<void>
隐藏webview。
返回
Promise
<void
>
表示操作成功或失败的Promise。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().hide();
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L470
listen()
listen<T>(event, handler): Promise<UnlistenFn>
监听此webview发出的event。
类型参数
类型参数 |
---|
T |
参数
参数 | 类型 | 描述 |
---|---|---|
事件 | EventName | 事件名称。只能包括字母数字字符,- ,/ ,: 和 _ 。 |
handler | EventCallback <T > | 事件处理程序。 |
返回
解析为一个取消监听事件的函数的Promise。注意,如果您的监听器超出作用域(例如组件卸载)则需要移除监听器。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';const unlisten = await getCurrentWebview().listen<string>('state-changed', (event) => { console.log(`Got error: ${payload}`);});
// you need to call unlisten if your handler goes out of scope e.g. the component is unmountedunlisten();
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L226
once()
once<T>(event, handler): Promise<UnlistenFn>
仅对此次发出的event进行一次监听。
类型参数
类型参数 |
---|
T |
参数
参数 | 类型 | 描述 |
---|---|---|
事件 | EventName | 事件名称。只能包括字母数字字符,- ,/ ,: 和 _ 。 |
handler | EventCallback <T > | 事件处理程序。 |
返回
解析为一个取消监听事件的函数的Promise。注意,如果您的监听器超出作用域(例如组件卸载)则需要移除监听器。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';const unlisten = await getCurrent().once<null>('initialized', (event) => { console.log(`Webview initialized!`);});
// you need to call unlisten if your handler goes out of scope e.g. the component is unmountedunlisten();
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L261
onDragDropEvent()
onDragDropEvent(handler): Promise<UnlistenFn>
监听文件拖拽事件。当用户将选定的文件放在webview上,拖放文件或取消操作时,触发监听器。
参数
参数 | 类型 |
---|---|
handler | EventCallback <DragDropEvent > |
返回
解析为一个取消监听事件的函数的Promise。注意,如果您的监听器超出作用域(例如组件卸载)则需要移除监听器。
例子
import { getCurrentWebview } from "@tauri-apps/api/webview";const unlisten = await getCurrentWebview().onDragDropEvent((event) => { if (event.payload.type === 'over') { console.log('User hovering', event.payload.position); } else if (event.payload.type === 'drop') { console.log('User dropped', event.payload.paths); } else { console.log('File drop cancelled'); }});
// you need to call unlisten if your handler goes out of scope e.g. the component is unmountedunlisten();
当调试器面板打开时,由于已知的限制,此事件的放置位置可能不准确。要获取正确的放置位置,请断开调试器。
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L588
position()
position(): Promise<PhysicalPosition>
相对于桌面左上角,webview客户端区域的左上角位置。
返回
webview的位置。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';const position = await getCurrentWebview().position();
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L362
reparent()
reparent(window): Promise<void>
将此webview移动到指定的标签。
参数
参数 | 类型 |
---|---|
窗口 | 字符串 | Window | WebviewWindow |
返回
Promise
<void
>
表示操作成功或失败的Promise。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().reparent('other-window');
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L519
setBackgroundColor()
setBackgroundColor(color): Promise<void>
指定webview的背景颜色。
平台特定
- macOS / iOS: 未实现。
- Windows:
- 在Windows 7上,不支持透明度,alpha值将被忽略。
- 在Windows 7以上版本:不支持半透明颜色,任何非
0
的alpha值将被替换为255
参数
参数 | 类型 |
---|---|
颜色 | null | Color |
返回
Promise
<void
>
表示操作成功或失败的Promise。
从
2.1.0
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L554
setFocus()
setFocus(): Promise<void>
将webview置于最前并聚焦。
返回
Promise
<void
>
表示操作成功或失败的Promise。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().setFocus();
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L454
setPosition()
setPosition(position): Promise<void>
设置webview的位置。
参数
参数 | 类型 | 描述 |
---|---|---|
位置 | LogicalPosition | PhysicalPosition | Position | 新的位置,以逻辑或物理像素为单位。 |
返回
Promise
<void
>
表示操作成功或失败的Promise。
例子
import { getCurrent, LogicalPosition } from '@tauri-apps/api/webview';await getCurrentWebview().setPosition(new LogicalPosition(600, 500));
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L435
setSize()
setSize(size): Promise<void>
调整webview的大小。
参数
参数 | 类型 | 描述 |
---|---|---|
大小 | LogicalSize | PhysicalSize | Size | 逻辑或物理大小。 |
返回
Promise
<void
>
表示操作成功或失败的Promise。
例子
import { getCurrent, LogicalSize } from '@tauri-apps/api/webview';await getCurrentWebview().setSize(new LogicalSize(600, 500));
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L417
setZoom()
setZoom(scaleFactor): Promise<void>
设置webview的缩放级别。
参数
参数 | 类型 |
---|---|
scaleFactor | 数字 |
返回
Promise
<void
>
表示操作成功或失败的Promise。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().setZoom(1.5);
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L502
show()
show(): Promise<void>
显示webview。
返回
Promise
<void
>
表示操作成功或失败的Promise。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().show();
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L486
size()
size(): Promise<PhysicalSize>
webview客户区域的物理大小。客户区域是webview的内容,不包括标题栏和边框。
返回
webview的大小。
例子
import { getCurrentWebview } from '@tauri-apps/api/webview';const size = await getCurrentWebview().size();
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L379
getAll()
static getAll(): Promise<Webview[]>
获取所有可用webview的Webview
实例列表。
返回
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L203
getByLabel()
static getByLabel(label): Promise<null | Webview>
获取与给定标签关联的webview。
参数
参数 | 类型 | 描述 |
---|---|---|
label | 字符串 | webview标签。 |
返回
PhysicalSize
<code dir="auto">null | Webview
>
与webview通信的Webview实例或null(如果webview不存在)。
例子
import { Webview } from '@tauri-apps/api/webview';const mainWebview = Webview.getByLabel('main');
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L189
getCurrent()
static getCurrent(): Webview
获取当前webview的Webview
实例。
返回
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L196
接口
WebviewOptions
创建webview的配置。
从
2.0.0
属性
属性 | 类型 | 描述 | 定义在 |
---|---|---|---|
acceptFirstMouse? | 布尔值 | 点击非活动webview时,是否也会点击到macOS的webview。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L693 |
backgroundColor? | 颜色 | 设置窗口和webview的背景颜色。#### 平台特定: - macOS / iOS:未实现。 - Windows: - 在Windows 7上,alpha通道被忽略。 - 在Windows 8及更高版本上,如果alpha通道不是0 ,则会被忽略。自 2.1.0以来 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L769 |
devtools? | 布尔值 | 是否启用Web调试器,通常称为浏览器调试工具。默认启用。此API在调试构建中工作,但在发布构建中需要devtools 功能标志才能启用。#### 平台特定 - macOS:这将调用< strong>macOS上的私有函数。 - Android:在Chrome中打开chrome://inspect/#devices 以获取调试工具窗口。Wry的WebView 调试工具API在Android上不受支持。 - iOS:打开Safari > 开发 > [您的设备名称] > [您的WebView]以获取调试工具窗口。自 2.1.0以来 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L756 |
dragDropEnabled? | 布尔值 | 是否在webview上启用拖放。默认启用。要在Windows前端使用HTML5拖放,需要禁用它。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L689 |
focus? | 布尔值 | webview是否应该有焦点。自 2.1.0以来 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L683 |
height | 数字 | 初始高度。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L671 |
incognito? | 布尔值 | webview是否应该以匿名模式启动。#### 平台特定 - Android:不受支持。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L705 |
proxyUrl? | 字符串 | WebView所有网络请求的代理URL。必须是http:// 或socks5:// URL。<#### 平台特定 - macOS:需要macos-proxy 功能标志,并且只针对macOS 14及更高版本编译。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L715 |
transparent? | 布尔值 | webview是否透明。注意,在macOS 上需要macos-private-api 功能标志,在tauri.conf.json > app > macOSPrivateApi 下启用。警告:在macOS 上使用私有API会阻止您的应用程序被接受到App Store 。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L677 |
url? | 字符串 | 远程URL或本地文件路径以打开。 - 可以直接在Tauri webview中打开的URL,例如https://github.com/tauri-apps - data: URL,例如data:text/html,<html>... ,仅支持与tauri 依赖项的webview-data-url Cargo功能一起使用。 - 本地文件路径或路由,例如/path/to/page.html 或/users ,附加到应用程序URL(开发时的devServer URL,或生产时的tauri://127.0.0.1/ 和https://tauri.localhost/ )。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L663 |
useHttpsScheme? | 布尔值 | 设置自定义协议是否应使用https://<scheme>.localhost 而不是Windows和Android上的默认http://<scheme>.localhost 。默认为false 。#### 注意:使用https 方案在尝试获取http 端点时不会允许混合内容,因此不会匹配macOS和Linux上使用的<scheme>://127.0.0.1 协议的行为。#### 警告:在版本之间更改此值将更改IndexedDB、cookies和localstorage的位置,并且您的应用程序无法访问它们。自2.1.0起。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L742 |
userAgent? | 字符串 | webview的用户代理。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L697 |
width | 数字 | 初始宽度。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L669 |
x | 数字 | 初始垂直位置。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L665 |
y | 数字 | 初始水平位置。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L667 |
zoomHotkeysEnabled? | 布尔值 | 是否启用通过热键进行页面缩放的缩放#### 平台特定: - Windows:控制WebView2的IsZoomControlEnabled 设置。- MacOS/Linux:注入一个polyfill,使用ctrl/command + -/= 进行缩放和缩小,每步20%,范围从20%到1000%。需要webview:allow-set-webview-zoom 权限。- Android/iOS:不支持。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L727 |
类型别名
颜色
type Color: [number, number, number] | [number, number, number, number] | object | string;
RGBA颜色。每个值的范围从0到255。
可以是字符串#ffffff
、包含3或4个元素的数组或对象。
从
2.0.0
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/window.ts#L2018
拖拽事件
type DragDropEvent: object | object | object | object;
拖放事件类型。
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L37
函数
getAllWebviews()
function getAllWebviews(): Promise<Webview[]>
获取所有可用webview的Webview
实例列表。
返回
从
2.0.0
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L64
getCurrentWebview()
function getCurrentWebview(): Webview
获取当前webview的Webview
实例。
返回
从
2.0.0
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L48
© 2025 Tauri 贡献者。CC-BY / MIT