vueuse-math-skilld

@vueuse/math 15.0.0

适用于 Vue 3 的响应式数学工具。每个组合式函数都会在 computed 中使用 toValue 解析输入，因此参数可以是普通数字、ref 或 getter（MaybeRefOrGetter<number>），返回值则是会追踪所有输入的 ComputedRef<number>（dist/index.js:70-71）。唯一的例外是：useClamp 接收可变 ref 时会返回可写 computed（dist/index.d.ts:83）。

环境

• 安装：npm i @vueuse/math @vueuse/core（README.md:10）。只有在与 whenever 等 core 函数组合使用时才需要 @vueuse/core。
• Vue ^3.5.0 同级依赖（package.json:42），自 v14 起为最低版本要求。
• Node.js >= 22（package.json:39）；v15 不再支持 Node.js 20（发行说明）。
• 自 v13 起仅支持 ESM："type": "module"，不提供 CommonJS 构建版本（package.json:3；发行说明）。如果必须在 CJS 环境中加载，请使用动态 import()。
• "sideEffects": false（package.json:24）：未使用的组合式函数会被 tree shake 移除。
• 运行时依赖：@vueuse/[email protected]（package.json:45），提供 clamp 和 reactify。
• 入口文件为 dist/index.js，类型文件为 dist/index.d.ts（package.json:30,34）。

导出项

来自 dist/index.d.ts:167：

• 函数：createGenericProjection、createProjection、logicAnd、logicNot、logicOr、useAbs、useAverage、useCeil、useClamp、useFloor、useMath、useMax、useMin、usePrecision、useProjection、useRound、useSum、useTrunc
• 类型：ProjectorFunction、UseProjection、UseMathKeys、UseMathReturn、UsePrecisionOptions
• 已弃用的别名：and、or、not（dist/index.d.ts:20-21,32-33,44-45）

签名、行为说明和各函数示例：references/api.md。特定版本的变更：references/migrations.md。

常见任务

可写的限幅状态；传入可变 ref，即可自动对赋值进行限幅：

import { useClamp } from '@vueuse/math'

const level = ref(0)
const clamped = useClamp(level, 0, 10)
clamped.value = 15 // clamped.value and level.value are 10

只读限幅；传入 getter 或只读 ref（dist/index.js:113）：

const ratio = useClamp(() => raw.value / total.value, 0, 1)

使用 rest 参数聚合固定数量的 refs，无需构建数组（dist/index.d.ts:154-155）：

const total = useSum(refA, refB, refC)
const peak = useMax(refA, refB, refC)

在不同区间之间映射数值，适用于滑块、图表或进度 UI：

const progress = useProjection(scrollY, [0, pageHeight], [0, 100])

在多个组件中复用同一个投影；区间可以是响应式的：

const toPercent = createProjection(domain, [0, 100])
const a = toPercent(inputA)

四舍五入到指定位数，并保留 number 类型，而不是 toFixed 返回的字符串：

const price = usePrecision(ref(3.1415), 2) // 3.14
const up = usePrecision(ref(3.1415), 2, { math: 'ceil' }) // 3.15

以响应式方式组合布尔标志，再将副作用传给来自 @vueuse/core 的 whenever：

import { whenever } from '@vueuse/core'
import { logicAnd } from '@vueuse/math'

whenever(logicAnd(ready, hasData), run)

规则与注意事项

• 切勿使用别名 and、or、not；自 v14 起已弃用，推荐使用 logicAnd、logicOr、logicNot（dist/index.d.ts:20,32,44；发布说明）。
• useAverage 会直接除以 array.length，不检查数组是否为空：输入空数组会得到 NaN（dist/index.js:91-96）。请自行处理空数组的情况。
• 不传入任何参数时，useMax() 会得到 -Infinity，而 useMin() 会得到 Infinity，因为两者都会将参数展开后传给 Math.max / Math.min（dist/index.js:157-176）。
• 聚合函数（useSum、useAverage、useMin、useMax）接受 ref、getter、数字及其数组，并通过 toValueArgsFlat 将嵌套数组展平一层（dist/index.js:75-81）。
• usePrecision 通过数值的十进制字符串进行缩放，以避免浮点误差（accurateMultiply，dist/index.js:187-193）；options.math 默认为 'round'（dist/index.d.ts:122）。
• useMath 仅接受 Math 中属于函数的键，例如 'pow' 或 'sqrt'，不接受 PI 之类的常量（dist/index.d.ts:96）。
• 投影默认采用线性方式：(input - from[0]) / (from[1] - from[0]) * (to[1] - to[0]) + to[0]（dist/index.js:12-14）。若要进行非线性映射（对数刻度、缓动），请传入自定义 projector，或使用 createGenericProjection 处理非数字域（dist/index.d.ts:4-6）。
• 在模板和侦听器中，优先使用这些组合式函数，而不是 computed(() => Math.x(...))；它们能集中处理 Math 调用、对每个参数保持响应性，并带有用于摇树优化的 @__NO_SIDE_EFFECTS__ 注解（dist/index.js:4,15,111）。