构建命令式组件 API

请先确定契约：FocusableInput 可以暴露聚焦、失焦和 getValue。请使用 forwardRef 包装它，保留一个指向真实输入元素的内部引用，并从 useImperativeHandle 返回这三个方法。

每个方法都会委托给底层输入元素，因此父组件可以获得所需的全部操作，而无需接触原始元素。

媒体组件非常适合使用命令式接口。VideoPlayer 可以暴露播放、暂停和 seekTo，每个方法都委托给内部视频引用上的原生视频元素方法。

seekTo 接受以秒为单位的时间并设置 currentTime，让父组件能够精确控制播放，而如果完全通过属性驱动播放，这种控制会很不方便。

轮播组件可以暴露下一项、上一项和 goToSlide，让外部控件或键盘处理程序驱动它。内部方法会更新当前索引状态，组件随后重新渲染到新的幻灯片。

这种方式将命令式触发与声明式渲染结合起来：父组件发出转换指令，轮播组件则通过正常的状态流程渲染结果。

命令式句柄是一份公开契约，因此请记录每个方法、它的参数以及返回值。清晰的文档会告诉使用者哪些内容受支持，并避免他们依赖未记录的内部实现。

请像对待其他接口表面一样对待这个句柄：简短的参考文档列出播放、暂停和 seekTo(秒) 等方法，可以避免误用和困惑。

一旦使用者依赖某个句柄，删除或重命名方法就会构成破坏性变更。请新增方法，而不要修改现有的方法签名；在删除任何内容前，请先平稳地弃用它。

将句柄视为版本化接口，可以避免组件随时间扩展时导致下游代码中断。

许多真实组件会混合使用这两种风格。VideoPlayer 可以以声明式方式接受源地址属性和 autoPlay 属性，同时也暴露命令式的播放和 seekTo，以处理属性难以准确表达的场景。

指导原则是：使用属性表示状态和配置，将命令式句柄保留给在特定时刻触发的一次性操作。

要测试命令式接口，请为组件渲染一个引用，将交互包裹在测试操作中，并通过 ref.current 调用暴露的方法。然后请断言可观察到的结果，例如视频已暂停或幻灯片索引发生了变化。

引用回调可以在渲染期间捕获句柄，让测试获得一个稳定的引用来调用方法。

Storybook 是展示命令式句柄的好地方。示例可以持有指向组件的引用，并渲染出调用其方法的按钮，让评审者交互式地执行播放、暂停或 goToSlide。

这些示例也可以充当实时文档，准确展示命令式接口在隔离环境中的行为。

包装非 React 库时，经常会使用命令式句柄。图表库会暴露重绘或更新方法，地图开发工具包会暴露 panTo 和 setZoom，富文本编辑器则会暴露 insertText 或 getContents。

将这类库包装在 React 组件中并提供简洁的句柄，可以让应用的其他部分以整洁、符合习惯的方式驱动它。

句柄上的方法通常会捕获当前状态，因此请使用 useImperativeHandle 的依赖数组，在需要时刷新这些方法，并使用 useCallback 管理内部辅助方法，以避免闭包中的值过时。

管理良好的句柄始终使用最新值运行，因此父组件调用 getValue 或 seekTo 时，得到的行为会与最新一次渲染保持一致。

应用命令式组件接口的设计指导原则。

您为 FocusableInput、VideoPlayer 和轮播组件设计了句柄，并让每个句柄暴露一组精简的操作方法。请记录并为这些方法建立版本，因为使用者会将它们作为公开接口来依赖。

请在 act 中通过 ref.current 测试命令式操作，并在 Storybook 中展示行为。同时，这种模式也能整洁地包装图表、地图和编辑器库。