React API 参考

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

Reel 属性

ReelProps

回调

ReelApi 方法

通过 apiRef:

const apiRef = useRef<ReelApi>(null);

// Navigation
apiRef.current?.next();
apiRef.current?.prev();
apiRef.current?.goTo(5);           // instant
apiRef.current?.goTo(5, true);     // animated

// Lifecycle
apiRef.current?.adjust();          // recalculate positions
apiRef.current?.observe();         // start observing keyboard
apiRef.current?.unobserve();       // stop observing keyboard

ReelIndicator 属性

ReelIndicatorProps

观察者组件

Observe

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

import { Observe } from '@reelkit/react';

<Observe signals={[controller.state.index]}>
  {() => <span>Current: {controller.state.index.value}</span>}
</Observe>

AnimatedObserve

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

import { AnimatedObserve } from '@reelkit/react';

<AnimatedObserve signal={controller.state.axisValue}>
  {(value) => (
    <div style={{ transform: `translateY(${value}px)` }} />
  )}
</AnimatedObserve>

SwipeToClose

<SwipeToClose> 把子元素包进一个跟随垂直滑动的容器，滑动超过阈值后调用 onClose——这就是 Lightbox 和 Stories Player 的关闭手势，可用于你自己的自定义浮层。SwipeToCloseProps 是它的属性类型；SwipeToCloseDirection 为 'up' | 'down'。

SoundProvider

<SoundProvider> 创建一个初始为静音的 SoundController，并通过 useSoundState 交给子元素。浮层会替你渲染一个；只有在自定义播放器的控件需要共享静音状态时，才需要自己包一层。

Hooks

useBodyLock

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

import { useBodyLock } from '@reelkit/react';

// Lock body scroll when overlay is open
useBodyLock(isOpen);

useOverlayUrlState

OverlayUrlStateOptions

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

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

useReactRouterUrlAdapter

A UrlAdapter ，底层用 React Router。在带路由的应用里把它作为 adapter 的 useOverlayUrlState 选项传入，让路由器始终是导航的唯一真相来源 —— 绕过路由器直接写 history.pushState 会让它的 location 过期，下一次导航就会把参数丢掉。写入只触及查询部分，pathname 和 hash 原样保留。每次变化都会报告路由器是在同一页面内压栈、替换，还是在历史中前进后退，因此从 <Link> 打开的画廊按一次返回就能关闭。

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

import { useReactRouterUrlAdapter } from '@reelkit/react/react-router-url-adapter';

const adapter = useReactRouterUrlAdapter();
const photo = useOverlayUrlState({
  param: 'photo',
  adapter,
  ...urlIndexKey(() => images.length),
});

useReelContext

useReelContext() 读取最近的父级 <Reel> 的 ReelContextValue，在其外部则返回 null。<ReelIndicator> 就是靠它自动连接的；在作为 <Reel> 子元素渲染的自定义控件里使用它，控件无需属性就能跟随滑块。ReelContext 是它背后的 context 对象——只有在测试或自定义包装组件里需要提供自己的值时才直接使用它。

useSoundState

useSoundState() 从最近的 <SoundProvider> 读取 SoundController，在其外部会抛出错误。Reel Player、Lightbox 和 Stories Player 都会用一个 provider 包住内容，所以通过它们的渲染属性传入的自定义控件可以调用它来读取或切换静音。

useFullscreen

useFullscreen({ ref }) 为 ref 中的元素驱动 Fullscreen API，并在组件卸载时退出全屏。UseFullscreenProps 是它的参数；UseFullscreenResult 是它返回的元组。

无障碍

<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 时出现的重复索引。

import { createDefaultKeyExtractorForLoop } from '@reelkit/react';

<Reel
  count={items.length}
  size={size}
  loop
  keyExtractor={createDefaultKeyExtractorForLoop(items.length)}
  itemBuilder={...}
/>

尺寸检测

observeElementSize、getViewportSize、observeViewportSize、isMobileWidth、fitAspectRatio 和 isTouchDevice 都从 @reelkit/react 重新导出，供需要像 reelkit 自带浮层那样确定自身尺寸的自定义浮层使用。参见核心 API 中的尺寸检测。

自动播放与下载

createTimerController、createSlideshowController 和 downloadFile 同样从 @reelkit/react 重新导出：分别是 stories 播放器背后的计时器、lightbox autoAdvance 背后的幻灯片控制器，以及其下载按钮背后的工具函数。参见核心 API 中的自动播放和下载。