用途:为 React 库设计公共 API 时提供原则与模式参考,适用于设计 hooks、组件或工具函数接口。
核心原则:简洁优先(Simple > Clever)、保持一致性、对 tree-shaking 友好、最大化 TypeScript 推断、确保 SSR 安全。
核心模式:返回值上,单值直接返回;状态加动作返回元组,如 useToggle 返回 [boolean, () => void];三个及以上字段返回对象,如 usePagination 返回 { page, nextPage, prevPage }。参数上,必填参数在前、可选参数在后,例如 useDebounce(value, delay, options?)。
SSR 安全:用 useState 惰性初始化并在 window 未定义时返回安全默认值。导出方式要求仅使用具名导出,如 export { useDebounce } from './useDebounce',避免默认导出。
更多组件设计与高级模式见 details.md。