Python阿拉伯数字转圆圈数字Unicode偏移转换实现教程

脚本专家

在自动生成文档大纲、制度文件或Markdown目录时，带圈数字（①⑪⑳）常用于最低层级小标题。Python标准库没有直接提供该转换方法，网上多数代码仅支持1到10，且缺少参数校验和统一封装。本文将基于Unicode偏移公式，实现一套覆盖1到20的圆圈数字转换工具，包括基础函数、安全容错版本、工具类封装以及业务整合方案。

## 原理：Unicode编码偏移

带圈数字在Unicode中是独立字符，编码区间为：

- ① U+2460  ← 对应数字1
- ⑩ U+2469  ← 对应数字10
- ⑪ U+246A  ← 对应数字11
- ⑳ U+2473  ← 对应数字20

规律非常简洁：数字n对应的代码点 = 0x2460 + n - 1。例如n=11时，0x2460+10=0x246A，即字符⑪。利用该偏移公式，无需手动维护字典，一行chr()即可获取圆圈字符。

## 基础转换函数

以下函数接受整数1~20，返回对应圆圈字符，并包含类型和范围校验。

2. def num_to_circle_char(n: int) -> str:
3.     """
4.     阿拉伯数字 1~20 转换为圆圈数字 ①②③…⑳
5.     :param n: 输入整数，范围 1 ~ 20
6.     :return: 圆圈单个字符
7.     """
8.     if not isinstance(n, int):
9.         raise TypeError("输入必须为整数类型")
10.     if not 1 <= n <= 20:
11.         raise ValueError("当前仅支持 1 ~ 20 的数字转换圆圈序号")
12.     code_point = 0x2460 + n - 1
13.     return chr(code_point)
15. if __name__ == "__main__":
16.     test_list = [1, 5, 10, 13, 18, 20]
17.     for num in test_list:
18.         res = num_to_circle_char(num)
19.         print(f"{num} → {res}")

复制代码

运行输出：

2. 1 → ①
3. 5 → ⑤
4. 10 → ⑩
5. 13 → ⑬
6. 18 → ⑱
7. 20 → ⑳

复制代码

## 异常容错安全版（生产推荐）

业务代码不希望因非法输入直接崩溃，可改用安全版：超出范围或类型错误时返回默认值，不抛异常。

2. def num_to_circle_char_safe(n: int, default: str = "") -> str:
3.     """
4.     安全版，越界返回默认值
5.     :param n: 目标数字
6.     :param default: 超出范围/类型错误时返回内容
7.     :return: 圆圈字符或默认值
8.     """
9.     try:
10.         if not isinstance(n, int):
11.             return default
12.         if 1 <= n <= 20:
13.             code_point = 0x2460 + n - 1
14.             return chr(code_point)
15.         return default
16.     except Exception:
17.         return default
19. # 测试
20. print(num_to_circle_char_safe(21))      # 空
21. print(num_to_circle_char_safe(0, "无")) # 无
22. print(num_to_circle_char_safe("abc"))   # 空
23. print(num_to_circle_char_safe(12))      # ⑫

复制代码

## 统一工具类封装

将圆圈数字转换与已有的“中文数字”、“第X篇”、“第X部分”整合到一个工具类中，便于项目管理。

2. class ChapterNumUtil:
3.     digits = ["", "一", "二", "三", "四", "五", "六", "七", "八", "九"]
5.     @classmethod
6.     def num_to_plain_chinese(cls, n: int) -> str:
7.         """纯中文数字：1→一、15→十五、100→一百"""
8.         if not isinstance(n, int) or n < 1 or n > 100:
9.             raise ValueError("仅支持1~100整数")
10.         if n == 100:
11.             return "一百"
12.         ten = n // 10
13.         unit = n % 10
14.         if ten == 0:
15.             return cls.digits[unit]
16.         elif ten == 1:
17.             return "十" if unit == 0 else f"十{cls.digits[unit]}"
18.         else:
19.             return f"{cls.digits[ten]}十" if unit == 0 else f"{cls.digits[ten]}十{cls.digits[unit]}"
21.     @classmethod
22.     def num_to_chinese_article_title(cls, n: int) -> str:
23.         return f"第{cls.num_to_plain_chinese(n)}篇"
25.     @classmethod
26.     def num_to_chinese_part_title(cls, n: int) -> str:
27.         return f"第{cls.num_to_plain_chinese(n)}部分"
29.     @classmethod
30.     def num_to_circle_char(cls, n: int) -> str:
31.         if not isinstance(n, int) or not 1 <= n <= 20:
32.             raise ValueError("圆圈序号仅支持1~20")
33.         return chr(0x2460 + n - 1)
35.     @classmethod
36.     def num_to_circle_char_safe(cls, n: int, default="") -> str:
37.         try:
38.             return cls.num_to_circle_char(n)
39.         except (TypeError, ValueError):
40.             return default
42. # 统一调用示例
43. util = ChapterNumUtil
44. print(util.num_to_chinese_article_title(3))  # 第三篇
45. print(util.num_to_chinese_part_title(12))    # 第十二部分
46. print(util.num_to_circle_char(7))            # ⑦
47. print(util.num_to_circle_char(19))           # ⑲
48. print(util.num_to_circle_char_safe(99, "超出范围"))  # 超出范围

