跳到內容
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。

參數
參數類型描述
windowWindow要將此 webview 新增至其中的視窗。
labelstring唯一的 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#L165

屬性

屬性類型描述定義於
labelstringwebview 標籤。它是 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
windowWindow託管此 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>

向所有 目標發射事件。

參數
參數類型描述
eventstring事件名稱。必須僅包含字母數字字符、-、/、: 和 _。
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 物件。
eventstring事件名稱。必須僅包含字母數字字符、-、/、: 和 _。
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
參數
參數類型描述
eventEventName事件名稱。必須僅包含字母數字字符、-、/、: 和 _。
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
參數
參數類型描述
eventEventName事件名稱。必須僅包含字母數字字符、-、/、: 和 _。
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。

參數
參數類型描述
labelstringwebview 標籤。
回傳

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?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#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 在 debug 組建中運作，但需要 devtools 功能標誌才能在 release 組建中啟用它。#### 平台特定 - 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#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?boolean是否應以無痕模式啟動 webview。#### 平台特定 - Android： 不支援。來源：https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L710
proxyUrl?stringWebView 的所有網路請求的代理 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?string要開啟的遠端 URL 或本機檔案路徑。 - 諸如 https://github.com/tauri-apps 之類的 URL 直接在 Tauri webview 上開啟。 - 諸如 data:text/html,<html>... 之類的 data: 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?stringwebview 的使用者代理程式。來源：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，使用 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

類型別名

Color

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

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