DocumentPreview 组件使用文档

📖 概述

DocumentPreview 是一个统一的文档预览组件，支持 PDF、Word、Excel、PPT 等多种格式。

核心特性

✅ 多环境支持：H5 + 微信小程序 ✅ 智能预览：根据文件大小自动选择最佳预览方式 ✅ 全格式支持：PDF、Word、Excel、PPT ✅ 优雅降级：大文件自动使用在线预览

---

🚀 快速开始

1. 基本使用

<template>
  <view class="page">
    <DocumentPreview
      :src="documentUrl"
      :fileType="fileType"
      :fileName="fileName"
      @rendered="handleRendered"
      @error="handleError"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue'
import DocumentPreview from '@/components/DocumentPreview/index.vue'

const documentUrl = ref('https://example.com/document.pdf')
const fileType = ref('pdf') // pdf, doc, docx, xls, xlsx, ppt, pptx
const fileName = ref('重要文档.pdf')

const handleRendered = () => {
  console.log('文档渲染完成')
}

const handleError = (err) => {
  console.error('文档渲染失败:', err)
}
</script>

---

📋 Props

属性	类型	默认值	必填	说明
src	String	-	✅	文档 URL（必须 HTTPS）
fileType	String	''	❌	文档类型（不填则自动检测）
fileName	String	''	❌	文件名（用于显示）
show	Boolean	false	❌	是否显示（H5 PDF 预览用）

fileType 支持的值

• 'pdf' - PDF 文档
• 'doc' / 'docx' - Word 文档
• 'xls' / 'xlsx' - Excel 表格
• 'ppt' / 'pptx' - PowerPoint 演示文稿

---

🎯 Events

事件名	参数	说明
rendered	-	文档渲染完成（H5）
error	Error	文档渲染失败
update:show	Boolean	更新显示状态（H5 PDF）

---

🔍 预览策略

小程序环境

文件大小	预览方式	体验
< 10MB	微信原生 API (wx.openDocument)	⭐⭐⭐ 跳转新页面
≥ 10MB	web-view + 腾讯文档预览	⭐⭐⭐⭐⭐ 在线预览

H5 环境

• PDF：使用 PdfPreview 组件（内嵌预览）
• Office 文档：使用 OfficeViewer 组件（内嵌预览）

---

💡 使用场景

场景 1：预览小文件 PDF

<DocumentPreview
  src="https://example.com/small.pdf"
  fileType="pdf"
  fileName="产品手册.pdf"
/>

小程序：使用微信原生 API（快速）✨ H5：内嵌预览（优雅）✨

---

场景 2：预览大文件 Word

<DocumentPreview
  src="https://example.com/large-document.docx"
  fileType="docx"
  fileName="大型技术文档.docx"
/>

小程序：自动跳转到腾讯文档在线预览（支持大文件）🚀 H5：内嵌预览

---

场景 3：自动检测文件类型

<DocumentPreview
  src="https://example.com/document.xlsx"
  fileName="销售数据表"
/>

不指定 fileType，组件会自动从 URL 中提取文件类型。

---

⚙️ 高级配置

域名白名单配置

小程序环境必须配置业务域名白名单：

1. 登录微信公众平台
2. 进入「开发」→「开发管理」→「开发设置」
3. 找到「业务域名」
4. 添加以下域名：
   • view.officeapps.live.com（腾讯文档预览）
   • 您自己的文档服务器域名（如 cdn.example.com）

HTTPS 要求

文档 URL 必须使用 HTTPS 协议：

// ✅ 正确
const url = 'https://cdn.example.com/document.pdf'

// ❌ 错误（HTTP 不支持）
const url = 'http://cdn.example.com/document.pdf'

---

🐛 故障排查

问题 1：小程序提示"无法打开文档"

原因：域名未配置白名单

解决：

1. 在微信公众平台配置业务域名
2. 确保文档 URL 使用 HTTPS
3. 清除小程序缓存重新打开

---

问题 2：大文件预览失败

原因：文件超过 10MB，但未正确跳转到 web-view

解决：

1. 检查 pages/document-preview/index 是否在 app.config.js 中注册
2. 检查 web-view 域名是否在白名单中
3. 查看控制台错误日志

---

问题 3：文件类型检测失败

原因：URL 中没有文件扩展名

解决：手动指定 fileType 属性

<DocumentPreview
  src="https://api.example.com/download?id=123"
  fileType="pdf"
/>

---

📦 依赖

小程序环境

• Taro 4.x（内置）
• web-view 组件（内置）
• 无需额外依赖

H5 环境

• 使用 iframe 预览（PDF 直开、Office 走腾讯文档预览）
• 无需额外依赖

---

🎨 样式自定义

组件使用了 Scoped 样式，如需自定义，可以使用深度选择器：

<style lang="less" scoped>
// 自定义加载容器
:deep(.loading-container) {
  background: #f0f0f0;
}

// 自定义错误提示
:deep(.error-container) {
  background: #fff0f0;
}
</style>

---

📝 更新日志

v1.0.0 (2025-01-30)

✨ 新功能：

• 支持多种文档格式预览
• 智能选择预览方式
• H5 + 小程序环境适配

🐛 Bug 修复：

• 修复 PdfPreview 组件 watch 未导入问题

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

📄 许可

MIT