紧凑格式化 3.x

a-calc 提供了强大的紧凑格式化功能，可以将大数字自动转换为易读的 K/M/B/T 格式，广泛应用于股票、加密货币、社交媒体等场景。

设计理念

紧凑格式化的核心特点：

保守显示：使用截断而非四舍五入，避免夸大数字
灵活配置：支持多种预设和自定义单位
国际化支持：支持中文、英文等多种单位系统

基础用法

使用 !c 将大数字转换为简洁格式：

javascript

import { calc } from 'a-calc'

calc('1234 | !c')            // '1.23K'
calc('1234567 | !c')         // '1.23M'
calc('1234567890 | !c')      // '1.23B'
calc('1234567890000 | !c')   // '1.23T'

Ctrl+D 选择词, Ctrl+/ 注释

默认单位阶梯

数值范围	单位	示例
< 1,000	无	999
≥ 1,000	K (千)	1.23K
≥ 1,000,000	M (百万)	1.23M
≥ 1,000,000,000	B (十亿)	1.23B
≥ 1,000,000,000,000	T (万亿)	1.23T

小数位数控制

使用 =N 指定小数位数，默认为 2 位：

javascript

calc('1234567 | !c')         // '1.23M' (默认2位)
calc('1234567 | !c =1')      // '1.2M'
calc('1234567 | !c =0')      // '1M'
calc('1234567 | !c =4')      // '1.2345M'

截断模式

紧凑格式化使用截断（向零取整）而非四舍五入，这是为了避免夸大数字。

javascript

calc('999999 | !c')          // '999.99K' (而非 1M)
calc('1999 | !c =0')         // '1K' (而非 2K)

正负号显示

使用 + 为正数添加正号：

javascript

calc('1234567 | !c')         // '1.23M'
calc('1234567 | +!c')        // '+1.23M'
calc('-1234567 | !c')        // '-1.23M'
calc('-1234567 | +!c')       // '-1.23M' (负号保持不变)

内置预设

使用 !c:预设名 快速应用预设配置：

en (英文/国际通用)

千进制，英文单位：

javascript

calc('1234567 | !c')         // '1.23M'
// 等同于
calc('1234567 | !c:en') // '1.23M'

cn (中文千进制)

千进制，中文单位：

javascript

calc('1234 | !c:cn')         // '1.23千'
calc('1234567 | !c:cn')      // '1.23百万'
calc('1234567890 | !c:cn')   // '1.23十亿'

wan (万进制)

万进制，适合中文习惯：

javascript

calc('12345 | !c:wan')       // '1.23万'
calc('123456789 | !c:wan')   // '1.23亿'
calc('1234567890123 | !c:wan') // '1.23万亿'

Ctrl+D 选择词, Ctrl+/ 注释

万进制 vs 千进制

千进制：每 1000 进一级，符合西方习惯
万进制：每 10000 进一级，符合中文习惯

javascript

calc('12345678 | !c')        // '12.34M' (千进制)
calc('12345678 | !c:wan')    // '1234.56万' (万进制)

storage (存储单位)

1024 进制，用于文件大小：

javascript

calc('1024 | !c:storage')        // '1KB'
calc('1048576 | !c:storage')     // '1MB'
calc('1073741824 | !c:storage')  // '1GB'

预设对照表

预设	单位	阶梯	示例输入	示例输出
`en`	`["", "K", "M", "B", "T"]`	1000	1234567	1.23M
`cn`	`["", "千", "百万", "十亿", "万亿"]`	1000	1234567	1.23百万
`wan`	`["", "万", "亿", "万亿"]`	10000	12345	1.23万
`storage`	`["B", "KB", "MB", "GB", "TB"]`	1024	1048576	1MB
`indian`	`["", "K", "L", "Cr"]`	1000/100	1234567	12.34L

自定义预设

通过 _compact 配置自定义预设，支持通过 set_config 全局设置或在调用时传入。

全局设置预设

javascript

