---
title: Utils 工具函数
description: 根入口与 ./utils 导出的公开工具函数
category: Foundations
status: beta
since: 1.0.0
tags: [utils, helpers, z-index, toast]
syncStatus: reviewed
verified: false
---

```ts
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` | 获取全局单例，排队或打开对话框 |
| `DialogManager` | `class` | 对话框队列类，`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 主题定制](./theming.zh.mdc)》 |

### 安装辅助

| 导出 | 签名 | 何时用 |
|------|------|--------|
| `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` 同样导出。
