更新记录

0.3.7（2026-06-10）

• feat: APP端组件增加加载失败状态提示
• docs: 新增PDF转图片API文档、自定义基座说明

0.3.6（2026-06-09）

• feat: 新增 PDF 转图片 API：getPDFInfo、renderPage、renderPages
• feat: uniapp app 使用缓存

0.3.5（2026-06-04）

• feat: uniapp app 使用缓存

平台兼容性

uni-app(4.76)

uni-app x(4.76)

lime-pdf PDF预览组件

UTS原生PDF预览器，支持本地和网络PDF文件预览，提供页面跳转、滑动切换等功能，兼容web、安卓、iOS、鸿蒙Next。组件使用原生能力渲染PDF文件，性能优异，支持密码保护的PDF文件，并提供丰富的事件回调。

插件依赖：lime-shared

安装方法

1. 在uni-app插件市场中搜索并导入lime-pdf
2. 导入后可能需要重新编译项目
3. 需要在自定义基座中使用
4. 安卓本地运行还需配置 gradle
5. 在页面中使用l-pdf组件或调用openPDF API

自定义基座说明：

• 本插件使用 UTS 原生能力，必须在自定义基座中运行，标准基座无法使用
• CLI 项目特别注意：请检查根目录 package.json，确保所有 @dcloudio/* 相关包的版本号一致，且与当前 HBuilderX 版本对齐。版本不一致会导致自定义基座编译失败或运行异常 使用说明：
• 组件方式（l-pdf）：在uniapp中只能源码运行，不支持试用；在uniappx支持普通授权和试用
• API方式（openPDF）：支持uniapp和uniappx的安卓、iOS平台，暂不支持鸿蒙、WEB平台

代码演示

方式一：组件方式（l-pdf）

通过l-pdf组件在页面中嵌入PDF预览。在uniapp中只能源码运行，uniappx中支持普通授权和试用，uniappx鸿蒙需要真机

基础使用

通过url可以设置pdf的路径，支持网络或本地。

<l-pdf 
    ref="pdfRef"
    url="/static/shareSDK.pdf"  
    @load="load"
    @fail="fail"
    @pageChanged="pageChanged"
    style="height:500px;width: 100%;">
</l-pdf>
<button @click="onClick">跳转指定页面</button>

// 组合式
const pdfRef = ref<LPdfComponentPublicInstance|null>(null)

const load = (info: UTSJSONObject)=>{
    // INFO 包含 页数，作者，标题，目录等
    console.log('info', info)
}

const fail = (err: UTSJSONObject)=>{
    // 发生错误时
    console.log('err', err)
}

const pageChanged = (info: UTSJSONObject)=> {
    // 切换页面时 
    console.log('pageChanged', info)
}

const onClick = ()=> {
    // 跳转到指定页面
    pdfRef.value?.jumpTo(3)
}

动态渲染

<l-pdf 
    ref="pdfRef"
    @load="load"
    @fail="fail"
    @pageChanged="pageChanged"
    style="height:500px;width: 100%;">
</l-pdf>
<button @click="render">render</button>

import type { RenderOptions } from '@/uni_modules/lime-pdf'
export default {
    data() {
        return {

        }
    },
    methods: {
        load(info: UTSJSONObject) {
            // INFO 包含 页数，作者，标题，目录等
            console.log('info', info)
        },
        fail(err: UTSJSONObject) {
            // 发生错误时
            console.log('err', err)
        },
        pageChanged(info: UTSJSONObject) {
            // 切换页面时
            console.log('pageChanged', info)
        },
        render() {
            // 调用渲染函数
            (this.$refs['pdfRef'] as LPdfComponentPublicInstance | null)?.render?.({
                url: "/static/shareSDK.pdf",
                page: 0,
                swipeHorizontal: false,
                password: 'password'
            } as RenderOptions) 
        }
    }
}

方式二：API方式（openPDF）

通过openPDF API在新页面打开PDF，带有标题栏和关闭按钮。支持uniapp和uniappx的安卓和iOS平台。

openPDF 打开PDF

<button @click="openPDF">打开PDF</button>

import { openPDF, type OpenPDFOptions } from '@/uni_modules/lime-pdf'

const openPDF = () => {
    openPDF({
        url: '/static/shareSDK.pdf',
        page: 0,
        swipeHorizontal: false,
        password: '',
        success: (res) => {
            console.log('加载成功', res)
        },
        fail: (err) => {
            console.log('加载失败', err)
        },
        complete: () => {
            console.log('完成')
        }
    } as OpenPDFOptions)
}

PDF 控制函数

通过导入以下函数控制已打开的PDF：

import { jumpToPage, nextPage, prevPage, renderPDF } from '@/uni_modules/lime-pdf'

jumpToPage(5)      // 跳转到第5页
nextPage()          // 下一页
prevPage()          // 上一页
renderPDF(options)   // 重新渲染PDF

快速预览

导入插件后，可以直接使用以下标签查看演示效果：

<!-- 代码位于 uni_modules/lime-pdf/components/lime-pdf -->
<lime-pdf />

插件标签说明

Vue2使用说明

main.js中添加以下代码：

// vue2项目中使用
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
Vue.use(VueCompositionAPI)

详细配置请参考官方文档：Vue Composition API

API文档

组件方式 API（l-pdf）

组件 Props 属性

组件 Events 事件

组件方法 API

通过组件实例调用方法：

// uniapp
const pdfRef = this.$refs.pdfRef

// uniappx (TypeScript)
const pdfRef = this.$refs["pdfRef"] as LPdfComponentPublicInstance

API方式 API（openPDF）

openPDF 打开PDF

在新页面打开PDF，带有标题栏和关闭按钮。支持安卓和iOS平台。

import { openPDF } from '@/uni_modules/lime-pdf'

openPDF({
    url: '/static/shareSDK.pdf',
    page: 0,
    swipeHorizontal: false,
    password: '',
    success: (res) => {
        console.log('加载成功', res)
    },
    fail: (err) => {
        console.log('加载失败', err)
    },
    complete: () => {
        console.log('完成')
    }
} as OpenPDFOptions) 

参数说明

PDF 控制函数

通过导入以下函数控制已打开的PDF：

import { jumpToPage, nextPage, prevPage, renderPDF } from '@/uni_modules/lime-pdf'

jumpToPage(5)      // 跳转到第5页
nextPage()          // 下一页
prevPage()          // 上一页
renderPDF(options)   // 重新渲染PDF

PDF 转图片 API

将 PDF 页面渲染为图片，支持 APP 端原生渲染。可用于自定义 PDF 展示、分页加载等场景。

getPDFInfo 获取PDF信息

获取 PDF 文件的基本信息（页数等）。

import { getPDFInfo } from '@/uni_modules/lime-pdf'

getPDFInfo({
  url: '/static/shareSDK.pdf',
  success: (res) => {
    console.log('PDF页数:', res.pageCount)
  },
  fail: (err) => {
    console.log('获取失败:', err.errMsg)
  }
})

renderPage 渲染单页

将 PDF 指定页面渲染为图片。

import { renderPage } from '@/uni_modules/lime-pdf'

renderPage({
  url: '/static/shareSDK.pdf',
  page: 0,           // 页码，从0开始
  dpi: 150,          // 渲染DPI，默认150
  format: 'jpg',     // 输出格式 'png' | 'jpg'，默认 'png'
  quality: 90,       // jpg质量 0-100，默认90
  asBase64: false,  // 是否返回base64 dataurl，默认false返回文件路径
  success: (res) => {
    console.log('图片路径:', res.path)
    console.log('图片尺寸:', res.width, 'x', res.height)
    console.log('页码:', res.page, '/', res.pageCount)
  },
  fail: (err) => {
    console.log('渲染失败:', err.errMsg)
  }
})

renderPages 渲染多页

将 PDF 多个页面渲染为图片。

import { renderPages } from '@/uni_modules/lime-pdf'

// 渲染指定页面
renderPages({
  url: '/static/shareSDK.pdf',
  pages: [0, 1, 2],  // 指定页码数组，不传则渲染全部页
  dpi: 150,
  format: 'jpg',
  quality: 90,
  asBase64: false,
  success: (res) => {
    console.log('渲染完成，共', res.images.length, '张图片')
    res.images.forEach((img, index) => {
      console.log(`第${index}张:`, img.path)
    })
  },
  fail: (err) => {
    console.log('渲染失败:', err.errMsg)
  }
})

// 渲染全部页面
renderPages({
  url: '/static/shareSDK.pdf',
  success: (res) => {
    console.log('PDF总页数:', res.pageCount)
  }
})

PDF 转图片使用示例

import { getPDFInfo, renderPage, renderPages } from '@/uni_modules/lime-pdf'

// 1. 先获取PDF信息
getPDFInfo({
  url: '/static/shareSDK.pdf',
  success: (res) => {
    console.log('PDF共有', res.pageCount, '页')
  }
})

// 2. 渲染封面页作为缩略图
renderPage({
  url: '/static/shareSDK.pdf',
  page: 0,
  dpi: 72,
  asBase64: true,
  success: (res) => {
    // 可用于显示缩略图
    console.log('封面图base64:', res.path)
  }
})

// 3. 批量渲染指定页面
renderPages({
  url: '/static/shareSDK.pdf',
  pages: [0, 1, 2, 3, 4],
  dpi: 150,
  format: 'jpg',
  success: (res) => {
    console.log('前5页渲染完成')
  }
})

使用注意事项

1. 组件需要在自定义基座中使用，普通编译环境可能无法正常运行
2. 安卓平台需要额外配置gradle，详见安装方法
3. 组件高度需要通过style属性设置，否则可能无法正常显示
4. 对于密码保护的PDF文件，需要提供正确的密码才能正常显示
5. 页面索引从0开始计算，例如第一页的索引为0

文档链接

📚 组件详细文档请访问以下站点：

• PDF预览组件文档 - 站点1
• PDF预览组件文档 - 站点2
• PDF预览组件文档 - 站点3

支持与赞赏

如果你觉得本插件解决了你的问题，可以考虑支持作者：

支付宝赞助	微信赞助