跳到内容
Tauri
指南 参考 博客 发布

webview

提供 API 来创建 webview，与其他 webview 通信以及操作当前的 webview。

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 添加到的窗口。
标签字符串唯一的 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')
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#L165

属性

属性类型描述定义于
label字符串webview 标签。它是 webview 的唯一标识符，可以用来稍后引用它。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L136
listenersRecord<string, EventCallback<any>[]>本地事件监听器。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L141
window窗口托管此 webview 的窗口。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L138

方法

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

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

emit()
emit(event, payload?): Promise<void>

向所有 目标 发出事件。

参数
参数类型描述
event字符串事件名称。必须仅包含字母数字字符、-, /, : 和 _。
payload?unknown事件有效负载。
返回

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

emitTo()
emitTo(
   target,
   event,
payload?): Promise<void>

向与给定目标匹配的所有 目标 发出事件。

参数
参数类型描述
targetstring | EventTarget目标窗口/Webview/WebviewWindow 的标签或原始 EventTarget 对象。
event字符串事件名称。必须仅包含字母数字字符、-, /, : 和 _。
payload?unknown事件有效负载。
返回

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

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

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

监听此 webview 上发出的事件。

类型参数
类型参数
T
参数
参数类型描述
event事件名称事件名称。必须仅包含字母数字字符、-, /, : 和 _。
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#L231

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

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

类型参数
类型参数
T
参数
参数类型描述
event事件名称事件名称。必须仅包含字母数字字符、-, /, : 和 _。
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#L266

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

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

reparent()
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#L524

setBackgroundColor()
setBackgroundColor(color): Promise<void>

指定 webview 背景颜色。

平台特定

  • macOS / iOS: 未实现。
  • Windows:
    • 在 Windows 7 上，不支持透明度，alpha 值将被忽略。
    • 在高于 Windows 7 的版本中：不支持半透明颜色，因此任何 alpha 值（0 除外）都将被替换为 255
参数
参数类型
colornull | Color
返回

Promise<void>

指示操作成功或失败的 Promise。

自

2.1.0

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

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

setPosition()
setPosition(position): Promise<void>

设置 webview 位置。

参数
参数类型描述
positionLogicalPosition | 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#L440

setSize()
setSize(size): Promise<void>

调整 webview 大小。

参数
参数类型描述
sizeLogicalSize | 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#L422

setZoom()
setZoom(scaleFactor): Promise<void>

设置 webview 缩放级别。

参数
参数类型
scaleFactornumber
返回

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

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

size()
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#L384

getAll()
static getAll(): Promise<Webview[]>

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

返回

Promise<Webview[]>

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

getByLabel()
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#L194

getCurrent()
static getCurrent(): Webview

获取当前 webview 的 Webview 实例。

返回

Webview

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

接口

WebviewOptions

要创建的 webview 的配置。

自

2.0.0

属性

属性类型描述定义于
acceptFirstMouse?boolean是否在 macOS 上单击非活动 webview 也会点击到 webview。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L698
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#L774
backgroundThrottling?BackgroundThrottlingPolicy更改默认的后台节流行为。默认情况下，浏览器使用挂起策略，该策略将在视图最小化或隐藏大约 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#L793
devtools?boolean是否启用 Web 检查器（通常称为浏览器开发工具）。默认情况下启用。此 API 在 调试 版本中有效，但在 发布 版本中需要 devtools 功能标志才能启用它。 #### 平台特定 - macOS: 这将在 macOS 上调用私有函数。 - Android: 在 Chrome 中打开 chrome://inspect/#devices 以获取开发工具窗口。Android 不支持 Wry 的 WebView 开发工具 API。 - iOS: 打开 Safari > 开发 > [您的设备名称] > [您的 WebView] 以获取开发工具窗口。 自 2.1.0来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L761
dragDropEnabled?boolean是否在 webview 上启用拖放。默认情况下启用。禁用它是为了在 Windows 上在前端使用 HTML5 拖放所必需的。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L694
focus?booleanwebview 是否应该具有焦点 自 2.1.0来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L688
heightnumber初始高度。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L676
incognito?booleanwebview 是否应以隐身模式启动。 #### 平台特定 - Android: 不支持。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L710
proxyUrl?字符串WebView 的代理 URL，用于所有网络请求。必须是 http:// 或 socks5:// URL。 #### 平台特定 - macOS: 需要 macos-proxy 功能标志，并且仅针对 macOS 14+ 编译。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L720
transparent?booleanwebview 是否透明。请注意，在 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#L682
url?字符串要打开的远程 URL 或本地文件路径。 - 诸如 https://github.com/tauri-apps 之类的 URL 直接在 Tauri webview 上打开。 - data: 诸如 data:text/html,<html>... 之类的 URL 仅在使用 tauri 依赖项的 webview-data-url Cargo 功能时才受支持。 - 诸如 /path/to/page.html 或 /users 之类的本地文件路径或路由将附加到应用程序 URL（开发中的 devServer URL，或生产中的 tauri://localhost/ 和 https://tauri.localhost/）。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L668
useHttpsScheme?boolean设置自定义协议是否应在 Windows 和 Android 上使用 https://<scheme>.localhost 而不是默认的 http://<scheme>.localhost。默认为 false。 #### 注意 使用 https 方案将不允许在尝试获取 http 端点时混合内容，因此将与 macOS 和 Linux 上使用的 <scheme>://localhost 协议的行为不匹配。 #### 警告 在版本之间更改此值将更改 IndexedDB、cookie 和本地存储位置，并且您的应用将无法访问它们。 自 2.1.0来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L747
userAgent?字符串webview 的用户代理。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L702
widthnumber初始宽度。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L674
xnumber初始垂直位置。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L670
ynumber初始水平位置。来源: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L672
zoomHotkeysEnabled?boolean是否启用通过热键进行页面缩放 #### 平台特定: - Windows: 控制 WebView2 的 IsZoomControlEnabled 设置。 - MacOS / Linux: 注入一个 polyfill，该 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#L732

类型别名

颜色

type Color: [number, number, number] | [number, number, number, number] | object | string;

RGBA 颜色。每个值的最小值和最大值为 255。

它可以是字符串 #ffffff、包含 3 或 4 个元素的数组或对象。

自

2.0.0

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

DragDropEvent

type DragDropEvent: object | object | object | object;

拖放事件类型。

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

函数

getAllWebviews()

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

getCurrentWebview()

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