Tauri 桌面应用嵌入外部网页：iframe 到 Webview 迁移实战

Webview API 的优势

相比 iframe，Tauri Webview API 具有以下明显优势：

1. 无跨域限制：使用系统级 webview 组件，不受浏览器同源策略限制。
2. 完整交互支持：支持所有正常的网页交互（点击、输入、导航等）。
3. 更好的性能：原生组件，性能优于 iframe。
4. 灵活的窗口管理：可以精确控制位置、大小、焦点等。

实现迁移

替换容器元素

首先，将 iframe 替换为一个容器 div，用于挂载 Webview：

<template>
  <main data-tauri-drag-region>
    <ActionBar 
      :shrink="false" 
      :max-w="true" 
      :icon-color="'black'" 
      :top-win-label="currentWindow.label" 
      :current-label="currentWindow.label"
    />
    <div data-tauri-drag-region>
      <div ref="webviewContainer"></div>
    </div>
  </main>
</template>

编写初始化逻辑

接下来我们来处理核心的 Webview 创建逻辑。这里需要引入必要的 API，并处理好生命周期。

import { ref, onMounted, onUnmounted, nextTick } from 'vue'
import { Webview } from '@tauri-apps/api/webview'
import { getCurrentWebviewWindow } from '@tauri-apps/api/webviewWindow'
import { openUrl } from '@tauri-apps/plugin-opener'

const webviewContainer = ref<HTMLElement | null>(null)
const externalWebview = ref<Webview | null>(null)
const webviewLabel = 'baidu-webview'
const currentWindow = getCurrentWebviewWindow()
let containerResizeObserver: ResizeObserver | null = null
let windowResizeListener: (() => void) | null = null

const updateWebviewBounds = async () => {
  if (!webviewContainer.value || !externalWebview.value) return
  try {
    const rect = webviewContainer.value.getBoundingClientRect()
    await externalWebview.value.setPosition(rect.left, rect.top)
    await externalWebview.value.setSize(rect.width, rect.height)
  } catch (error) {
    console.error('更新 webview 边界失败:', error)
  }
}

const initWebview = async () => {
  await nextTick()
  if (!webviewContainer.value) {
    console.error('webviewContainer 未找到')
    return
  }

  const windowInstance = getCurrentWebviewWindow()
  try {
    const existing = await Webview.getByLabel(webviewLabel)
    if (existing) {
      await existing.close()
    }
  } catch (error) {
    console.log('没有找到已存在的 webview')
  }

  try {
    const rect = webviewContainer.value.getBoundingClientRect()
    const newWebview = new Webview(windowInstance, webviewLabel, {
      url: 'https://www.baidu.com',
      x: rect.left,
      y: rect.top,
      width: rect.width,
      height: rect.height,
      focus: true,
      dragDropEnabled: true
    })
    externalWebview.value = newWebview

    containerResizeObserver = new ResizeObserver(() => {
      updateWebviewBounds()
    })
    containerResizeObserver.observe(webviewContainer.value)

    windowResizeListener = () => {
      updateWebviewBounds()
    }
    window.addEventListener('resize', windowResizeListener, { passive: true })

    newWebview.once('tauri://created', async () => {
      console.log('Webview 创建成功')
      await updateWebviewBounds()
    })

    newWebview.once('tauri://error', (error) => {
      console.error('Webview 创建失败:', error)
      externalWebview.value = null
    })
  } catch (error) {
    console.error('创建 webview 失败:', error)
    console.log('尝试在系统浏览器中打开百度')
    try {
      await openUrl('https://www.baidu.com')
    } catch (openError) {
      console.error('在浏览器中打开失败:', openError)
    }
  }
}

onMounted(async () => {
  await initWebview()
})

onUnmounted(async () => {
  if (containerResizeObserver) {
    containerResizeObserver.disconnect()
  }
  if (windowResizeListener) {
    window.removeEventListener('resize', windowResizeListener)
  }
  if (externalWebview.value) {
    try {
      await externalWebview.value.close()
    } catch (error) {
      console.error('关闭 webview 失败:', error)
    }
  }
})

