一个强大而优雅的 Python 库，用于 Word 文档的自动化处理。提供链式调用语法，让文档操作变得简单直观。
- 🔗 链式调用：流畅的 API 设计，支持链式操作
- 🎯 精确选择：支持正则表达式、函数条件等多种筛选方式
- 📊 表格处理：强大的表格操作功能，包括自动调整、边框控制等
- 📝 段落控制：文本替换、对齐、字体等段落级别操作
- 📄 页面设置：页面方向、节操作等文档级别控制
- 🧩 模块化设计：清晰的模块结构，按需导入
# 使用 uv (推荐)
uv add git+https://github.com/PyBalance/docx-flow.git
# 使用 pip
pip install git+https://github.com/PyBalance/docx-flow.gitfrom docx_flow import DocxEditor
from docx_flow.conditions import RegexCondition
from docx_flow.actions import ReplaceTextAction, AlignParagraphAction
# 打开文档
editor = DocxEditor('document.docx')
# 链式操作：找到包含特定文本的段落并替换，然后居中对齐
editor.select_paragraphs() \
.where(RegexCondition(r'重要提示')) \
.apply(ReplaceTextAction('重要提示', '⭐ 重要提示')) \
.apply(AlignParagraphAction('center'))
# 保存文档
editor.save('output.docx')from docx_flow import (
DocxEditor, RegexCondition, TableColumnCondition, TableTextCondition,
AlignParagraphAction, SetTableWidthAction, ReplaceTextAction,
SetTabStopAction, RemoveTableBordersAction, SetTableColumnWidthAction,
AutoFitTableAction, SetFontSizeAction, ClearAndSetTabStopAction
)
from docx.shared import Inches
# 打开文档
editor = DocxEditor('complex_document.docx')
# 1. 第一节中的表格去掉边框，设置宽度
editor.select_tables()\
.in_section(0)\
.apply(RemoveTableBordersAction())\
.apply(SetTableWidthAction(Inches(6.0)))
# 2. 第二节中包含"重要"的段落右对齐
editor.select_paragraphs()\
.in_section(1)\
.where(RegexCondition(r'重要'))\
.apply(AlignParagraphAction('right'))
# 3. 第二节所有段落添加制表位
editor.select_paragraphs()\
.in_section(1)\
.apply(SetTabStopAction(2.0))
# 4. 从第三节开始替换文本
editor.select_paragraphs()\
.from_section(2)\
.apply(ReplaceTextAction('旧文本', '新文本'))
# 5. 4列表格设置列宽
col_widths = [Inches(1.5), Inches(2.0), Inches(1.5), Inches(2.0)]
editor.select_tables()\
.where(TableColumnCondition(4))\
.apply(SetTableColumnWidthAction(col_widths))
# 保存结果
editor.save('processed_document.docx')选择器用于从文档中选择特定的元素：
select_paragraphs()- 选择所有段落select_tables()- 选择所有表格select_sections()- 选择所有节
条件用于过滤选中的元素：
RegexCondition(pattern)- 基于正则表达式匹配段落文本TableColumnCondition(count)- 基于列数匹配表格TableTextCondition(text)- 基于文本内容匹配表格FunctionCondition(func)- 基于自定义函数匹配元素
操作用于修改选中的元素：
AlignParagraphAction(alignment)- 设置段落对齐方式SetTabStopAction(position_in_cm)- 设置制表位（厘米）ClearAndSetTabStopAction(position_in_cm)- 清除并重设制表位（厘米）ReplaceTextAction(old, new)- 替换文本SetFontSizeAction(size)- 设置字体大小SetTableWidthAction(width)- 设置表格宽度RemoveTableBordersAction()- 移除表格边框SetTableColumnWidthAction(widths)- 设置表格列宽AutoFitTableAction(mode)- 自动调整表格大小
in_section(index)- 只处理指定节中的元素from_section(index)- 处理从指定节开始的所有元素
主要的编辑器类，用于加载和保存文档。
class DocxEditor:
def __init__(self, docx_path: str)
def select_paragraphs(self) -> FluentSelector
def select_tables(self) -> FluentSelector
def select_sections(self) -> FluentSelector
def save(self, output_path: str) -> None流畅接口的核心类，支持链式调用。
class FluentSelector:
def where(self, condition: Condition) -> 'FluentSelector'
def in_section(self, section_index: int) -> 'FluentSelector'
def from_section(self, section_index: int) -> 'FluentSelector'
def apply(self, action: Action) -> 'FluentSelector'
def get(self) -> List[Any]
def get_by_index(self, index: int) -> 'FluentSelector'
@property
def count(self) -> intclass RegexCondition(Condition):
def __init__(self, pattern: str)匹配段落文本的正则表达式条件。
class TableColumnCondition(Condition):
def __init__(self, column_count: int)匹配指定列数的表格条件。
class TableTextCondition(Condition):
def __init__(self, text: str)匹配包含指定文本的表格条件。
class FunctionCondition(Condition):
def __init__(self, func: Callable[[Any], bool])基于自定义函数的条件。
class AlignParagraphAction(Action):
def __init__(self, alignment: str)设置段落对齐方式。支持的对齐方式：
'left'- 左对齐'center'- 居中对齐'right'- 右对齐'justify'- 两端对齐
class SetTabStopAction(Action):
def __init__(self, position_in_cm: float)设置段落的制表位位置（以厘米为单位）。
class SetFontSizeAction(Action):
def __init__(self, size: Union[int, str])设置字体大小。size可以是绝对值（如18）或相对值（如'+4'）。
class ClearAndSetTabStopAction(Action):
def __init__(self, position_in_cm: float)清除现有制表位并设置新的制表位位置（以厘米为单位）。
class AutoFitTableAction(Action):
def __init__(self, autofit_mode: str = 'contents', first_col_ratio: float = None)自动调整表格大小。支持'contents'（内容自适应）、'window'（窗口自适应）、'fixed'（固定宽度）模式。
class ReplaceTextAction(Action):
def __init__(self, old_text: str, new_text: str)替换段落或表格单元格中的文本。
class SetTableWidthAction(Action):
def __init__(self, width: Any)设置表格宽度。width 可以是 Inches(6.0), Cm(15.0) 等。
class RemoveTableBordersAction(Action):移除表格的所有边框。
class SetTableColumnWidthAction(Action):
def __init__(self, column_widths: List[Any])设置表格各列的宽度。
# 统一所有重要段落的格式
editor.select_paragraphs()\
.where(RegexCondition(r'重要|关键|核心'))\
.apply(AlignParagraphAction('center'))
# 统一所有表格的宽度
editor.select_tables()\
.apply(SetTableWidthAction(Inches(6.0)))# 替换所有出现的公司名称
editor.select_paragraphs()\
.apply(ReplaceTextAction('旧公司名', '新公司名'))
# 也替换表格中的内容
editor.select_tables()\
.apply(ReplaceTextAction('旧公司名', '新公司名'))# 只处理第一节的内容
editor.select_paragraphs()\
.in_section(0)\
.apply(SetTabStopAction(2.0))
# 从第三节开始的所有内容
editor.select_paragraphs()\
.from_section(2)\
.apply(ReplaceTextAction('草稿', '正式版'))# 只处理4列的表格
editor.select_tables()\
.where(TableColumnCondition(4))\
.apply(SetTableColumnWidthAction([
Inches(1.0), Inches(2.0), Inches(1.5), Inches(1.5)
]))
# 移除所有表格的边框
editor.select_tables()\
.apply(RemoveTableBordersAction())-
文档备份：在处理重要文档前，请务必备份原文件。
-
测试环境：建议先在测试文档上验证操作效果。
-
性能考虑：对于大型文档，某些操作可能需要较长时间。
-
兼容性：本库基于 python-docx，支持 .docx 格式（不支持 .doc）。
-
错误处理：库会优雅地处理错误情况，不匹配的操作会被跳过。
本项目使用 TDD（测试驱动开发）方式开发，包含完整的测试套件：
# 运行所有测试
python -m pytest
# 运行特定测试
python -m pytest tests/test_conditions.py
# 查看测试覆盖率
python -m pytest --cov=docx_flowMIT License
欢迎提交 Issue 和 Pull Request！
- 添加了完整的 LLM 函数文档 (llm.txt)
- 优化了代码示例和使用说明
- 改进了文档结构
- 初始版本发布
- 支持基本的段落和表格操作
- 实现流畅的链式调用接口
- 完整的功能演示