基础、日期和数值工具
从 @/utils 导入以下函数。基础能力的实现位于 @/utils/core,精度工具也可从 @/utils/precision 单独导入。
类型、标识和错误处理
| API | 输入与返回 |
|---|---|
isValueType<T>(value, type) | 按 Object.prototype.toString 标签判断,普通函数和 async 函数都匹配 Function。 |
isPromise<T>(value) | 有可调用的 then 时返回 true,包括自定义 PromiseLike。 |
isAsyncFunction(fn) | 判断函数是否用 async 声明,普通返回 Promise 的函数不匹配。 |
uuid(length = 16, radix = 62) | Web Crypto 随机标识。字符集依次是数字、大写、小写,基数范围 1–62,长度是非负安全整数。参数非法抛 RangeError;结果不是 RFC UUID。 |
callWithErrorHandling(fn, onError, args?) | 返回同步执行结果;抛错时调用回调并返回 undefined。不会等待 Promise。 |
callWithAsyncErrorHandling(fn, onError, args?) | 等待函数返回值,处理同步抛错和拒绝。回调自身抛错时,错误会传给调用方。 |
ts
import { callWithAsyncErrorHandling, uuid } from '@/utils'
export const draftId = () => 'draft-' + uuid(12, 36)
export function loadOrReport<T>(
load: () => Promise<T>,
report: (error: Error) => void,
) {
return callWithAsyncErrorHandling(load, report)
}对象、路径和日期
updateObjectValue(obj, key, value, callback?)只修改对象的自有属性;新旧值均为普通对象时浅合并,其他情况替换。成功后调用回调。removeDuplicateKeys(obj)返回自有可枚举属性的浅拷贝。JavaScript 对象字面量的同名键已经在创建时由后值覆盖,不能用这个函数找回前值。equalRouterPath(a, b)忽略 query、hash 和末尾斜杠。需要区分筛选参数或标签实例时用完整路径。getDateByNaiveDatePicker(value, isRange)把清空的范围null转成[null, null],其他值原样保留。它不转换单位、时区或格式。getAppEnvironment()返回 Vite 的import.meta.env,用于读取MODE、DEV、PROD等。客户端可见的配置不要放密钥。detectOperatingSystem()基于浏览器 User-Agent 返回OperatingSystem,识别 iOS(含桌面标识 iPad)、Android、Windows、macOS、Linux 或 Unknown。它适合辅助显示,不代替能力检测。
定点运算
输入 CurrencyArguments 可为数字、字符串或 currency.js 实例。模板缺省精度为 8 位小数;运算结果仍是 currency.js 实例,可取 .value 或 .toString()。
交互示例
修改两个数,对比 add 与 JavaScript + 的结果。示例直接调用 workspace 内的 @ray-template/utils/precision。
每个数最多输入 7 位整数和 8 位小数。
查看示例源码
vue
<template>
<div class="ray-demo" :lang="locale ?? 'zh-CN'">
<div class="ray-demo-fields">
<div>
<label :for="firstId">{{ copy.first }}</label>
<input
:id="firstId"
v-model.trim="first"
inputmode="decimal"
:aria-describedby="hintId"
:aria-invalid="!isDecimal(first)"
/>
</div>
<div>
<label :for="secondId">{{ copy.second }}</label>
<input
:id="secondId"
v-model.trim="second"
inputmode="decimal"
:aria-describedby="hintId"
:aria-invalid="!isDecimal(second)"
/>
</div>
</div>
<p :id="hintId" class="ray-demo-hint">{{ copy.hint }}</p>
<output class="ray-demo-result" :for="`${firstId} ${secondId}`">
<span v-if="result">
{{ copy.fixed }}:<code>{{ result.fixed }}</code>
<br />
{{ copy.native }}:<code>{{ result.native }}</code>
</span>
<span v-else>{{ copy.invalid }}</span>
</output>
</div>
</template>
<script setup lang="ts">
import { add } from '@ray-template/utils/precision'
import { computed, ref, useId } from 'vue'
const props = defineProps<{ locale?: 'zh-CN' | 'en' }>()
const copy = computed(() =>
props.locale === 'en'
? {
first: 'First number',
second: 'Second number',
fixed: 'Fixed precision',
native: 'JavaScript addition',
hint: 'Enter up to 7 integer digits and 8 decimal places per number.',
invalid: 'Enter two valid decimal numbers.',
}
: {
first: '第一个数',
second: '第二个数',
fixed: '定点运算',
native: 'JavaScript 加法',
hint: '每个数最多输入 7 位整数和 8 位小数。',
invalid: '请输入两个有效的十进制数。',
},
)
const first = ref('0.1')
const second = ref('0.2')
const firstId = useId()
const secondId = useId()
const hintId = useId()
const isDecimal = (value: string) =>
/^[+-]?(?:\d{1,7}(?:\.\d{0,8})?|\.\d{1,8})$/.test(value)
const result = computed(() => {
if (!isDecimal(first.value) || !isDecimal(second.value)) return
return {
fixed: add(first.value, second.value).toString(),
native: Number(first.value) + Number(second.value),
}
})
</script>API
| API | 行为 |
|---|---|
add(...values) | 求和,无参数返回零。 |
subtract(first, ...rest) | 依次相减。 |
multiply(first, ...rest) | 依次相乘,字符串因子会先解析。 |
divide(first, ...rest) | 依次相除,零除或非有限结果抛 RangeError。 |
format(value, options?) | 按精度转换,默认返回数字;type: 'string' 返回保留精度的数字字符串。 |
distribute(value, length, options?) | 平分金额,余数优先给前几份。0 和 1 都视作一份,负数或非整数抛错;支持 precision 和 type。 |
isCurrency(value) | 判断是否是当前 currency.js 类的实例。 |
ts
import { add, distribute, format } from '@/utils'
export const amount = format(add('0.1', '0.2'), {
precision: 2,
type: 'string',
})
export const parts = distribute(10, 3, { precision: 2, type: 'string' })分摊或货币结算由业务明确小数位和舍入规则。保留字符串或整数分值跨接口传输可避免展示时的二进制浮点误差。