pdfh5

v3.0.0

Published

4 months ago

JS plugin of preview PDF for mobile. web/h5/移动端PDF预览手势缩放插件

0High
0Medium
0Low

gjtool

pdf pdf.js pdfjs pdfh5 pdfh5.js javascript plugin library mobile

pdfh5.js

有问题可以加Q群咨询，技术交流群，也可以探讨技术，另有开发技术讨论微信群可以问群主拉入微信群

pdfh5.js示例

更新信息

2025.10.19 更新： v3.0.0大版本更新，支持官方pdf.js v5.4.296，移除svg渲染模式，恢复懒加载模式，新增分段加载模式，新增沙箱集成（防止JavaScript注入等），新增密码pdf文件预览，优化手势缩放（后续会继续优化，目前还是有问题）。
根据需求选择加载模式：小文件直接全部加载，中等文件用懒加载，大文件用分段加载。如果同时配置多个模式，按优先级：分段加载 > 懒加载 > 传统加载。

pdfh5在线预览

https://pdfh5.gjtool.cn/pdfh5/pdf.html

https://pdfh5.gjtool.cn/pdfh5/password.pdf 密码 123456zxcv..

快速开始（有两种方式）

一、script标签引入方式

1.创建div容器

<div id="demo"></div>

2.引入pdfh5.js（插件会自动检测并加载PDF.js资源）

<script src="js/pdfh5.js"></script>

3.实例化

var pdfh5 = new Pdfh5(document.querySelector("#demo"), {
    pdfurl: "./default.pdf"
});

二、npm安装方式（适应于vue）, react使用方法类似vue（example/react-test是react使用示例）

1.安装

npm install pdfh5

2.静态资源引用
将pdfh5文件夹下的cmaps、iccs、standard_fonts、wasm、js/pdf.worker.min.js都放置到public静态资源目录下
3.使用

<script setup lang="ts">
import Pdfh5 from "pdfh5"
import { ref, onMounted, onUnmounted } from 'vue'

const container = ref<HTMLElement>()
let pdfViewer: any = null

onMounted(async () => {
  try {
    
    console.log('Pdfh5构造函数:', Pdfh5);

    // 创建PDF查看器
    pdfViewer = new Pdfh5(container.value!, {
      pdfurl: "/git.pdf",
      textLayer: true,
      workerSrc:"./pdf.worker.min.js",
      cMapUrl: './cmaps/',
      standardFontDataUrl: './standard_fonts/',
      iccUrl: './iccs/',
      wasmUrl: './wasm/'
    });
    console.log('PDF查看器创建成功:', pdfViewer);

  } catch (error) {
    console.error('PDF初始化失败:', error);
  }
})

onUnmounted(() => {
  if (pdfViewer && typeof pdfViewer.destroy === 'function') {
    pdfViewer.destroy()
  }
})
</script>

<template>
  <div class="pdf-container" ref="container"></div>
</template>

<style scoped>
.pdf-container {
  width: 100%;
  height: 100vh;
}
</style>

API接口方法

实例化

pdfh5实例化的时候传两个参数，selector选择器，options配置项参数，会返回一个pdfh5实例对象，可以用来操作pdf，监听相关事件

var pdfh5 = new Pdfh5(selector, options);

|参数名称 |类型 |取值 |是否必须 |作用 | |:---:|:---:|:---:|:---:|:---:| |selector | HTMLElement | - | √ |pdfh5的容器,html DOM元素对象 | |options | Object | - | × |pdfh5的配置项参数 |

options配置项参数列表

示例： 配置项参数 pdfurl

var pdfh5 = new Pdfh5(document.querySelector("#demo"), {
	pdfurl: "./default.pdf"
});

基础配置

渲染配置

交互配置

懒加载配置

|参数名称 |类型 |取值 |默认值 |作用 | |:---:|:---:|:---:|:---:|:---:| |lazyLoad | Boolean |true、false |false |启用懒加载模式，只渲染可见页面 |

