# @gullabs/react-flipbook 中文文档

规范地址：https://npmcn.com/package/%40gullabs/react-flipbook/

版本：3\.2\.2
npm 元数据更新时间：2026-10-01T03:47:02.207Z
中文译文更新时间：2026-11-17T06:13:11.691Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gullabs/react-flipbook
原文对照：https://npmcn.com/package/%40gullabs/react-flipbook/?lang=original
项目主页：https://github.com/gul-labs/flipbook/tree/main/packages/react#readme
源码仓库：https://github.com/gul-labs/flipbook

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：311 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18\.0
- 运行依赖：1 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-08-31T11:47:06.945Z
- 最新版本发布：2026-10-01T03:47:01.849Z
- 近 30 天下载量：5779（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

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

## 安装

```sh
npm install @gullabs/react-flipbook
```

也可以使用：`pnpm add @gullabs/react-flipbook`、`yarn add @gullabs/react-flipbook`、`bun add @gullabs/react-flipbook`

## README

# @ gullabs/ 反应- flipbook

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

完整单重文件 :

-   [https://github.com/gul-labs/flipbook#readme 页面存档备份,存于互联网档案馆](https://github.com/gul-labs/flipbook#readme)
-   从 `react-pageflip@2.x`数字 : [https://github.com/gul-labs/flipbook/blob/main/MIGARINE.md 互联网档案馆的存檔,存档日期2014-12-21](https://github.com/gul-labs/flipbook/blob/main/MIGRATION.md)
-   已锁定 API 表面 : [https://github.com/gul-labs/flipbook/blob/main/docs/API-CONTRACT.md 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/gul-labs/flipbook/blob/main/docs/API-CONTRACT.md)
-   活页面 (描述/ 突出显示) : [https://github.com/gul-labs/flipbook/blob/main/docs/LIVE-PAGE-FACES.md 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/gul-labs/flipbook/blob/main/docs/LIVE-PAGE-FACES.md)

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

## 快速启动

```tsx
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](https://github.com/gul-labs/flipbook/blob/main/packages/core/LICENSE)。 。 。 .

版权 (c) 2026 Gul Labs.

## 常见问题

### @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 和提交记录判断。

