单位位置 3.x

单位位置语法用于在格式化结果中添加货币符号或其他单位，并控制其显示位置。

语法概览

语法	说明	示例
!u	去除单位（等同于 !uh）	100元 → 100
!u:单位	显示单位（位置可配置）	100 → 100元
!ua:单位	单位在数字后 (after)	100 → 100元
!ub:单位	单位在数字前 (before)	100 → $100
!um:单位	单位在中间 (middle)	-100 → -$100
!uh:单位	只转换，不显示单位	100分 → 1

!u - 去除单位（等同于 !uh）

!u 单独使用时，用于去除表达式中的单位，不进行单位转换：

calc('100元 | !u')              // '100' (去除单位)
calc('100元 | !uh')             // '100' (等同于 !u)

!u 和 !uh 的关系

!u 是 !uh 的缩写，两者完全等价。都是去除单位，不进行转换。

!u:unit - 显示单位（推荐）

最简洁的单位语法，默认单位在数字后面：

calc('100 | !u:元')              // '100元'
calc('100.5 | =2 !u:元')         // '100.50元'

可通过 set_config 设置全局默认位置：

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

set_config({ _unit_default_position: 'before' })
calc('100 | !u:$')   // '$100'

set_config({ _unit_default_position: 'middle' })
calc('-100 | + !u:$') // '-$100'

set_config({ _unit_default_position: 'after' })
calc('100 | !u:元')   // '100元'

!ua:unit - 单位在数字后 (after)

calc('100 | !ua:元')             // '100元'
calc('-50 | + !ua:元')           // '-50元'
calc('1234.5 | =2, !ua:元')      // '1,234.50元'

表达式

填充数据 (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

!ub:unit - 单位在数字前 (before)

calc('100 | !ub:$')              // '$100'
calc('-50 | !ub:$')              // '$-50'
calc('100 | + !ub:$')            // '$+100'
calc('1234.5 | =2, !ub:$')       // '$1,234.50'

表达式

填充数据 (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

!um:unit - 单位在中间 (middle)

将货币符号放在正负号和数字之间，常用于金融数据展示：

calc('8 | + !um:$')              // '+$8'
calc('-6 | + !um:$')             // '-$6'

// 不同货币
calc('100 | + !um:¥')            // '+¥100'
calc('-50 | + !um:€')            // '-€50'

// 结合千分位和小数
calc('12345 | +, !um:$')         // '+$12,345'
calc('-12345.67 | +=2, !um:$')   // '-$12,345.67'

// 多字符单位
calc('100 | + !um:USD')          // '+USD100'

表达式

填充数据 (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

中间位置说明

当没有符号时，!um 效果等同于 !ub：

calc('100 | !um:$')              // '$100' (无符号，同 !ub)
calc('100 | + !um:$')            // '+$100' (有符号，在中间)

!uh:unit - 只转换不显示

进行单位转换但不在结果中显示单位：

calc('100 | =2 !uh:元', {
  _unit_convert_out: { '元': { '分': 0.01 } }
})  // '1.00' (100分转换为1元，但不显示"元")

位置对比

const value = '-1234.56'

calc(`${value} | + !ua:$`)       // '-1234.56$'  (数字后)
calc(`${value} | + !ub:$`)       // '$-1234.56'  (数字前，符号在单位后)
calc(`${value} | + !um:$`)       // '-$1234.56'  (中间，符号在单位前)

@ 变量引用

使用 @ 前缀在单位语法中引用变量值：

// 基础引用
calc('100 | !ua:@unit', { unit: '元' })    // '100元'
calc('100 | !ub:@currency', { currency: '$' })  // '$100'
calc('-100 | + !um:@symbol', { symbol: '¥' })   // '-¥100'

// 变量路径
calc('100 | !ua:@config.unit', {
  config: { unit: '元' }
})  // '100元'

单位位置映射

可以为不同的单位预设不同的显示位置。

在 _unit_convert_out 中配置

使用 _position 字段：

calc('100 | =2 !u:元', {
  _unit_convert_out: {
    '元': {
      '分': 0.01,
      _position: 'after'  // 元在数字后
    }
  }
})  // '1.00元'

calc('100 | =2 !u:$', {
  _unit_convert_out: {
    '$': {
      '￠': 0.01,
      _position: 'before'  // $ 在数字前
    }
  }
})  // '$1.00'

使用 _unit_position_map

直接配置单位到位置的映射（优先级高于 _unit_convert_out 中的配置）：

calc('100 | !u:$', {
  _unit_position_map: {
    '$': 'before',
    '€': 'middle',
    '元': 'after'
  }
})  // '$100'

calc('-100 | + !u:€', {
  _unit_position_map: { '€': 'middle' }
})  // '-€100'

位置优先级

从低到高：

1. _unit_default_position（全局默认）
2. _unit_convert_out 中的 _position
3. _unit_position_map
4. 显式语法 !ua: / !ub: / !um:（最高）

calc('100 | !ua:$', {
  _unit_position_map: { '$': 'before' }  // 被 !ua 覆盖
})  // '100$' (显式 !ua 优先)

配置项速查

配置项	类型	说明
_unit_default_position	'after' | 'before' | 'middle'	全局单位位置
_unit_position_map	object	单位到位置的映射
_unit_convert_out[unit]._position	string	在单位转换中配置位置

格式语法	说明
!u	去除单位（等同于 !uh）
!u:unit	显示单位（位置可配置）
!ua:unit	单位在数字后
!ub:unit	单位在数字前
!um:unit	单位在中间
!uh:unit	只转换不显示单位
!u:@var	使用变量值作为单位

完整示例

多币种金融系统

const currencyOptions = {
  _unit_convert_out: {
    '元': {
      '分': 0.01,
      _position: 'after'
    },
    '$': {
      '￠': 0.01,
      _position: 'before'
    },
    '€': {
      'cent': 0.01,
      _position: 'before'
    }
  }
}

calc('12345 | =2, !u:元', currencyOptions)   // '123.45元'
calc('12345 | =2, !u:$', currencyOptions)    // '$123.45'
calc('12345 | =2, !u:€', currencyOptions)    // '€123.45'

涨跌幅显示

// 中间位置适合显示涨跌
calc('5.23 | + !um:$')           // '+$5.23'
calc('-3.17 | + !um:$')          // '-$3.17'

// 结合千分位和小数
calc('12345.67 | +=2, !um:$')    // '+$12,345.67'
calc('-12345.67 | +=2, !um:¥')   // '-¥12,345.67'

动态货币符号

function formatPrice(value, currency) {
  return calc(`${value} | =2, !u:@currency`, {
    currency,
    _unit_position_map: {
      '$': 'before',
      '€': 'before',
      '£': 'before',
      '元': 'after',
      '円': 'after'
    }
  })
}

formatPrice(1234.5, '$')    // '$1,234.50'
formatPrice(1234.5, '€')    // '€1,234.50'
formatPrice(1234.5, '元')   // '1,234.50元'
formatPrice(1234.5, '円')   // '1,234.50円'

与紧凑格式化组合

// 紧凑格式 + 单位位置
calc('1234567 | !c !ua:元')      // '1.23M元'
calc('1234567 | !c !ub:$')       // '$1.23M'
calc('-1234567 | +!c !um:$')     // '-$1.23M'