feat: 书籍列表

Author: wkylin

src/components/stateless/InteractiveBook/InteractiveBook.mdx

@@ -87,6 +87,22 @@ import * as InteractiveBookStories from './InteractiveBook.stories'
   <Story of={InteractiveBookStories.MinimalMode} />
 </Canvas>
 
+## 翻页音效（开启）
+
+默认开启翻页音效（`enableSound={true}`），翻页时会播放纸张翻动的声音。点击、拖拽、键盘翻页均触发音效。
+
+<Canvas>
+  <Story of={InteractiveBookStories.SoundEnabled} />
+</Canvas>
+
+## 翻页音效（禁用）
+
+设置 `enableSound={false}` 禁用翻页音效，适合需要安静环境的场景。
+
+<Canvas>
+  <Story of={InteractiveBookStories.SoundDisabled} />
+</Canvas>
+
 ## Props（可调参数）
 
 <ArgTypes />
@@ -222,6 +238,32 @@ function Example() {
 }
 ```
 
+### 翻页音效配置
+
+```tsx
+import InteractiveBook from '@stateless/InteractiveBook'
+
+function Example() {
+  return (
+    <>
+      {/* 默认开启音效 */}
+      <InteractiveBook
+        coverImage="/cover.jpg"
+        pages={pages}
+        enableSound={true}
+      />
+
+      {/* 禁用音效 */}
+      <InteractiveBook
+        coverImage="/cover.jpg"
+        pages={pages}
+        enableSound={false}
+      />
+    </>
+  )
+}
+```
+
 ## 页面数据结构
 
 ```tsx
@@ -255,6 +297,7 @@ interface BookPage {
 | 页角点击      | 鼠标悬停在页面右下角/左下角，出现卷起效果后点击翻页 | `showCornerFlip` |
 | 导航栏按钮    | 底部导航栏的前后翻页按钮                            | `showNavigation` |
 | 键盘快捷键    | 方向键、Home、End、Escape                           | `enableKeyboard` |
+| 翻页音效      | 翻页时播放纸张翻动音效                              | `enableSound`    |
 | 封面点击/拖拽 | 点击或向左拖拽封面打开书籍                          | 始终可用   |
 
 > **注意**：最后一页（结束页）禁用拖拽，鼠标光标恢复为普通箭头。

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

@@ -231,6 +231,7 @@ const meta: Meta<typeof InteractiveBook> = {
     enableKeyboard: { control: 'boolean', description: '是否启用键盘导航' },
     showNavigation: { control: 'boolean', description: '是否显示底部导航栏' },
     showCornerFlip: { control: 'boolean', description: '是否显示页角翻页热区（海浪呼吸效果）' },
+    enableSound: { control: 'boolean', description: '是否启用翻页音效' },
     pageImages: { control: 'object', description: '图片模式：图片 URL 数组，每张图片对应书的一面' },
     pdfUrl: { control: 'text', description: 'PDF 模式：PDF 文件 URL' },
   },
@@ -465,3 +466,49 @@ export const MinimalMode: Story = {
     showCornerFlip: false,
   },
 }
+
+// ─── 翻页音效（开启）─────────────────────────
+export const SoundEnabled: 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>enableSound=true</code>），翻页时会播放纸张翻动的声音。 点击、拖拽、键盘翻页均触发音效。
+      </p>
+      <InteractiveBook {...args} />
+    </div>
+  ),
+  args: {
+    coverImage: AiCover,
+    bookTitle: 'AI Agent 完全指南',
+    bookAuthor: 'AI 专家',
+    pages: bookPages,
+    width: 350,
+    height: 500,
+    enableKeyboard: true,
+    enableSound: true,
+  },
+}
+
+// ─── 翻页音效（禁用）─────────────────────────
+export const SoundDisabled: 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>enableSound=false</code> 禁用翻页音效，适合需要安静环境的场景。
+      </p>
+      <InteractiveBook {...args} />
+    </div>
+  ),
+  args: {
+    coverImage: AiCover,
+    bookTitle: 'AI Agent 完全指南',
+    bookAuthor: 'AI 专家',
+    pages: bookPages,
+    width: 350,
+    height: 500,
+    enableKeyboard: true,
+    enableSound: false,
+  },
+}

src/components/stateless/InteractiveBook/index.tsx

@@ -53,6 +53,16 @@ export interface InteractiveBookProps {
   showNavigation?: boolean
   /** 是否显示页角翻页热区（海浪呼吸效果），默认 true */
   showCornerFlip?: boolean
+  /** 是否启用翻页音效，默认 true */
+  enableSound?: boolean
+  /** 自定义音效文件 URL，默认使用内置翻页音效 */
+  soundSrc?: string
+  /** 初始是否打开书籍（跳过封面动画），默认 false */
+  defaultOpen?: boolean
+  /** 受控模式：外部控制书籍开合状态。传入后会覆盖内部 isOpen */
+  open?: boolean
+  /** 书籍关闭时的回调（用户点击关闭按钮时触发） */
+  onClose?: () => void
 }
 
 // ─── 图片懒加载组件 ────────────────────────────────
@@ -274,8 +284,25 @@ export default function InteractiveBook({
   enableKeyboard = true,
   showNavigation = true,
   showCornerFlip = true,
+  enableSound = true,
+  soundSrc,
+  defaultOpen = false,
+  open: controlledOpen,
+  onClose,
 }: InteractiveBookProps) {
-  const [isOpen, setIsOpen] = useState(false)
+  const [isOpen, setIsOpen] = useState(controlledOpen ?? defaultOpen)
+
+  // 受控模式：外部 open 变化时同步内部状态
+  useEffect(() => {
+    if (controlledOpen === undefined) return
+    if (controlledOpen !== isOpen) {
+      setIsOpen(controlledOpen)
+      if (!controlledOpen) {
+        setCurrentPageIndex(-1)
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [controlledOpen])
   const [currentPageIndex, setCurrentPageIndex] = useState(-1)
   const [isHovering, setIsHovering] = useState(false)
   const [isDragging, setIsDragging] = useState(false)
@@ -294,6 +321,7 @@ export default function InteractiveBook({
   // 使用 DOM <audio> 元素而非 new Audio()，在 Storybook iframe 中更可靠
   const audioRef = useRef<HTMLAudioElement | null>(null)
   const playPageTurnSound = () => {
+    if (!enableSound) return
     const audio = audioRef.current
     if (!audio) return
     audio.currentTime = 0
@@ -326,6 +354,7 @@ export default function InteractiveBook({
     e.stopPropagation()
     setIsOpen(false)
     setCurrentPageIndex(-1)
+    onClose?.()
   }
 
   const nextPage = (e: React.MouseEvent) => {
@@ -1280,7 +1309,7 @@ export default function InteractiveBook({
       )}
 
       {/* 翻页音效 — 使用 DOM audio 元素，兼容 Storybook iframe */}
-      <audio ref={audioRef} src={pageTurnAudio} preload="auto" />
+      {enableSound && <audio ref={audioRef} src={soundSrc || pageTurnAudio} preload="auto" />}
     </div>
   )
 }