# jPreview

**Repository Path**: raingad/j-preview

## Basic Information

- **Project Name**: jPreview
- **Description**: 一款纯JQ实现的预览插件，支持office文档，图片，音乐，视频，pdf等常用的文件！纯js技术实现在线文件预览。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://view.raingad.com
- **GVP Project**: No

## Statistics

- **Stars**: 103
- **Forks**: 41
- **Created**: 2023-05-08
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: jquery-plugins

**Tags**: 文件预览, 在线文件预览, pdf预览, 文档预览

## README

# jPreview

**特别注意：2.0 版本在部分插件中使用了 CDN 资源。如果您需要在内网环境使用，请使用 1.0 版本。同时，doc 和 ppt 文件预览使用了微软在线预览服务。**

#### 介绍
jPreview 是一款基于 jQuery 实现的纯前端文件预览插件。它致力于提供统一的文件预览体验，支持 Office 文档、图片、音乐、视频、PDF 等多种常用文件格式。对于部分纯前端难以解析的文档，插件采用了 Office Online 在线预览方案。

**主要特性：**
*   **多格式支持**：支持 doc, docx, ppt, pptx, wps, xls, xlsx, pdf, mp4, mp3, jpg, png 等。
*   **纯 JS 实现**：大部分格式（如 Excel, PDF, 多媒体, 图片）均为纯 JavaScript 本地解析渲染。
*   **易于集成**：依赖 jQuery，配置简单，开箱即用。

#### 体验地址
在线体验：[https://view.raingad.com/](https://view.raingad.com/)

测试链接格式：
```
https://view.raingad.com/preview.html?src=你的文件地址
```

#### 软件架构

项目的目录结构如下，核心资源位于 `static` 目录下：

```
jpreview/
    ├─source         # 预览资源示例库
    ├─static         # 静态资源库（核心依赖）
    │  ├─common      # 公共 CSS/JS (包含 jPreview.js)
    │  ├─docxjs      # Word 预览库
    │  ├─embedpdf    # PDF 预览库
    │  ├─luckysheet  # Excel 预览库
    │  ├─pptxjs      # PPT 预览库
    │  └─viewer      # 图片预览库
    ├─index.html     # Demo 首页
    └─preview.html   # 预览实现页面
```

#### 使用说明

要将 jPreview 集成到您的项目中，请按照以下步骤操作：

##### 1. 引入必要的 CSS 和 JS 文件

在您的 HTML 文件中引入 jQuery 和 jPreview 的核心样式及脚本。

**CSS 引入：**
```html
<link rel="stylesheet" href="static/common/css/main.css">
<link rel="stylesheet" href="static/common/css/audio.css">
<link rel="stylesheet" href="static/luckysheet/css/pluginsCss.css">
<link rel="stylesheet" href="static/luckysheet/css/plugins.css">
<link rel="stylesheet" href="static/luckysheet/css/luckysheet.css">
<link rel="stylesheet" href="static/luckysheet/css/iconfont.css">
<link rel="stylesheet" href="static/pptxjs/css/pptxjs.css">
<link rel="stylesheet" href="static/viewer/viewer.css">
```

**JS 引入：**
```html
<script type="text/javascript" src="static/common/js/jquery-2.0.3.min.js"></script>
<script type="text/javascript" src="static/common/js/jPreview.js"></script>
```

##### 2. 初始化插件

在页面加载完成后，调用 `jPreview.preview` 方法进行初始化：

```javascript
jPreview.preview({
    container: "container",     // 必填，容器ID
    staticPath: "./static",     // 必填，静态资源相对路径
    url: "",                    // 选填，预览资源路径，若为空则自动获取URL中的src参数
    ext: "",                    // 必填（若url无后缀），资源后缀名，用于识别文件类型
    name: "",                   // 选填，资源名称
    watermarkTxt: "文件预览系统", // 选填，水印文字
    watermarkSize: "",          // 选填，水印文字大小，默认为16px
    priority: 1,                // 选填，优先级 1：优先使用插件预览 2：优先使用Office在线预览
    oburl: "",                  // 选填，第三方Office在线预览地址。
                                // 说明：.ppt和.doc默认需要第三方支持。若不传此参数或传空，不支持的文件将无法预览。
});
```

##### 3. 部署说明

1.  **静态资源**：将 `static` 文件夹复制到您的项目中，并确保初始化时的 `staticPath` 指向正确的位置。
2.  **PDF 预览配置**：PDF 预览插件采用了 `.mjs` 文件。如果您使用 Nginx 服务器，需要在 `mime.types` 或 `nginx.conf` 中添加 MIME 类型配置，否则浏览器可能无法正确加载模块。

**Nginx 配置示例：**
```nginx
http {
    ...
    types {
        application/javascript mjs;
    }
    ...
}
```

#### 集成开源库说明

本项目集成了多个优秀的开源库来实现不同格式的预览：

1.  **docx-preview**: 用于预览 `.docx` 文档。
2.  **pptxjs**: 用于预览 `.pptx` 演示文稿。
3.  **luckysheet**: 强大的在线 Excel 表格组件。
4.  **sheetjs**: 辅助 Excel 解析，支持 `.xls`。
5.  **superVideo**: 视频播放器。
6.  **yAudio**: 音频播放器。
7.  **watermark**: 水印生成插件。
8.  **viewer.js**: 强大的图片查看器。
9.  **embedPDF**: PDF 文件预览。

#### 已知问题

*   **PDF 中文路径**：PDF 文档暂时不支持包含中文字符的路径。
*   **安全提示**：PDF 文件预览机制可能存在 XSS 攻击风险，请确保预览的文件来源可信或进行必要的安全过滤。