wc-word-report-tool 0.4.15

Chinese Word report formatter: tables, headers/footers, TOC, page numbering, cover, headings.

wc_word_report_tool

基于 python-docx 的中文 Word 报告格式化工具，内置：

1. 数字转中文大写：number_to_chinese_upper() 把数字转成人民币金额大写。
2. Word 格式化：WordFormatter 提供从封面、正文、表格、页眉页脚到目录、页码的完整覆盖，默认值贴近中国公文标准。

版本：v0.4.15 作者：willcha 许可证：MIT Python：>=3.9

安装

pip install wc_word_report_tool

数字转大写

from wc_word_report_tool import number_to_chinese_upper

print(number_to_chinese_upper(123456.78))
# 壹拾贰万叁仟肆佰伍拾陆元柒角捌分

命令行也可以直接用：

wc-rmb-upper 100200.03

设计理念（v0.4.3）

v0.4.3 对 API 做了收敛，目标：

1. 覆盖完整：补齐表格、页眉页脚、文档默认样式等 v0.1.x 缺失能力。
2. 命名一致：所有新方法使用 snake_case（heading / body / set_header），告别拼音 + 大小写混杂。
3. 默认合理：默认值贴近公文标准（仿宋_GB2312、三号 14pt、1.5 倍行距）。
4. 严格校验：未知对齐方式抛 ValueError 而非静默降级，便于调试。

格式化器在创建时绑定文档，后续方法不再重复传入 doc：

formatter = WordFormatter(doc)
formatter.cover_text("项目名称")
formatter.heading("一、项目概况")
formatter.body("正文内容")
formatter.add_toc()

快速上手

完整报告骨架

from docx import Document
from wc_word_report_tool import WordFormatter

doc = Document()
formatter = WordFormatter(doc)

# 1. 文档级设置
formatter.setup_defaults()
formatter.set_document_language()
# setup_defaults 只设置页面参数；正文格式通过 body() 单独设置

# 2. 封面
WordFormatter.insert_img(doc, "logo.png", width=5)
WordFormatter.blank_lines(doc, 2)
formatter.cover_text("测试项目", font_name="宋体", font_size=22, bold=True)
WordFormatter.blank_lines(doc, 8)
WordFormatter.right_text(doc, "委托单位：XXX公司")
WordFormatter.right_text(doc, "编制单位：YYY公司")

# 3. 正文（新节）
formatter.insert_section()
formatter.heading("1. 概述")
formatter.body("本项目位于……，建设内容包括……")
formatter.body("项目背景说明……")

# 4. 表格
WordFormatter.add_table(
    doc,
    headers=["序号", "项目", "金额（万元）"],
    rows=[
        ["1", "建筑工程", "1200.50"],
        ["2", "安装工程", "850.00"],
        ["3", "合计", "2050.50"],
    ],
    col_widths=[2, 6, 4],
    font_size=12,
)

# 5. 页眉页脚 + 页码从正文开始
WordFormatter.set_header(doc.sections[1], "测试项目 竣工决算报告", alignment="居中")
formatter.set_page_number_from_section(start_section_idx=1, start=1,
                                            prefix="第 ", suffix=" 页")

# 6. 目录
formatter.add_toc(title="目  录", levels=(1, 3))

doc.save("demo.docx")

API 总览

文档级设置

方法	用途	备注
set_default_font(doc, *, font_size, cn_font, en_font)	设置 Normal 样式默认字体
setup_defaults(*, top, bottom, left, right, gutter)	一键设置默认页边距；不设置正文格式
set_document_language(lang)	设置 DOCX 文档语言
set_page_margins(doc, *, top, bottom, left, right, gutter, horizontal_alignment)	页边距	替代 set_all_layout / set_document_layout

段落与标题

方法	用途
body(text, *, font_name, font_size, indent, bold, highlight, alignment)	正文段落（首行缩进 + 1.5 倍行距）
blank_lines(doc, count)	批量空行
heading(text, *, level, font_name, font_size, bold)	通用标题（默认一级标题格式）
cover_text(doc, text, *, font_name, font_size, bold)	封面文本（居中）
right_text(doc, text, *, font_name, font_size, indent)	右对齐段落（公司名/日期）
created_time(doc, value, *, font_name, font_size, bold)	数字日期文本，默认右对齐
chinese_date(doc, value, *, font_name, font_size, bold, alignment)	中文完整日期，默认居中
chinese_year_month(doc, value, *, font_name, font_size, bold, alignment)	中文年月，默认居中
insert_img(doc, img_path, width, *, alignment)	插入图片（width 单位 cm）

表格

方法	用途
add_table(doc, headers, rows, *, col_widths, font_size, header_bold, alignment, border_color, border_size)	一站式创建带表头表格
set_cell(cell, text, *, font_name, font_size, bold, alignment, line_spacing)	设置单元格格式（支持加粗/对齐）
set_table_borders(table, *, color, size)	为表格添加边框

WordFormatter.add_table(
    doc,
    headers=["序号", "项目", "金额"],
    rows=[["1", "建安费", "1200"], ["2", "设备费", "850"]],
    col_widths=[2, 5, 3],          # cm
    header_bold=True,
    alignment="居中",
)