import { set_config, calc } from 'a-calc'

// 全局设置预设
set_config({
  _compact: {
    stock: {
      symbols: ["股", "万股", "亿股"],
      step: 10000
    },
    rmb: {
      symbols: ["元", "万元", "亿元"],
      step: 10000
    }
  }
})

// 使用预设
calc('12345 | !c:stock')     // '1.23万股'
calc('12345 | !c:rmb')       // '1.23万元'

数组形式（简写）

只定义单位数组，阶梯默认为 1000：

javascript

calc('1234567 | !c:stock', {
  _compact: {
    stock: ["", "千", "百万", "十亿"]
  }
})  // '1.23百万'

对象形式（完整）

定义单位和阶梯：

javascript

calc('12345 | !c:rmb', {
  _compact: {
    rmb: {
      symbols: ["元", "万元", "亿元"],
      step: 10000
    }
  }
})  // '1.23万元'

数组阶梯（不规则进制）

step 可以是数组，支持不规则的进制转换：

javascript

// 时间单位：秒 →(×60)→ 分 →(×60)→ 时 →(×24)→ 天
const timePreset = {
  _compact: {
    time: {
      symbols: ["秒", "分", "时", "天"],
      step: [60, 60, 24]
    }
  }
}

calc('60 | !c:time', timePreset)     // '1分'
calc('3600 | !c:time', timePreset)   // '1时'
calc('86400 | !c:time', timePreset)  // '1天'
calc('90061 | !c:time', timePreset)  // '1.04天'

数组阶梯工作原理：

原始值: 90061秒
第1步: 90061 ÷ 60 = 1501.01... (≥60，继续)
第2步: 1501.01 ÷ 60 = 25.01... (≥24，继续)
第3步: 25.01 ÷ 24 = 1.04... (无更高级别)
结果: 1.04天

覆盖内置预设

自定义预设可以覆盖同名的内置预设：

javascript

calc('1234567 | !c:cn', {
  _compact: {
    cn: ["", "K", "百万", "B"]  // 覆盖内置 cn 预设
  }
})  // '1.23百万'

直接配置

不使用预设名称，直接配置 _compact_symbols 和 _compact_step：

javascript

// 自定义单位
calc('1234567 | !c', {
  _compact_symbols: ["", "千", "百万", "十亿", "万亿"]
})  // '1.23百万'

// 自定义阶梯
calc('12345 | !c', {
  _compact_symbols: ["", "万", "亿"],
  _compact_step: 10000
})  // '1.23万'

// 数组阶梯
calc('3600 | !c', {
  _compact_symbols: ["秒", "分", "时"],
  _compact_step: [60, 60]
})  // '1时'

与单位语法组合

紧凑格式化可以与单位位置语法 (!u 系列) 组合使用：

javascript

// !c + !ua - 紧凑格式 + 单位在后
calc('1234567 | !c !ua:元')      // '1.23M元'
calc('1234 | !c !ua:股')         // '1.23K股'

// !c + !ub - 紧凑格式 + 单位在前
calc('1234567 | !c !ub:$')       // '$1.23M'
calc('-1234567 | !c !ub:$')      // '$-1.23M'

// !c + !um - 紧凑格式 + 单位在中间
calc('1234567 | +!c !um:$')      // '+$1.23M'
calc('-1234567 | +!c !um:$')     // '-$1.23M'

// 预设 + 单位
calc('12345 | !c:wan !ua:元')    // '1.23万元'
calc('123456789 | !c:wan !um:¥') // '¥1.23亿' (无符号时同 !ub)
calc('-123456789 | +!c:wan !um:¥') // '-¥1.23亿'

与单位转换组合

先进行单位转换，再进行紧凑格式化：

javascript

// 分转元，再显示紧凑格式
calc('100000 | !c !ua:元', {
  _unit_convert_out: { '元': { '分': 0.01 } }
})  // '1K元' (100000分 → 1000元 → 1K元)