复制代码

## 实战场景：大纲层级搭配

制度文档中常需多级编号，可结合工具类实现：

- 层级0：num_to_chinese_article_title(2) → 第二篇
- 层级1：num_to_chinese_part_title(3) → 第三部分
- 层级2：普通阿拉伯数字 1、2、3
- 层级3：小数 1.1、1.2
- 层级6：num_to_circle_char(2) → ②

示例代码：

2. article = ChapterNumUtil.num_to_chinese_article_title(2)
3. circle = ChapterNumUtil.num_to_circle_char(2)
4. print(f"{article}\n  4.1 管理要求\n    {circle} 业务办理流程")

复制代码

输出：

2. 第二篇
3.   4.1 管理要求
4.     ② 业务办理流程

复制代码

## 常见踩坑

1. **超过20无标准字符**：Unicode只定义了①到⑳（U+2460～U+2473），21及以上没有标准圆圈字符。业务设计时建议控制层级不超过20，若必须使用21以上，改用(21)括号文本替代。
2. **不要用字符串拼接(1)代替**：(1)是三个普通符号，与原生圆圈字符在字体排版、对齐、导出Word/Markdown时视觉差异明显。规范文档必须使用Unicode圆圈字符。
3. **浮点数类型问题**：10.0虽数值等于10，但类型为float，会触发类型校验。调用前需强制转整数 int(num)。
4. **编码兼容性**：主流编辑器、Word、WPS、浏览器均完美支持U+2460~U+2473，无乱码风险。

## 拓展：批量生成全部圆圈序号

快速打印1~20所有圆圈字符用于调试：

2. circle_list = [num_to_circle_char(i) for i in range(1, 21)]
3. print(circle_list)
4. # ['①', '②', '③', '④', '⑤', '⑥', '⑦', '⑧', '⑨', '⑩', '⑪', '⑫', '⑬', '⑭', '⑮', '⑯', '⑰', '⑱', '⑲', '⑳']

复制代码

## 总结

圆圈数字本质是连续Unicode字符，通过固定偏移公式0x2460+n-1快速计算，无需字典映射。基础函数严格限制1~20，安全容错版本适配生产环境。与中文数字、第X篇等封装在同一工具类中，命名统一，多层级大纲生成时便于调用。原生Unicode圆圈字符排版规范，适合自动化生成制度手册或Markdown文档。注意序号上限20，超出需改用括号格式作为备选方案。

热心网友5

这个教程非常实用！以前我处理目录大纲时，遇到带圈数字只能手动打或者去网上找转义表，最多支持到⑩。楼主直接用Unicode偏移一行chr()搞定，还做了类型校验和范围限制，安全版的设计对生产环境也很友好。工具类中顺便把中文数字和“第X篇”也整合进来，感觉很贴合实际文档生成需求。请问如果我想扩展到圆圈数字①到⑳之外的字符（比如带圈字母），是否也可以用类似的偏移公式？

热心网友5

楼主分享的帖子非常实用，尤其是Unicode偏移公式的思路很清晰，直接chr()就能搞定，比手动维护字典优雅多了。安全容错版本考虑到了生产环境，避免抛异常导致程序中断，这个设计很周到。工具类里还整合了中文数字转换，方便统一管理章节编号，对文档生成场景很有帮助。 请问如果未来需要支持21以上的圆圈数字（比如Unicode里还有带括弧的⓪⑲⑳之后就没有了），是否只能通过组合字符或自定义字体来实现？有没有其他替代方案？

热心网友5

非常好的教程，原理清晰、代码规范，从基础函数到容错版本再到工具类封装，层层递进，很适合直接用在项目里。之前自己写这类转换总要手动维护字典，看到Unicode偏移公式后确实清爽很多。安全版的做法也很实用，生产环境里确实需要避免因为非法输入直接抛异常。另外，工具类里顺便封装了中文数字和“第X篇”的转换，这个思路很棒，一套工具解决多种标题目的是很省事的。感谢分享！