sxdfilepreviewv2
v1.0.1
Published
Vue2 文件预览组件，支持多格式文件预览、缩放、打印等功能
Maintainers
lipl502Readme
文件预览解决方案
这是一个基于 Vue 2 的文件预览解决方案，支持主流办公文件的在线预览，包括 Word、Excel、PPT 和 PDF 文件。本项目采用 Vue 2 技术栈开发，确保了更好的兼容性和稳定性。
功能特性
- 支持文件类型：
- Word 文档 (.docx)
- Excel 表格 (.xlsx)
- PowerPoint 演示文稿 (.pptx)
- PDF 文档 (.pdf)
- 支持本地文件预览和远程 URL 文件预览
- 支持大文件分页加载
- 完整的跨平台支持：
- 完美适配 PC 端和移动端
- iOS（iPhone/iPad）和 Android 设备上表现优异
- 响应式设计，自适应不同屏幕尺寸
- 针对移动端优化了触控体验和性能
- 优雅的加载状态和错误处理
技术栈
- 核心框架：Vue 2.7.x（使用 Vue 2 的最新稳定版本）
- 路由管理：Vue Router 3.6.x（与 Vue 2 配套的路由版本）
- 文件预览：
- Word：@vue-office/docx
- Excel：@vue-office/excel
- PPT：@vue-office/pptx
- PDF：pdfjs-dist（Mozilla PDF.js）
- 开发工具：
- Vue CLI
- Babel
- ESLint
技术方案说明
PDF 预览方案
本项目选择使用 Mozilla 的 PDF.js（pdfjs-dist）而不是 @vue-office/pdf 的原因：
功能完整性：
- PDF.js 是 Mozilla 维护的成熟方案，功能更加完整
- 支持文档大纲、缩放、搜索等高级功能
- 支持表单填写和注释
性能优势：
- 支持分页按需加载，减少内存占用
- 渲染性能更好，适合大型 PDF 文件
- 支持流式加载，无需等待整个文件下载完成
兼容性：
- 浏览器兼容性更好
- 支持更多 PDF 特性和格式
- 渲染效果更接近原生
社区支持：
- 有庞大的社区支持
- 问题修复和更新及时
- 文档完善，示例丰富
实践经验：
- 在测试中发现，使用 @vue-office/pdf 预览大型 PDF 文件时，在移动端存在严重问题
- 具体表现为：在文件未完全加载完成时，页面会自动多次重新加载
- 这可能是由移动设备内存限制或操作系统的内存管理机制导致
- 而使用 PDF.js 的分页渲染机制可以很好地解决这个问题
渲染实现说明
PDF.js 的渲染流程：
核心渲染过程：
const page = await pdfDoc.getPage(pageNumber) const viewport = page.getViewport({ scale: scale }) const canvas = document.getElementById(`pdf-page-${pageNumber}`) const context = canvas.getContext('2d') canvas.height = viewport.height canvas.width = viewport.width const renderContext = { canvasContext: context, viewport: viewport } await page.render(renderContext).promise技术细节：
- 直接将 PDF 内容渲染到 Canvas，而不是转换成图片再加载
- 每个页面使用独立的 Canvas 元素
- 采用分页渲染机制，提升渲染性能
- 支持缩放、旋转等视图操作
性能优化：
- 实现分页渲染，避免一次性渲染所有页面
- 使用 Canvas 直接渲染，减少内存占用
- 支持流式加载，提升首屏加载速度
移动端适配：
- 针对移动端内存限制进行优化
- 避免了整个文件内容同时加载到内存的问题
- 解决了大型 PDF 在移动端反复重载的问题
旧版 Office 格式支持方案
如果需要支持旧版 Office 格式（.doc、.xls、.ppt），建议采用以下方案：
服务器转换方案：
- 使用 LibreOffice/OpenOffice 搭建文件转换服务
- 将旧版格式转换为新版格式后再预览
- 优点：可控性强，无需第三方服务
- 缺点：需要自行维护服务器
商业转换服务：
- 使用 Microsoft Office 365 API
- 使用金山 WPS 开放平台
- 优点：稳定性好，维护成本低
- 缺点：需要付费，依赖第三方服务
客户端转换：
- 提示用户使用 Office 或 WPS 另存为新版格式
- 优点：实现简单，无需额外服务
- 缺点：用户体验不够友好
快速开始
安装依赖
npm install开发环境运行
npm run serve生产环境构建
npm run build代码检查
npm run lint项目结构
src/
├── components/ # 公共组件
├── views/ # 页面组件
│ ├── Home.vue # 首页（文件选择）
│ ├── FilePreview.vue # 文件预览页
│ └── ExcelPreview.vue # Excel预览页
├── router/ # 路由配置
└── App.vue # 根组件
public/
├── files/ # 本地测试文件
└── pdfjs/ # PDF.js 相关文件使用示例
本地文件预览
将文件放在 public/files 目录下，然后通过首页的预览按钮进行预览。
URL 文件预览
在首页输入文件 URL 后点击预览按钮即可。
示例 URL：
- Word：http://static.shanhuxueyuan.com/test.docx
- Excel：http://static.shanhuxueyuan.com/test.xlsx
- PDF：http://static.shanhuxueyuan.com/test.pdf
- PPT：https://501351981.github.io/vue-office/examples/dist/static/test-files/test.pptx
注意事项
- 文件格式限制：
- 仅支持新版 Office 格式：.docx、.xlsx、.pptx
- 不支持旧版 Office 格式：.doc、.xls、.ppt
- 如需预览旧版格式，请参考上述"旧版 Office 格式支持方案"
- 由于浏览器的跨域限制，某些网站的文件可能无法直接预览
- 建议将较大文件先下载到本地后再进行预览
- 确保文件 URL 可以被公开访问
参考资源
License
MIT
项目开发说明
本项目是一个特殊的实验性项目，完全通过与 Cursor（AI 驱动的智能 IDE）的交互来完成。从项目初始化到最终完成，所有的代码都是通过与 Cursor AI 助手的对话生成的，没有手动编写任何一行代码。这个开发过程展示了 AI 辅助编程的潜力，以及如何利用先进的 AI 工具来加速开发流程。
主要特点：
- 零手写代码：所有代码均由 Cursor AI 生成
- 完整对话驱动：通过自然语言描述需求，AI 理解并实现功能
- 快速迭代：AI 能够根据反馈快速调整和优化代码
- 高质量输出：生成的代码遵循最佳实践，包含完整的错误处理和用户体验考虑
这种开发方式展示了 AI 在软件开发中的应用前景，以及如何利用 AI 工具来提高开发效率。
详细说明组件的安装、使用、Props、示例等，让使用者快速上手。示例：
# vue2-file-viewer
Vue2 文件预览组件，支持 PDF、Office 等多格式文件预览，提供缩放、打印、下载等功能。
## 安装
```bash
npm install vue2-file-viewer js-base64 --save<template>
<FileViewer
:fileList="fileList"
:kkFileViewHost="kkHost"
:leftFileList="true"
/>
</template>
<script>
import FileViewer from 'vue2-file-viewer';
export default {
components: { FileViewer },
data() {
return {
fileList: [
{ name: '文档1.pdf', url: 'https://xxx.pdf' },
{ name: '表格.xlsx', url: 'https://xxx.xlsx' }
],
kkHost: 'http://127.0.0.1:8012'
};
}
};
</script>Props 说明 参数名 类型 默认值 说明 fileList Array [] 文件列表，格式：[{name, url}] kkFileViewHost String 'http://127.0.0.1:8012' kkFileView 服务地址 leftFileList Boolean false 是否显示左侧文件目录
#### 4. `.npmignore`（排除无关文件）
指定不需要发布到 npm 的文件（类似 `.gitignore`），减少包体积： 排除 node_modules node_modules/ 排除开发环境文件 .env.env.*.gitignore.git/.DS_Store 排除测试文件（如果有） tests/tests/ 排除打包配置（如果不需要） webpack.config.js babel.config.js
### **四、发布到 npm**
1. **检查代码**
确保组件代码可正常运行，无语法错误，`package.json` 配置正确（尤其是 `name` 和 `version`）。
2. **首次发布**
在包根目录执行发布命令：
```bash
npm publish若发布成功，终端会显示 + 包名@版本号，且可在 npm 官网 搜索到你的包。 若失败，常见原因： 未登录：重新执行 npm login。 源错误：确保使用 https://registry.npmjs.org/（非淘宝源）。 包名重复：修改 package.json 中的 name 为唯一名称。 版本号重复：每次发布需更新 version（见下方 “版本更新”）。
sxdfilepreviewv2
Vue2 文件预览组件，支持 docx、excel、pptx、pdf 等格式，提供缩放、打印、下载功能。
安装
npm install sxdfilepreviewv2 js-base64 @vue-office/docx @vue-office/excel @vue-office/pptx pdfjs-dist --save
npm install sxdfilepreviewv2 js-base64 --save