@agilehub/vue-pdf-flipbook 1.2.0 → 1.3.2

package/README.md

@@ -282,6 +282,7 @@ onBeforeUnmount(stopPan)
 | `fileSize` | `number` | 自动读取 `Content-Range` | PDF 原始字节数；跨域响应未暴露 `Content-Range` 时必须由文件元数据接口提供，变化时重新加载 |
 | `initialPage` | `number` | `1` | 每次加载文档的初始页码，从 1 开始 |
 | `initialMode` | `'single'` / `'double'` | 根据 PDF 首页比例选择 | 横向页面默认单栏，纵向页面默认双栏；显式传入时优先使用指定模式，后续可用 `setMode()` 切换 |
+| `flipAnimation` | `{ single?: boolean; double?: boolean }` | 两种模式均开启 | 按实际单栏、双栏布局分别控制翻页动画；关闭时翻页直接定位，属性变化无需重新加载 PDF |
 | `height` | `string` / `number` | `100%` | 默认填满父容器高度；数字单位为 px |
 | `background` | `string` | `'transparent'` | 背景色 |
 | `workerSrc` | `string` | 内置 Worker | 自定义 PDF.js Worker URL |
@@ -291,6 +292,16 @@ onBeforeUnmount(stopPan)
 
 双页模式在空间不足时自动显示单页。`visiblePages` 反映实际显示页，而 `mode` 表示选择的模式。
 
+例如单栏直接切页、双栏保留翻书动画：
+
+```vue
+<VuePdfFlipbook :url="pdfUrl" :flip-animation="{ single: false, double: true }" />
+```
+
+两项都不传时均播放动画；可只传其中一项。按钮、缩略图、`goToPage()` 以及书页鼠标操作使用实际布局对应的设置，关闭动画后仍会等待目标页渲染完成并发送原有页码事件。窄屏下双栏会退化为单栏，此时采用 `single` 的设置。
+
+关闭动画时，引擎只在页面或容器尺寸变化时重绘，停止空闲时的持续帧循环和动画 Canvas 克隆监听，以减少 CPU 与 DOM 更新开销。阅读模式、缩放适配、缩略图预加载范围及事件保持一致；重新开启动画无需重载 PDF。若在翻页中关闭动画，会先完成当前折页，再进入按需绘制。
+
 可通过 `<VuePdfFlipbook :url="pdfUrl" loading-text="文档加载中，请稍候…" />` 自定义加载提示。加载错误仍显示错误标题和具体错误信息，不使用此文案。
 
 双页模式两侧显示纸张层叠边缘，厚度按当前页组之前和之后的页数分配：前半本右厚左薄，后半本左厚右薄，翻页或跳页后平滑变化。每侧最多 16px，短文档按页数减薄，单页模式隐藏。布局在双页状态下每侧预留 18px，防止页叠被裁切；封面及封底的页叠随闭合位置移动。
