feat: interactive book

Author: wkylin

src/components/stateless/InteractiveBook/InteractiveBook.mdx

@@ -9,18 +9,21 @@ import * as InteractiveBookStories from './InteractiveBook.stories'
 
 # InteractiveBook
 
-3D 交互式书籍组件，支持翻页动画、键盘导航和自定义内容。
+3D 交互式书籍组件，支持翻页动画、键盘导航和自定义内容。提供 JSX 内容、图片和 PDF 三种渲染模式。
 
 ## 组件特性
 
-- 🎨 3D 翻页动画效果
+- 🎨 3D 翻页动画效果（基于 Framer Motion）
 - ⌨️ 完整的键盘导航支持（箭头键、Escape、Home、End）
 - 📖 双面内容显示（正面内容 + 背面内容）
-- � 页角海浪卷起翻页提示
-- 🖱️ 拖拽翻页 & 点击翻页
-- �🎯 空状态处理
+- 🌊 页角海浪卷起翻页提示（可配置隐藏）
+- 🖱️ 拖拽翻页 & 点击翻页（速度感知阈值）
+- 🎯 空状态处理
 - 🔄 页面变化回调
 - 📱 响应式设计
+- 🖼️ 图片模式（逐页图片渲染，智能懒加载）
+- 📄 PDF 模式（react-pdf 渲染，本地 Worker，不依赖 CDN）
+- 🔧 可配置导航栏和页角翻页热区
 
 ## 组件预览
 
@@ -44,15 +47,65 @@ import * as InteractiveBookStories from './InteractiveBook.stories'
   <Story of={InteractiveBookStories.FewPages} />
 </Canvas>
 
+## 图片模式
+
+传入 `pageImages` 数组后，书页内容改为逐页渲染图片。仅预加载当前页 ±2 范围内的图片，支持几百页不卡顿。
+
+<Canvas>
+  <Story of={InteractiveBookStories.ImageBook} />
+</Canvas>
+
+## PDF 模式
+
+传入 `pdfUrl` 后，使用 react-pdf 渲染 PDF 文件。本地 Worker，不依赖 CDN。每两页 PDF 组成一个书页（正面 + 背面）。
+
+<Canvas>
+  <Story of={InteractiveBookStories.PdfBook} />
+</Canvas>
+
+## 隐藏导航栏
+
+设置 `showNavigation={false}` 可隐藏底部导航栏，仅保留拖拽、页角点击和键盘翻页方式。
+
+<Canvas>
+  <Story of={InteractiveBookStories.HideNavigation} />
+</Canvas>
+
+## 隐藏页角翻页热区
+
+设置 `showCornerFlip={false}` 可隐藏页角海浪翻页热区，仅保留拖拽、导航栏和键盘翻页方式。
+
+<Canvas>
+  <Story of={InteractiveBookStories.HideCornerFlip} />
+</Canvas>
+
+## 极简模式
+
+同时隐藏导航栏和页角翻页热区，仅保留拖拽和键盘翻页，适合嵌入式场景。
+
+<Canvas>
+  <Story of={InteractiveBookStories.MinimalMode} />
+</Canvas>
+
 ## Props（可调参数）
 
 <ArgTypes />
 
 <Controls />
 
+## 渲染模式优先级
+
+组件支持三种渲染模式，优先级从高到低：
+
+| 优先级 | 模式     | 触发条件         | 说明                                     |
+| ------ | -------- | ---------------- | ---------------------------------------- |
+| 1      | PDF 模式 | 传入 `pdfUrl`    | 使用 react-pdf 渲染 PDF 文件             |
+| 2      | 图片模式 | 传入 `pageImages`| 逐页加载图片，智能懒加载当前页 ±2 范围   |
+| 3      | JSX 模式 | 传入 `pages`     | 自定义 React 内容，支持正面/背面         |
+
 ## 基本使用
 
-### 简单使用
+### JSX 模式（默认）
 
 ```tsx
 import InteractiveBook from '@stateless/InteractiveBook'
@@ -81,6 +134,52 @@ function Example() {
 }
 ```
 
