calc

calc 是 a-calc 的核心函数，用于执行精确计算和格式化。

函数变体

函数	描述
calc	核心计算函数，错误时抛出异常
fmt	格式化函数，参数为 (value, format_str, options)

基本签名

function calc(
  expr: string | number,
  options?: CalcConfig
): string | number  // 可能抛出异常

参数

expr

• 类型: string | number
• 必填: 是

计算表达式，支持以下格式：

// 纯数字
calc('123')              // '123'
calc(123)                // '123'

// 表达式
calc('1 + 2 * 3')        // '7'

// 带格式化
calc('10 / 3 | =2')      // '3.33'

// 带变量
calc('a + b', { a: 1, b: 2 })  // '3'

options

• 类型: object | array
• 必填: 否

配置选项或数据源。

配置属性

属性	类型	默认值	描述
_error	any	-	计算错误时返回的值，不设置则抛出异常
_unit	boolean	false	是否启用单位计算
_compact_symbols	string[]	["", "K", "M", "B", "T"]	紧凑格式单位数组
_compact_step	number | number[]	1000	紧凑格式阶梯，支持数组实现不规则阶梯
_unit_default_position	'after' | 'before' | 'middle'	-	默认单位位置
_empty_values	any[]	-	多路取值时视为空值的值数组
_empty_check	function	-	多路取值时自定义空值判断函数
[key: string]	any	-	变量值

只支持全局配置的选项

以下配置只能通过 set_config 全局设置，不支持在 calc 选项中传入：

• _fmt - 默认格式化字符串
• _unit_convert_out / _unit_convert_in - 单位转换映射
• _unit_default_out / _unit_default_in - 默认单位
• _unit_position_map / _unit_thousands_map / _unit_compact_map - 单位联动映射
• _thousands / _compact - 千分位和紧凑格式预设

支持局部和全局配置的选项

以下配置既可以在调用时传入（局部配置），也可以通过 set_config 全局设置（局部配置优先级更高）：

• _unit_default_position - 默认单位位置
• _compact_symbols / _compact_step - 紧凑格式单位和阶梯

返回值

• 类型: string | number | _error

默认返回字符串，使用 !n 格式化返回数字，错误时返回 _error 值。

使用示例

基本计算

import { calc } from 'a-calc'

calc('1 + 2')                    // '3'
calc('10 / 3')                   // '3.33333...'
calc('2 ** 10')                  // '1024'

变量填充

// 对象形式
calc('a + b', { a: 1, b: 2 })    // '3'

// 数组形式（多数据源）
calc('a + b', [{ a: 1 }, { b: 2 }])  // '3'

// 数组形式（配置 + 数据）
calc('a + b', [
  { _error: 0 },  // 配置
  { a: 1, b: 2 }  // 数据
])  // '3'

格式化

// 表达式内格式化
calc('10 / 3 | =2')              // '3.33'

// 使用 _fmt 配置
calc('10 / 3', { _fmt: '=2' })   // '3.33'

// _fmt 和表达式格式化可以组合，表达式格式化优先级更高
calc('10 / 3 | =4', { _fmt: '=2' })  // '3.3333' (表达式的 =4 覆盖 _fmt 的 =2)

错误处理

// 不设置 _error 时会抛出异常
calc('a + b')                    // Error: 非法的表达式

// 自定义错误返回值
calc('a + b', { _error: '-' })   // '-'
calc('a + b', { _error: 0 })     // 0
calc('a + b', { _error: null })  // null
calc('a + b', { _error: 'N/A' }) // 'N/A'

单位计算

calc('100元 + 50元', { _unit: true })     // '150元'
calc('10% + 5%', { _unit: true })          // '15%'

语法模式

// calc() - 标准语法（默认）
calc('1+2')                               // '3'
calc('1 + 2')                             // '3'

// calc_space() - 空格语法（支持所有 3.x 新功能）
import { calc_space } from 'a-calc'

calc_space('1 + 2')                       // '3'
calc_space('1 + 2 | = 2')                 // '3.00'
calc_space('100 | , = 2')                 // '100.00'

紧凑格式化

// 默认千进制
calc('1234567 | !c')                      // '1.23M'

// 使用预设
calc('12345 | !c:wan')                    // '1.23万'

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

完整示例

import { calc } from 'a-calc'

// 电商价格计算
const total = calc('price * quantity * (1 - discount) | ~5=2,', {
  price: 199.9,
  quantity: 3,
  discount: 0.15
})
// '509.75'

// 带单位的计算
const sum = calc('base + bonus | =2', {
  base: '1000元',
  bonus: '200元',
  _unit: true
})
// '1200.00元'

// 错误处理
const result = calc('invalid', { _error: '-' })  // '-'

表达式

填充数据 (JSON)

结果:

Ctrl+D 选择词, Ctrl+/ 注释GitHub LightXCode LightEclipseQuiet LightSolarized LightDuotone LightBBEditNoctis LilacTokyo Night DayWhite LightGitHub DarkVS Code DarkDraculaMonokaiMonokai DimmedSublimeAtom OneMaterialNordTokyo NightTokyo Night StormSolarized DarkGruvbox DarkDuotone DarkDarculaCopilotAndromedaAuraXCode DarkOkaidiaBespinKimbieAbyssTomorrow Night BlueRedABCDEFWhite DarkAndroid Studio