@gitlon/format

常用展示格式化工具。包含日期、数字、金额、百分比、文件大小、手机号、银行卡和字符串格式化。

所有函数均为独立命名导出，便于按需使用。

安装

pnpm add @gitlon/format

也可安装聚合包：

pnpm add gitlon

导入

直接使用子包：

import {
  formatBankCard,
  formatDate,
  formatDateTime,
  formatFileSize,
  formatMoney,
  formatNumber,
  formatPercent,
  formatPhone,
  formatString,
} from '@gitlon/format'

通过主包使用：

import { formatDate, formatMoney, formatPhone } from 'gitlon'

API 总览

| 函数 | 默认行为 | | --- | --- | | formatDate | 格式化为 YYYY-MM-DD | | formatDateTime | 格式化为 YYYY-MM-DD HH:mm:ss | | formatNumber | 添加千分位，保留原数字小数表现 | | formatMoney | 添加千分位，保留 2 位小数 | | formatPercent | 比例乘以 100，保留 2 位小数并追加 % | | formatFileSize | 按 1024 进制转换文件大小 | | formatPhone | 中国大陆手机号按 3-4-4 分组或脱敏 | | formatBankCard | 银行卡号按每 4 位分组或脱敏 | | formatString | 去除首尾空白、设置默认值或截断 |

日期

formatDate('2026-09-15')
// '2026-09-15'

formatDate(new Date('2026-09-15T10:30:00'), 'YYYY年MM月DD日')
// '2026年09月15日'

formatDateTime('2026-09-15 10:30:45')
// '2026-09-15 10:30:45'

formatDateTime(1789439445000, 'MM-DD HH:mm')
// 按当前运行环境时区格式化

签名：

import type { ConfigType } from '@gitlon/time'

function formatDate(value: ConfigType, format?: string): string
function formatDateTime(value: ConfigType, format?: string): string

规则：

• formatDate 默认格式为 YYYY-MM-DD。
• formatDateTime 默认格式为 YYYY-MM-DD HH:mm:ss。
• 使用 @gitlon/time（dayjs）解析和格式化。
• null、undefined、空字符串或无效日期返回 ''。

数字

formatNumber(1234567.8)
// '1,234,567.8'

formatNumber('1234567.8', { decimals: 2 })
// '1,234,567.80'

formatNumber(1234567.8, {
  decimals: 2,
  separator: '.',
  decimalSeparator: ',',
  prefix: '约 ',
  suffix: ' 元',
})
// '约 1.234.567,80 元'

interface NumberFormatOptions {
  decimals?: number
  separator?: string
  decimalSeparator?: string
  prefix?: string
  suffix?: string
}

function formatNumber(value: unknown, options?: NumberFormatOptions): string

| 选项 | 默认值 | 说明 | | --- | --- | --- | | decimals | 不指定 | 固定小数位；负数按 0 处理，小数向下取整 | | separator | , | 千分位分隔符 | | decimalSeparator | . | 小数分隔符 | | prefix | '' | 结果前缀 | | suffix | '' | 结果后缀 |

数字及数字字符串可用。空值、空字符串、NaN、Infinity 或无法转为有限数字的值返回 ''。

金额

formatMoney(1234567.8)
// '1,234,567.80'

formatMoney(1234567.8, { symbol: '¥' })
// '¥1,234,567.80'

formatMoney(1234567.8, {
  symbol: ' USD',
  symbolPosition: 'suffix',
  decimals: 2,
})
// '1,234,567.80 USD'

interface MoneyFormatOptions extends NumberFormatOptions {
  symbol?: string
  symbolPosition?: 'prefix' | 'suffix'
}

function formatMoney(value: unknown, options?: MoneyFormatOptions): string

• 默认保留 2 位小数。
• 默认不添加货币符号。
• symbolPosition 默认是 prefix。
• 其他数字格式选项继承自 NumberFormatOptions。

百分比

