number-to-chinese

使用 TypeScript 开发的轻量级插件，用于将数字转换为中文表示，支持普通中文数字和金融大写数字。最大支持千亿级别的数字转换。

注意事项

支持范围

• 最大支持数字: 999,999,999,999（九千九百九十九亿九千九百九十九万九千九百九十九）
• 支持单位: 个、十、百、千、万、亿
• 超出范围: 万亿（10^12）及以上的数字将抛出错误

其他限制

• 不支持负数返回，内部会将负数转换为其绝对值的中文表示
• 仅支持整数，不支持小数
• 支持 JavaScript 最大安全整数范围内的数字

安装

# 使用 npm
npm install zh-num

# 使用 yarn
yarn add zh-num

# 使用 pnpm
pnpm add zh-num

快速开始

import { numberToChinese } from 'zh-num'

// 基本使用
console.log(numberToChinese(123)) // "一百二十三"
console.log(numberToChinese(1001)) // "一千零一"

// 金融大写数字
console.log(numberToChinese(123, { useCapital: true })) // "壹佰贰拾叁"
console.log(numberToChinese(1001, { useCapital: true })) // "壹仟零壹"

API 说明

numberToChinese(value, options?)

将数字转换为中文表示。

参数

• value: number | string - 要转换的数字，可以是数字或数字字符串
• options?: NumberToChineseOptions - 转换选项（可选）

返回值

• string - 转换后的中文数字字符串

选项

interface NumberToChineseOptions {
  /**
   * 是否使用大写（金融）中文数字
   * @default false
   */
  useCapital?: boolean
}

使用示例

基本数字转换

import { numberToChinese } from 'zh-num'

// 个位数
numberToChinese(0) // "零"
numberToChinese(5) // "五"

// 十位数
numberToChinese(10) // "十"
numberToChinese(25) // "二十五"

// 百位数
numberToChinese(100) // "一百"
numberToChinese(123) // "一百二十三"

// 千位数
numberToChinese(1000) // "一千"
numberToChinese(1234) // "一千二百三十四"

// 万位数
numberToChinese(10000) // "一万"
numberToChinese(12345) // "一万二千三百四十五"

// 亿位数
numberToChinese(100000000) // "一亿"
numberToChinese(123456789) // "一亿二千三百四十五万六千七百八十九"

// 千亿位数
numberToChinese(123456789012) // "一千二百三十四亿五千六百七十八万九千零一十二"
numberToChinese(999999999999) // "九千九百九十九亿九千九百九十九万九千九百九十九"

金融大写数字

import { numberToChinese } from 'zh-num'

// 金融大写数字
numberToChinese(123, { useCapital: true }) // "壹佰贰拾叁"
numberToChinese(1001, { useCapital: true }) // "壹仟零壹"
numberToChinese(12345, { useCapital: true }) // "壹万贰仟叁佰肆拾伍"
numberToChinese(123456789, { useCapital: true }) // "壹亿贰仟叁佰肆拾伍万陆仟柒佰捌拾玖"

字符串输入

import { numberToChinese } from 'zh-num'

// 字符串输入
numberToChinese('123') // "一百二十三"
numberToChinese('1001') // "一千零一"
numberToChinese('-123') // "一百二十三"（负数取绝对值）

处理零

import { numberToChinese } from 'zh-num'

// 中间零的处理
numberToChinese(1001) // "一千零一"
numberToChinese(1010) // "一千零一十"
numberToChinese(10001) // "一万零一"

// 连续零的处理
numberToChinese(100001) // "十万零一"
numberToChinese(1000001) // "一百万零一"

// 末尾零的处理
numberToChinese(10) // "十"
numberToChinese(100) // "一百"
numberToChinese(1000) // "一千"

说明

数字转中文读法，边界问题有点多，所以我写了一堆测试用例，把各种数量级和极端情况都跑了一遍，自认为能够满足日常使用。如果有什么问题或者建议，欢迎反馈。