pdf-h5-react 0.0.0-stage → 0.3.0

package/dist/core/pdfjs.d.ts

@@ -0,0 +1,51 @@
+import { PDFDocumentProxy, PDFDocumentLoadingTask } from 'pdfjs-dist';
+import { PdfSource } from '../types';
+import * as pdfjsLib from 'pdfjs-dist';
+/**
+ * pdf.js 的 DocumentInitParameters 在 6.x 里已不再从包根导出，
+ * 这里从类型声明的实际路径推导，避免把内部结构写死。
+ */
+type DocumentInitParameters = Parameters<typeof pdfjsLib.getDocument>[0];
+/**
+ * pdf.js 运行时配置。
+ *
+ * 默认使用 jsDelivr CDN 上「与当前依赖版本严格一致」的 worker / cmaps /
+ * standard_fonts / wasm，因此库可以零配置直接跑起来。生产环境建议自托管：
+ * 运行 `npm run assets`（或手动拷贝 pdfjs-dist 的这几个目录），然后调用
+ * `configurePdfjs({ workerSrc: '/pdfjs/pdf.worker.min.mjs', ... })`。
+ */
+export declare const PDFJS_VERSION: string;
+export interface PdfjsRuntimeOptions {
+    workerSrc?: string;
+    cMapUrl?: string;
+    standardFontDataUrl?: string;
+    wasmUrl?: string;
+    iccUrl?: string;
+    /** 0 = errors, 1 = warnings, 5 = infos（pdf.js VerbosityLevel） */
+    verbosity?: number;
+}
+/** 覆盖 pdf.js 的静态资源地址（worker / cmaps / 字体 / wasm） */
+export declare function configurePdfjs(options: PdfjsRuntimeOptions): void;
+export declare function getPdfjsRuntimeOptions(): Readonly<PdfjsRuntimeOptions>;
+export { pdfjsLib };
+/** 把各种 PdfSource 归一化成 pdf.js 的 DocumentInitParameters */
+export declare function toDocumentParams(source: PdfSource, extra?: Record<string, unknown>): DocumentInitParameters;
+export interface LoadPdfOptions {
+    password?: string;
+    onProgress?: (loaded: number, total: number) => void;
+    onPassword?: (reason: number) => void;
+    /** 允许 pdf.js 在解析出错时尽量恢复，默认 true */
+    stopAtErrors?: boolean;
+    /** 关闭 worker 端 OffscreenCanvas（部分老安卓内核更稳） */
+    disableOffscreenCanvas?: boolean;
+}
+export interface LoadedPdf {
+    doc: PDFDocumentProxy;
+    task: PDFDocumentLoadingTask;
+}
+/**
+ * 加载 PDF。注意：调用方负责在卸载时销毁返回值里的 task。
+ */
+export declare function loadPdf(source: PdfSource, options?: LoadPdfOptions): LoadedPdf;
+/** 便捷方法：等待加载完成并返回文档代理 */
+export declare function loadPdfDocument(source: PdfSource, options?: LoadPdfOptions): Promise<PDFDocumentProxy>;

package/dist/core/readerEvents.d.ts