分段加载配置

UI组件配置

其他配置

|参数名称 |类型 |取值 |默认值 |作用 | |:---:|:---:|:---:|:---:|:---:| |goto | Number |页码数字 |0 |加载pdf跳转到第几页 | |enableHWA | Boolean |true、false |true |是否启用硬件加速，对图片渲染很重要 |

手势缩放配置

|参数名称 |类型 |取值 |默认值 |作用 | |:---:|:---:|:---:|:---:|:---:| |tapZoomFactor | Number |数字 |2 |双击缩放倍数 | |zoomOutFactor | Number |数字 |1.2 |缩放回弹因子 | |animationDuration| Number |数字，单位毫秒 |300 |缩放动画持续时间 | |maxZoom | Number |数字 |4 |最大缩放倍数 | |minZoom | Number |数字 |0.5 |最小缩放倍数 | |dampingFactor | Number |数字 |0.85 |阻尼因子 |

注释编辑器配置

|参数名称 |类型 |取值 |默认值 |作用 | |:---:|:---:|:---:|:---:|:---:| |annotationEditorMode| String |"NONE"、"FREETEXT"、"HIGHLIGHT"、"INK"、"STAMP"、"SIGNATURE" |"NONE" |注释编辑器模式 | |editorParams | Object |编辑器参数对象 |{} |注释编辑器参数配置 |

沙箱安全配置

|参数名称 |类型 |取值 |默认值 |作用 | |:---:|:---:|:---:|:---:|:---:| |sandboxEnabled | Boolean |true、false |true |是否启用沙箱模式，防止JavaScript注入和XSS攻击 |

沙箱配置选项（sandboxOptions）

沙箱配置示例

var pdfh5 = new Pdfh5(document.querySelector("#demo"), {
    pdfurl: "./document.pdf",
    sandboxEnabled: true,
    sandboxOptions: {
        allowScripts: false,        // 禁止JavaScript执行
        allowForms: true,           // 允许表单交互
        allowPopups: false,         // 禁止弹窗
        allowSameOrigin: true,       // 允许同源访问
        sandbox: "allow-same-origin allow-scripts",
        referrerPolicy: "strict-origin-when-cross-origin"
    }
});

资源路径配置说明

var pdfh5 = new Pdfh5(document.querySelector("#demo"), {
    pdfurl: "./document.pdf",
    workerSrc: "./pdf.worker.min.js",
    cMapUrl: "../cmaps/",
    standardFontDataUrl: "../standard_fonts/",
    iccUrl: "../iccs/",
    wasmUrl: "../wasm/"
});

资源文件说明

插件需要以下PDF.js资源文件：

cmaps/ - 字体映射文件（用于正确显示中文字体）
standard_fonts/ - 标准字体文件（用于PDF标准字体渲染）
iccs/ - 颜色配置文件（用于颜色管理和色彩空间转换）
wasm/ - WebAssembly文件（用于高性能PDF渲染和图像解码）
pdf.worker.min.js - PDF.js Worker文件（用于后台PDF处理）

pdf请求示例

1、文件地址

new Pdfh5(document.querySelector("#demo"), {
	pdfurl: "git.pdf"
});

2、pdf文件流或者arraybuffer已经得到，如何渲染

 new Pdfh5(document.querySelector("#demo"), {
 	data: blob,  //blob arraybuffer
 });

methods 方法列表

基础控制方法

交互控制方法

|方法名 |传参 |传参取值 |作用 | |:---:|:---:|:---:|:---:| |setScrollEnabled| Boolean |true、false |启用/禁用PDF滚动 | |setZoomEnabled | Boolean |true、false |启用/禁用PDF手势缩放 | |isScrollEnabled| - |无参数 |获取滚动状态 | |isZoomEnabled | - |无参数 |获取缩放状态 | |setProgressiveLoading | Boolean, Object |Boolean:是否启用, Object:配置选项{chunkSize, maxMemoryPages} |设置分段加载配置 | |getProgressiveLoadingStatus | - |无参数 |获取分段加载状态 | |getMemoryUsage | - |无参数 |获取内存使用情况 |

