React API 参考

完整参考： @reelkit/react 的组件、属性与方法。

Reel 属性

ReelProps

属性	类型	默认值	说明
count	number	required	条目总数
size	[number, number]	-	以 [宽, 高] 表示的尺寸。省略时通过 ResizeObserver 自动测量
itemBuilder	(index, indexInRange, size) => ReactElement	required	渲染每张幻灯片的函数
direction	'vertical' \| 'horizontal'	'vertical'	滚动方向
initialIndex	number	0	起始索引
loop	boolean	false	启用无限循环
enableWheel	boolean	false	启用鼠标滚轮导航
wheelDebounceMs	number	200	滚轮事件防抖时长（毫秒）
enableNavKeys	boolean	true	启用键盘导航
onNavKeyPress	(increment: -1 \| 1) => void	-	方向键导航的自定义处理器。会替换默认的上一张 / 下一张行为。
transition	TransitionTransformFn	slideTransition	过渡效果函数。内置有 slideTransition、fadeTransition、flipTransition、cubeTransition、zoomTransition
transitionDuration	number	300	动画时长（毫秒）
enableGestures	boolean	true	启用触摸 / 鼠标拖拽导航
swipeDistanceFactor	number	0.12	滑动阈值（0-1）
rangeExtractor	(index: number, count: number) => number[]	defaultRangeExtractor	自定义函数，决定渲染哪些索引
keyExtractor	(index: number) => string	-	供 React 协调使用的自定义 key 函数（配合 loop 时很有用）
apiRef	RefObject<ReelApi>	-	用于访问 API 方法的 ref
className	string	-	容器元素的 CSS 类名
style	CSSProperties	-	容器元素的内联样式
ariaLabel	string	-	轮播区域的无障碍标签，供屏幕阅读器朗读

回调

属性	类型	说明
afterChange	(index, indexInRange) => void	幻灯片切换完成后调用
beforeChange	(index, nextIndex, indexInRange) => void	幻灯片切换开始前调用
onSlideDragStart	(index) => void	拖拽手势开始时调用
onSlideDragEnd	(index) => void	拖拽手势结束时调用
onSlideDragCanceled	(index) => void	拖拽被取消时调用

ReelApi 方法

通过 apiRef:

typescript

方法	类型	说明
next()	() => void	切到下一张幻灯片
prev()	() => void	切到上一张幻灯片
goTo(index, animate?)	(number, boolean?) => Promise	切到指定幻灯片
adjust()	() => void	重新计算幻灯片位置
observe()	() => void	开始监听键盘
unobserve()	() => void	停止监听键盘

ReelIndicator 属性

ReelIndicatorProps

属性	类型	默认值	说明
count	number	auto	条目总数。嵌套在 Reel 内部时会自动从父级连接；单独使用时请显式传入
active	number	auto	当前活动索引。嵌套在 Reel 内部时会自动从父级连接；单独使用时请显式传入
direction	'vertical' \| 'horizontal'	'vertical'	指示器方向
radius	number	3	圆点尺寸（像素）
visible	number	5	正常尺寸圆点的最大可见数量
gap	number	4	圆点之间的间距（像素）
activeColor	string	'#fff'	活动圆点颜色
inactiveColor	string	'rgba(255,255,255,0.5)'	非活动圆点颜色
edgeScale	number	0.5	溢出边缘圆点的缩放比例
onDotClick	(index: number) => void	-	点击圆点时的回调
className	string	-	自定义 CSS 类名
style	CSSProperties	-	自定义内联样式

观察者组件

Observe

把核心信号桥接到 React 渲染，且不会引起父组件重渲染。订阅的信号变化时，只有 children 函数会重新执行。

tsx

属性	类型	默认值	说明
signals	Subscribable[]	required	要订阅的信号。其中任意一个发出通知都会重新执行 children 函数 —— 且只有这个函数，父组件不受影响。
children	() => ReactElement \| null	required	渲染函数，每次变化都会重新执行。请在它内部读取信号的值；在外部读取的值只会被捕获一次，然后就过期了。

AnimatedObserve

订阅动画值信号，并用 requestAnimationFrame.

tsx

属性	类型	默认值	说明
signal	Signal<AnimatedValue>	required	发出 { value, duration, done? } 的信号。duration 大于 0 时会从当前值插值过渡到新值；为 0 则直接跳过去。
children	(value: number) => ReactElement	required	渲染函数，接收当前帧的插值结果，并同步提交，让 DOM 跟得上动画。

Hooks

useBodyLock

锁住 body 滚动，并补偿滚动条宽度带来的位移。

typescript

useOverlayUrlState

OverlayUrlStateOptions

为浮层构建一个 URL 状态控制器，你再把它交给 *UrlOverlay 的 controller 属性。

参见 React 指南中的 URL 状态，那里有完整讲解和示例。

选项	类型	默认值	说明
param	string	required	承载当前幻灯片的查询参数，例如 "photo"。
adapter	UrlAdapter	History API	Navigation system to read and write through. Pass a router-backed adapter in a routed app so the router's own location does not go stale.
codec	{ decode(raw) => Id \| null; encode(id) => string }	required	传输格式：参数文本 ↔ 稳定身份，与集合无关。它与 locator 组成共用同一个 Id 的配套组合 —— 默认的 ?photo=3 索引画廊展开 ...urlIndexKey(() => images.length) 即可；也可以提供你自己的实现（base64、slug），让画廊重新排序后书签依然有效。
locator	{ locate(id) => number \| null; locateAsync?(id) => Promise<number \| null>; identify(index) => id }	required	把身份映射成位置，并自己判断有效性：locate（同步）、locateAsync（分页画廊的异步兜底）、identify（写回）。普通的索引画廊展开 ...urlIndexKey(() => images.length) 即可 —— 它同时提供这个定位器和配套的编解码器，并以实时数量为上界约束 ?photo=3，于是过期的 ?photo=99 会自动从 URL 中消失，而不是打开一张从未指定的幻灯片。分页信息流或按身份寻址的画廊则自行提供配套的编解码器 + 定位器。

useReactRouterUrlAdapter

A UrlAdapter ，底层用 React Router。在带路由的应用里把它作为 adapter 的 useOverlayUrlState 选项传入，让路由器始终是导航的唯一真相来源 —— 绕过路由器直接写 history.pushState 会让它的 location 过期，下一次导航就会把参数丢掉。

它从独立的子路径导出，因此没有路由器的应用永远不会把 react-router-dom 打进产物。 react-router-dom 是可选的同级依赖。

tsx

无障碍

<Reel> 渲染为 role="region" ，并带 aria-roledescription="carousel"。把 ariaLabel 属性设好，可以给这个区域一个屏幕阅读器能读的名字。一个 polite 的实时区域会在每次切换时播报“第 N 张，共 M 张”，且不会重渲染轮播。非活动幻灯片会带上 inert 属性，于是焦点和辅助技术导航会跳过它们。

<ReelIndicator> 渲染为 role="tablist" ，圆点上使用漫游 tabindex；方向键移动焦点，Enter 或空格激活对应幻灯片。

如果你要围绕 <Reel>? captureFocusForReturn, createFocusTrap、 getFocusableElements 都从 @reelkit/react 重新导出，用于焦点归还和焦点陷阱。

工具

createDefaultKeyExtractorForLoop

创建一个 key 提取器，处理开启 loop 时出现的重复索引。

tsx