@@ -0,0 +1,116 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+/** 渲染一页的耗时信息 */
+export interface RenderTiming {
+    pageNumber: number;
+    /** 本页渲染耗时（ms） */
+    pageTime: number;
+}
+export interface ReaderStatus {
+    /** 文档是否已就绪 */
+    ready: boolean;
+    /** 是否正在加载 */
+    loading: boolean;
+    /** 总页数，未就绪时为 0 */
+    total: number;
+    /** 当前页（1 基） */
+    page: number;
+    /** 当前缩放倍率 */
+    zoom: number;
+    /** 已解析尺寸的页数（渐进式度量进度） */
+    measured: number;
+    /** 位图缓存估算占用（字节） */
+    cacheBytes: number;
+    /** 已挂载的页面 DOM 数（虚拟化效果的直接体现） */
+    mountedPages: number;
+    /** 最近一次错误信息 */
+    error: string | null;
+    /** 手势缩放是否启用 */
+    zoomEnabled: boolean;
+    /** 滚动是否启用 */
+    scrollEnabled: boolean;
+}
+export interface ZoomEventPayload {
+    zoom: number;
+    /** 相对缩放开始时的倍率变化 */
+    scaleChange: number;
+    /** 手势 / 动画开始时的倍率 */
+    startZoom: number;
+    /** 本次缩放耗时（ms），动画结束或手势结束时给出 */
+    duration: number;
+    /** 触发来源，便于区分埋点 */
+    source: 'gesture' | 'doubleTap' | 'button' | 'wheel' | 'api' | 'reset';
+}
+export interface ScrollEventPayload {
+    scrollTop: number;
+    scrollLeft: number;
+    currentPage: number;
+    /** 卷动进度 0-1 */
+    progress: number;
+}
+export interface ReaderEvents {
+    /** 开始初始化（文档尚未加载） */
+    init: {
+        src: unknown;
+    };
+    /** 文档已加载，可以拿到总页数 */
+    ready: {
+        doc: PDFDocumentProxy;
+        total: number;
+    };
+    /** 加载失败 */
+    error: {
+        error: Error;
+        message: string;
+        time: number;
+    };
+    /** 某一页渲染完成 */
+    render: RenderTiming & {
+        totalTime: number;
+    };
+    /** 渲染成功（首屏可用） */
+    success: {
+        message: string;
+        time: number;
+    };
+    /** 加载流程结束（无论成功失败都会触发，与 pdfh5 的 complete 语义一致） */
+    complete: {
+        status: 'success' | 'error';
+        message: string;
+        time: number;
+    };
+    /** 滚动（已节流） */
+    scroll: ScrollEventPayload;
+    /** 当前页变化 */
+    pageChange: {
+        page: number;
+        total: number;
+    };
+    /** 缩放值变化（手势过程中也会触发，已节流） */
+    zoom: {
+        zoom: number;
+        source: ZoomEventPayload['source'];
+    };
+    /** 缩放开始 */
+    zoomStart: {
+        zoom: number;
+        source: ZoomEventPayload['source'];
+    };
+    /** 缩放结束（含动画） */
+    zoomEnd: ZoomEventPayload;
+    /** 缩放开关变化 */
+    zoomEnabled: {
+        enabled: boolean;
+    };
+    /** 滚动开关变化 */
+    scrollEnabled: {
+        enabled: boolean;
+    };
+    /** 用户点击回到顶部 */
+    backTop: {
+        from: number;
+    };
+    /** 组件销毁 */
+    destroy: Record<string, never>;
+}
+export type ReaderEventName = keyof ReaderEvents;
+export type ReaderEventPayload<K extends ReaderEventName> = ReaderEvents[K];

package/dist/core/renderQueue.d.ts

