跳转到正文

基础、日期和数值工具 ​

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

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

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

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