更新记录

1.0.0（2025-06-07） 下载此版本

更新日志

本文档记录了 nutpi-chinese-number-format 插件的所有重要更改。

[1.0.0] - 2024-12-19

新增功能

• ✨ 数字转中文功能 (toChinese)
• ✨ 中文转数字功能 (toNumber)
• ✨ 中文数字大写转换 (toUpperCase)
• ✨ 带单位的中文数字转换 (toChineseWithUnits)
• ✨ 大数字近似表示 (toChineseApproximate)
• ✨ 月份中文转换 (toChineseMonth)

平台兼容性

uni-app(4.65)

uni-app x(4.65)

nutpi-chinese-number-format

一个功能强大的中文数字格式化 UTS 插件，支持数字与中文之间的双向转换，适用于 uni-app 和 uni-app x 项目。

🌟 功能特性

• ✅ 数字转中文：支持阿拉伯数字转换为中文数字
• ✅ 中文转数字：支持中文数字转换为阿拉伯数字
• ✅ 大写转换：支持中文数字大写格式转换
• ✅ 单位支持：支持万、亿等中文数字单位
• ✅ 近似表示：支持大数字的近似中文表示
• ✅ 月份转换：支持数字月份转中文月份
• ✅ 多地区支持：支持简体中文（zh-CN）和繁体中文（zh-TW）
• ✅ 类型安全：完整的 TypeScript 类型定义
• ✅ 跨平台：支持 App、H5、小程序等多个平台

📦 安装

通过 uni_modules 安装

1. 将 nutpi-chinese-number-format 文件夹复制到项目的 uni_modules 目录下
2. 重新编译项目

手动安装

1. 下载插件源码
2. 将插件文件夹放置到 uni_modules 目录
3. 在 HBuilderX 中重新编译项目

🚀 快速开始

基本用法

import {
  toChinese,
  toChineseWithUnits,
  toNumber,
  toUpperCase,
  toChineseApproximate,
  toChineseMonth,
} from "@/uni_modules/nutpi-chinese-number-format";

// 数字转中文
const chinese = toChinese(123); // "一二三"
const chineseCN = toChinese(123, "zh-CN"); // "一二三"

// 数字转带单位的中文
const withUnits = toChineseWithUnits(12345); // "一萬二千三百四十五"
const withUnitsCN = toChineseWithUnits(12345, "zh-CN"); // "一万二千三百四十五"

// 中文转数字
const number = toNumber("一二三"); // 123
const numberFromChinese = toNumber("一萬二千三百四十五"); // 12345

// 转换为大写
const uppercase = toUpperCase("一二三"); // "壹貳參"
const uppercaseCN = toUpperCase("一二三", "zh-CN"); // "壹贰叁"

// 大数字近似表示
const approximate = toChineseApproximate(123456789); // "一點二億"
const approximateCN = toChineseApproximate(123456789, { locale: "zh-CN" }); // "一点二亿"

// 月份转换
const month = toChineseMonth(10); // "十月"
const traditionalMonth = toChineseMonth(1, { format: "traditional" }); // "正月"

在 Vue 组件中使用

<template>
  <view class="container">
    <text>数字 123 转中文：{{ chineseNumber }}</text>
    <text>中文 "一二三" 转数字：{{ arabicNumber }}</text>
  </view>
</template>

<script setup lang="ts">
import { toChinese, toNumber } from "@/uni_modules/nutpi-chinese-number-format";

const chineseNumber = toChinese(123);
const arabicNumber = toNumber("一二三");
</script>

📚 API 文档

类型定义

// 支持的地区类型
export type Locales = "zh-TW" | "zh-CN";

// 选项接口
export interface Options {
  locale?: Locales;
  precision?: number;
}

// 月份选项接口
export interface MonthOptions {
  locale?: Locales;
  format?: "traditional" | "simple";
}

核心函数

toChinese(num: number, locale?: Locales): string

将阿拉伯数字转换为中文数字。

参数：

