vueuse-math-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vueuse/vueuse

@vueuse/math

vueuse/vueuse

@vueuse/math

Version: 14.2.1 (Feb 2026) Deps: @vueuse/shared@14.2.1 Tags: alpha: 14.0.0-alpha.3 (Sep 2025), beta: 14.0.0-beta.1 (Sep 2025), latest: 14.2.1 (Feb 2026)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

**版本：**14.2.1（2026年2月） 依赖：@vueuse/shared@14.2.1 **标签：**alpha: 14.0.0-alpha.3（2025年9月），beta: 14.0.0-beta.1（2025年9月），latest: 14.2.1（2026年2月）

参考链接：文档 — API参考、使用指南 • GitHub问题 — 问题反馈、解决方案、边缘场景 • GitHub讨论 — 问答、模式分享、实践方案 • 版本发布记录 — 更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes — prioritize recent major/minor releases.

DEPRECATED:
```
and
```
,
```
or
```
,
```
not
```
— v14 deprecated in favor of original names
```
logicAnd
```
,
```
logicOr
```
,
```
logicNot
```
source
BREAKING: Requires Vue 3.5+ — v14 moved to Vue 3.5 as minimum version, enabling native
```
useTemplateRef
```
and
```
MaybeRefOrGetter
```
source
BREAKING: ESM-only — v13 dropped CommonJS (CJS) support entirely source
NEW:
```
useAverage
```
— reactively calculate average from an array or variadic arguments
NEW:
```
useSum
```
— reactively calculate sum from an array or variadic arguments
NEW:
```
createProjection
```
— create a reusable numeric projector between two numeric domains
NEW:
```
createGenericProjection
```
— create a projector with a custom mapping function for arbitrary types
NEW:
```
usePrecision
```
— options now include
```
math
```
property for rounding strategy (
```
floor
```
,
```
ceil
```
,
```
round
```
)
NEW:
```
useClamp
```
— returns
```
ComputedRef
```
instead of
```
Ref
```
when input is a getter or readonly ref
NEW:
```
useMath
```
— provides reactive access to any standard
```
Math
```
method via key name
NEW:
```
logicAnd
```
,
```
logicOr
```
,
```
logicNot
```
— variadic reactive boolean logic supporting multiple refs
NEW:
```
useMax
```
,
```
useMin
```
— support both array and variadic arguments for reactive comparison
NEW:
```
useAbs
```
,
```
useCeil
```
,
```
useFloor
```
,
```
useRound
```
,
```
useTrunc
```
— dedicated reactive wrappers for common Math methods
NEW:
```
useProjection
```
— reactive numeric projection from one domain to another

Also changed:

tsdown

build system v14 ·

WatchSource<T>

types v14 ·

MaybeRefOrGetter

native v12.8

本节记录各版本的API变更信息 — 优先关注近期的主版本/次版本更新。

已废弃：
```
and
```
、
```
or
```
、
```
not
```
— v14版本中已废弃，推荐使用原名
```
logicAnd
```
、
```
logicOr
```
、
```
logicNot
```
来源
破坏性变更：要求Vue 3.5+ — v14版本将最低支持版本升级为Vue 3.5，以支持原生
```
useTemplateRef
```
和
```
MaybeRefOrGetter
```
来源
破坏性变更：仅支持ESM — v13版本完全移除了CommonJS（CJS）支持来源
新增：
```
useAverage
```
— 响应式计算数组或多个参数的平均值
新增：
```
useSum
```
— 响应式计算数组或多个参数的总和
新增：
```
createProjection
```
— 创建可复用的数值投影器，实现两个数值域之间的映射
新增：
```
createGenericProjection
```
— 创建支持自定义映射函数的投影器，适用于任意类型的域映射
新增：
```
usePrecision
```
— 配置项新增
```
math
```
属性，用于指定舍入策略（
```
floor
```
、
```
ceil
```
、
```
round
```
）
新增：
```
useClamp
```
— 当输入为getter或只读ref时，返回
```
ComputedRef
```
而非
```
Ref
```
新增：
```
useMath
```
— 通过键名提供对标准
```
Math
```
方法的响应式访问
新增：
```
logicAnd
```
、
```
logicOr
```
、
```
logicNot
```
— 支持多个ref的可变参数响应式布尔逻辑运算
新增：
```
useMax
```
、
```
useMin
```
— 同时支持数组和可变参数，实现响应式比较
新增：
```
useAbs
```
、
```
useCeil
```
、
```
useFloor
```
、
```
useRound
```
、
```
useTrunc
```
— 为常用Math方法提供专用的响应式包装器
新增：
```
useProjection
```
— 实现从一个数值域到另一个数值域的响应式数值投影

