@agilehub/vue-pdf-flipbook

Vue PDF Flipbook Next

基于 Vue 3、PDF.js 和 PageFlip 的 PDF 翻页组件。核心负责 PDF 加载、页面渲染、单页 / 双页布局和点击、拖拽翻页，内置阅读区两侧翻页按钮、首次加载提示和可选的缩略图列表。缩略图可放在书页底部，也可挂载到外部容器；工具栏、缩放、全屏和快捷键由外部实现。组件不依赖 UI 框架。

灵感来源：Paperturn、turnjs。采用 MIT License。

安装

适用于 Vue 3.4+ 项目，Node.js 要求为 22.15+。以下命令任选一个，在调用方项目根目录执行：

pnpm add @agilehub/vue-pdf-flipbook

npm install @agilehub/vue-pdf-flipbook

yarn add @agilehub/vue-pdf-flipbook

包名为 @agilehub/vue-pdf-flipbook，安装、组件导入和类型导入都使用这个完整名称。Vue 是 peer dependency，由业务项目提供；PDF.js 和 Worker 已由组件提供，普通接入不需要额外安装 pdfjs-dist 或复制 Worker。

在应用入口或使用组件的页面引入一次样式：

import '@agilehub/vue-pdf-flipbook/style.css'

在业务页面使用

下面可保存为业务项目中的 PdfReader.vue。它接收 PDF 地址，提供翻页、缩略图开关、错误提示与重试。PDF 地址必须支持 HTTP Range / 206；跨域时还需要 CORS，具体要求见大文件按需预览。

<script setup lang="ts">
import { ref } from 'vue'
import { VuePdfFlipbook } from '@agilehub/vue-pdf-flipbook'
import type { PdfFlipbookExpose, PdfFlipbookState } from '@agilehub/vue-pdf-flipbook'
import '@agilehub/vue-pdf-flipbook/style.css'

const props = defineProps<{ url: string; fileSize?: number }>()
const reader = ref<PdfFlipbookExpose>()
const state = ref<PdfFlipbookState>()
const errorMessage = ref('')

function onError(error: unknown) {
  errorMessage.value = error instanceof Error ? error.message : String(error)
}

function onStateChange(value: PdfFlipbookState) {
  state.value = value
  if (value.loading) errorMessage.value = ''
}
</script>

<template>
  <section class="vpf-example-page">
    <nav class="vpf-example-toolbar" aria-label="阅读工具栏">
      <button :disabled="!state?.canPrevious || state?.pageLoading" @click="reader?.previous()">上一页</button>
      <span>{{ state?.page ?? 1 }} / {{ state?.pages ?? 0 }}</span>
      <button :disabled="!state?.canNext || state?.pageLoading" @click="reader?.next()">下一页</button>
      <button :disabled="!state?.pages || state?.loading" @click="state?.thumbnailsVisible ? reader?.hideThumbnails() : reader?.showThumbnails()">缩略图</button>
    </nav>
    <p v-if="errorMessage" role="alert">
      {{ errorMessage }} <button @click="reader?.reload()">重试</button>
    </p>
    <div class="vpf-example-reader">
      <VuePdfFlipbook
        ref="reader" :url="props.url" :file-size="props.fileSize"
        height="100%" loading-text="文档加载中，请稍候…"
        @state-change="onStateChange" @error="onError"
      />
    </div>
  </section>
</template>

<style scoped>
.vpf-example-page { display: flex; flex-direction: column; width: 100%; height: 80dvh; min-width: 0; min-height: 0; overflow: hidden; }
.vpf-example-toolbar { display: flex; flex: none; flex-wrap: wrap; align-items: center; gap: 8px; padding: 8px; }
.vpf-example-reader { flex: 1; min-width: 0; min-height: 0; overflow: hidden; }
</style>

父页面使用这个业务封装，例如在同目录的 App.vue 中：

<script setup lang="ts">
import PdfReader from './PdfReader.vue'
</script>

<template>
  <!-- 将 public/catalog.pdf 替换成你的文件，并确保服务端支持 Range / 206。 -->
  <PdfReader url="/catalog.pdf" />
</template>

也支持全局注册，在业务项目的 main.ts 中使用默认导出：

import { createApp } from 'vue'
import App from './App.vue'
import PdfFlipbook from '@agilehub/vue-pdf-flipbook'
import '@agilehub/vue-pdf-flipbook/style.css'

createApp(App).use(PdfFlipbook).mount('#app')

注册后可直接使用 <VuePdfFlipbook />。需要调用实例方法时，仍应导入 PdfFlipbookExpose 为组件 ref 标注类型。

更多使用说明

完整说明按功能拆分，统一入口见功能文档目录。