webview
此内容尚不支持你的语言。
Provides APIs to create webviews, communicate with other webviews and manipulate the current webview.
Webview events
Events can be listened to using Webview.listen:
import { getCurrentWebview } from "@tauri-apps/api/webview";getCurrentWebview().listen("my-webview-event", ({ event, payload }) => { });
Classes
Webview
Create new webview or get a handle to an existing one.
Webviews are identified by a label a unique identifier that can be used to reference it later.
It may only contain alphanumeric characters a-zA-Z
plus the following special characters -
, /
, :
and _
.
Example
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();
Since
2.0.0
Extended by
Constructors
new Webview()
new Webview( window, label, options): Webview
Creates a new Webview.
Parameters
Parameter | Type | Description |
---|---|---|
window | Window | the window to add this webview to. |
label | string | The unique webview label. Must be alphanumeric: a-zA-Z-/:_ . |
options | WebviewOptions | - |
Returns
The Webview instance to communicate with the webview.
Example
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});
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L159
Properties
Property | Type | Description | Defined in |
---|---|---|---|
label | string | The webview label. It is a unique identifier for the webview, can be used to reference it later. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L130 |
listeners | Record <string , EventCallback <any >[]> | Local event listeners. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L135 |
window | Window | The window hosting this webview. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L132 |
Methods
close()
close(): Promise<void>
Closes the webview.
Returns
Promise
<void
>
A promise indicating the success or failure of the operation.
Example
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().close();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L399
emit()
emit(event, payload?): Promise<void>
Emits an event to all targets.
Parameters
Parameter | Type | Description |
---|---|---|
event | string | Event name. Must include only alphanumeric characters, - , / , : and _ . |
payload ? | unknown | Event payload. |
Returns
Promise
<void
>
Example
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().emit('webview-loaded', { loggedIn: true, token: 'authToken' });
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L288
emitTo()
emitTo( target, event,payload?): Promise<void>
Emits an event to all targets matching the given target.
Parameters
Parameter | Type | Description |
---|---|---|
target | string | EventTarget | Label of the target Window/Webview/WebviewWindow or raw EventTarget object. |
event | string | Event name. Must include only alphanumeric characters, - , / , : and _ . |
payload ? | unknown | Event payload. |
Returns
Promise
<void
>
Example
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().emitTo('main', 'webview-loaded', { loggedIn: true, token: 'authToken' });
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L316
listen()
listen<T>(event, handler): Promise<UnlistenFn>
Listen to an emitted event on this webview.
Type Parameters
Type Parameter |
---|
T |
Parameters
Parameter | Type | Description |
---|---|---|
event | EventName | Event name. Must include only alphanumeric characters, - , / , : and _ . |
handler | EventCallback <T > | Event handler. |
Returns
A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.
Example
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();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L225
onDragDropEvent()
onDragDropEvent(handler): Promise<UnlistenFn>
Listen to a file drop event. The listener is triggered when the user hovers the selected files on the webview, drops the files or cancels the operation.
Parameters
Parameter | Type |
---|---|
handler | EventCallback <DragDropEvent > |
Returns
A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.
Example
import { getCurrentWebview } from "@tauri-apps/api/webview";const unlisten = await getCurrentWebview().onDragDropEvent((event) => { if (event.payload.type === 'hover') { console.log('User hovering', event.payload.paths); } 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();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L547
once()
once<T>(event, handler): Promise<UnlistenFn>
Listen to an emitted event on this webview only once.
Type Parameters
Type Parameter |
---|
T |
Parameters
Parameter | Type | Description |
---|---|---|
event | EventName | Event name. Must include only alphanumeric characters, - , / , : and _ . |
handler | EventCallback <T > | Event handler. |
Returns
A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.
Example
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();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L260
position()
position(): Promise<PhysicalPosition>
The position of the top-left hand corner of the webview’s client area relative to the top-left hand corner of the desktop.
Returns
The webview’s position.
Example
import { getCurrentWebview } from '@tauri-apps/api/webview';const position = await getCurrentWebview().position();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L361
reparent()
reparent(window): Promise<void>
Moves this webview to the given label.
Parameters
Parameter | Type |
---|---|
window | string | Window | WebviewWindow |
Returns
Promise
<void
>
A promise indicating the success or failure of the operation.
Example
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().reparent('other-window');
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L513
setFocus()
setFocus(): Promise<void>
Bring the webview to front and focus.
Returns
Promise
<void
>
A promise indicating the success or failure of the operation.
Example
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().setFocus();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L480
setPosition()
setPosition(position): Promise<void>
Sets the webview position.
Parameters
Parameter | Type | Description |
---|---|---|
position | LogicalPosition | PhysicalPosition | The new position, in logical or physical pixels. |
Returns
Promise
<void
>
A promise indicating the success or failure of the operation.
Example
import { getCurrent, LogicalPosition } from '@tauri-apps/api/webview';await getCurrentWebview().setPosition(new LogicalPosition(600, 500));
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L446
setSize()
setSize(size): Promise<void>
Resizes the webview.
Parameters
Parameter | Type | Description |
---|---|---|
size | LogicalSize | PhysicalSize | The logical or physical size. |
Returns
Promise
<void
>
A promise indicating the success or failure of the operation.
Example
import { getCurrent, LogicalSize } from '@tauri-apps/api/webview';await getCurrentWebview().setSize(new LogicalSize(600, 500));
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L416
setZoom()
setZoom(scaleFactor): Promise<void>
Set webview zoom level.
Parameters
Parameter | Type |
---|---|
scaleFactor | number |
Returns
Promise
<void
>
A promise indicating the success or failure of the operation.
Example
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().setZoom(1.5);
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L496
size()
size(): Promise<PhysicalSize>
The physical size of the webview’s client area. The client area is the content of the webview, excluding the title bar and borders.
Returns
The webview’s size.
Example
import { getCurrentWebview } from '@tauri-apps/api/webview';const size = await getCurrentWebview().size();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L378
getAll()
static getAll(): Promise<Webview[]>
Gets a list of instances of Webview
for all available webviews.
Returns
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L202
getByLabel()
static getByLabel(label): Promise<null | Webview>
Gets the Webview for the webview associated with the given label.
Parameters
Parameter | Type | Description |
---|---|---|
label | string | The webview label. |
Returns
The Webview instance to communicate with the webview or null if the webview doesn’t exist.
Example
import { Webview } from '@tauri-apps/api/webview';const mainWebview = Webview.getByLabel('main');
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L188
getCurrent()
static getCurrent(): Webview
Get an instance of Webview
for the current webview.
Returns
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L195
Interfaces
WebviewOptions
Configuration for the webview to create.
Since
2.0.0
Properties
Property | Type | Description | Defined in |
---|---|---|---|
acceptFirstMouse? | boolean | Whether clicking an inactive webview also clicks through to the webview on macOS. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L650 |
dragDropEnabled? | boolean | Whether the drag and drop is enabled or not on the webview. By default it is enabled. Disabling it is required to use HTML5 drag and drop on the frontend on Windows. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L646 |
height | number | The initial height. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L634 |
incognito? | boolean | Whether or not the webview should be launched in incognito mode. #### Platform-specific - Android: Unsupported. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L662 |
proxyUrl? | string | The proxy URL for the WebView for all network requests. Must be either a http:// or a socks5:// URL. #### Platform-specific - macOS: Requires the macos-proxy feature flag and only compiles for macOS 14+. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L672 |
transparent? | boolean | Whether the webview is transparent or not. Note that on macOS this requires the macos-private-api feature flag, enabled under tauri.conf.json > app > macOSPrivateApi . WARNING: Using private APIs on macOS prevents your application from being accepted to the App Store . | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L640 |
url? | string | Remote URL or local file path to open. - URL such as https://github.com/tauri-apps is opened directly on a Tauri webview. - data: URL such as data:text/html,<html>... is only supported with the webview-data-url Cargo feature for the tauri dependency. - local file path or route such as /path/to/page.html or /users is appended to the application URL (the devServer URL on development, or tauri://localhost/ and https://tauri.localhost/ on production). | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L626 |
userAgent? | string | The user agent for the webview. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L654 |
width | number | The initial width. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L632 |
x | number | The initial vertical position. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L628 |
y | number | The initial horizontal position. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L630 |
zoomHotkeysEnabled? | boolean | Whether page zooming by hotkeys is enabled ## Platform-specific: - Windows: Controls WebView2’s IsZoomControlEnabled setting. - MacOS / Linux: Injects a polyfill that zooms in and out with ctrl/command + -/= , 20% in each step, ranging from 20% to 1000%. Requires webview:allow-set-webview-zoom permission - Android / iOS: Unsupported. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L684 |
Type Aliases
DragDropEvent
type DragDropEvent: object | object | object | object;
The drag and drop event types.
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L36
Functions
getAllWebviews()
function getAllWebviews(): Promise<Webview[]>
Gets a list of instances of Webview
for all available webviews.
Returns
Since
2.0.0
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L63
getCurrentWebview()
function getCurrentWebview(): Webview
Get an instance of Webview
for the current webview.
Returns
Since
2.0.0
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L47
© 2024 Tauri Contributors. CC-BY / MIT