+### 图片模式
+
+```tsx
+import InteractiveBook from '@stateless/InteractiveBook'
+
+// 每张图片对应书的一面，两张组成一个书页（正面 + 背面）
+const pageImages = [
+  '/images/page1.jpg',
+  '/images/page2.jpg',
+  '/images/page3.jpg',
+  // ... 更多图片
+]
+
+function Example() {
+  return (
+    <InteractiveBook
+      coverImage="https://example.com/cover.jpg"
+      bookTitle="图片翻书"
+      pages={[]}
+      pageImages={pageImages}
+      width={350}
+      height={500}
+    />
+  )
+}
+```
+
+### PDF 模式
+
+```tsx
+import InteractiveBook from '@stateless/InteractiveBook'
+
+function Example() {
+  return (
+    <InteractiveBook
+      coverImage="https://example.com/cover.jpg"
+      bookTitle="PDF 文档"
+      pages={[]}
+      pdfUrl="/assets/pdf/sample.pdf"
+      width={350}
+      height={500}
+    />
+  )
+}
+```
+
 ### 带回调的使用
 
 ```tsx
@@ -104,6 +203,25 @@ function Example() {
 }
 ```
 
+### 配置导航和页角翻页
+
+```tsx
+import InteractiveBook from '@stateless/InteractiveBook'
+
+function Example() {
+  return (
+    <InteractiveBook
+      coverImage="https://example.com/cover.jpg"
+      bookTitle="极简模式"
+      pages={pages}
+      showNavigation={false}    // 隐藏底部导航栏
+      showCornerFlip={false}    // 隐藏页角翻页热区
+      enableKeyboard={true}     // 保留键盘翻页
+    />
+  )
+}
+```
+
 ## 页面数据结构
 
 ```tsx
@@ -117,44 +235,42 @@ interface BookPage {
 
 ## 键盘导航
 
-组件支持以下键盘操作：
+组件支持以下键盘操作（需设置 `enableKeyboard={true}`）：
 
-- `←` / `→`：前后翻页
-- `Escape`：关闭书籍
-- `Home`：回到封面
-- `End`：跳到最后一页
+| 快捷键     | 功能       |
+| ---------- | ---------- |
+| `←`        | 向前翻页   |
+| `→`        | 向后翻页   |
+| `Escape`   | 关闭书籍   |
+| `Home`     | 回到封面   |
+| `End`      | 跳到最后页 |
 
 ## 交互方式
 
 组件支持多种翻页交互方式：
 
-| 交互方式      | 说明                                                |
-| ------------- | --------------------------------------------------- |
-| 拖拽翻页      | 在页面上按住并左右拖拽，超过阈值后松手翻页          |
-| 页角点击      | 鼠标悬停在页面右下角/左下角，出现卷起效果后点击翻页 |
-| 导航栏按钮    | 底部导航栏的前后翻页按钮                            |
-| 键盘快捷键    | 方向键、Home、End、Escape                           |
-| 封面点击/拖拽 | 点击或向左拖拽封面打开书籍                          |
+| 交互方式      | 说明                                                | 可配置     |
+| ------------- | --------------------------------------------------- | ---------- |
+| 拖拽翻页      | 在页面上按住并左右拖拽，超过阈值后松手翻页          | 始终可用   |
+| 页角点击      | 鼠标悬停在页面右下角/左下角，出现卷起效果后点击翻页 | `showCornerFlip` |
+| 导航栏按钮    | 底部导航栏的前后翻页按钮                            | `showNavigation` |
+| 键盘快捷键    | 方向键、Home、End、Escape                           | `enableKeyboard` |
+| 封面点击/拖拽 | 点击或向左拖拽封面打开书籍                          | 始终可用   |
 
 > **注意**：最后一页（结束页）禁用拖拽，鼠标光标恢复为普通箭头。
 
 ## 高级用法
 
 ### 自定义样式
 
-组件使用 CSS Modules，可以通过以下方式定制样式：
-
-```less
-// 自定义样式文件
-.my-book {
-  .container {
-    // 自定义容器样式
-  }
+组件使用 CSS Modules（Less），可以通过 `className` 传入自定义样式：
 
-  .emptyState {
-    // 自定义空状态样式
-  }
-}
+```tsx
+<InteractiveBook
+  className="my-custom-book"
+  coverImage="/cover.jpg"
+  pages={pages}
+/>
 ```
 
 ### 响应式设计