页面导航方法

|方法名 |传参 |传参取值 |作用 | |:---:|:---:|:---:|:---:| |goToPage | Number |Number:要跳转的pdf页数 |pdf跳转到第几页（pdf加载完成后使用） | |nextPage | - |无参数 |跳转到下一页 | |prevPage | - |无参数 |跳转到上一页 | |scrollToTop | - |无参数 |滚动到顶部 |

缩放控制方法

|方法名 |传参 |传参取值 |作用 | |:---:|:---:|:---:|:---:| |zoomIn | - |无参数 |放大PDF | |zoomOut | - |无参数 |缩小PDF | |setScale | Number |Number:缩放比例 |设置缩放比例 | |setZoomEnabled | Boolean |true、false |启用/禁用缩放手势 | |isZoomEnabled | Boolean |无参数 |获取缩放状态 | |setZoomConstraints| Object |{minScale, maxScale, step} |设置缩放约束 | |getZoomConstraints| - |无参数 |获取缩放约束 | |isZooming | - |无参数 |检查是否正在缩放 |

搜索功能方法

|方法名 |传参 |传参取值 |作用 | |:---:|:---:|:---:|:---:| |searchText | String |String:搜索关键词 |搜索文本 | |findNext | - |无参数 |查找下一个匹配项 | |findPrevious | - |无参数 |查找上一个匹配项 | |clearSearch | - |无参数 |清除搜索高亮 |

下载和打印方法

|方法名 |传参 |传参取值 |作用 | |:---:|:---:|:---:|:---:| |downloadPDF | String |String:下载文件名，默认"document.pdf" |下载PDF | |printPDF | - |无参数 |打印PDF（渲染所有页面到打印容器） |

分段加载方法

|方法名 |传参 |传参取值 |作用 | |:---:|:---:|:---:|:---:| |setProgressiveLoading | Boolean, Object |Boolean:是否启用, Object:配置选项{chunkSize, maxMemoryPages} |设置分段加载配置 | |getProgressiveLoadingStatus | - |无参数 |获取分段加载状态 | |getMemoryUsage | - |无参数 |获取内存使用情况 |

注释编辑器方法

分段加载需要的服务端配置说明

1. Nginx配置（推荐）

分段加载需要服务端支持HTTP范围请求（Range Requests），Nginx默认支持静态文件的范围请求，但需要正确配置：

# 基础配置 - 支持PDF文件的范围请求
location ~* \.(pdf)$ {
    # 启用范围请求支持
    add_header Accept-Ranges bytes;
    
    # 设置正确的MIME类型
    add_header Content-Type application/pdf;
    
    # 缓存控制（可选）
    expires 1h;
    add_header Cache-Control "public, immutable";
    
    # CORS支持（如果需要跨域）
    add_header Access-Control-Allow-Origin "*";
    add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS";
    add_header Access-Control-Allow-Headers "Range, Content-Range";
    
    # 处理OPTIONS请求
    if ($request_method = 'OPTIONS') {
        add_header Access-Control-Allow-Origin "*";
        add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS";
        add_header Access-Control-Allow-Headers "Range, Content-Range";
        add_header Access-Control-Max-Age 86400;
        return 204;
    }
}

2. 反向代理配置

如果使用Nginx作为反向代理，需要额外配置：

location /api/pdf/ {
    proxy_pass http://backend_server;
    
    # 禁用缓冲，支持流式传输
    proxy_buffering off;
    proxy_request_buffering off;
    
    # 设置超时时间
    proxy_read_timeout 300s;
    proxy_connect_timeout 60s;
    
    # 使用HTTP/1.1
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    
    # 传递原始请求头
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    
    # 支持范围请求
    proxy_set_header Range $http_range;
    proxy_set_header If-Range $http_if_range;
}

3. Apache配置

如果使用Apache服务器：

