# 基础、日期和数值工具
从 `@/utils` 导入以下函数。基础能力的实现位于 `@/utils/core`,精度工具也可从 `@/utils/precision` 单独导入。
## 基础工具交互示例
比较 PromiseLike 与 async 函数,试试同步和异步错误回调,或观察路径、日期范围和对象更新的结果。
::: details 查看基础工具示例源码
<<< @/../admin/src/views/demo/docs-core-utils.tsx
:::
## 类型、标识和错误处理
| API | 输入与返回 |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `isValueType(value, type)` | 按 `Object.prototype.toString` 标签判断,普通函数和 async 函数都匹配 `Function`。 |
| `isPromise(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(
load: () => Promise,
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`。
::: details 查看示例源码
<<< @/examples/PrecisionDemo.vue
:::
后台的精度实验还能切换减法、乘法、除法以及按份分摊。
::: details 查看完整精度示例源码
<<< @/../admin/src/views/demo/precision/index.tsx
:::
### 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` 后需仍在安全整数范围内;这些方法不提供任意精度运算。保留字符串或整数分值跨接口传输可避免展示时的二进制浮点误差。
[基础函数](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/utils/src/core/index.ts) · [精度实现](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/utils/src/precision.ts) · [日期选择器辅助](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/utils/get-date-by-naive-date-picker.ts)