// 美分转美元
calc('1000000 | !c !um:$', {
  _unit_convert_out: { '$': { '￠': 0.01 } }
})  // '$10K' (1000000美分 → 10000美元 → 10K)

边缘情况

小于阈值

小于第一个阶梯值时保持原样：

javascript

calc('999 | !c')             // '999' (< 1000)
calc('0 | !c')               // '0'
calc('0.5 | !c')             // '0.5'

非常小的数

小数会被截断显示：

javascript

calc('0.001 | !c')           // '0'
calc('0.999 | !c')           // '0.99'

超大数字

超过最高级别时继续使用最高单位：

javascript

calc('1234567890000000 | !c')  // '1234.56T'
calc('1e18 | !c')              // '1000000T'

小数输入

输入的小数也能正确处理：

javascript

calc('1234.567 | !c')        // '1.23K'
calc('1234567.89 | !c')      // '1.23M'

配置项速查

配置项	类型	说明
`_compact_symbols`	string[]	单位数组，从小到大
`_compact_step`	number \| number[]	阶梯值，数字或数组
`_compact`	object	自定义预设配置（可通过 set_config 全局设置）

格式语法	说明	示例
`!c`	使用默认预设	1.23M
`!c:preset`	使用指定预设	`!c:wan` → 123.45万
`!c =N`	指定小数位数	`!c =1` → 1.2M
`+!c`	显示正号	+1.23M

完整示例

股票交易量

javascript

const stockOptions = {
  _compact: {
    stock: {
      symbols: ["股", "万股", "亿股"],
      step: 10000
    }
  }
}

calc('12345 | !c:stock', stockOptions)      // '1.23万股'
calc('123456789 | !c:stock', stockOptions)  // '1.23亿股'

加密货币

javascript

const cryptoOptions = {
  _compact: {
    btc: {
      symbols: ["", "K", "M", "B"],
      step: 1000
    }
  }
}

calc('1234567 | !c:btc !ub:₿', cryptoOptions)  // '₿1.23M'
calc('-1234567 | +!c:btc !um:₿', cryptoOptions) // '-₿1.23M'

社交媒体粉丝数

javascript

const socialOptions = {
  _compact_symbols: ["", "K", "M"],
  _compact_step: 1000
}

calc('1234 | !c', socialOptions)      // '1.23K'
calc('1234567 | !c', socialOptions)   // '1.23M'

文件大小

javascript

calc('1536 | !c:storage')             // '1.5KB'
calc('1610612736 | !c:storage')       // '1.5GB'
calc('1610612736 | !c:storage =0')    // '1GB'

紧凑格式化 3.x ​

设计理念 ​

基础用法 ​

默认单位阶梯 ​

小数位数控制 ​

正负号显示 ​

内置预设 ​

en (英文/国际通用) ​

cn (中文千进制) ​

wan (万进制) ​

storage (存储单位) ​

预设对照表 ​

自定义预设 ​

全局设置预设 ​

数组形式（简写） ​

对象形式（完整） ​

数组阶梯（不规则进制） ​

覆盖内置预设 ​

直接配置 ​

与单位语法组合 ​

与单位转换组合 ​

边缘情况 ​

小于阈值 ​

非常小的数 ​

超大数字 ​

小数输入 ​

配置项速查 ​

完整示例 ​

股票交易量 ​

加密货币 ​

社交媒体粉丝数 ​

文件大小 ​

紧凑格式化 3.x

设计理念

基础用法

默认单位阶梯

小数位数控制

正负号显示

内置预设

en (英文/国际通用)

cn (中文千进制)

wan (万进制)

storage (存储单位)

预设对照表

自定义预设

全局设置预设

数组形式（简写）

对象形式（完整）

数组阶梯（不规则进制）

覆盖内置预设

直接配置

与单位语法组合

与单位转换组合

边缘情况

小于阈值

非常小的数

超大数字

小数输入

配置项速查

完整示例

股票交易量

加密货币

社交媒体粉丝数

文件大小