Skill: fooying/python-docx (version 1.0.0)

# python-docx Skill ## 概述 本Skill提供使用python-docx生成专业Word文档的标准方法和最佳实践。 ## 适用场景 - 生成安全服务方案文档 - 生成技术架构设计文档 - 生成任何需要专业排版的Word文档 ## 技术栈 - **核心库**: `python-docx` - **辅助库**: `docx.shared`, `docx.enum`, `docx.oxml.ns` ## 标准代码模板 ### 1. 文档初始化 ```python from docx import Document from docx.shared import Inches, Pt, RGBColor, Cm from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.enum.table import WD_TABLE_ALIGNMENT from docx.oxml.ns import qn def create_document(): """创建标准文档""" doc = Document() # 设置默认字体（关键！） style = doc.styles['Normal'] style.font.name = 'Microsoft YaHei' style._element.rPr.rFonts.set(qn('w:eastAsia'), 'Microsoft YaHei') return doc ``` ### 2. 字体设置（必须！） ```python def set_font(run, font_name='Microsoft YaHei'): """设置字体""" run.font.name = font_name run._element.rPr.rFonts.set(qn('w:eastAsia'), font_name) ``` ### 3. 标题添加 ```python def add_heading_custom(doc, text, level=1): """ 添加标准标题 Args: doc: Document对象 text: 标题文本 level: 1=一级, 2=二级, 3=三级 Returns: 标题段落对象 """ heading = doc.add_heading(level=level) run = heading.add_run(text) set_font(run) if level == 1: run.font.size = Pt(16) run.font.color.rgb = RGBColor(0, 51, 102) run.font.bold = True elif level == 2: run.font.size = Pt(14) run.font.color.rgb = RGBColor(0, 51, 102) run.font.bold = True else: run.font.size = Pt(12) run.font.color.rgb = RGBColor(0, 0, 0) run.font.bold = True return heading ``` ### 4. 段落添加 ```python def add_para_custom(doc, text, bold=False, indent=0, color=None): """ 添加标准段落 Args: doc: Document对象 text: 段落文本 bold: 是否加粗 indent: 首行缩进（厘米） color: RGBColor颜色对象 Returns: 段落对象 """ p = doc.add_paragraph() p.paragraph_format.first_line_indent = Cm(indent) run = p.add_run(text) run.font.size = Pt(11) set_font(run) if bold: run.font.bold = True if color: run.font.color.rgb = color return p ``` ### 5. 项目符号列表 ```python def add_bullet_custom(doc, text, level=0): """ 添加项目符号段落 Args: doc: Document对象 text: 列表项文本 level: 缩进级别（0=一级, 1=二级） Returns: 段落对象 """ p = doc.add_paragraph(style='List Bullet') p.paragraph_format.left_indent = Cm(0.5 + level * 0.5) run = p.add_run(text) run.font.size = Pt(11) set_font(run) return p ``` ### 6. 编号列表 ```python def add_numbered_custom(doc, text, level=0): """ 添加编号列表段落 Args: doc: Document对象 text: 列表项文本 level: 缩进级别 Returns: 段落对象 """ p = doc.add_paragraph(style='List Number') p.paragraph_format.left_indent = Cm(0.5 + level * 0.5) run = p.add_run(text) run.font.size = Pt(11) set_font(run) return p ``` ### 7. 表格创建 ```python def create_table(doc, headers, data): """ 创建标准表格 Args: doc: Document对象 headers: 表头列表 data: 二维列表，每行是一个列表 Returns: 表格对象 """ table = doc.add_table(rows=1+len(data), cols=len(headers)) table.style = 'Light Grid Accent 1' table.alignment = WD_TABLE_ALIGNMENT.CENTER # 表头 for i, header in enumerate(headers): cell = table.rows[0].cells[i] cell.text = header for paragraph in cell.paragraphs: for run in paragraph.runs: run.font.bold = True run.font.size = Pt(10) set_font(run) # 数据 for row_idx, row_data in enumerate(data, 1): for col_idx, cell_data in enumerate(row_data): cell = table.rows[row_idx].cells[col_idx] cell.text = str(cell_data) for paragraph in cell.paragraphs: for run in paragraph.runs: run.font.size = Pt(9) set_font(run) return table ``` ### 8. 图片插入 ```python def insert_image(doc, image_path, width=Inches(6), caption=None): """ 插入标准图片 Args: doc: Document对象 image_path: 图片路径 width: 图片宽度 caption: 图片标题（可选） Returns: 段落对象 """ # 插入图片 p = doc.add_paragraph() p.alignment = WD_ALIGN_PARAGRAPH.CENTER run = p.add_run() run.add_picture(image_path, width=width) # 添加标题 if caption: p = doc.add_paragraph() p.alignment = WD_ALIGN_PARAGRAPH.CENTER run = p.add_run(caption) run.font.size = Pt(10) run.font.color.rgb = RGBColor(102, 102, 102) set_font(run) return p ``` ### 9. 分页 ```python def add_page_break(doc): """添加分页符""" doc.add_page_break() ``` ### 10. 封面创建 ```python def create_cover(doc, title, subtitle=None, customer=None, date=None, version=None): """ 创建标准封面 Args: doc: Document对象 title: 主标题 subtitle: 副标题（可选） customer: 客户名称（可选） date: 日期（可选） version: 版本号（可选） """ # 空行占位 for _ in range(6): doc.add_paragraph() # 主标题 p = doc.add_paragraph() p.alignment = WD_ALIGN_PARAGRAPH.CENTER run = p.add_run(title) run.font.size = Pt(28) run.font.bold = True run.font.color.rgb = RGBColor(0, 51, 102) set_font(run) # 副标题 if subtitle: p = doc.add_paragraph() p.alignment = WD_ALIGN_PARAGRAPH.CENTER run = p.add_run(subtitle) run.font.size = Pt(16) run.font.color.rgb = RGBColor(102, 102, 102) set_font(run) # 空行 for _ in range(4): doc.add_paragraph() # 信息 info = doc.add_paragraph() info.alignment = WD_ALIGN_PARAGRAPH.CENTER if customer: run = info.add_run(f'客户：{customer}\n') run.font.size = Pt(14) set_font(run) if date: run = info.add_run(f'日期：{date}\n') run.font.size = Pt(14) set_font(run) if version: run = info.add_run(f'版本：{version}') run.font.size = Pt(14) set_font(run) ``` ## 完整示例 ```python # 创建文档 doc = create_document() # 添加封面 create_cover(doc, title='安全服务方案', subtitle='Security Service Proposal', customer='某某公司', date='2026-03-23', version='V1.0' ) # 分页 doc.add_page_break() # 添加一级标题 add_heading_custom(doc, '一、 服务概述', level=1) # 添加二级标题 add_heading_custom(doc, '1.1 服务背景', level=2) # 添加正文 add_para_custom(doc, '这是正文内容，首行缩进两字符。', indent=0.5) # 添加项目符号 add_bullet_custom(doc, '项目符号内容') # 添加编号列表 add_numbered_custom(doc, '编号列表内容') # 添加表格 headers = ['列1', '列2', '列3'] data = [['A', 'B', 'C'], ['D', 'E', 'F']] create_table(doc, headers, data) # 保存 doc.save('output.docx') ``` ## 常见问题 **Q: 中文显示为方框？** A: 确保每个run都调用set_font()设置字体 **Q: 表格样式不统一？** A: 设置table.style = 'Light Grid Accent 1' **Q: 图片无法显示？** A: 检查图片路径是否正确，使用绝对路径 **Q: 文档格式错乱？** A: 确保所有文本都设置了字体和大小 ## 参考 - python-docx官方文档: https://python-docx.readthedocs.io/


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)