{"skill":{"slug":"python-docx","displayName":"python-docx","summary":"提供基于python-docx库的标准方法，支持生成带封面、标题、段落、列表、表格与图片的专业Word文档。","description":"# python-docx Skill\n\n## 概述\n\n本Skill提供使用python-docx生成专业Word文档的标准方法和最佳实践。\n\n## 适用场景\n\n- 生成安全服务方案文档\n- 生成技术架构设计文档\n- 生成任何需要专业排版的Word文档\n\n## 技术栈\n\n- **核心库**: `python-docx`\n- **辅助库**: `docx.shared`, `docx.enum`, `docx.oxml.ns`\n\n## 标准代码模板\n\n### 1. 文档初始化\n\n```python\nfrom docx import Document\nfrom docx.shared import Inches, Pt, RGBColor, Cm\nfrom docx.enum.text import WD_ALIGN_PARAGRAPH\nfrom docx.enum.table import WD_TABLE_ALIGNMENT\nfrom docx.oxml.ns import qn\n\ndef create_document():\n    \"\"\"创建标准文档\"\"\"\n    doc = Document()\n\n    # 设置默认字体（关键！）\n    style = doc.styles['Normal']\n    style.font.name = 'Microsoft YaHei'\n    style._element.rPr.rFonts.set(qn('w:eastAsia'), 'Microsoft YaHei')\n\n    return doc\n```\n\n### 2. 字体设置（必须！）\n\n```python\ndef set_font(run, font_name='Microsoft YaHei'):\n    \"\"\"设置字体\"\"\"\n    run.font.name = font_name\n    run._element.rPr.rFonts.set(qn('w:eastAsia'), font_name)\n```\n\n### 3. 标题添加\n\n```python\ndef add_heading_custom(doc, text, level=1):\n    \"\"\"\n    添加标准标题\n\n    Args:\n        doc: Document对象\n        text: 标题文本\n        level: 1=一级, 2=二级, 3=三级\n\n    Returns:\n        标题段落对象\n    \"\"\"\n    heading = doc.add_heading(level=level)\n    run = heading.add_run(text)\n    set_font(run)\n\n    if level == 1:\n        run.font.size = Pt(16)\n        run.font.color.rgb = RGBColor(0, 51, 102)\n        run.font.bold = True\n    elif level == 2:\n        run.font.size = Pt(14)\n        run.font.color.rgb = RGBColor(0, 51, 102)\n        run.font.bold = True\n    else:\n        run.font.size = Pt(12)\n        run.font.color.rgb = RGBColor(0, 0, 0)\n        run.font.bold = True\n\n    return heading\n```\n\n### 4. 段落添加\n\n```python\ndef add_para_custom(doc, text, bold=False, indent=0, color=None):\n    \"\"\"\n    添加标准段落\n\n    Args:\n        doc: Document对象\n        text: 段落文本\n        bold: 是否加粗\n        indent: 首行缩进（厘米）\n        color: RGBColor颜色对象\n\n    Returns:\n        段落对象\n    \"\"\"\n    p = doc.add_paragraph()\n    p.paragraph_format.first_line_indent = Cm(indent)\n\n    run = p.add_run(text)\n    run.font.size = Pt(11)\n    set_font(run)\n\n    if bold:\n        run.font.bold = True\n    if color:\n        run.font.color.rgb = color\n\n    return p\n```\n\n### 5. 项目符号列表\n\n```python\ndef add_bullet_custom(doc, text, level=0):\n    \"\"\"\n    添加项目符号段落\n\n    Args:\n        doc: Document对象\n        text: 列表项文本\n        level: 缩进级别（0=一级, 1=二级）\n\n    Returns:\n        段落对象\n    \"\"\"\n    p = doc.add_paragraph(style='List Bullet')\n    p.paragraph_format.left_indent = Cm(0.5 + level * 0.5)\n\n    run = p.add_run(text)\n    run.font.size = Pt(11)\n    set_font(run)\n\n    return p\n```\n\n### 6. 编号列表\n\n```python\ndef add_numbered_custom(doc, text, level=0):\n    \"\"\"\n    添加编号列表段落\n\n    Args:\n        doc: Document对象\n        text: 列表项文本\n        level: 缩进级别\n\n    Returns:\n        段落对象\n    \"\"\"\n    p = doc.add_paragraph(style='List Number')\n    p.paragraph_format.left_indent = Cm(0.5 + level * 0.5)\n\n    run = p.add_run(text)\n    run.font.size = Pt(11)\n    set_font(run)\n\n    return p\n```\n\n### 7. 表格创建\n\n```python\ndef create_table(doc, headers, data):\n    \"\"\"\n    创建标准表格\n\n    Args:\n        doc: Document对象\n        headers: 表头列表\n        data: 二维列表，每行是一个列表\n\n    Returns:\n        表格对象\n    \"\"\"\n    table = doc.add_table(rows=1+len(data), cols=len(headers))\n    table.style = 'Light Grid Accent 1'\n    table.alignment = WD_TABLE_ALIGNMENT.CENTER\n\n    # 表头\n    for i, header in enumerate(headers):\n        cell = table.rows[0].cells[i]\n        cell.text = header\n        for paragraph in cell.paragraphs:\n            for run in paragraph.runs:\n                run.font.bold = True\n                run.font.size = Pt(10)\n                set_font(run)\n\n    # 数据\n    for row_idx, row_data in enumerate(data, 1):\n        for col_idx, cell_data in enumerate(row_data):\n            cell = table.rows[row_idx].cells[col_idx]\n            cell.text = str(cell_data)\n            for paragraph in cell.paragraphs:\n                for run in paragraph.runs:\n                    run.font.size = Pt(9)\n                    set_font(run)\n\n    return table\n```\n\n### 8. 图片插入\n\n```python\ndef insert_image(doc, image_path, width=Inches(6), caption=None):\n    \"\"\"\n    插入标准图片\n\n    Args:\n        doc: Document对象\n        image_path: 图片路径\n        width: 图片宽度\n        caption: 图片标题（可选）\n\n    Returns:\n        段落对象\n    \"\"\"\n    # 插入图片\n    p = doc.add_paragraph()\n    p.alignment = WD_ALIGN_PARAGRAPH.CENTER\n    run = p.add_run()\n    run.add_picture(image_path, width=width)\n\n    # 添加标题\n    if caption:\n        p = doc.add_paragraph()\n        p.alignment = WD_ALIGN_PARAGRAPH.CENTER\n        run = p.add_run(caption)\n        run.font.size = Pt(10)\n        run.font.color.rgb = RGBColor(102, 102, 102)\n        set_font(run)\n\n    return p\n```\n\n### 9. 分页\n\n```python\ndef add_page_break(doc):\n    \"\"\"添加分页符\"\"\"\n    doc.add_page_break()\n```\n\n### 10. 封面创建\n\n```python\ndef create_cover(doc, title, subtitle=None, customer=None, date=None, version=None):\n    \"\"\"\n    创建标准封面\n\n    Args:\n        doc: Document对象\n        title: 主标题\n        subtitle: 副标题（可选）\n        customer: 客户名称（可选）\n        date: 日期（可选）\n        version: 版本号（可选）\n    \"\"\"\n    # 空行占位\n    for _ in range(6):\n        doc.add_paragraph()\n\n    # 主标题\n    p = doc.add_paragraph()\n    p.alignment = WD_ALIGN_PARAGRAPH.CENTER\n    run = p.add_run(title)\n    run.font.size = Pt(28)\n    run.font.bold = True\n    run.font.color.rgb = RGBColor(0, 51, 102)\n    set_font(run)\n\n    # 副标题\n    if subtitle:\n        p = doc.add_paragraph()\n        p.alignment = WD_ALIGN_PARAGRAPH.CENTER\n        run = p.add_run(subtitle)\n        run.font.size = Pt(16)\n        run.font.color.rgb = RGBColor(102, 102, 102)\n        set_font(run)\n\n    # 空行\n    for _ in range(4):\n        doc.add_paragraph()\n\n    # 信息\n    info = doc.add_paragraph()\n    info.alignment = WD_ALIGN_PARAGRAPH.CENTER\n\n    if customer:\n        run = info.add_run(f'客户：{customer}\\n')\n        run.font.size = Pt(14)\n        set_font(run)\n\n    if date:\n        run = info.add_run(f'日期：{date}\\n')\n        run.font.size = Pt(14)\n        set_font(run)\n\n    if version:\n        run = info.add_run(f'版本：{version}')\n        run.font.size = Pt(14)\n        set_font(run)\n```\n\n## 完整示例\n\n```python\n# 创建文档\ndoc = create_document()\n\n# 添加封面\ncreate_cover(doc, \n    title='安全服务方案',\n    subtitle='Security Service Proposal',\n    customer='某某公司',\n    date='2026-03-23',\n    version='V1.0'\n)\n\n# 分页\ndoc.add_page_break()\n\n# 添加一级标题\nadd_heading_custom(doc, '一、 服务概述', level=1)\n\n# 添加二级标题\nadd_heading_custom(doc, '1.1 服务背景', level=2)\n\n# 添加正文\nadd_para_custom(doc, '这是正文内容，首行缩进两字符。', indent=0.5)\n\n# 添加项目符号\nadd_bullet_custom(doc, '项目符号内容')\n\n# 添加编号列表\nadd_numbered_custom(doc, '编号列表内容')\n\n# 添加表格\nheaders = ['列1', '列2', '列3']\ndata = [['A', 'B', 'C'], ['D', 'E', 'F']]\ncreate_table(doc, headers, data)\n\n# 保存\ndoc.save('output.docx')\n```\n\n## 常见问题\n\n**Q: 中文显示为方框？**  \nA: 确保每个run都调用set_font()设置字体\n\n**Q: 表格样式不统一？**  \nA: 设置table.style = 'Light Grid Accent 1'\n\n**Q: 图片无法显示？**  \nA: 检查图片路径是否正确，使用绝对路径\n\n**Q: 文档格式错乱？**  \nA: 确保所有文本都设置了字体和大小\n\n## 参考\n\n- python-docx官方文档: https://python-docx.readthedocs.io/\n","topics":["文档"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":615,"installsAllTime":23,"installsCurrent":1,"stars":1,"versions":1},"createdAt":1777805437683,"updatedAt":1778492833926},"latestVersion":{"version":"1.0.0","createdAt":1777805437683,"changelog":"python-docx Skill 1.0.0 initial release:\n\n- Provides standard code templates and best practices for generating professional Word documents with python-docx.\n- Includes functions for document initialization, font settings, headings, paragraphs, bullet/numbered lists, tables, image insertion, pagination, and cover page creation.\n- Offers a complete example of generating a document with structured content.\n- Adds troubleshooting tips for common issues in using python-docx.\n- Lists core and auxiliary library dependencies, and links to official documentation.","license":"MIT-0"},"metadata":null,"owner":{"handle":"fooying","userId":"s172d0nd81xtkz14rc6g1wdmj183x0mv","displayName":"Fooying","image":"https://avatars.githubusercontent.com/u/1964043?v=4"},"moderation":null}