修复导入错误

在实现过程中，你可能会遇到一个典型的错误：

Uncaught ReferenceError: WebviewWindow is not defined

原因：模板中使用了 WebviewWindow.getCurrent()，但在 script 中只导入了 getCurrentWebviewWindow 函数，没有导入 WebviewWindow 类。

解决方法：

1. 在 script 中添加 const currentWindow = getCurrentWebviewWindow() 来获取当前窗口实例。
2. 在模板中将 WebviewWindow.getCurrent().label 替换为 currentWindow.label。

修改后的代码片段如下：

const currentWindow = getCurrentWebviewWindow()

<ActionBar :top-win-label="currentWindow.label" :current-label="currentWindow.label"/>

关键技术点

1. Webview 生命周期管理

创建、更新位置和大小、关闭都需要调用对应的方法：

// 创建
const newWebview = new Webview(windowInstance, label, options)
// 更新位置和大小
await webview.setPosition(x, y)
await webview.setSize(width, height)
// 关闭
await webview.close()

2. 响应式布局处理

使用 ResizeObserver 监听容器尺寸变化，自动调整 Webview 大小，避免页面缩放后出现白边或遮挡。

containerResizeObserver = new ResizeObserver(() => {
  updateWebviewBounds()
})
containerResizeObserver.observe(webviewContainer.value)

3. 窗口大小变化处理

监听窗口 resize 事件，确保 Webview 始终正确显示，特别是当主窗口被拖动或调整大小时。

windowResizeListener = () => {
  updateWebviewBounds()
}
window.addEventListener('resize', windowResizeListener, { passive: true })

4. 清理资源

在组件卸载时务必清理所有监听器和 Webview 实例，防止内存泄漏。

onUnmounted(async () => {
  if (containerResizeObserver) {
    containerResizeObserver.disconnect()
  }
  if (windowResizeListener) {
    window.removeEventListener('resize', windowResizeListener)
  }
  if (externalWebview.value) {
    await externalWebview.value.close()
  }
})

5. 错误处理和降级方案

当 Webview 创建失败时，提供降级方案，比如在系统浏览器中打开，提升用户体验。

try {
  const newWebview = new Webview(windowInstance, webviewLabel, options)
} catch (error) {
  console.error('创建 webview 失败:', error)
  try {
    await openUrl('https://www.baidu.com')
  } catch (openError) {
    console.error('在浏览器中打开失败:', openError)
  }
}

iframe vs Webview 对比

最佳实践

何时使用 iframe

• 嵌入同源内容
• 简单的静态内容展示
• 不需要复杂交互的场景

何时使用 Tauri Webview

• 嵌入第三方网站（如百度、Google）
• 需要完整网页交互
• 需要精确控制窗口行为
• 需要更好的性能

注意事项

1. 获取正确的窗口实例：使用 getCurrentWebviewWindow() 而不是 WebviewWindow.getCurrent()。
2. 清理资源：务必在组件卸载时清理 Webview 和监听器。
3. 响应式布局：使用 ResizeObserver 处理容器尺寸变化。
4. 错误处理：提供降级方案，提升用户体验。
5. 唯一标识：为每个 Webview 设置唯一的 label，避免冲突。

总结

通过这次从 iframe 到 Tauri Webview 的迁移实践，我们成功解决了百度网页点击无响应的问题。关键经验包括：

1. 理解技术限制：iframe 在嵌入第三方网站时存在根本性限制。
2. 选择正确方案：Tauri Webview API 是嵌入外部网站的最佳选择。
3. 注意 API 使用：正确使用 getCurrentWebviewWindow() 而不是 WebviewWindow。
4. 完善生命周期管理：妥善处理创建、更新、销毁等各个环节。
5. 提供降级方案：在 Webview 创建失败时提供备选方案。

这次实践不仅解决了具体问题，也加深了对 Tauri 框架的理解，为后续开发积累了宝贵经验。

参考资料

• Tauri 2.0 官方文档
• Tauri Webview API
• Tauri WebviewWindow API
• Opener 插件文档