页眉页脚

方法	用途
set_header(section, text, *, alignment, font_name, font_size)	设置节页眉（默认楷体小五号）
set_footer(section, text, *, alignment, font_name, font_size)	设置节页脚（默认楷体小五号）
clear_header(section) / clear_footer(section)	清空节页眉/页脚
set_header_image(section, image_path, *, width, height, alignment, floating, bottom_border, y_offset_pt)	设置页眉图片；可浮于文字上方并调整垂直位置
set_footer_image(section, image_path, *, width, height, alignment, floating, bottom_border, y_offset_pt)	设置页脚图片；可浮于文字上方并调整垂直位置

WordFormatter.set_header(doc.sections[1], "项目名称 报告名称", alignment="居中")
WordFormatter.set_footer(doc.sections[1], "编制单位名称", alignment="居右")
WordFormatter.set_header_image(doc.sections[1], "logo.png", width=3)

节与页码

方法	用途
insert_section(start_type, *, add_page_number, restart_page_number, inherit_header, inherit_footer)	插入新节并控制页眉页脚继承
set_page_number_start(section, start)	设置节页码起始值
add_page_number(paragraph, *, prefix, suffix, alignment, font_name, font_size)	向段落添加 PAGE 域
add_footer_page_number(section, *, prefix, suffix, ...)	节页脚添加页码
restart_page_numbering(section, *, start, add_footer_number, ...)	重启单节页码
insert_section_with_page_numbering(doc, *, start_page_number, ...)	插入节并重启页码（组合方法）
set_page_number_from_section(doc, start_section_idx, *, start, ...)	跨节页码：从指定节起编号，之前节无页码

# 文档有 3 个节：0=前置（封面/扉页/目录）, 1=正文起, 2=正文续
WordFormatter.set_page_number_from_section(
    doc, start_section_idx=1, start=1,
    prefix="第 ", suffix=" 页", alignment="居中",
)
# 节0 无页码，节1 从"第 1 页"开始，节2 链接前节延续编号

目录

方法	用途
add_toc(*, title, levels, title_style, toc_level_styles, ...)	插入 Word 目录域（TOC field）；标题默认使用 Normal 样式
set_toc_level_style(level, *, font_name, ...)	设置某一级 TOC 样式
set_paragraph_style(style_name, *, base_style_name, ...)	创建/更新自定义段落样式
add_custom_heading(text, *, style_name, level, ...)	使用自定义样式添加标题

formatter.add_toc(
    title="目  录",
    levels=(1, 3),
    toc_level_styles={
        1: {"font_name": "黑体", "font_size": 14, "bold": True, "space_after": 6},
        2: {"font_name": "仿宋_GB2312", "font_size": 12, "left_indent": 24},
    },
)
formatter.heading("1. 一级标题")

底层工具方法

方法	用途
set_run_font(run, *, cn_font, en_font, size, bold, color, highlight)	设置 run 字体
set_paragraph_format(paragraph, *, alignment, line_spacing, ...)	设置段落格式
resolve_alignment(alignment, *, strict)	对齐方式解析

字号参数

font_size 参数支持两种形式：

• 数字（pt）：font_size=14 表示 14pt
• 中文字号字符串：font_size="三号" = 16pt，font_size="小五" = 9pt

支持的中文字号：初号/小初/一号/小一/二号/小二/三号/小三/四号/小四/五号/小五/六号/小六/七号/八号。

对齐方式参数

alignment 参数支持多种形式：

类型	示例
中文	"居中" / "居左" / "居右" / "左对齐" / "右对齐" / "两端对齐"
英文	"center" / "left" / "right" / "justify"
单字母	"C" / "L" / "R"
数字	1 / 2 / 3
枚举	WD_PARAGRAPH_ALIGNMENT.CENTER

默认 strict=False 时未知值回退 LEFT；strict=True 时抛 ValueError。

单位约定

参数	单位
top/bottom/left/right（页边距）	cm
gutter（装订线）	cm
width（图片宽度）	cm
col_widths（列宽）	cm
font_size（字号）	pt 或中文字号
space_before/space_after	pt
first_line_indent_pt	pt
border_size（边框粗细）	1/8 pt（4 = 0.5pt 细线，8 = 1pt）

版本说明

v0.4.3 起只保留当前 API，不提供旧方法名兼容层。常用入口为 setup_defaults、cover_text、heading、body 和日期方法。

注意事项

1. 目录刷新：python-docx 可写入 TOC 域，但目录内容需在 Word/OnlyOffice 打开后刷新（F9 或右键 → 更新域）才会显示页码。
2. 页码分节：从某页开始重新编号本质上是"从某个分节开始重新编号"。建议在正文起、附录起等关键节点显式插入分节。
3. 字体可用性：默认字体 仿宋_GB2312 / 楷体 / 黑体 在 Windows 上预装；macOS / Linux 可能需要额外安装或回退到 仿宋 / STKaiti / SimHei。

测试

cd wc_word_report_tool
PYTHONPATH=src python3 -m pytest tests/ -q

打包上传

cd wc_word_report_tool
python3 -m pip install --upgrade build twine
./publish_to_pypi.sh

License

MIT