@@ -0,0 +1,45 @@
+export type RenderPriority = 'visible' | 'prefetch';
+export interface RenderQueueOptions {
+    visibleConcurrency?: number;
+    prefetchConcurrency?: number;
+    /** 任务之间让出主线程的延迟（ms），默认 0 */
+    yieldDelay?: number;
+}
+export declare class RenderQueue {
+    private jobs;
+    private readonly running;
+    private visibleRunning;
+    private prefetchRunning;
+    private readonly visibleConcurrency;
+    private readonly prefetchConcurrency;
+    private readonly yieldDelay;
+    private pumping;
+    private stats;
+    constructor(options?: RenderQueueOptions);
+    /** 提交任务；同 key 已在排队或执行中则复用其 Promise（引用计数 +1） */
+    enqueue<T>(key: string, priority: RenderPriority, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * 归还一次使用权（引用计数 -1），归零时才真正取消。
+     *
+     * 为什么不能直接 cancel：任务在多个调用方之间共享（同一 page@scale 可能被
+     * 可见区与预取区同时需要；React 严格模式下 effect 也会挂载两次）。
+     * 「谁先卸载谁就 cancel」会把别人仍需的任务杀掉 —— 表现为页面一直空白：
+     * 任务被 abort → Promise reject → 没有重试者。
+     */
+    release(key: string, reason?: unknown): void;
+    /** 取消某个 key（排队中直接丢弃，执行中触发 abort） */
+    cancel(key: string, reason?: unknown): void;
+    /** 丢弃所有未开始的预取任务，返回丢弃数量 */
+    dropPendingPrefetch(keep?: (key: string) => boolean): number;
+    get pending(): number;
+    get active(): number;
+    getStats(): {
+        started: number;
+        completed: number;
+        cancelled: number;
+    };
+    cancelAll(reason?: unknown): void;
+    private canStart;
+    private pump;
+    private start;
+}

package/dist/core/throttle.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 高频事件节流工具。
+ *
+ * H5 阅读器里滚动、捏合、尺寸变化、进度、搜索输入都是高频源，
+ * 一律先经过这里的三个工具再进入 React 状态，避免「一帧多次 setState」。
+ */
+export type AnyFn = (...args: any[]) => any;
+export interface Cancelable {
+    cancel(): void;
+    /** 立即执行挂起的调用（用于离开页面 / 提交前冲刷） */
+    flush(): void;
+    /** 是否有挂起调用 */
+    pending(): boolean;
+}
+/**
+ * 每帧最多执行一次。滚动、缩放等「跟手」操作首选。
+ */
+export declare function rafThrottle<T extends AnyFn>(fn: T): T & Cancelable;
+export interface ThrottleOptions {
+    /** 首次调用是否立即执行，默认 true */
+    leading?: boolean;
+    /** 尾随调用是否补一次，默认 true */
+    trailing?: boolean;
+}
+/**
+ * 固定时间窗节流（滚动进度、加载进度、日志上报）。
+ */
+export declare function throttle<T extends AnyFn>(fn: T, wait?: number, options?: ThrottleOptions): T & Cancelable;
+/**
+ * 防抖（搜索输入、缩放落定后的重渲染）。
+ */
+export declare function debounce<T extends AnyFn>(fn: T, wait?: number): T & Cancelable;
+/**
+ * 批量合并：把一帧内多次 push 的条目合成一次回调。
+ * 用于「500 页尺寸陆续到达」这类必须批量更新的场景。
+ */
+export declare function rafBatch<T>(onFlush: (items: T[]) => void, maxBatch?: number): {
+    push(item: T): void;
+    cancel(): void;
+};

package/dist/core/zoomAnimation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 缩放动画。
+ *
+ * pdfh5 有 `animationDuration`（默认 300ms），双击 / 按钮缩放走缓动动画而不是瞬变。
+ * 那个手感差异很明显：瞬变会让人「晕」，动画则保留了空间连续性。
+ *
+ * 实现要点：
+ * 1. 用 rAF 推进，缓动用 easeOutCubic（快进慢出，符合手指离开后的惯性直觉）；
+ * 2. 每帧回调的是「插值后的 zoom + 锚点滚位」，调用方只负责应用，不关心动画细节；
+ * 3. 可中途取消（用户再次触摸时立刻停下），避免和手势抢控制权；
+ * 4. 尊重 `prefers-reduced-motion`：系统要求减少动效时直接跳到终值。
+ */
+export interface ZoomAnimationOptions {
+    from: number;
+    to: number;
+    duration: number;
+    /** 每帧回调：progress 为 0-1 */
+    onUpdate: (zoom: number, progress: number) => void;
+    onDone?: () => void;
+    /** 缓动函数，默认 easeOutCubic */
+    easing?: (t: number) => number;
+}
+export interface AnimationHandle {
+    cancel(): void;
+    readonly finished: boolean;
+}
+/** 是否应当禁用动画（系统偏好 / 不可见页面） */
+export declare function shouldReduceMotion(): boolean;
+/**
+ * 启动一次缩放动画。
+ * duration <= 0 或系统要求减少动效时，同步跳到终值并立即结束。
+ */
+export declare function animateZoom(options: ZoomAnimationOptions): AnimationHandle;

package/dist/hooks/useElementSize.d.ts

@@ -0,0 +1,18 @@
+export interface ElementSize {
+    width: number;
+    height: number;
+}
+/**
+ * 观察容器尺寸。
+ *
+ * 关键点：必须用 callback ref 而不是 useRef + 挂载时 effect。
+ * 因为调用方常常「先渲染 loading 占位、加载完才渲染容器」，
+ * 用 useRef 的话首帧 ref 还是 null，effect 不会再跑，尺寸就永远停在 0。
+ *
+ * ResizeObserver 在拖动窗口 / 旋转屏幕时会连发多次，这里每帧合并一次再写 state。
+ */
+export declare function useElementSize<T extends HTMLElement>(): {
+    readonly ref: (node: T | null) => void;
+    readonly width: number;
+    readonly height: number;
+};

package/dist/hooks/usePageMetrics.d.ts

@@ -0,0 +1,27 @@
+import { PDFDocumentProxy, PDFPageProxy } from 'pdfjs-dist';
+import { PageMetric } from '../types';
+export interface UsePageMetricsResult {
+    metrics: ReadonlyArray<PageMetric | undefined>;
+    /** 已解析尺寸的页数（用于进度显示） */
+    resolved: number;
+    /** 取页面代理（带 LRU + 并发合并） */
+    getPage(pageNumber: number): Promise<PDFPageProxy>;
+    peekPage(pageNumber: number): PDFPageProxy | undefined;
+    /** 请求解析某一页的尺寸（幂等，滚动接近时调用） */
+    ensurePage(pageNumber: number): void;
+}
+export interface UsePageMetricsOptions {
+    /** 首屏并发解析的页数，默认 4 */
+    initialPages?: number;
+}
+/**
+ * 渐进式页面度量。
+ *
+ * 大文档不可能一次性 getPage() 全部页面（等于把整份文件解析一遍）。
+ * 这里分三层：
+ * 1. 首屏并发解析前 N 页，拿到真实尺寸；
+ * 2. 其余页先用「已解析页的平均尺寸」占位（layout 里传 fallback），滚动时不至于跳动；
+ * 3. 滚动接近某页时 ensurePage() 解析它 —— 尺寸校正走 rafBatch，一帧合并多页，
+ *    避免「多页尺寸同时到达 → 每页一次 setState → 布局抖动」。
+ */
+export declare function usePageMetrics(doc: PDFDocumentProxy | null, options?: UsePageMetricsOptions): UsePageMetricsResult;

package/dist/hooks/usePdfDocument.d.ts

@@ -0,0 +1,19 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+import { PdfSource } from '../types';
+export interface PdfDocumentState {
+    doc: PDFDocumentProxy | null;
+    numPages: number;
+    loading: boolean;
+    progress: {
+        loaded: number;
+        total: number;
+    } | null;
+    error: Error | null;
+    /** 需要密码时为 true */
+    needPassword: boolean;
+    /** pdf.js PasswordResponses：1 = NEED_PASSWORD，2 = INCORRECT_PASSWORD */
+    passwordReason: number;
+    submitPassword(password: string): void;
+    cancelPassword(): void;
+}
+export declare function usePdfDocument(source: PdfSource | null | undefined, enabled?: boolean): PdfDocumentState;

package/dist/hooks/usePinchGesture.d.ts

@@ -0,0 +1,41 @@
+import { PinchGeometry } from '../core/gestures';
+export interface PinchGestureOptions {
+    /** 滚动容器 */
+    scrollRef: React.RefObject<HTMLElement | null>;
+    /** 承载内容的元素（transform 作用在它身上） */
+    contentRef: React.RefObject<HTMLElement | null>;
+    enabled: boolean;
+    zoom: number;
+    minZoom: number;
+    maxZoom: number;
+    /** 双击目标倍率 */
+    doubleTapZoom: number;
+    /** 内容的最大滚动范围计算器 */
+    maxScroll: () => {
+        left: number;
+        top: number;
+    };
+    onCommit(zoom: number, scrollLeft: number, scrollTop: number): void;
+    /** 双击缩放（可选）。不提供时退化为 onCommit */
+    onDoubleTap?(zoom: number, scrollLeft: number, scrollTop: number): void;
+    onGestureStart?(): void;
+    onGestureEnd?(): void;
+}
+export interface PinchGestureState {
+    /** 捏合中（此时内容走 transform 预演） */
+    active: boolean;
+    /** 预演 transform；null 表示不预演 */
+    preview: PinchGeometry | null;
+}
+/**
+ * 双指捏合 + 双击缩放。
+ *
+ * 实现要点（移动端性能关键）：
+ * 1. 捏合过程中**不**改变真实 zoom，只设置一个 CSS transform 做预演 ——
+ *    transform 只触发合成，不触发布局 / 重绘，因此可以跟手到 60fps；
+ * 2. 松手时才提交 zoom + scroll，并清除 transform；
+ * 3. 用 pointerdown/move/up 统一处理（iOS Safari 13+ / Android Chrome 均支持），
+ *    配合 touch-action: none 阻止浏览器默认的整页缩放；
+ * 4. 双击使用本地时间戳判定，不依赖 300ms click 延迟。
+ */
+export declare function usePinchGesture(options: PinchGestureOptions): PinchGestureState;

package/dist/hooks/useVirtualPages.d.ts

@@ -0,0 +1,48 @@
+export interface VirtualWindow {
+    /** 需要真正挂载 DOM 的页（1 基，含首尾） */
+    mounted: number[];
+    /** 需要渲染位图的页 */
+    visible: number[];
+    /** 需要预渲染的页（可见区上下各 buffer 屏） */
+    prefetch: number[];
+    /** 当前阅读页 */
+    current: number;
+}
+export interface UseVirtualPagesOptions {
+    /** 页面盒子（来自 computeLayout），左右滚动时用 left/width */
+    boxes: ReadonlyArray<{
+        pageNumber: number;
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+    }>;
+    mode: 'scroll' | 'page';
+    /** 距离可见区多少屏开始预渲染，默认 1.2 */
+    prefetchScreens?: number;
+    /** 距离可见区多少屏开始挂载 DOM（比预渲染更远，保证快速滚动时不留白） */
+    mountScreens?: number;
+    /** 容器尺寸 */
+    viewportWidth: number;
+    viewportHeight: number;
+}
+/**
+ * 虚拟化：只挂载「看得见 + 缓冲」的页面 DOM。
+ *
+ * 为什么不直接渲染全部：500 页文档每页 2 个 canvas + 数百个 span，
+ * DOM 节点数和内存都会直接打爆移动端。
+ *
+ * 滚动位置由滚动容器自身维护（不用 transform 虚拟滚动），
+ * 因为原生滚动的惯性 / 回弹在 iOS 上无法用 JS 复刻。
+ */
+export declare function useVirtualPages(scrollRef: React.RefObject<HTMLElement | null>, options: UseVirtualPagesOptions): VirtualWindow;
+export interface ScrollProgress {
+    current: number;
+    total: number;
+    ratio: number;
+}
+/** 缩略图用的懒加载观察器：进入视口才渲染 */
+export declare function useInView<T extends Element>(rootMargin?: string): {
+    ref: React.RefObject<T | null>;
+    inView: boolean;
+};

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { PdfH5Reader, PdfH5ReaderProps as ReaderProps } from './components/PdfH5Reader';
+import { PdfH5ReaderHandle as ReaderHandle } from './types';
+export { PdfH5Reader };
+export type PdfH5ReaderProps = ReaderProps;
+export type PdfH5ReaderHandle = ReaderHandle;
+export { configurePdfjs, getPdfjsRuntimeOptions, loadPdf, loadPdfDocument, pdfjsLib } from './core/pdfjs';
+export type { PdfjsRuntimeOptions } from './core/pdfjs';
+export { LruCache } from './core/lru';
+export type { LruCacheOptions, LruCacheStats } from './core/lru';
+export { EventEmitter } from './core/eventEmitter';
+export type { Listener } from './core/eventEmitter';
+export type { ReaderEvents, ReaderEventName, ReaderEventPayload, ReaderStatus, RenderTiming, ScrollEventPayload, ZoomEventPayload, } from './core/readerEvents';
+export { animateZoom, shouldReduceMotion } from './core/zoomAnimation';
+export type { AnimationHandle, ZoomAnimationOptions } from './core/zoomAnimation';
+export { DEFAULT_ANNOTATION_STYLE, createAnnotationId, groupByPage, isAnnotationValid, isPointInPage, rectFromPoints, rectToPixel, toNormalized, toPixel, } from './core/annotations';
+export type { Annotation, AnnotationKind, AnnotationMode, AnnotationStyle, FreetextAnnotation, HighlightAnnotation, InkAnnotation, NormPoint, NormRect, } from './core/annotations';
+export { AnnotationLayer } from './components/AnnotationLayer';
+export type { AnnotationLayerProps } from './components/AnnotationLayer';
+export { rafThrottle, throttle, debounce, rafBatch } from './core/throttle';
+export type { Cancelable } from './core/throttle';
+export { BitmapCache, TextLayerCache, PageProxyCache, ThumbnailCache } from './core/cache';
+export { RenderQueue } from './core/renderQueue';
+export { computeLayout, pageAtOffset, offsetForPage, quantizeScale, quantizePixelRatio, viewportScaleFor, clampCanvasSize, bitmapBytes } from './core/layout';
+export type { PageBox, ViewerLayout } from './core/layout';
+export { pinchTransform, pinchCommit, doubleTapTarget, zoomAtPoint } from './core/gestures';
+export { usePdfDocument } from './hooks/usePdfDocument';
+export type { PdfDocumentState } from './hooks/usePdfDocument';
+export { usePageMetrics } from './hooks/usePageMetrics';
+export { usePinchGesture } from './hooks/usePinchGesture';
+export { useVirtualPages } from './hooks/useVirtualPages';
+export { useElementSize } from './hooks/useElementSize';
+export { searchDocument, extractPageText, clearSearchCache } from './lib/search';
+export { flattenOutline } from './lib/outline';
+export type { OutlineEntry } from './lib/outline';
+export { makeSnippet, splitSnippet, findInPage } from './lib/text';
+export { highlightTextNodes } from './lib/highlight';
+export { createThumbnailCanvas } from './lib/thumbnail';
+export type { CacheStatsSnapshot, FitMode, LoadProgress, PageMetric, PdfSource, SearchHit, ThemeMode, ViewerMode, } from './types';
+export declare function usePdfH5ReaderActions(ref: React.RefObject<PdfH5ReaderHandle | null>): {
+    next: () => void | undefined;
+    prev: () => void | undefined;
+    goTo: (page: number) => void | undefined;
+    zoomIn: () => void | undefined;
+    zoomOut: () => void | undefined;
+    resetZoom: () => void | undefined;
+};