跳转到内容

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 backend
await webview.emit("some-event", "data");
// listen to an event from the backend
const 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-/:_
optionsWebviewOptions-
返回

Webview

与 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
listenersRecord<string, EventCallback<any>[]>本地事件监听器。来源https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L136
windowWindow承载此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事件名称。只能包括字母数字字符,-/:_
handlerEventCallback<T>事件处理程序。
返回

Promise<UnlistenFn>

解析为一个取消监听事件的函数的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 unmounted
unlisten();

来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L226

once()
once<T>(event, handler): Promise<UnlistenFn>

仅对此次发出的event进行一次监听。

类型参数
类型参数
T
参数
参数类型描述
事件EventName事件名称。只能包括字母数字字符,-/:_
handlerEventCallback<T>事件处理程序。
返回

Promise<UnlistenFn>

解析为一个取消监听事件的函数的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 unmounted
unlisten();

来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L261

onDragDropEvent()
onDragDropEvent(handler): Promise<UnlistenFn>

监听文件拖拽事件。当用户将选定的文件放在webview上,拖放文件或取消操作时,触发监听器。

参数
参数类型
handlerEventCallback<DragDropEvent>
返回

Promise<UnlistenFn>

解析为一个取消监听事件的函数的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 unmounted
unlisten();

当调试器面板打开时,由于已知的限制,此事件的放置位置可能不准确。要获取正确的放置位置,请断开调试器。

来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L588

position()
position(): Promise<PhysicalPosition>

相对于桌面左上角,webview客户端区域的左上角位置。

返回

Promise<PhysicalPosition>

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的内容,不包括标题栏和边框。

返回

PhysicalSize<PhysicalSize>

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实例列表。

返回

PhysicalSize<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实例。

返回

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实例列表。

返回

PhysicalSize<Webview[]>

2.0.0

来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L64


getCurrentWebview()

function getCurrentWebview(): Webview

获取当前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