@@ -422,7 +433,9 @@ function onError(error: unknown) {
 
 连续请求相同或重叠的目标窗口会保留已完成的渲染记录。书页点击、拖拽也会检查动画必需页面：未准备好时保留当前页，通过 `pageLoading` 提示外部，准备完成后自动翻页；已准备好时保留原有拖拽交互。尚未绘制的 Canvas 隐藏，避免显示黑色底图。
 
-组件使用自定义 `PDFDataRangeTransport`：第一次请求就带 `Range: bytes=0-65535`，之后只请求 PDF.js 所需的字节段，关闭流式下载和自动预取。请求按 64 KiB 对齐，PDF.js 可能合并相邻段。每段校验 HTTP `206`、长度以及浏览器可见的 `Content-Range`；收到 `200` 时立即取消响应并报告错误，不再回退到整文件下载。
+组件使用自定义 `PDFDataRangeTransport`：第一次请求就带 `Range: bytes=0-262143`，之后只请求 PDF.js 所需的字节段，关闭流式下载和自动预取。请求按 256 KiB 对齐，PDF.js 可能合并相邻段，减少大图、字体跨多个小段时的网络往返。每段校验 HTTP `206`、长度以及浏览器可见的 `Content-Range`；收到 `200` 时立即取消响应并报告错误，不再回退到整文件下载。
+
+首段下载与 PDF.js/Worker 模块加载并行进行。分段请求遵守服务器的 HTTP 缓存策略，组件不再强制 `no-store`；实际缓存命中仍取决于浏览器、服务器响应头及开发者工具是否启用“停用缓存”。Network 中的多条 PDF 请求对应字节段，不是一条请求对应一页。排查慢请求时分别检查排队、等待首字节（TTFB）和下载耗时：较长的 TTFB 常需检查 CDN 命中及源站响应；图像较大的 PDF 还受下载带宽影响。
 
 跨域服务器必须允许 CORS 和 Range 请求。建议 OSS/CDN 的 `Access-Control-Expose-Headers` 包含 `Content-Range, Accept-Ranges, Content-Length, Content-Encoding, ETag`，PDF 的 `Content-Type` 设置为 `application/pdf`。组件优先从 `Content-Range` 获取总长度，不再依赖浏览器是否能读到 `Accept-Ranges`。
 

package/dist/composables/types.d.ts

@@ -1,4 +1,4 @@
-import type { PdfFlipbookProps, PdfFlipbookState, ReaderMode } from '../types';
+import type { PdfFlipAnimation, PdfFlipbookProps, PdfFlipbookState, ReaderMode } from '../types';
 export interface PageSize {
     width: number;
     height: number;
@@ -33,3 +33,5 @@ export interface FlipEnginePort {
      */
     flip: (pageIndex: number, corner: 'top' | 'bottom') => void;
 }
+/** 根据实际显示方向确定是否播放翻页动画；属性变化会在下次交互时立即生效。 */
+export declare function isFlipAnimationEnabled(animation: PdfFlipAnimation | undefined, mode: ReaderMode): boolean;

package/dist/composables/usePageFlip.d.ts

@@ -14,6 +14,8 @@ interface EngineEvents {
      */
     canStartUserTurn: (forward: boolean, prepare?: boolean) => boolean;
     getLayoutMode: () => ReaderMode;
+    isAnimationEnabled: () => boolean;
+    onInstantUserTurn: (forward: boolean) => void;
 }
 /**
  * 封装 PageFlip 实例、输入拦截和临时 Canvas 克隆。
@@ -25,11 +27,12 @@ interface EngineEvents {
 export declare function usePageFlip(flipbookElement: Ref<HTMLElement | undefined>, events: EngineEvents): {
     initialize: (pageSize: PageSize, pageCount: number, currentPage: number) => void;
     destroy: () => void;
+    syncAnimationMode: () => void;
     /** 导航层翻页前调用；无参数，返回引擎实例是否存在。 */
     isReady: () => boolean;
     update: () => void;
     /**
-     * 导航准备完成后启动翻页，并按首尾页状态调整动画时长。
+     * 导航准备完成后按实际模式选择动画翻页或直接定位。
      * @param pageIndex 目标页面在 PageFlip 中的零基索引。
      * @param corner 起翻页角，top 为上角，bottom 为下角。
      * @returns void；动画完成状态由引擎事件另行通知导航层。

package/dist/composables/usePdfFlipbook.d.ts

@@ -39,6 +39,7 @@ export declare function usePdfFlipbook(props: ResolvedFlipbookProps, emit: Flipb
     pageCount: Readonly<import("vue").Ref<number, number>>;
     initialViewReady: import("vue").Ref<boolean, boolean>;
     initialLoadError: import("vue").ComputedRef<string>;
+    animationEnabled: import("vue").ComputedRef<boolean>;
     pageLoading: Readonly<import("vue").Ref<boolean, boolean>>;
     mode: Readonly<import("vue").Ref<ReaderMode, ReaderMode>>;
     activePages: import("vue").ComputedRef<Set<number>>;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { Plugin } from 'vue';
 import VuePdfFlipbook from './VuePdfFlipbook.vue';
-export type { PdfFlipbookExpose, PdfFlipbookProps, PdfFlipbookState, PdfPageNavigationSlotProps, PdfThumbnailSlotProps, PdfThumbnailsSlotProps, PdfThumbnailItem, ReaderMode } from './types';
+export type { PdfFlipAnimation, PdfFlipbookExpose, PdfFlipbookProps, PdfFlipbookState, PdfPageNavigationSlotProps, PdfThumbnailSlotProps, PdfThumbnailsSlotProps, PdfThumbnailItem, ReaderMode } from './types';
 export { VuePdfFlipbook };
 export { default as PdfCanvasPage } from './components/PdfCanvasPage.vue';
 declare const plugin: Plugin;