formatPercent(0.1234)
// '12.34%'

formatPercent(12.34, { input: 'percent' })
// '12.34%'

formatPercent(0.5, { decimals: 0, prefix: '完成：' })
// '完成：50%'

interface PercentFormatOptions extends NumberFormatOptions {
  input?: 'ratio' | 'percent'
}

function formatPercent(value: unknown, options?: PercentFormatOptions): string

• input 默认是 ratio，输入值先乘以 100。
• 已经是百分数值时，传入 input: 'percent'。
• 默认保留 2 位小数。
• % 固定追加在自定义 suffix 之后。

文件大小

formatFileSize(0)
// '0 B'

formatFileSize(1024)
// '1.00 KB'

formatFileSize(1536)
// '1.50 KB'

formatFileSize(1024 * 1024, { decimals: 0 })
// '1 MB'

interface FileSizeFormatOptions {
  decimals?: number
  separator?: string
}

function formatFileSize(value: unknown, options?: FileSizeFormatOptions): string

• 使用二进制换算：1 KB = 1024 B。
• 单位范围：B、KB、MB、GB、TB、PB。
• 默认保留 2 位小数；0 B 不带小数。
• 负数、空值或非法数字返回 ''。

手机号

formatPhone('13812345678')
// '138 1234 5678'

formatPhone('138-1234-5678', { separator: '-' })
// '138-1234-5678'

formatPhone('13812345678', { mask: true })
// '138****5678'

interface PhoneFormatOptions {
  separator?: string
  mask?: boolean
}

function formatPhone(value: unknown, options?: PhoneFormatOptions): string

输入会先移除非数字字符，再按中国大陆手机号规则 1[3-9]xxxxxxxxx 判断。无效输入返回 ''。脱敏时固定输出前 3 位和后 4 位。

银行卡

formatBankCard('6222021234567890123')
// '6222 0212 3456 7890 123'

formatBankCard('6222021234567890123', { separator: '-' })
// '6222-0212-3456-7890-123'

formatBankCard('6222021234567890123', { mask: true })
// '6222 **** **** **** 0123'

interface BankCardFormatOptions {
  separator?: string
  mask?: boolean
}

function formatBankCard(value: unknown, options?: BankCardFormatOptions): string

输入会先移除非数字字符。少于 12 位返回 ''；普通模式每 4 位分组。该函数只负责展示，不执行 Luhn 合法性校验；校验请使用 @gitlon/validate 的 isBankCard。

字符串

formatString('  hello  ')
// 'hello'

formatString('abcdefghijkl', { maxLength: 5 })
// 'abcde...'

formatString('abcdefghijkl', { maxLength: 5, ellipsis: '…' })
// 'abcde…'

formatString(null, { defaultValue: '-' })
// '-'

formatString('  hello  ', { trim: false })
// '  hello  '

interface StringFormatOptions {
  trim?: boolean
  maxLength?: number
  ellipsis?: string
  defaultValue?: string
}

function formatString(value: unknown, options?: StringFormatOptions): string

• trim 默认是 true。
• maxLength 表示截断后保留的原字符串长度，不包含省略号。
• ellipsis 默认是 ...。
• null、undefined 或清理后的空字符串使用 defaultValue；未设置时返回 ''。

类型导入

import type {
  BankCardFormatOptions,
  FileSizeFormatOptions,
  MoneyFormatOptions,
  NumberFormatOptions,
  PercentFormatOptions,
  PhoneFormatOptions,
  StringFormatOptions,
} from '@gitlon/format'

使用聚合包时：

import type { MoneyFormatOptions, PhoneFormatOptions } from 'gitlon'

边界行为

• 格式化函数用于展示层；无法处理的主要输入返回 ''，不提供错误信息。
• formatPhone、formatBankCard 会清除输入中的非数字字符。
• formatBankCard 只格式化，不判断卡号是否真实或有效。
• 日期结果受本地时区及 dayjs 解析规则影响。