组件/Utils 工具函数

Utils 工具函数

根入口与 ./utils 导出的公开工具函数

自 1.0.0BETA
import { nextZIndex, toast, hasWindow } from '@talex-touch/tuffex/utils'

API 参考

z-index 管理

统一分配浮层层级,组件不再各写 z-index。

导出签名何时用
nextZIndex()() => number新建浮层时取下一个递增层级
getZIndex()() => number读取当前最高层级,不递增
refreshZIndex(seed?, reason?)(seed?: number, reason?: string) => number以某个基准重新计数
resetZIndex(seed?, reason?)(seed?: number, reason?: string) => number卸载或测试后重置到种子值
configureZIndex(options)(options) => void全局配置基准种子与覆盖值
onZIndexEvent(listener)(listener) => () => void订阅层级变化,返回取消订阅函数
createZIndexAllocator()() => TxZIndexAllocator创建带独立计数器的分配器,不与模块级状态共享
useZIndexAllocator()() => TxZIndexAllocator在 setup 中取得 app 级分配器,未安装时退回模块级分配器

环境守卫

SSR 安全:访问 window / document / navigator 前先判断。

导出签名何时用
hasWindow()() => boolean访问 window 前判断
hasDocument()() => boolean访问 document 前判断
hasNavigator()() => boolean访问 navigator(振动、剪贴板)前判断

触感反馈 vibrate

封装 navigator.vibrate,提供语义化震动。

导出签名何时用
vibrate{ light() … error(), stop, isSupported }直接触发预设,如 vibrate.success()
useVibrate(type, options?)(type: VibrateType, options?) => void按语义触发一次可配置的震动
useAutoVibrate(duration, options?)(duration: number[], options?) => boolean按毫秒数组直接震动一次,环境不支持时返回 false
stopVibrate()() => void打断进行中的震动
isVibrateSupported()() => boolean能力检测

轻提示 toast

全局提示队列,页面无需各自挂宿主;渲染仍需 TxToastHost。

导出签名何时用
toast(options)(options) => string弹出提示,返回用于关闭的 id
dismissToast(id)(id: string) => void关闭指定提示
clearToasts()() => void清空全部提示
pauseToasts()() => void暂停全部自动关闭倒计时,重复调用无副作用
resumeToasts()() => void从暂停时剩余的时间继续倒计时

对话框编排 dialog-manager

按优先级排队,带生命周期回调,串行管理全局对话框。

导出签名何时用
getDialogManager()() => DialogManager获取全局单例,排队或打开对话框
DialogManagerclass对话框队列类,getDialogManager() 返回其单例,按优先级登记与注销对话框

动画

导出签名何时用
useReducedMotion()() => Ref<boolean>跟随系统 prefers-reduced-motion 的响应式偏好,挂载与 KeepAlive 激活时监听
useFlip(targetRef, opts?)(ref, opts?) => UseFlipReturn对元素做 FLIP 过渡(TxFlipOverlay 底层)
useAutoResize(targetRef, opts?)(ref, opts?) => UseAutoResizeReturn测量尺寸变化并过渡(TxAutoSizer 底层)
stepSpring(position, velocity, target, spring, dt)(position, velocity, target, spring, dt) => [number, number]在自有帧循环中沿弹簧推进数值(spring 为 { stiffness, damping, mass? },dt 以秒计),换目标时保留速度;可作 useJellyIndicator glide 的 integrate
solveSpring(position, velocity, target, spring, t)(position, velocity, target, spring, t) => [number, number]同一弹簧的闭式解:任意时刻 t(秒)的精确位置与速度;用于可拖动时间线、逐帧渲染和断言某一时刻的位置
createSpringTrack(spring, initial)(spring, initial) => { retarget(t, target), sample(t) }可中途换目标的弹簧轨道:换目标时保留当时的位置与速度,sample(t) 可按任意顺序精确读取
useMorphBox(box, content, opts?)(box, content, opts?) => { morphing, settle }容器跟随内容自然尺寸做弹簧过渡,途中再变保留速度;TxMorph 与 TxTransitionSmoothSize 的尺寸引擎
useIndicatorBox(options)(options) => UseIndicatorBoxReturn测量目标相对容器的位置与尺寸,供滑动指示器跟随,并用 ResizeObserver 保持同步
useJellyIndicator(options?)(options?) => UseJellyIndicatorReturn驱动滑动指示器的弹簧引擎,支持 jelly 与 glide 两种材质;测量与绘制由宿主负责
resolveGsapEase(value)(value: string) => string | ((t: number) => number)交给 GSAP 前转换缓动:spring(...)、cubic-bezier(...) 转为进度函数(GSAP 不认识,会静默换成默认缓动),GSAP 缓动名原样返回
resolveCssEase(spec)(spec: string | undefined | null) => (t: number) => number在 JS 中按 CSS 缓动求值:cubic-bezier(...)、等距 linear(...) 与 linear / ease / ease-in / ease-out / ease-in-out;其他写法退化为钳制线性,从不返回 null;按写法缓存,可逐帧调用
createSpringEase(omega?, zeta?)(omega = 10, zeta = 0.72) => (t: number) => number按时间线归一化的闭式欠阻尼弹簧:冲过 1 再回落,终点恰为 1;与逐帧积分的 stepSpring 不同,可直接当 ease 用
parseSpringEase(value)(value: string | undefined | null) => ((t: number) => number) | null解析 spring / spring(omega) / spring(omega, zeta),其他写法返回 null
createCubicBezier(x1, y1, x2, y2)(x1, y1, x2, y2) => (t: number) => number等价于 CSS cubic-bezier();图表入口的 cubicBezier 即此函数
parseCubicBezier(value)(value: string | undefined | null) => [number, number, number, number] | null解析 cubic-bezier(...);GSAP 缓动名、关键字、弹簧写法,或 x 控制点超出 0, 1 时返回 null
applyThemeTransition(updateTheme, options?)(updateTheme, options?) => Promise<void> | void通过 View Transitions API 执行平滑主题切换(柔和模糊圆、斜切光刃、横向扫光等),详见《Theming 主题定制》

安装辅助

导出签名何时用
withInstall(component)<T>(component: T) => T & { install }给组件挂 install,支持 app.use() 全局注册

技术实现

  • 桶文件:packages/tuffex/packages/components/src/utils/index.ts 再导出 packages/tuffex/packages/utils/*。
  • 子路径入口 @talex-touch/tuffex/utils;根入口 @talex-touch/tuffex 同样导出。