React 指南

Reel 组件

Reel 组件是主容器，负责管理滑动器状态、处理触摸手势、键盘导航和动画。

自动尺寸

size 属性是可选的。省略时，Reel 会通过 ResizeObserver 自动测量容器，并适配由 CSS 决定的布局。容器的尺寸必须由父级决定（例如 flex、grid 或显式的 CSS 尺寸）。

itemBuilder 模式

itemBuilder 属性是一个函数，接收索引并返回该幻灯片的内容。正是这个模式让虚拟化成为可能 —— 只有可见的条目会被渲染。

导航

内置的导航方式：

• 触摸 / 滑动： 拖动即可翻页，带惯性和吸附
• 键盘： 方向键和 Escape
• 鼠标滚轮： 用 enableWheel 属性开启
• 编程式： 使用 apiRef for next(), prev(), goTo()

URL 状态

useOverlayUrlState 为浮层构建一个 URL 状态控制器并整个返回，你再把它作为 *UrlOverlay 的 controller 属性传进去。打开状态归 URL 所有，因此绑定后的浮层会自己打开，链接就是通常的打开方式。参数原本不存在时第一次写入压入一条历史记录，之后每次写入都是替换，所以翻页永远不会把返回键埋掉。留着控制器就能读取 value/position ，也能编程式地驱动它： set(position) 打开， set(null) 关闭，而 set 正是浮层内部在切换幻灯片时使用的底层写入。

选项对象接受 param, codec、 locator （这三个都是必填的），外加可选的 adapter。 codec 和 locator 是共用同一个 Id的配套组合，因此总是一起出现 —— 对于普通的 ?photo=3 画廊，展开 ...urlIndexKey(() => images.length)即可，它会一次性返回两半。 urlIndexKey 把参数映射成幻灯片索引，并以 getter 返回的实时数量为上界，因此过期或越界的 ?photo=99 会被拒绝并自动从 URL 中消失，而不是打开一张 URL 从未指定的幻灯片。请传 getter 而不是数字，这样分页信息流增长时上界依然正确。它包装了 createIndexLocator (the locator half) and pairs it with indexCodec。分页信息流或按身份寻址的画廊则自行提供配套的 codec + locator 。完整的选项表见 React API 参考.

ReelIndicator

可选组件，显示 Instagram 风格的进度指示器，标出当前在滑动器中的位置。放在 Reel内部时，它会通过上下文自动连接到父级的 count 和 active 值 —— 不需要手动接状态。

在线演示：基础滑动器

试试看 —— 点按钮在幻灯片之间切换。

要点

• size 属性

  可选的 [宽, 高] 元组；省略则由 CSS 自动决定尺寸

• itemBuilder

  接收索引并返回幻灯片内容

• apiRef

  访问控制器方法以进行导航

• afterChange

  跟踪当前索引以更新界面

在线演示：无限列表

reelkit 在任何时刻只渲染 DOM 里的 3 张幻灯片 （当前、上一张、下一张）。因此即便列表有 10,000+ 条目也能顺畅滚动。

10,000 个条目 —— DOM 里只有 3 个。用按钮或输入数字跳转。

在线演示：可增长列表

模拟按需加载的无限信息流 —— 就像 TikTok 或 Instagram。先加载 20 条，滚到接近末尾时，新的一批会自动到达。

滚到末尾 —— 新条目会自动加载。计数和指示器会随着批次到达而增长。

性能建议

• 缓存数据数组

  把条目数组用 useMemo包起来。每次渲染都产生新的数组引用会触发一次 count 更新并重新计算可见范围。

• 让 itemBuilder 保持轻量

  它在每次可见范围变化时都会运行（通常是 3 张幻灯片）。不要在里面做重计算或副作用。

• 临近边缘时加载数据

  使用 afterChange 来检测用户是否接近末尾，并在幻灯片用完之前取下一批（见上面的可增长列表演示）。

• 在可滚动页面里关掉滚轮

  把 enableWheel={false} ，当滑动器嵌在可滚动布局里时，避免抢走页面滚动。