# 启用mod_rewrite和mod_headers
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule headers_module modules/mod_headers.so

# 配置PDF文件处理
<LocationMatch "\.pdf$">
    # 启用范围请求
    Header set Accept-Ranges bytes
    
    # 设置MIME类型
    Header set Content-Type "application/pdf"
    
    # CORS支持
    Header set Access-Control-Allow-Origin "*"
    Header set Access-Control-Allow-Methods "GET, HEAD, OPTIONS"
    Header set Access-Control-Allow-Headers "Range, Content-Range"
    
    # 缓存控制
    Header set Cache-Control "public, max-age=3600"
</LocationMatch>

4. Node.js Express配置

如果使用Node.js作为后端：

const express = require('express');
const app = express();

// 支持范围请求的中间件
app.use('/pdf', (req, res, next) => {
    // 设置CORS头
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Methods', 'GET, HEAD, OPTIONS');
    res.header('Access-Control-Allow-Headers', 'Range, Content-Range');
    
    // 处理OPTIONS请求
    if (req.method === 'OPTIONS') {
        res.status(204).end();
        return;
    }
    
    next();
});

// 静态文件服务，支持范围请求
app.use('/pdf', express.static('pdf-files', {
    setHeaders: (res, path) => {
        if (path.endsWith('.pdf')) {
            res.setHeader('Content-Type', 'application/pdf');
            res.setHeader('Accept-Ranges', 'bytes');
        }
    }
}));

5. PHP配置

如果使用PHP作为后端：

<?php
// 设置CORS头
header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET, HEAD, OPTIONS');
header('Access-Control-Allow-Headers: Range, Content-Range');

// 处理OPTIONS请求
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(204);
    exit;
}

// 支持范围请求的PDF文件服务
$file = $_GET['file'];
$filePath = 'pdf-files/' . $file;

if (file_exists($filePath)) {
    $fileSize = filesize($filePath);
    $range = $_SERVER['HTTP_RANGE'] ?? '';
    
    if ($range) {
        // 处理范围请求
        $ranges = explode('=', $range);
        $offset = explode('-', $ranges[1]);
        $start = intval($offset[0]);
        $end = isset($offset[1]) ? intval($offset[1]) : $fileSize - 1;
        
        header('HTTP/1.1 206 Partial Content');
        header('Content-Range: bytes ' . $start . '-' . $end . '/' . $fileSize);
        header('Content-Length: ' . ($end - $start + 1));
        header('Content-Type: application/pdf');
        header('Accept-Ranges: bytes');
        
        $fp = fopen($filePath, 'rb');
        fseek($fp, $start);
        echo fread($fp, $end - $start + 1);
        fclose($fp);
    } else {
        // 完整文件请求
        header('Content-Type: application/pdf');
        header('Content-Length: ' . $fileSize);
        header('Accept-Ranges: bytes');
        readfile($filePath);
    }
}
?>

6. 配置验证

验证服务端是否正确支持范围请求：

# 测试范围请求
curl -H "Range: bytes=0-1023" -I http://your-server.com/path/to/file.pdf

# 应该返回：
# HTTP/1.1 206 Partial Content
# Accept-Ranges: bytes
# Content-Range: bytes 0-1023/1048576
# Content-Length: 1024

事件监听方法

|方法名 |传参 |传参取值 |作用 | |:---:|:---:|:---:|:---:| |on | (String, Function)|String：监听的事件名，Function：监听的事件回调 |监听事件 | |off | String |String：要移除的事件名 |移除事件监听 | |trigger | (String, Object) |String：事件名，Object：事件数据 |触发事件 |

状态获取方法

|方法名 |传参 |传参取值 |作用 | |:---:|:---:|:---:|:---:| |getStatus | - |无参数 |获取当前状态信息 |

on方法监听所有事件-事件名列表

示例： 监听pdf准备开始渲染，此时可以拿到pdf总页数

pdfh5.on("ready", function () {
	console.log("总页数：" + this.totalNum)
})