**其他变更：**v14版本的

tsdown

构建系统 · v14版本的

WatchSource<T>

类型 · v12.8版本原生支持

MaybeRefOrGetter

Best Practices

最佳实践

Use
```
useClamp
```
with a mutable
```
ref
```
to create a self-validating state. When a mutable ref is passed, it returns a writable computed that automatically clamps any value assigned to it source

// Preferred: prevents invalid state assignment
const value = useClamp(shallowRef(0), 0, 10)
value.value = 15 // state remains 10

Pass reactive arrays for domains in
```
useProjection
```
to handle dynamic scaling. This is preferred for UI elements like zoomable charts or responsive sliders where the input/output boundaries change over time source
Define reusable mappers with
```
createProjection
```
outside component logic. This ensures consistent scaling across different parts of the application and reduces the overhead of redefining domains source
Leverage rest arguments in aggregation composables for ad-hoc calculations.
```
useSum
```
,
```
useAverage
```
,
```
useMax
```
, and
```
useMin
```
accept multiple refs directly, avoiding the need to create intermediate array refs

// Preferred: cleaner syntax for fixed sets of refs
const total = useSum(refA, refB, refC)

Prefer
```
usePrecision
```
over
```
toFixed
```
for numeric operations.
```
usePrecision
```
returns a
```
number
```
, which prevents type-coercion bugs and allows further mathematical operations without re-parsing strings source
Use explicit rounding modes in
```
usePrecision
```
for specific UI requirements. Pass the
```
math
```
option ('floor' | 'ceil' | 'round') to control how fractional values are handled in paginators or progress bars source
Combine
```
logicAnd
```
or
```
logicOr
```
with
```
@vueuse/core
```
's
```
whenever
```
for cleaner side effects. This pattern is more readable than complex manual
```
computed
```
properties when triggering actions based on multiple reactive flags source
Employ
```
createGenericProjection
```
for non-linear domain mapping. Provide a custom projector function to handle logarithmic scales or custom eased transitions between numeric domains source
Use
```
useMath
```
to reactively derive values from standard
```
Math
```
methods. It automatically wraps multiple arguments and ensures the result updates whenever any input dependency changes source
Use
```
logicNot
```
for reactive boolean inversion in templates. It expresses intent more clearly than
```
!ref.value
```
or manual
```
computed
```
wrappers when defining visibility or disabled states

将
```
useClamp
```
与可变
```
ref
```
配合使用，创建自验证状态。当传入可变ref时，它会返回一个可写的computed对象，自动限制分配给它的任何值来源

// 推荐写法：防止无效状态赋值
const value = useClamp(shallowRef(0), 0, 10)
value.value = 15 // 状态仍保持为10

在
```
useProjection
```
中传入响应式数组作为域，以处理动态缩放。这适用于可缩放图表或响应式滑块等UI元素，这类场景中输入/输出边界会随时间变化来源
在组件逻辑外部使用
```
createProjection
```
定义可复用的映射器。这能确保应用不同部分的缩放逻辑一致，同时减少重复定义域的开销来源
在聚合类组合式函数中使用剩余参数进行临时计算。
```
useSum
```
、
```
useAverage
```
、
```
useMax
```
和
```
useMin
```
直接接受多个ref，无需创建中间数组ref

// 推荐写法：固定数量ref的更简洁语法
const total = useSum(refA, refB, refC)

数值运算优先使用
```
usePrecision
```
而非
```
toFixed
```
。
```
usePrecision
```
返回
```
number
```
类型，可避免类型转换错误，且无需重新解析字符串即可进行后续数学运算来源
针对特定UI需求，在
```
usePrecision
```
中使用显式的舍入模式。传入
```
math
```
选项（'floor' | 'ceil' | 'round'）来控制分页器或进度条等组件中分数值的处理方式来源
将
```
logicAnd
```
或
```
logicOr
```
与@vueuse/core的
```
whenever
```
配合使用，实现更简洁的副作用逻辑。当基于多个响应式标志触发操作时，这种模式比复杂的手动
```
computed
```
属性更具可读性来源
使用
```
createGenericProjection
```
实现非线性域映射。提供自定义投影函数来处理对数缩放或数值域之间的自定义缓动过渡来源
使用
```
useMath
```
从标准Math方法中响应式推导值。它会自动包装多个参数，并确保当任何输入依赖项变化时结果都会更新来源
在模板中使用
```
logicNot
```
进行响应式布尔值取反。在定义可见性或禁用状态时，它比
```
!ref.value
```
或手动
```
computed
```
包装器更能清晰表达意图