fmt

fmt 是专门的格式化函数，用于对数字进行格式化处理。相比 calc，它提供了更简洁的 API，且跳过表达式解析，性能更好。

基本用法

import { fmt } from 'a-calc'

fmt(100, '=2')           // '100.00'
fmt(1234567, ',')        // '1,234,567'
fmt(0.1234, '%=2')       // '12.34%'

函数签名

function fmt(
  value: number | string,
  format?: string,
  options?: FmtOptions
): string | number

参数

参数	类型	描述
value	number | string	要格式化的数字
format	string	格式化字符串，语法与 calc 的 | 后部分相同
options	FmtOptions	可选配置项

返回值

默认返回格式化后的字符串。如果格式化字符串包含 !n，则返回数字类型。

格式化字符串

格式化字符串语法与 calc 函数完全一致：

小数位控制

fmt(3.14159, '=2')       // '3.14'   精确2位
fmt(3.14159, '<=2')      // '3.14'   最多2位
fmt(3.1, '>=3')          // '3.100'  最少3位
fmt(3.14159, '>=2<=4')   // '3.1415' 2-4位范围

舍入规则

fmt(1.125, '~5=2')       // '1.13'   四舍五入
fmt(1.125, '~6=2')       // '1.12'   银行家舍入
fmt(1.124, '~+=2')       // '1.13'   进位
fmt(1.129, '~-=2')       // '1.12'   截断（默认）

千分位

fmt(1234567, ',')        // '1,234,567'
fmt(1234567.89, ',=2')   // '1,234,567.89'

百分比

fmt(0.1234, '%')         // '12.34%'
fmt(0.1234, '%=1')       // '12.3%'

科学计数法

fmt(123456789, '!e')     // '1.23456789e+8'
fmt(123456789, '!e=2')   // '1.23e+8'

正负号

fmt(100, '+')            // '+100'
fmt(-100, '+')           // '-100'

分数形式

fmt(0.5, '/')            // '1/2'
fmt(0.75, '/')           // '3/4'

返回数字

fmt(100, '=2!n')         // 100 (number 类型)
fmt(100, '=2')           // '100.00' (string 类型)

配置选项

_error

错误时返回的值：

fmt('abc', '=2')                    // '-' (使用全局默认)
fmt('abc', '=2', { _error: 'N/A' }) // 'N/A'
fmt('abc', '=2', { _error: 0 })     // 0

_compact_symbols

紧凑格式化单位：

fmt(1500, '!c', {
  _compact_symbols: ['', 'K', 'M', 'B']
})  // '1.5K'

fmt(1500000, '!c', {
  _compact_symbols: ['', 'K', 'M', 'B']
})  // '1.5M'

_compact_step

紧凑格式进位步长（默认 1000）：

fmt(10000, '!c', {
  _compact_symbols: ['', '万', '亿'],
  _compact_step: 10000
})  // '1万'

与 calc 的区别

特性	calc	fmt
表达式计算	支持	不支持
变量填充	支持	不支持
格式化	支持	支持
性能	需要解析表达式	直接格式化，更快
API 风格	calc('100 | =2')	fmt(100, '=2')

使用场景

纯格式化场景

当你只需要格式化数字，不涉及计算时，使用 fmt 更简洁：

// 推荐
fmt(price, ',=2')

// 不推荐（多余的表达式解析）
calc(`${price} | ,=2`)

表格数据格式化

const data = [1234.5, 5678.9, 9012.3]
const formatted = data.map(n => fmt(n, ',=2'))
// ['1,234.50', '5,678.90', '9,012.30']

金融数据展示

// 金额
fmt(1234567.89, ',=2')          // '1,234,567.89'

// 涨跌幅
fmt(0.0523, '%=2+')             // '+5.23%'
fmt(-0.0312, '%=2+')            // '-3.12%'

// 紧凑格式
fmt(15000000, '!c', {
  _compact_symbols: ['', 'K', 'M', 'B']
})  // '15M'

类型定义

interface FmtOptions {
  _error?: any
  _compact_symbols?: string[]
  _compact_step?: number
  _compact?: Record<string, any>
  _thousands?: Record<string, ThousandsConfig>
}

type Fmt = (
  value: number | string,
  format?: string,
  options?: FmtOptions
) => string | number