生命周期事件

交互事件

控制事件

注释编辑器事件

事件监听示例

// 监听PDF加载完成事件
pdfh5.on("complete", function (status, msg, time) {
    console.log("状态：" + status + "，总耗时：" + time + "毫秒，总页数：" + this.totalNum, msg);
});

// 监听滚动事件
pdfh5.on("scroll", function (data) {
    console.log("scrollTop:" + data.scrollTop, "currentNum:" + data.currentNum);
});

// 监听注释编辑器事件
pdfh5.on("annotationAdded", function (data) {
    console.log("注释已添加：", data);
});

pdfh5.on("annotationModeChanged", function (mode) {
    console.log("注释模式已切换为：", mode);
});

完整使用示例

基础使用

var pdfh5 = new Pdfh5(document.querySelector("#demo"), {
    pdfurl: "./document.pdf",
    scale: 1.5,
    textLayer: true,
    zoomEnable: true,
    scrollEnable: true
});

高级配置示例

var pdfh5 = new Pdfh5(document.querySelector("#demo"), {
    // 基础配置
    pdfurl: "./large-document.pdf",
    password: "123456", // 如果有密码保护
    
    // 渲染配置
    scale: 1.0,
    textLayer: true,
    enableHWA: true,
    
    // 交互配置
    zoomEnable: true,
    scrollEnable: true,
    backTop: true,
    pageNum: true,
    loadingBar: true,
    
    // 手势缩放配置
    tapZoomFactor: 2,
    maxZoom: 4,
    minZoom: 0.5,
    
    // 分段加载配置（大文件推荐）
    progressiveLoading: true,
    chunkSize: 65536,
    maxMemoryPages: 5,
    
    // 注释编辑器配置
    annotationEditorMode: "FREETEXT",
    editorParams: {
        freeTextColor: "#000000",
        freeTextSize: 12,
        inkColor: "#000000",
        inkThickness: 1
    },
    
    // 沙箱安全配置
    sandboxEnabled: true,
    sandboxOptions: {
        allowScripts: false,
        allowForms: true,
        allowPopups: false,
        allowSameOrigin: true
    },
    
    // 资源路径配置
    workerSrc: "./pdf.worker.min.js",
    cMapUrl: "../cmaps/",
    standardFontDataUrl: "../standard_fonts/",
    iccUrl: "../iccs/",
    wasmUrl: "../wasm/"
});

// 事件监听
pdfh5.on("ready", function() {
    console.log("PDF加载完成，总页数：", this.totalNum);
});

pdfh5.on("annotationAdded", function(data) {
    console.log("新注释已添加：", data);
});

// 方法调用
pdfh5.setAnnotationEditorMode("HIGHLIGHT");
pdfh5.setProgressiveLoading(true, {chunkSize: 32768});

打赏榜单

JayLin ￥6.66
靓仔城￥6.67
南蓝￥8.80
我是太阳￥29.99
*小波￥1.00
*鑫 ¥9.99
*手 ¥9.99
*勇￥19.99
*爷 ¥5.00
*超 ¥20.00
3*Y ¥5.00
*阳 ¥5.00
**雄 ¥5.00
A*r ¥1.23
*客 ¥5.00
*运 ¥66.66
*辰 ¥30.00
*黎 ¥6.66+¥5.00
**福 ¥6.66
*🏀 ¥6.66+¥1.00
*阳 ¥10.00
自闭中 ¥16.66+¥16.00
*焕 ¥6.66
*人 ¥5.00
*。 ¥5.20
半*) ¥5.00
*1 ¥15.00
*蕾 ¥16.66+¥8.80
*军 ¥10.00
**强 ¥58.88
E*y ¥6.60
J*u ¥13.00
A*a ¥50.00
*东 ¥8.80
j*y ¥9.99
*宇 ¥6.66
*涛￥1.00
*. ￥10.00
*☺ ￥6.66
*霸￥6.66
a*r ￥20.00
木槿(**耀) ￥50.00