一、前言
在文档处理、大纲生成、制度文件、报表标题等开发场景中，我们经常需要把阿拉伯数字转换成规范中文数字，比如：
1 → 一、10 → 十、15 → 十五、23 → 二十三，再衍生出结构化标题：第一篇、第十五部分、第三十五章等。
Python 标准库没有内置数字转中文的工具函数，很多新手自己写逻辑时容易踩坑：十几的特殊读法、整十省略个位、拼接标题前缀后缀混乱等问题。
本文分三层实现：
- 基础版：1~99 纯中文数字转换（一、十、二十三）；
- 拓展版：封装成通用工具，支持生成「第X篇、第X部分」标准文档标题；
- 高阶扩展：简单拓展支持百位数，可自行延伸千、万级大数。
全部代码可直接复制使用，适配制度大纲、Markdown、Word 文档自动化生成场景。
二、基础需求分析（1~99中文数字规则）
先梳理中文数字固定语法规则，这是编写代码的核心依据：
- 1~9：直接输出「一、二…九」；
- 10~19：十位只读「十」，10 = 十、13 = 十三，十位不带一；
- 20~99：十位+十+个位，整十省略个位，20 = 二十、25 = 二十五；
- 100：单独处理为「一百」。
三、基础函数：纯数字转中文（1~100）
完整代码
defnum_to_plain_chinese(n:int)->str:""" 阿拉伯数字 1~100 转为纯中文数字 :param n: 输入整数 1 - 100 :return: 纯中文数字字符串 """ifnotisinstance(n,int):raiseTypeError("输入必须为整数")ifn<1orn>100:raiseValueError("当前仅支持 1 ~ 100 的数字转换")digits=["","一","二","三","四","五","六","七","八","九"]# 分离十位、个位ten_digit=n//10unit_digit=n%10ifn==100:return"一百"# 个位数 1-9iften_digit==0:returndigits[unit_digit]# 十位数 10-19eliften_digit==1:ifunit_digit==0:return"十"else:returnf"十{digits[unit_digit]}"# 二十~九十九else:ifunit_digit==0:returnf"{digits[ten_digit]}十"else:returnf"{digits[ten_digit]}十{digits[unit_digit]}"# 测试用例if__name__=="__main__":test_nums=[1,5,10,12,15,20,36,99,100]fornumintest_nums:print(f"{num}→{num_to_plain_chinese(num)}")运行输出
1 → 一 5 → 五 10 → 十 12 → 十二 15 → 十五 20 → 二十 36 → 三十六 99 → 九十九 100 → 一百代码关键点说明
- 校验输入：限制整数范围，防止非法数字报错；
- 数字映射数组
digits：下标对应中文，空字符串占位规避0的干扰； - 分段逻辑区分 个位数、十几、几十几，解决中文特殊读法；
- 单独处理100，适配长文档百级章节场景。
四、业务拓展：生成规范文档标题（第X篇/第X部分）
实际开发中，单纯的中文数字很少单独使用，更多搭配前缀「第」、后缀「篇/部分/章」生成大纲标题。
基于上面基础函数封装通用工具，统一命名规范，方便区分不同层级标题转换函数。
4.1 转换为「第X篇」标题函数
defnum_to_chinese_article_title(n:int)->str:"""数字转 第一篇、第十篇、第十五篇 格式标题"""chinese_str=num_to_plain_chinese(n)returnf"第{chinese_str}篇"# 测试print(num_to_chinese_article_title(1))# 第一篇print(num_to_chinese_article_title(15))# 第十五篇print(num_to_chinese_article_title(20))# 第二十篇print(num_to_chinese_article_title(99))# 第九十九篇4.2 转换为「第X部分」标题函数
defnum_to_chinese_part_title(n:int)->str:"""数字转 第一部分、第十三部分 格式标题"""chinese_str=num_to_plain_chinese(n)returnf"第{chinese_str}部分"print(num_to_chinese_part_title(12))# 第十二部分4.3 统一工具类封装（项目推荐写法）
多个转换函数整合为工具类，导入一处全局使用，命名区分层级，便于后期维护：
classChineseNumUtil:digits=["","一","二","三","四","五","六","七","八","九"]@classmethoddefnum_to_plain_chinese(cls,n:int)->str:ifnotisinstance(n,int):raiseTypeError("输入必须为整数")ifn<1orn>100:raiseValueError("仅支持 1 ~ 100")ten=n//10unit=n%10ifn==100:return"一百"iften==0:returncls.digits[unit]eliften==1:return"十"ifunit==0elsef"十{cls.digits[unit]}"else:returnf"{cls.digits[ten]}十"ifunit==0elsef"{cls.digits[ten]}十{cls.digits[unit]}"@classmethoddefnum_to_chinese_article_title(cls,n:int)->str:"""第X篇"""returnf"第{cls.num_to_plain_chinese(n)}篇"@classmethoddefnum_to_chinese_part_title(cls,n:int)->str:"""第X部分"""returnf"第{cls.num_to_plain_chinese(n)}部分"# 调用示例if__name__=="__main__":util=ChineseNumUtilprint(util.num_to_plain_chinese(15))print(util.num_to_chinese_article_title(15))print(util.num_to_chinese_part_title(15))五、常见开发踩坑点
坑1：十几数字错误输出「一十X」
很多新手直接拼接一十，出现「一十三」，不符合中文阅读习惯。
解决办法：单独判断十位等于1的分支，省略十位的「一」。
坑2：未做输入校验，传入浮点数、负数、超大数字
传入10.5、-3、200会直接数组下标越界。
解决办法：函数开头增加类型、范围校验，主动抛出异常方便调试。
坑3：多个标题转换逻辑重复，复制粘贴冗余代码
分别写「篇」「部分」两套数字转换逻辑，后期修改要多处改动。
解决办法：抽离底层纯数字转换公共函数，上层仅拼接前后缀。
坑4：函数命名混乱，无法区分层级
直接命名convert_num，后期新增1.1、（1）、① 等格式转换时难以区分。
解决办法：采用统一命名规范：num_to_chinese_xxx_title，后缀区分篇、部分、小节。
六、简单扩展：支持百以上大数（简易版）
如果业务需要超过100的数字，可简单扩展百位逻辑，示例：
defnum_to_plain_chinese_extend(n:int)->str:digits=["","一","二","三","四","五","六","七","八","九"]ifn==100:return"一百"if101<=n<=199:hundred="一百"rest=n-100ifrest==0:returnhundredreturnhundred+num_to_plain_chinese(rest)# 其余复用原有逻辑ten_digit=n//10unit_digit=n%10iften_digit==0:returndigits[unit_digit]eliften_digit==1:return"十"ifunit_digit==0elsef"十{digits[unit_digit]}"else:returnf"{digits[ten_digit]}十"ifunit_digit==0elsef"{digits[ten_digit]}十{digits[unit_digit]}"print(num_to_plain_chinese_extend(115))# 一百十五七、总结
- 中文数字转换核心是拆分十位、个位，特殊处理10~19省略「一」的语法；
- 分层开发：底层公共函数输出纯中文数字，上层封装各类文档标题格式；
- 工具类集中管理转换逻辑，统一命名，便于项目维护和扩展；
- 增加输入校验，规避非法参数导致的程序崩溃；
- 可根据业务需求自由拓展后缀，快速生成「第X章、第X节」等标准化大纲标题，广泛应用于文档自动化、爬虫文本处理、报表生成场景。