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 {
    // 检查是否已存在同名 Webview，避免冲突
    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)

    // 监听窗口 resize 事件
    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 函数。解决方法很简单：在 script 中添加 const currentWindow = getCurrentWebviewWindow()，并将模板中的引用替换为 currentWindow.label。

关键技术点总结

1. Webview 生命周期管理

创建、更新位置和大小、关闭都需要显式调用 API。确保在组件卸载前正确关闭实例，防止内存泄漏。

2. 响应式布局处理

使用 ResizeObserver 监听容器尺寸变化，自动调整 Webview 大小，保证在不同分辨率下显示正常。

3. 资源清理

务必在 onUnmounted 中清理所有监听器和 Webview 实例。这是很多开发者容易忽略的地方，会导致应用卡顿或报错。

4. 错误处理和降级方案

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

iframe vs Webview 对比

最佳实践建议

• 何时使用 iframe：仅适用于嵌入同源内容或简单的静态展示，不需要复杂交互的场景。
• 何时使用 Tauri Webview：嵌入第三方网站（如百度、Google）、需要完整网页交互、需要精确控制窗口行为或追求更好性能时。
• 注意事项：
  • 获取正确的窗口实例：使用 getCurrentWebviewWindow() 而不是 WebviewWindow.getCurrent()。
  • 唯一标识：为每个 Webview 设置唯一的 label，避免冲突。
  • 清理资源：务必在组件卸载时清理 Webview 和监听器。

总结

通过这次从 iframe 到 Tauri Webview 的迁移实践，我们成功解决了百度网页点击无响应的问题。核心经验在于理解技术限制，选择正确的方案，并完善生命周期管理。这次实践不仅解决了具体问题，也加深了对 Tauri 框架的理解，为后续开发积累了宝贵经验。

参考资料

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