翻页书 | Tuff Docs

概述

TxFlipBook 在左右静态书页之间翻动一张真实双面纸叶。v-model 是从 0 开始的当前右页索引。翻页过程中，纸叶正反面分别保留自己的页面内容。页面来自 pages 或 #page，组件不内置上游图片集合。

用法

Book、DitherBook 和内嵌宽屏书页

示例加载中...

演示提供文字页、自制 SVG 插槽图形、当前页滑块、真实翻页事件、纸张设置和开场重放。三种来源呈现都可使用：

模式	来源行为
`book`	核心 Book：左右静态页与双面旋转纸叶，不内置工具栏或设置。调用方可直接控制索引。
`dither-book`	DitherBook 组合：前后按钮、页面标题、设置面板、紧凑默认值和可选十次开场翻页。比例 16:10，透视 2400px，折痕宽度 48px，最终倾角 6°/−4°。
`extracted-book`	SimpleCompExtracted 的私有 Book：比例 16:9，透视 3000px，折痕宽度 64px，最终倾角 8°/−6°。桌面显示侧向 SVG 箭头，手机显示底部导航；浮动设置保留更大的参数范围。

DitherBook 开场等待 300ms，快速翻页时长为 140ms，间隔为 70ms；最后一次使用普通翻页时长，与来源一致。宽屏预设等待 800ms，每次为 120ms，间隔为 20ms。可见开场结束前，宽屏预设禁用手动前后切换。两种入口姿态与 1200/1500ms 入场时长也分别保留。可复用组件默认 intro=false，演示明确开启来源播放。

最佳实践

使用稳定的 id，并提供有权展示的文字或图片。组件不包含 Pinterest 图片或外部纸纹。
自制图形使用 #page="{ page, index, side }"。这个插槽会渲染在真实左右书页与翻动纸叶的正反面。
页面内容应为非交互内容，页面级翻页按钮会覆盖它。应用操作放在书页外。
需要保存编辑结果时使用 v-model:settings。单独参数优先于设置对象，设置对象优先于模式和紧凑默认值。
书页与图表组合使用 mode="extracted-book" size="lg"。父级背景点击可排除交互元素后调用 previous() 或 next()，不要注册文档级点击事件。
有限文档设置 loop=false。第一页之前的左页保持留白，边界按钮禁用。

API 参考

属性

属性	类型	默认值	说明
`pages`	`FlipBookPage[]`	必填	真实页面内容；空数组渲染 `#empty`。
`modelValue`	`number`	内部 `0`	当前右页索引，取整后循环或限制在边界内。
`mode`	`book / dither-book / extracted-book`	`dither-book`	核心模式或上表的来源组合预设。
`compact`	`boolean`	`false`	默认留白 6px、圆角 8px、阴影 10px。
`settings`	`Partial<FlipBookSettings>`	模式默认值	受控或编辑器设置对象。
`padding`	`number`	`10`，宽屏 `14`	图片或内容留白，单位为像素。
`imageRadius`	`number`	`20`，宽屏 `32`	图片或内容圆角，单位为像素。
`creaseOpacity`	`number`	`11`	折痕不透明度百分比。
`paperColor`	`string`	主题表面变量	纸张 CSS 颜色，支持主题变量表达式。
`shadowIntensity`	`number`	`24`，宽屏 `34`	内容阴影模糊范围，单位为像素。
`loop`	`boolean`	`true`	保留来源循环书页，或使用有限边界。
`controls`	`boolean`	`true`	显示组合模式的导航和标题；核心 `book` 不读取。
`settingsPanel`	`boolean`	`true`	显示组合模式设置入口与编辑器。
`intro`	`boolean`	`false`	可见时启动来源开场翻页。
`introFlips`	`number`	`10`	开场翻页次数。
`animated`	`boolean`	`true`	启用翻页和入场动效；关闭后立即完成操作。
`disabled`	`boolean`	`false`	禁止手动导航、重放和设置输入。
`duration`	`number`	`450`	普通翻页时长，单位为毫秒。
`size`	`xs / sm / md / lg`	`md`	最大宽度分别为 300/400/512/640px，随宿主收缩。
`ariaLabel`	`string`	`Flip book`	书页分组无障碍名称。
`labels`	`FlipBookLabels`	英文文字	前后按钮、设置、纸张字段和重放文字。

FlipBookPage 字段为 id?: string | number、title?: string、src?: string、alt?: string 和 content?: string。默认页在提供 src 时显示图片，否则显示标题和文字。FlipBookSettings 包含 padding、imageRadius、creaseOpacity、paperColor 和 shadowIntensity。FlipBookLabels 接受 previous、next、settings、padding、imageRadius、creaseOpacity、paperColor、shadowIntensity 和 intro。

DitherBook 编辑器的留白范围为 0～30，圆角和折痕为 0～40，阴影为 0～48。宽屏编辑器保留留白和折痕 0～100、圆角 0～32、阴影 0～50。直接传入属性不受编辑器范围限制。

事件

事件	参数	含义
`update:modelValue`	`index: number`	请求真实右页。
`update:settings`	`settings: FlipBookSettings`	纸张编辑器输入改变。
`change`	`page: FlipBookPage, index: number`	导航请求切换到其他调用方页面。
`flip-start`	`from: number, to: number, direction: 1 / -1`	翻页开始，也包含减少动态效果时的立即翻页。
`flip-end`	`index: number`	动画或立即完成后提交目标书页。

插槽与实例方法

API	契约
`#page`	`{ page, index, side }`；side 为 `left / right / front / back`。
`#empty`	没有页面时的内容。
`previous()` / `next()`	按来源禁用和开场规则翻页。
`goTo(index)`	请求页面，遵循禁用、翻页忙碌和循环或边界规则。
`replayIntro()`	仅在启用动画且未减少动态效果时重放，按可见状态开始或恢复。

左右方向键翻页，Home 和 End 请求首页或尾页。输入框保留原生键盘行为。页面级翻页按钮和工具栏按钮都有无障碍名称及聚焦轮廓。标题变化复用 TxTextMorph，不引入第二套文字动画引擎。

技术实现

来源是 Amicro 中采用 Apache-2.0 的 dither-charts/DitherBook.tsx 的 Book/DitherBook、字节相同的 simple-comp/DitherBook.tsx 和 simple-comp/SimpleCompExtracted.tsx 内独立的私有 Book。固定提交为 43c29ce9cdd16459e3eab4992381b8d35b38776a。分发保留 Vue/TuffEx 修改声明和完整 Apache 许可，仓库 MIT 声明不覆盖文件级许可。

纸叶使用原生 Web 动画接口和已有共享弹簧时间曲线。useMotionActivity 统一管理可见性、文档状态、KeepAlive 和减少动态效果。失活或卸载时取消定时器与动画，正在失活的翻页提交目标状态。减少动态效果跳过开场，手动翻页仍会立即完成。纸纹由本地 CSS 生成，不请求网络素材。