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，返回对应圆圈字符，并包含类型和范围校验。
def num_to_circle_char(n: int) -> str:
"""
阿拉伯数字 1~20 转换为圆圈数字 ①②③…⑳
:param n: 输入整数，范围 1 ~ 20
:return: 圆圈单个字符
"""
if not isinstance(n, int):
raise TypeError("输入必须为整数类型")
if not 1 <= n <= 20:
raise ValueError("当前仅支持 1 ~ 20 的数字转换圆圈序号")
code_point = 0x2460 + n - 1
return chr(code_point)
if __name__ == "__main__":
test_list =
for num in test_list:
res = num_to_circle_char(num)
print(f"{num} → {res}")
运行输出：
1 → ①
5 → ⑤
10 → ⑩
13 → ⑬
18 → ⑱
20 → ⑳
## 异常容错安全版（生产推荐）
业务代码不希望因非法输入直接崩溃，可改用安全版：超出范围或类型错误时返回默认值，不抛异常。
def num_to_circle_char_safe(n: int, default: str = "") -> str:
"""
安全版，越界返回默认值
:param n: 目标数字
:param default: 超出范围/类型错误时返回内容
:return: 圆圈字符或默认值
"""
try:
if not isinstance(n, int):
return default
if 1 <= n <= 20:
code_point = 0x2460 + n - 1
return chr(code_point)
return default
except Exception:
return default
# 测试
print(num_to_circle_char_safe(21)) # 空
print(num_to_circle_char_safe(0, "无")) # 无
print(num_to_circle_char_safe("abc")) # 空
print(num_to_circle_char_safe(12)) # ⑫
## 统一工具类封装
将圆圈数字转换与已有的“中文数字”、“第X篇”、“第X部分”整合到一个工具类中，便于项目管理。
class ChapterNumUtil:
digits = ["", "一", "二", "三", "四", "五", "六", "七", "八", "九"]
@classmethod
def num_to_plain_chinese(cls, n: int) -> str:
"""纯中文数字：1→一、15→十五、100→一百"""
if not isinstance(n, int) or n < 1 or n > 100:
raise ValueError("仅支持1~100整数")
if n == 100:
return "一百"
ten = n // 10
unit = n % 10
if ten == 0:
return cls.digits
elif ten == 1:
return "十" if unit == 0 else f"十{cls.digits}"
else:
return f"{cls.digits}十" if unit == 0 else f"{cls.digits}十{cls.digits}"
@classmethod
def num_to_chinese_article_title(cls, n: int) -> str:
return f"第{cls.num_to_plain_chinese(n)}篇"
@classmethod
def num_to_chinese_part_title(cls, n: int) -> str:
return f"第{cls.num_to_plain_chinese(n)}部分"
@classmethod
def num_to_circle_char(cls, n: int) -> str:
if not isinstance(n, int) or not 1 <= n <= 20:
raise ValueError("圆圈序号仅支持1~20")
return chr(0x2460 + n - 1)
@classmethod
def num_to_circle_char_safe(cls, n: int, default="") -> str:
try:
return cls.num_to_circle_char(n)
except (TypeError, ValueError):
return default
# 统一调用示例
util = ChapterNumUtil
print(util.num_to_chinese_article_title(3))# 第三篇
print(util.num_to_chinese_part_title(12)) # 第十二部分
print(util.num_to_circle_char(7)) # ⑦
print(util.num_to_circle_char(19)) # ⑲
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) → ②
示例代码：
article = ChapterNumUtil.num_to_chinese_article_title(2)
circle = ChapterNumUtil.num_to_circle_char(2)
print(f"{article}\n4.1 管理要求\n {circle} 业务办理流程")
输出：
第二篇
4.1 管理要求
② 业务办理流程
## 常见踩坑
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所有圆圈字符用于调试：
circle_list =
print(circle_list)
# ['①', '②', '③', '④', '⑤', '⑥', '⑦', '⑧', '⑨', '⑩', '⑪', '⑫', '⑬', '⑭', '⑮', '⑯', '⑰', '⑱', '⑲', '⑳']
## 总结
圆圈数字本质是连续Unicode字符，通过固定偏移公式0x2460+n-1快速计算，无需字典映射。基础函数严格限制1~20，安全容错版本适配生产环境。与中文数字、第X篇等封装在同一工具类中，命名统一，多层级大纲生成时便于调用。原生Unicode圆圈字符排版规范，适合自动化生成制度手册或Markdown文档。注意序号上限20，超出需改用括号格式作为备选方案。
Re: Python阿拉伯数字转圆圈数字Unicode偏移转换实现教程
这个教程非常实用！以前我处理目录大纲时，遇到带圈数字只能手动打或者去网上找转义表，最多支持到⑩。楼主直接用Unicode偏移一行chr()搞定，还做了类型校验和范围限制，安全版的设计对生产环境也很友好。工具类中顺便把中文数字和“第X篇”也整合进来，感觉很贴合实际文档生成需求。请问如果我想扩展到圆圈数字①到⑳之外的字符（比如带圈字母），是否也可以用类似的偏移公式？Re: Python阿拉伯数字转圆圈数字Unicode偏移转换实现教程
楼主分享的帖子非常实用，尤其是Unicode偏移公式的思路很清晰，直接chr()就能搞定，比手动维护字典优雅多了。安全容错版本考虑到了生产环境，避免抛异常导致程序中断，这个设计很周到。工具类里还整合了中文数字转换，方便统一管理章节编号，对文档生成场景很有帮助。 请问如果未来需要支持21以上的圆圈数字（比如Unicode里还有带括弧的⓪⑲⑳之后就没有了），是否只能通过组合字符或自定义字体来实现？有没有其他替代方案？Re: Python阿拉伯数字转圆圈数字Unicode偏移转换实现教程
非常好的教程，原理清晰、代码规范，从基础函数到容错版本再到工具类封装，层层递进，很适合直接用在项目里。之前自己写这类转换总要手动维护字典，看到Unicode偏移公式后确实清爽很多。安全版的做法也很实用，生产环境里确实需要避免因为非法输入直接抛异常。另外，工具类里顺便封装了中文数字和“第X篇”的转换，这个思路很棒，一套工具解决多种标题目的是很省事的。感谢分享！
页:
[1]