# uni pdf

**Repository Path**: TonyQ/uni-pdf

## Basic Information

- **Project Name**: uni pdf
- **Description**: uni app android 加载 pdf
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-26
- **Last Updated**: 2025-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 移动端-H5-小程序在线预览pdf，图片，视频

## 项目概述

本项目是一个基于uni-app开发的多端文件预览解决方案，支持在移动端、H5和小程序环境下预览PDF文档、图片和视频文件。项目使用了ss-preview组件，该组件封装了不同平台下文件预览的实现方式，提供了统一的接口，简化了开发流程。

## 功能特点

- **多种文件格式支持**：支持预览PDF文档、图片（单张/多张）和视频文件
- **多平台兼容**：支持App、H5和微信小程序等多个平台
- **简单易用**：提供统一的组件接口，使用方便
- **灵活扩展**：可通过服务端转换实现对doc、docx、xls、xlsx等其他格式文档的预览
- **完整示例**：包含完整的使用示例和代码参考

## 安装说明

### 方式一：使用HBuilderX导入

1. 在HBuilderX中点击菜单栏的`插件`->`uni-app插件市场`->`找插件`
2. 搜索`ss-preview`，找到`移动端-H5-小程序在线预览pdf，图片，视频`插件
3. 点击`使用HBuilderX导入插件`，选择要导入的项目

### 方式二：下载插件ZIP

1. 从插件市场下载`ss-preview`插件ZIP包
2. 解压后复制到项目的`uni_modules`目录下

> **注意**：uni_modules必须在项目根目录下，如果在src目录下，需要修改路径配置。

## 使用方法

### 基本用法

1. 创建预览页面（如`preview.vue`）：

```vue
<template>
	<view>
		<ss-preview :fileUrl="fileUrl" :fileType="fileType" :imageList="imageList"></ss-preview>
	</view>
</template>

<script>
	export default {
		data() {
			return {
				fileUrl: '',
				fileType:'',
				imageList:[],
			}
		},
		onLoad(option) {
			let options = JSON.parse(decodeURIComponent(option.item))
			this.fileType = options.type;
			if(options.type === '1') return this.imageList = options.src
            this.fileUrl = options.src;
		},
	}
</script>
```

2. 在列表页面（如`index.vue`）中调用预览页面：

```vue
<template>
    <view class="box">
		<view style="margin-bottom:32rpx;">uni-app预览文件</view>
		<view v-for="(item,index) in fileList" :key="index">
			<view style="word-break: break-all;">{{item.src}}</view>
			<button class="previewBtn" @click="toPage(item)">{{item.name}}</button>
		</view>
    </view>
</template>

<script>
export default {
    data() {
        return {
			fileList:[
				{
					type:'1',
					name:'预览图片',
					src:['https://example.com/image1.jpg','https://example.com/image2.jpg']
				},
				{
					type:'2',
					name:'预览文档',
					src:'https://example.com/document.pdf'
				},
				{
					type:'3',
					name:'预览视频',
					src:'https://example.com/video.mp4',
				},
               {
                  type: '4',  // 注意：Base64 PDF使用类型'4'
                  name: '预览文档Base64 pdf',
                  src: 'JVBERi0xLjcKJaGzxdcKMSAw...'  // 这里是Base64编码的PDF数据
               }
			]
        };
    },
    methods: {
        toPage(item){
            uni.navigateTo({
                url: '/pages/preview?item=' + encodeURIComponent(JSON.stringify(item))
            })
        }
    }
}
</script>
```

## 组件参数说明

| 属性      | 是否必填 | 值类型  | 默认值 | 说明                                      |
| --------- | -------- | ------- | ------ | ----------------------------------------- |
| fileUrl   | 否       | String  | 空     | 预览单个文档或视频传递url                 |
| fileType  | 是       | String  | 空     | 类型（1.预览图片，2.预览文件，3.预览视频）|
| imageList | 否       | Array   | 空数组 | 预览单个或多个图片传递数组                |

## 平台兼容性说明

### App端

- 支持预览PDF文档、图片和视频
- 预览视频需在`manifest.json`的App模块配置中勾选VideoPlayer(视频播放)
- PDF文档预览使用内置的PDF阅读器

### H5端

- 完全支持预览PDF文档、图片和视频
- PDF文档预览使用内置的PDF阅读器

### 微信小程序

- 支持预览图片和视频
- PDF文档预览通过微信官方方法`uni.downloadFile`下载成功后，使用`uni.openDocument`打开

## 特别说明

### PDF文件处理

1. **普通PDF文件**：直接通过URL加载
2. **Base64编码的PDF**：组件内部会自动处理，无需额外操作

### 其他格式文档预览

对于doc、docx、xls、xlsx等其他格式文档，可通过服务端转换为PDF文件流实现预览：

```javascript
// 示例：通过服务端接口转换文档格式
let types = fileUrl.substr(fileUrl.lastIndexOf('.'));
if(types !== '.pdf'){
    this.fileUrl = `https://your-convert-api.com?file=${encodeURIComponent(fileUrl)}`
}
```

## 注意事项

1. **uni_modules目录位置**：必须在项目根目录下，如果在src目录下，需要修改路径：
   ```javascript
   // 修改前
   /uni_modules/ss-preview/hybrid/html/pdf-reader/index.html?file=${encodeURIComponent(value)}
   // 修改后
   /src/uni_modules/ss-preview/hybrid/html/pdf-reader/index.html?file=${encodeURIComponent(value)}
   ```

2. **不支持vite打包**

3. **视频组件说明**：预览视频也可以直接使用video标签，但video为原生组件，层级较高，在APP滑动的界面可能会产生兼容性问题

4. **图片预览替代方案**：也可以使用uni-app的方法`uni.previewImage`实现预览

## 常见问题

### 文件加载失败

如果出现类似以下错误：
```
Fetch API cannot load file:///storage/emulated/0/Android/data/io.dcloud.HBuilder/apps/HBuilder/www/uni_modules/ss-preview/hybrid/html/pdf-reader/...
```

可能的原因：
1. 文件路径不正确
2. 文件格式不支持
3. Base64编码的PDF文件格式不正确

解决方案：
- 检查文件URL是否正确
- 确保文件格式受支持
- 对于Base64编码的PDF，确保编码格式正确

### 如果只使用 hybrid 则不能放在uni_modules中，需要移动到static文件夹下，这时候的引入路径则改为 /static/hybrid/html/pdf-reader/index.html?


## 项目结构

```
├── uni_modules/ss-preview/         # 预览组件目录
│   ├── components/                 # 组件目录
│   │   └── ss-preview/            # 预览组件
│   │       └── ss-preview.vue     # 预览组件实现
│   ├── hybrid/                    # 混合开发目录
│   │   └── html/                  # HTML目录
│   │       ├── pdf-reader/        # PDF阅读器
│   │       │   ├── index.html     # PDF阅读器入口
│   │       │   ├── viewer.js      # PDF阅读器实现
│   │       │   └── ...           # 其他PDF阅读器文件
│   │       └── pdf.html          # PDF预览HTML
│   ├── package.json               # 组件配置
│   └── readme.md                  # 组件说明
├── pages/                         # 页面目录
│   ├── index.vue                  # 首页（文件列表）
│   └── preview.vue                # 预览页面
├── App.vue                        # 应用入口组件
├── main.js                        # 应用入口JS
├── manifest.json                  # 应用配置
└── pages.json                     # 页面配置
```