@gullabs/react-flipbook

中文文档
3.2.2发布于 2026/10/01MITTypeScriptESM + CJS构建来源已验证近 30 天下载 5779

反应 18/19 绑定@gullabs/flipbook-core. 维持了反应分叉-pageflip.

中文使用文档
文档目录4 节
  1. 快速启动
  2. 首小时规则
  3. 常见道具和活动
  4. 许可证

@ gullabs/ 反应- flipbook

反应18/19 装订 @gullabs/flipbook-core。 。 。 . 维持了反应分叉-pageflip. 许可证 : 麻省理工学院 (引擎依赖是MPL-2.0).

完整单重文件 :

npm i @gullabs/react-flipbook
# pulls @gullabs/flipbook-core; react is a peer (>=18)

快速启动

import { useState } from 'react';
import HTMLFlipBook, { type BookSnapshot } from '@gullabs/react-flipbook';

export function Book() {
  // Seed from onLoaded. onPageChange fires only for real turns, never on mount.
  const [book, setBook] = useState<{ page: number; pageCount: number } | null>(null);
  const sync = (s: BookSnapshot) => setBook({ page: s.page, pageCount: s.pageCount });

  return (
    <>
      <p>{book ? `Page ${book.page + 1} of ${book.pageCount}` : 'Loading…'}</p>
      <HTMLFlipBook width={300} height={500} onLoaded={sync} onPageChange={sync}>
        {/* Host element required. Style content on an INNER wrapper — the
            engine owns layout + paper on the leaf root. */}
        <div>
          <div style={{ height: '100%', padding: 16 }}>Page 1</div>
        </div>
        <div>
          <div style={{ height: '100%', padding: 16 }}>Page 2</div>
        </div>
      </HTMLFlipBook>
    </>
  );
}

首小时规则

  1. onLoaded 初始计数器 —— 说 onPageChange / 核心 flip 别 在挂载上起火(仅在页索引实际变化时起火).
  2. 内置包装符样式,而不是叶根. 引擎写位置, 大小、剪接和纸张在根上.
  3. 已控制 page 需求 onPageChange - 否则引擎会转动 你的道具把它折回(一本被锁入的书).
  4. 不驱动 initialPage 从活的 URL 状态 - 这是一个重挂键. 冻结在山上或使用控制的深层链接 page。 。 。 .
  5. 保持页面儿童身份稳定 onTurnProgress。 。 。 . 纪念 页面元素。 一个在每次进步中重建它们的父母 都会流泪 书到中途。 把洗手手手拇指放进兄弟会,别放在页面上 孩子们.

常见道具和活动

宣传/事件作用
width 编号 : height需要的页面大小
page + 键 onPageChange控制页面( 可选) pageTransition数字 : 'animate' | 'instant'(中文(简体) )
onLoaded 编号 : onReady初始 / 一次/ 一次引擎快照( E)page, (中文(简体) ), pageCount, (中文(简体) ), visiblePages, (...) (中文(简体) )
onTurnProgress折叠进度 0…1 在动画或拖动时。 静静地在瞬间/减速转弯和悬浮地皮上 解决 onPageChange 编号 : onChangeState。 。 。 .
lazyRadius仅反应窗口 。 核心 PageFlip 忽略它; 香草主机必须窗口 DOM 本身 .
onTurnRejected转动未启动( T)reason, (中文(简体) ), direction, (中文(简体) ), targetPage, (中文(简体) ), landedOn(中文(简体) )
controls'auto' | 'visible' | 'none'
hardCovers单叶覆盖,密度高
pageBackground纸张颜色( 任何 CSS 颜色; 不透明为结构)
injectStyles默认 true; 设置 false 严格CSP和进口核心 style.css
页面媒体纵向卷发会结冰 <video> 作为画布和条纹 <audio>。 。 。 . video[controls], (中文(简体) ), audio[controls], (中文(简体) ), iframe, (中文(简体) ), embed,以及 object 不要开始折叠。 播放并暂停停留主机的工作——参见核心README.

处理方法ref → FlipBookHandle:

方法作用
flipNext 编号 : flipPrev相对转动( A)boolean(中文(简体) )
flipToPage(n)动画到页面( A)boolean(中文(简体) )
turnToPage(n)即时跳跃( I)boolean(中文(简体) )
cancelTurn()放弃在飞行中转弯而不作出承诺. read 在肖像复制被移除后,在完成的转弯和取消时起火.
destroy()把引擎拆下来 财务报告和审定财务报表 退出反弹壳
pageFlip()逃生舱-核心 PageFlip | null

查询诸如 getPageCount 编号 : getVisiblePages 住在这里 引擎 (单位:千美元)pageFlip()?.getPageCount())或打开 usePageFlip() 状态——不在握把上. 偏爱 destroy() 把手放在那边 pageFlip()?.destroy(): 后一眼泪 引擎关闭,但在下一次渲染之前不退出反弹壳.

许可证

麻省理工为这个包裹。 发动机@gullabs/flipbook-core)是MPL-2.0——见 https://github.com/gul-labs/flipbook/blob/main/packages/core/LICENSE 互联网档案馆的存檔,存档日期2013-12-02。 。 。 .

版权 (c) 2026 Gul Labs.

版本与发布记录

@gullabs/react-flipbook 共发布 5 个版本,首次发布于 2026/08/31;过去 12 个月发布了 5 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.2.2latest2026/10/011 个月前
3.2.12026/09/092 个月前
3.2.02026/09/092 个月前
3.1.02026/09/012 个月前
3.0.02026/08/312 个月前

关于 @gullabs/react-flipbook 的常见问题

@gullabs/react-flipbook 是什么?

反应 18/19 绑定@gullabs/flipbook-core. 维持了反应分叉-pageflip.

如何安装 @gullabs/react-flipbook?

在项目目录运行 npm install @gullabs/react-flipbook,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=18)、react-dom(>=18)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gullabs/react-flipbook 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gullabs/react-flipbook 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gullabs/react-flipbook 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.18.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gullabs/react-flipbook 可以商用吗?

@gullabs/react-flipbook 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gullabs/react-flipbook 的下载量有多少?

根据 npm 官方下载统计,@gullabs/react-flipbook 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,779 次,日均约 193 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gullabs/react-flipbook 还在维护吗?

最新版本 3.2.2 发布于 2026/10/01(1 个月前);至今共发布 5 个版本,其中过去 12 个月发布了 5 个;首次发布于 2026/08/31。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。