webview
提供用于创建 webview、与其他 webview 通信以及操作当前 webview 的 API。
事件可以使用 Webview.listen 监听
import { getCurrentWebview } from "@tauri-apps/api/webview";getCurrentWebview().listen("my-webview-event", ({ event, payload }) => { });
创建新的 webview 或获取现有 webview 的句柄。
Webview 通过一个“label”来标识,这是一个唯一的标识符,可用于以后引用。它只能包含字母数字字符 a-zA-Z
以及以下特殊字符 -
、/
、:
和 _
。
import { Window } from "@tauri-apps/api/window"import { Webview } from "@tauri-apps/api/webview"
const appWindow = new Window('uniqueLabel');
appWindow.once('tauri://created', async function () { // `new Webview` Should be called after the window is successfully created, // or webview may not be attached to the window since window is not created yet.
// loading embedded asset: const webview = new Webview(appWindow, 'theUniqueLabel', { url: 'path/to/page.html',
// create a webview with specific logical position and size x: 0, y: 0, width: 800, height: 600, }); // alternatively, load a remote URL: const webview = new Webview(appWindow, 'theUniqueLabel', { url: 'https://github.com/tauri-apps/tauri',
// create a webview with specific logical position and size x: 0, y: 0, width: 800, height: 600, });
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( window, label, options): Webview
创建一个新的 Webview。
参数 | 类型 | 描述 |
---|---|---|
window | 窗口 | 要将此 webview 添加到的窗口。 |
标签 | 字符串 | 唯一的 webview 标签。必须是字母数字:a-zA-Z-/:_ 。 |
选项 | WebviewOptions | - |
与 webview 通信的 Webview 实例。
import { Window } from '@tauri-apps/api/window'import { Webview } from '@tauri-apps/api/webview'const appWindow = new Window('my-label')
appWindow.once('tauri://created', async function() { const webview = new Webview(appWindow, 'my-label', { url: 'https://github.com/tauri-apps/tauri',
// create a webview with specific logical position and size x: 0, y: 0, width: 800, height: 600, });
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#L193
属性 | 类型 | 描述 | 定义于 |
---|---|---|---|
label | 字符串 | webview 标签。它是 webview 的唯一标识符,可用于以后引用。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L154 |
listeners | Record <string , EventCallback <any >[]> | 本地事件监听器。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L159 |
window | 窗口 | 托管此 webview 的窗口。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L156 |
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#L588
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#L435
emit<T>(event, payload?): Promise<void>
向所有 目标 发出事件。
类型参数 |
---|
T |
参数 | 类型 | 描述 |
---|---|---|
event | 字符串 | 事件名称。必须只包含字母数字字符、- 、/ 、: 和 _ 。 |
载荷 (payload) ? | T | 事件载荷。 |
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#L324
emitTo<T>( target, event,payload?): Promise<void>
向所有与给定目标匹配的 目标 发出事件。
类型参数 |
---|
T |
参数 | 类型 | 描述 |
---|---|---|
目标 | string | EventTarget | 目标窗口/WebView/WebviewWindow 的标签,或原始 EventTarget 对象。 |
event | 字符串 | 事件名称。必须只包含字母数字字符、- 、/ 、: 和 _ 。 |
载荷 (payload) ? | T | 事件载荷。 |
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#L352
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#L522
listen<T>(event, handler): Promise<UnlistenFn>
监听此 webview 上发出的事件。
类型参数 |
---|
T |
参数 | 类型 | 描述 |
---|---|---|
event | 事件名称 | 事件名称。必须只包含字母数字字符、- 、/ 、: 和 _ 。 |
处理程序 | 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#L261
onDragDropEvent(handler): Promise<UnlistenFn>
监听文件拖放事件。当用户将选定的文件悬停在 webview 上、拖放文件或取消操作时,会触发监听器。
参数 | 类型 |
---|---|
处理程序 | 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#L640
once<T>(event, handler): Promise<UnlistenFn>
只监听此 webview 上发出的事件一次。
类型参数 |
---|
T |
参数 | 类型 | 描述 |
---|---|---|
event | 事件名称 | 事件名称。必须只包含字母数字字符、- 、/ 、: 和 _ 。 |
处理程序 | 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#L296
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#L397
reparent(window): Promise<void>
将此 webview 移动到给定的标签。
参数 | 类型 |
---|---|
window | string | 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#L571
setAutoResize(autoResize): Promise<void>
设置当父窗口调整大小时,webview 是否应自动调整大小和位置。
参数 | 类型 |
---|---|
自动调整大小 | 布尔值 (boolean) |
Promise
<void
>
表示操作成功或失败的 Promise。
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().setAutoResize(true);
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L505
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#L606
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#L489
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#L470
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#L452
setZoom(scaleFactor): Promise<void>
设置 webview 缩放级别。
参数 | 类型 |
---|---|
缩放因子 | 数字 |
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#L554
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#L538
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#L414
static getAll(): Promise<Webview[]>
获取所有可用 webview 的 Webview
实例列表。
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L238
static getByLabel(label): Promise<null | Webview>
获取与给定标签关联的 webview 的 Webview。
参数 | 类型 | 描述 |
---|---|---|
标签 | 字符串 | webview 标签。 |
与 webview 通信的 Webview 实例,如果 webview 不存在则为 null。
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#L224
static getCurrent(): Webview
获取当前 webview 的 Webview
实例。
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L231
要创建的 webview 的配置。
2.0.0
属性 | 类型 | 描述 | 定义于 |
---|---|---|---|
acceptFirstMouse? | 布尔值 (boolean) | 在 macOS 上,点击非活动 webview 是否也会穿透到 webview。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L745 |
allowLinkPreview? | 布尔值 (boolean) | 在 macOS 和 iOS 上,长按链接会显示链接预览,此功能默认启用。请参阅 https://docs.rs/objc2-web-kit/latest/objc2_web_kit/struct.WKWebView.html#method.allowsLinkPreview | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L849 |
backgroundColor? | Color | 设置窗口和 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#L821 |
backgroundThrottling? | 后台节流策略 | 更改默认的后台节流行为。默认情况下,浏览器使用暂停策略,当视图被最小化或隐藏后大约 5 分钟,它会节流计时器甚至卸载整个选项卡(视图)以释放资源。这将暂停所有任务,直到文档的可见性状态从隐藏变为可见,即将视图带回前台。## 平台特定 - Linux / Windows / Android:不支持。像挂起的 WebLock 事务这样的变通方法可能足够。- iOS:支持版本 17.0+。- macOS:支持版本 14.0+。请参阅 https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578 自 2.3.0 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L840 |
devtools? | 布尔值 (boolean) | 是否启用 Web 检查器(通常称为浏览器开发工具)。默认启用。此 API 在 **debug** 构建中有效,但在 **release** 构建中需要 `devtools` 功能标志才能启用。平台特定 - macOS:这将在 **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#L808 |
disableInputAccessoryView? | 布尔值 (boolean) | 允许在 iOS 上禁用输入附件视图。附件视图是当文本输入元素获得焦点时出现在键盘上方的视图。它通常显示一个带有“完成”、“下一步”按钮的视图。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L856 |
dragDropEnabled? | 布尔值 (boolean) | Webview 上是否启用拖放功能。默认情况下,它是启用的。在 Windows 上使用 HTML5 拖放前端时需要禁用它。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L741 |
focus? | 布尔值 (boolean) | webview 是否应该获得焦点 自 2.1.0 版本起 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L735 |
height | 数字 | 初始高度。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L723 |
incognito? | 布尔值 (boolean) | webview 是否应该以隐身模式启动。平台特定 - Android: 不支持。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L757 |
javascriptDisabled? | 布尔值 (boolean) | 我们是否应该禁用 webview 上的 JavaScript 代码执行。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L844 |
proxyUrl? | 字符串 | 用于所有网络请求的 WebView 代理 URL。必须是 http:// 或 socks5:// URL。平台特定 - macOS:需要 macos-proxy 功能标志,并且仅针对 macOS 14+ 编译。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L767 |
transparent? | 布尔值 (boolean) | 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#L729 |
url? | 字符串 | 要打开的远程 URL 或本地文件路径。- URL,例如 https://github.com/tauri-apps ,直接在 Tauri webview 中打开。- data: URL,例如 data:text/html,<html>... ,仅在 tauri 依赖项的 webview-data-url Cargo 功能启用时受支持。- 本地文件路径或路由,例如 /path/to/page.html 或 /users ,会附加到应用程序 URL(开发模式下的 devServer URL,或生产环境下的 tauri:/// 和 https://tauri.localhost/ )。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L715 |
useHttpsScheme? | 布尔值 (boolean) | 设置自定义协议是否应在 Windows 和 Android 上使用 https://<scheme>.localhost 而不是默认的 http://<scheme>.localhost 。默认为 false 。#### 注意 使用 https 方案在尝试获取 http 端点时将不允许混合内容,因此将不匹配 macOS 和 Linux 上使用的 <scheme>:// 协议的行为。#### 警告 在版本之间更改此值将更改 IndexedDB、cookie 和本地存储位置,并且您的应用程序将无法访问它们。自 2.1.0 版本起 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L794 |
userAgent? | 字符串 | webview 的用户代理。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L749 |
width | 数字 | 初始宽度。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L721 |
x | 数字 | 初始垂直位置。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L717 |
y | 数字 | 初始水平位置。 | 来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L719 |
zoomHotkeysEnabled? | 布尔值 (boolean) | 是否启用通过快捷键进行页面缩放。平台特定:- 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#L779 |
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#L2079
type DragDropEvent: object | object | object | object;
拖放事件类型。
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L42
function getAllWebviews(): Promise<Webview[]>
获取所有可用 webview 的 Webview
实例列表。
2.0.0
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L69
function getCurrentWebview(): Webview
获取当前 webview 的 Webview
实例。
2.0.0
来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L53
© 2025 Tauri 贡献者。CC-BY / MIT