基础、日期和数值工具
从 @/utils 导入以下函数。基础能力的实现位于 @/utils/core,精度工具也可从 @/utils/precision 单独导入。
基础工具交互示例
比较 PromiseLike 与 async 函数,试试同步和异步错误回调,或观察路径、日期范围和对象更新的结果。
查看基础工具示例源码
tsx
import { useI18n } from '@/hooks'
import {
callWithAsyncErrorHandling,
callWithErrorHandling,
detectOperatingSystem,
equalRouterPath,
getAppEnvironment,
getDateByNaiveDatePicker,
isAsyncFunction,
isPromise,
isValueType,
removeDuplicateKeys,
updateObjectValue,
uuid,
} from '@/utils'
import {
NButton,
NCard,
NDatePicker,
NFlex,
NInput,
NInputNumber,
NSelect,
NSwitch,
} from 'naive-ui'
import DemoPage from './components/DemoPage'
import DemoResult from './components/DemoResult'
export default defineComponent({
name: 'DocsCoreUtils',
setup() {
const { t } = useI18n('docsExamples')
const text = (key: string) => t<string>(key)
const kind = ref<'text' | 'thenable' | 'async'>('thenable')
const length = ref<number | null>(8)
const radix = ref<number | null>(36)
const generated = ref('')
const fail = ref(false)
const errorResult = ref('')
const first = ref('/orders/?page=1')
const second = ref('/orders#details')
const field = ref(text('core.pending'))
const range = ref<[number, number] | null>(null)
const row = reactive<{ order: { id?: string; status: string } }>({
order: { id: 'ORD-001', status: text('core.initial') },
})
const { MODE, DEV, PROD } = getAppEnvironment()
const sample = computed(() => {
if (kind.value === 'async') return async () => text('core.complete')
if (kind.value === 'thenable')
return { then: () => text('core.complete') }
return text('core.complete')
})
const generate = () => {
generated.value =
callWithErrorHandling(
() => uuid(length.value ?? 0, radix.value ?? 36),
(error: Error) => {
generated.value = error.message
},
) ?? generated.value
}
const handleError = (error: Error) => {
errorResult.value = error.message
}
const run = async (asyncMode: boolean) => {
const execute = () => {
if (fail.value) throw new Error(text('core.failed'))
return text('core.succeeded')
}
const result = asyncMode
? await callWithAsyncErrorHandling(async () => execute(), handleError)
: callWithErrorHandling(execute, handleError)
if (result) errorResult.value = result
}
return () => (
<DemoPage title={text('core.title')} description={text('core.intro')}>
<div class="r-demo-grid">
<NCard title="isValueType · isPromise · isAsyncFunction">
<NSelect
aria-label={text('core.inputType')}
options={[
{ label: text('core.text'), value: 'text' },
{ label: text('core.thenable'), value: 'thenable' },
{ label: text('core.asyncFn'), value: 'async' },
]}
v-model:value={kind.value}
/>
<DemoResult label={text('core.checkResult')}>
<pre>
{JSON.stringify(
{
String: isValueType(sample.value, 'String'),
Function: isValueType(sample.value, 'Function'),
isPromise: isPromise(sample.value),
isAsyncFunction: isAsyncFunction(sample.value),
},
null,
2,
)}
</pre>
</DemoResult>
</NCard>
<NCard title={text('core.errorCallbacks')}>
<NFlex>
<NInputNumber
v-model:value={length.value}
min={0}
max={64}
aria-label={text('core.idLength')}
/>
<NInputNumber
v-model:value={radix.value}
min={1}
max={62}
aria-label={text('core.radix')}
/>
<NButton onClick={generate}>{text('core.generate')}</NButton>
</NFlex>
<DemoResult label={text('core.identifier')}>
{generated.value}
</DemoResult>
<NFlex align="center">
<NSwitch
v-model:value={fail.value}
aria-label={text('core.simulateFailure')}
/>{' '}
{text('core.simulateFailure')}
<NButton onClick={() => run(false)}>
{text('core.runSync')}
</NButton>
<NButton onClick={() => run(true)}>
{text('core.runAsync')}
</NButton>
</NFlex>
<DemoResult label={text('core.execution')}>
{errorResult.value}
</DemoResult>
</NCard>
<NCard title={text('core.pathAndObject')}>
<NFlex>
<NInput
v-model:value={first.value}
aria-label={text('core.pathOne')}
/>
<NInput
v-model:value={second.value}
aria-label={text('core.pathTwo')}
/>
<code>{String(equalRouterPath(first.value, second.value))}</code>
</NFlex>
<NFlex>
<NInput
v-model:value={field.value}
aria-label={text('core.orderStatus')}
/>
<NButton
onClick={() =>
updateObjectValue(row, 'order', {
status: field.value,
})
}
>
{text('core.merge')}
</NButton>
</NFlex>
<DemoResult label={text('core.shallowCopy')}>
<code>{JSON.stringify(removeDuplicateKeys(row))}</code>
</DemoResult>
</NCard>
<NCard title={text('core.dateAndEnvironment')}>
<NDatePicker
v-model:value={range.value}
type="daterange"
clearable
aria-label={text('core.dateRange')}
/>
<DemoResult label={text('core.dateResult')}>
<code>
{JSON.stringify(getDateByNaiveDatePicker(range.value, true))}
</code>
</DemoResult>
<DemoResult label={text('core.environment')}>
<code>
{JSON.stringify({
MODE,
DEV,
PROD,
os: detectOperatingSystem(),
})}
</code>
</DemoResult>
</NCard>
</div>
</DemoPage>
)
},
})类型、标识和错误处理
| 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"
class="ray-demo-input"
inputmode="decimal"
:aria-describedby="hintId"
:aria-invalid="!isDecimal(first)"
/>
</div>
<div>
<label :for="secondId">{{ copy.second }}</label>
<input
:id="secondId"
v-model.trim="second"
class="ray-demo-input"
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>
<br />
<code>isCurrency: {{ result.isFixed }} / {{ result.isNative }}</code>
</span>
<span v-else>{{ copy.invalid }}</span>
</output>
</div>
</template>
<script setup lang="ts">
import { add, isCurrency } 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
const fixed = add(first.value, second.value)
const native = Number(first.value) + Number(second.value)
return {
fixed: fixed.toString(),
native,
isFixed: isCurrency(fixed),
isNative: isCurrency(native),
}
})
</script>后台的精度实验还能切换减法、乘法、除法以及按份分摊。
查看完整精度示例源码
tsx
import { useI18n } from '@/hooks'
import { add, distribute, divide, format, multiply, subtract } from '@/utils'
import {
NCard,
NDynamicTags,
NFormItem,
NGrid,
NGridItem,
NInputNumber,
} from 'naive-ui'
import DemoPage from '../components/DemoPage'
import DemoResult from '../components/DemoResult'
const operations = { add, subtract, multiply, divide }
export default defineComponent({
name: 'CalculatePrecision',
setup() {
const { t } = useI18n('demoDetails')
const operands = reactive({
add: ['0.1', '0.2'],
subtract: ['1', '0.7'],
multiply: ['0.1', '0.2'],
divide: ['1', '3'],
})
const amount = ref<number | null>(10)
const parts = ref<number | null>(3)
const allocation = computed(() =>
amount.value === null || parts.value === null
? []
: distribute(amount.value, parts.value),
)
return () => (
<DemoPage title={t('precision.title')} description={t('precision.intro')}>
<div class="r-demo-grid">
{(Object.keys(operations) as (keyof typeof operations)[]).map(
(operation) => {
const values = operands[operation]
const invalid =
!values.length ||
values.some(
(value) => !/^-?(?:\d+(?:\.\d*)?|\.\d+)$/.test(value),
)
const zeroDivisor =
operation === 'divide' &&
values.slice(1).some((value) => Number(value) === 0)
let result = t('precision.invalid')
if (!invalid && !zeroDivisor) {
try {
result = String(format(operations[operation](...values)))
} catch {
result = t('precision.invalid')
}
}
return (
<NCard key={operation} title={t(`precision.${operation}`)}>
<div class="r-demo-card-stack">
<NDynamicTags v-model:value={operands[operation]} />
<DemoResult
label={t('result')}
error={invalid || zeroDivisor}
>
<strong>
{zeroDivisor ? t('precision.zero') : result}
</strong>
</DemoResult>
</div>
</NCard>
)
},
)}
<NCard class="r-demo-grid__wide" title={t('precision.allocation')}>
<div class="r-demo-card-stack">
<NGrid cols="1 480:2" responsive="self" xGap={16}>
<NGridItem>
<NFormItem label={t('precision.amount')} showFeedback={false}>
<NInputNumber v-model:value={amount.value} />
</NFormItem>
</NGridItem>
<NGridItem>
<NFormItem label={t('precision.parts')} showFeedback={false}>
<NInputNumber
v-model:value={parts.value}
min={1}
max={12}
precision={0}
/>
</NFormItem>
</NGridItem>
</NGrid>
<DemoResult label={t('result')}>
<code>
{allocation.value.length
? allocation.value.join(' + ')
: t('empty')}
</code>
</DemoResult>
</div>
</NCard>
</div>
</DemoPage>
)
},
})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' })分摊或货币结算由业务明确小数位和舍入规则。currency.js 使用 JavaScript Number 存储缩放后的整数,金额乘以 10 ** precision 后需仍在安全整数范围内;这些方法不提供任意精度运算。保留字符串或整数分值跨接口传输可避免展示时的二进制浮点误差。