跳转到正文

基础、日期和数值工具 ​

从 @/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 位小数。

定点运算:0.30000000
JavaScript 加法:0.30000000000000004
查看示例源码
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' })

分摊或货币结算由业务明确小数位和舍入规则。保留字符串或整数分值跨接口传输可避免展示时的二进制浮点误差。

基础函数 · 精度实现 · 日期选择器辅助