Number 数字格式化

    提供一系列数字格式化工具函数，支持保留精度、千分位分隔、自动单位转换等功能。

    安装

    npm
    yarn
    pnpm
    bun
    deno
    npx shadcn@latest add https://codebase.anyask.dev/r/utils-number.json

    formatWithPrecision

    保留指定小数位数的数字格式化函数。超出精度的部分会被四舍五入，不足则保持原样。

    功能特点

    • 支持任意数值类型的输入
    • 自动处理空值和 NaN
    • 精度超出截断，不足保持原样

    使用示例

    formatNumber

    数字格式化函数，支持自动添加单位（万、百万、千万、亿）和千分位分隔。

    功能特点

    • 自动识别数值范围添加适当单位
    • 支持自定义小数位数
    • 支持自定义千分位分隔符
    • 可选择是否启用单位格式化

    单位换算规则

    数值范围单位
    ≥ 1亿亿
    ≥ 1千万千万
    ≥ 1百万百万
    ≥ 1万万
    < 1万原值显示

    使用示例

    formatNumberWithUnit

    带单位的数字格式化，在格式化后的数字后追加指定单位。

    功能特点

    • 自动格式化数字并追加单位
    • 自动处理空值情况
    • 0 会被正常格式化

    使用示例

    formatWithSeparator

    为数字添加千分位分隔符。

    功能特点

    • 支持自定义分隔符
    • 自动处理整数和小数部分
    • 空值返回空字符串

    使用示例

    formatAndSplitValueUnit

    将带单位的数值字符串分离为值和单位两部分。

    功能特点

    • 智能识别数值和单位
    • 支持格式化选项
    • 空值返回 { value: null, unit: null }

    使用示例

    formatAndSplitValueIntegerDecimalUnit

    将带单位的数值字符串分离为整数部分、小数部分和单位三部分。

    功能特点

    • 分别返回整数部分、小数部分和单位
    • 小数部分带 . 分隔符标识
    • 适合需要分别渲染整数和小数的场景

    返回值结构

    {
  integerPart: string | null;  // 整数部分
  decimalPart: string | null;  // 小数部分（带 . 标识）
  unit: string | null;         // 单位
}

    使用示例

    API 参考

    通用类型

    type FormatNumberInput = string | number | null | undefined;

interface FormatNumberOptions {
  /** 保留的小数位数 */
  precision?: number;
  /** 千分位分隔符 */
  separator?: string;
  /** 是否格式化数值（添加单位：万、百万、千万、亿） */
  shouldFormat?: boolean;
}

    函数签名

    函数签名
    formatWithPrecision(value: FormatNumberInput, precision?: number) => string | null
    formatNumber(value: FormatNumberInput, options?: FormatNumberOptions) => string | null
    formatNumberWithUnit(value: FormatNumberInput, unit: string, options?: FormatNumberOptions) => string | null
    formatWithSeparator(value: FormatNumberInput, separator?: string) => string
    formatAndSplitValueUnit(input: FormatNumberInput, options?: FormatNumberOptions) => { value: string | null, unit: string | null }
    formatAndSplitValueIntegerDecimalUnit(input: FormatNumberInput, options?: FormatNumberOptions) => { integerPart: string | null, decimalPart: string | null, unit: string | null }