跳到主要内容

Hooks 一览

库内部用到的通用 hooks 都从包的根导出，自己写组件时可以直接用。它们都能在服务端渲染（不在模块顶层访问 window / document）。

useControllable

受控 / 非受控二合一：传了 value 就受控，否则用 defaultValue 自己管。setter 支持函数写法，值没变时不会触发 onChange。库里所有取值类组件都基于它。

非受控：
3
受控（上限 12）：
10

useControllable(value, defaultValue, onChange?)

属性类型默认值说明
value*T | undefined—受控值。undefined 表示非受控。
defaultValue*T—非受控时的初始值。
onChange(value: T) => void—值变化时触发，第一个参数是新值。
返回[T, (next: T | ((prev: T) => T)) => void]—当前值和 setter。

useMediaQuery / useBreakpoint

订阅一条媒体查询。useBreakpoint(bp) 是它针对四个断点的简写，见“响应式”页。

能悬停：否触屏：否系统要求减弱动效：否系统深色：否

useMediaQuery(query, fallback?)

属性类型默认值说明
query*string—媒体查询字符串。
fallbackbooleanfalse服务端渲染时返回的值。

useEscape / useOutsidePress

自己做可关闭的浮层时用。useEscape 内部维护一个栈：叠了几层时只有最上面那层响应。

签名

属性类型默认值说明
useEscape(active: boolean, onEscape: () => void) => void—active 为 true 期间监听 Esc。事件已经被 preventDefault 的不处理。
useOutsidePress(active, refs: RefObject[], onOutside: (e: PointerEvent) => void) => void—pointerdown 落在所有 refs 之外时触发（捕获阶段）。
useScrollLock(active: boolean) => void—锁住页面滚动，并补上滚动条的宽度避免跳动。支持嵌套。

大多数情况下不需要直接用这三个：悬浮卡片和各种弹出组件已经处理了关闭、焦点和滚动锁。

useEvent

返回一个引用恒定、内部永远调用最新闭包的回调。适合交给定时器、事件监听、子组件的 effect 依赖。

切换步长：定时器没有重建，但加的数马上变了。

合计 0

全部导出

通用

属性类型默认值说明
useControllable(value, defaultValue, onChange?)—受控 / 非受控二合一。
useEvent(fn) => fn—引用恒定的回调。
useMediaQuery(query, fallback?) => boolean—媒体查询。
useBreakpoint(bp, fallback?) => boolean—视口是否不小于某个断点。
usePresence(open, exitMs?) => { mounted, state, ref }—进退场。见动效工具。
useEscape(active, onEscape)—Esc 关闭，只有最上层响应。
useOutsidePress(active, refs, onOutside)—点在若干元素之外。
useScrollLock(active)—锁页面滚动。
useIsoLayoutEffecttypeof useLayoutEffect—浏览器里是 useLayoutEffect，服务端是 useEffect（不报警告）。
mergeRefs(...refs) => RefCallback—不是 hook：把多个 ref 合成一个，转发 ref 的同时自己也要用时用它。

读取上下文

属性类型默认值说明
useOink() => OinkContextValue—主题、强调色、动效偏好及切换方法。见主题。
useAppShell() => AppShellState—所在 AppShell 的侧栏状态与开关方法；必须在 AppShell 里面调用。见 AppShell。
useFloatingCard() => FloatingCardContextValue | null—所在悬浮卡片的 close()、placement、modal 等；不在卡片里时返回 null。
useFieldControl(own, labelable?) => FieldControlResult—自己写表单控件时，把所在 Field 的 id、禁用、必填、错误描述接过来。
usePosition(options) => …—锚定定位：弹出层相对触发元素的位置计算，Popover、Menu 等都基于它。