跳到内容
Tauri

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 通信的 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
listenersRecord<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<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#L261

onDragDropEvent(handler): Promise<UnlistenFn>

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

参数类型
处理程序EventCallback<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#L640

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

只监听此 webview 上发出的事件一次。

类型参数
T
参数类型描述
event事件名称事件名称。必须只包含字母数字字符、-/:_
处理程序EventCallback<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#L296

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#L397

reparent(window): Promise<void>

将此 webview 移动到给定的标签。

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

Promise<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#L414

static getAll(): Promise<Webview[]>

获取所有可用 webview 的 Webview 实例列表。

Promise<Webview[]>

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

static getByLabel(label): Promise<null | Webview>

获取与给定标签关联的 webview 的 Webview。

参数类型描述
标签字符串webview 标签。

Promise<null | 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 实例。

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

Promise<Webview[]>

2.0.0

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


function getCurrentWebview(): Webview

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