Tauri 嵌入百度网页：从 iframe 迁移到 Webview 的实战经验

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)
    }
  }
})

修复 WebviewWindow 导入错误

在实现过程中遇到了一个常见错误：Uncaught ReferenceError: WebviewWindow is not defined。

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

解决方法：

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

关键技术点

1. Webview 生命周期管理

创建、更新位置和大小、关闭都需要显式调用 API：

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

2. 响应式布局处理

使用 ResizeObserver 监听容器尺寸变化，自动调整 Webview 大小，避免页面缩放导致错位。

3. 窗口大小变化处理

监听窗口 resize 事件，确保 Webview 始终正确显示，防止被遮挡或溢出。

4. 清理资源

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

5. 错误处理和降级方案

当 Webview 创建失败时，降级到在系统浏览器中打开，保证功能可用性。

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 插件文档