• num: 要转换的数字
• locale: 地区设置，默认为 'zh-TW'

返回值： 中文数字字符串

示例：

toChinese(123); // "一二三"
toChinese(123, "zh-CN"); // "一二三"

toChineseWithUnits(num: number, locale?: Locales): string

将数字转换为带单位的中文表示。

参数：

• num: 要转换的数字
• locale: 地区设置，默认为 'zh-TW'

返回值： 带单位的中文数字字符串

示例：

toChineseWithUnits(12345); // "一萬二千三百四十五"
toChineseWithUnits(12345, "zh-CN"); // "一万二千三百四十五"

toNumber(str: string): number

将中文数字字符串转换为阿拉伯数字。

参数：

• str: 中文数字字符串

返回值： 数字，如果转换失败返回 NaN

示例：

toNumber("一二三"); // 123
toNumber("一萬二千三百四十五"); // 12345

toUpperCase(str: string, locales?: Locales): string

将中文数字转换为大写形式。

参数：

• str: 中文数字字符串
• locales: 地区设置，默认为 'zh-TW'

返回值： 大写中文数字字符串

示例：

toUpperCase("一二三"); // "壹貳參"
toUpperCase("一二三", "zh-CN"); // "壹贰叁"

toChineseApproximate(num: number, options?: Options): string

将大数字转换为近似的中文表示。

参数：

• num: 要转换的数字
• options: 选项对象
  • locale: 地区设置，默认为 'zh-TW'
  • precision: 精度，默认为 1

返回值： 近似的中文数字字符串

示例：

toChineseApproximate(123456789); // "一點二億"
toChineseApproximate(123456789, { locale: "zh-CN", precision: 2 }); // "一点二三亿"

toChineseMonth(month: number, options?: MonthOptions): string

将数字月份转换为中文月份。

参数：

• month: 月份数字（1-12）
• options: 选项对象
  • locale: 地区设置，默认为 'zh-TW'
  • format: 格式类型，'traditional' 或 'simple'，默认为 'simple'

返回值： 中文月份字符串

示例：

toChineseMonth(10); // "十月"
toChineseMonth(1, { format: "traditional" }); // "正月"
toChineseMonth(12, { format: "traditional", locale: "zh-CN" }); // "腊月"

🔧 开发注意事项

环境要求

• HBuilderX: 3.6.8 或更高版本
• uni-app: 支持 Vue 2 和 Vue 3
• uni-app x: 完全支持
• 平台支持: App（Android/iOS/Harmony）、H5、小程序等

性能优化

1. 预计算映射表: 插件内部使用预计算的反向映射表来优化 toNumber 函数的性能
2. 类型推断: 所有函数都提供完整的 TypeScript 类型支持
3. 内存效率: 避免不必要的字符串操作和对象创建

使用建议

1. 地区设置: 根据目标用户选择合适的地区设置（'zh-TW' 或 'zh-CN'）
2. 错误处理: toNumber 函数在转换失败时返回 NaN，请做好错误处理
3. 大数字处理: 对于超大数字，建议使用 toChineseApproximate 函数
4. 月份验证: toChineseMonth 函数只接受 1-12 的整数，其他值返回空字符串

常见问题

Q: 为什么 toNumber 返回 NaN？ A: 可能的原因包括：

• 输入字符串包含无法识别的字符
• 输入为空字符串
• 输入格式不正确

Q: 如何处理小数？ A: 插件支持小数转换，使用相应地区的小数点符号（繁体："點"，简体："点"）

Q: 支持哪些数字范围？ A: 理论上支持 JavaScript Number 类型的所有有效数字范围

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🤝 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。

📞 联系方式

如有问题或建议，请通过以下方式联系：

• 作者：坚果派
• 公众号：nutpi
• 电话：
• 官网：https://www.nutpi.net/
• 提交 Issue：https://gitcode.com/nutpi/uni-chinese-number-format/issues

注意: 本插件基于 UTS (UniApp TypeScript) 开发，确保在支持 UTS 的环境中使用。