@@ -175,3 +291,6 @@ interface BookPage {
 - 封面图片建议使用合适的尺寸以获得最佳显示效果
 - 组件内部使用 Framer Motion 进行动画，性能已优化
 - 空页面数组会显示友好的空状态提示
+- PDF 模式使用本地 Worker（`pdfjs-dist/build/pdf.worker.min.mjs`），无需外部 CDN
+- 图片模式仅预加载当前页 ±2 范围的图片，适合大量页面场景
+- `pdfUrl` 优先级高于 `pageImages`，`pageImages` 优先级高于 `pages`

src/components/stateless/InteractiveBook/InteractiveBook.stories.tsx

@@ -224,11 +224,15 @@ const meta: Meta<typeof InteractiveBook> = {
   title: 'Stateless/InteractiveBook',
   component: InteractiveBook,
   argTypes: {
-    bookTitle: { control: 'text' },
-    bookAuthor: { control: 'text' },
-    width: { control: 'number' },
-    height: { control: 'number' },
-    enableKeyboard: { control: 'boolean' },
+    bookTitle: { control: 'text', description: '书籍标题' },
+    bookAuthor: { control: 'text', description: '书籍作者' },
+    width: { control: 'number', description: '书页宽度（px）' },
+    height: { control: 'number', description: '书页高度（px）' },
+    enableKeyboard: { control: 'boolean', description: '是否启用键盘导航' },
+    showNavigation: { control: 'boolean', description: '是否显示底部导航栏' },
+    showCornerFlip: { control: 'boolean', description: '是否显示页角翻页热区（海浪呼吸效果）' },
+    pageImages: { control: 'object', description: '图片模式：图片 URL 数组，每张图片对应书的一面' },
+    pdfUrl: { control: 'text', description: 'PDF 模式：PDF 文件 URL' },
   },
   parameters: {
     layout: 'centered',
@@ -390,3 +394,74 @@ export const PdfBook: Story = {
     enableKeyboard: true,
   },
 }
+
+// ─── 隐藏导航栏 ─────────────────────────────────────
+export const HideNavigation: Story = {
+  name: '隐藏底部导航栏',
+  render: (args: InteractiveBookProps) => (
+    <div className="flex h-[800px] w-full flex-col items-center justify-center gap-4 bg-neutral-100 p-10">
+      <p style={{ color: '#6b7280', fontSize: '0.875rem', textAlign: 'center', maxWidth: 460 }}>
+        设置 <code>showNavigation=false</code> 隐藏底部导航栏，仅保留拖拽、页角点击和键盘翻页方式。
+      </p>
+      <InteractiveBook {...args} />
+    </div>
+  ),
+  args: {
+    coverImage: AiCover,
+    bookTitle: 'AI Agent 完全指南',
+    bookAuthor: 'AI 专家',
+    pages: bookPages,
+    width: 350,
+    height: 500,
+    enableKeyboard: true,
+    showNavigation: false,
+  },
+}
+
+// ─── 隐藏页角翻页 ─────────────────────────────────────
+export const HideCornerFlip: Story = {
+  name: '隐藏页角翻页热区',
+  render: (args: InteractiveBookProps) => (
+    <div className="flex h-[800px] w-full flex-col items-center justify-center gap-4 bg-neutral-100 p-10">
+      <p style={{ color: '#6b7280', fontSize: '0.875rem', textAlign: 'center', maxWidth: 460 }}>
+        设置 <code>showCornerFlip=false</code> 隐藏页角海浪翻页热区，仅保留拖拽、导航栏和键盘翻页方式。
+      </p>
+      <InteractiveBook {...args} />
+    </div>
+  ),
+  args: {
+    coverImage: AiCover,
+    bookTitle: 'AI Agent 完全指南',
+    bookAuthor: 'AI 专家',
+    pages: bookPages,
+    width: 350,
+    height: 500,
+    enableKeyboard: true,
+    showCornerFlip: false,
+  },
+}
+
+// ─── 极简模式（同时隐藏导航栏和页角翻页）─────────────
+export const MinimalMode: Story = {
+  name: '极简模式',
+  render: (args: InteractiveBookProps) => (
+    <div className="flex h-[800px] w-full flex-col items-center justify-center gap-4 bg-neutral-100 p-10">
+      <p style={{ color: '#6b7280', fontSize: '0.875rem', textAlign: 'center', maxWidth: 460 }}>
+        同时设置 <code>showNavigation=false</code> 和 <code>showCornerFlip=false</code>，
+        仅保留拖拽和键盘翻页，适合嵌入式场景。
+      </p>
+      <InteractiveBook {...args} />
+    </div>
+  ),
+  args: {
+    coverImage: AiCover,
+    bookTitle: 'AI Agent 完全指南',
+    bookAuthor: 'AI 专家',
+    pages: bookPages,
+    width: 350,
+    height: 500,
+    enableKeyboard: true,
+    showNavigation: false,
+    showCornerFlip: false,
+  },
+}

src/components/stateless/InteractiveBook/index.module.less

@@ -586,8 +586,8 @@
 
 .page.dragging {
   box-shadow:
-    0 10px 30px rgb(0 0 0 / 20%),
-    0 0 0 2px rgb(59 130 246 / 15%);
+    0 2px 16px rgb(0 0 0 / 14%),
+    0 0 0 1px rgb(59 130 246 / 10%);
 
   &::before {
     content: '';