wordZero

WordZero - Golang Word操作库

项目介绍

WordZero 是一个使用 Golang 实现的 Word 文档操作库，提供基础的文档创建、修改等操作功能。该库遵循最新的 Office Open XML (OOXML) 规范，专注于现代 Word 文档格式（.docx）的支持。

核心特性

• 🚀 完整的文档操作: 创建、读取、修改 Word 文档
• 🎨 丰富的样式系统: 18种预定义样式，支持自定义样式和样式继承
• 📝 文本格式化: 字体、大小、颜色、粗体、斜体等完整支持
• 📐 段落格式: 对齐、间距、缩进等段落属性设置
• 🏷️ 标题导航: 完整支持Heading1-9样式，可被Word导航窗格识别
• ⚡ 高性能: 零依赖的纯Go实现，内存占用低
• 🔧 易于使用: 简洁的API设计，链式调用支持

安装

go get github.com/ZeroHawkeye/wordZero

版本说明

推荐使用带版本号的安装方式：

# 安装最新版本
go get github.com/ZeroHawkeye/wordZero@latest

# 安装指定版本
go get github.com/ZeroHawkeye/wordZero@v0.4.0

项目结构

wordZero/
├── pkg/                      # 公共包
│   ├── document/            # 文档核心操作
│   │   ├── document.go      # 主要文档操作API
│   │   ├── table.go         # 表格操作功能
│   │   ├── page.go          # 页面设置功能 ✨ 新增
│   │   ├── header_footer.go # 页眉页脚功能 ✨ 新增
│   │   ├── toc.go           # 目录生成功能 ✨ 新增
│   │   ├── footnotes.go     # 脚注尾注功能 ✨ 新增
│   │   ├── numbering.go     # 列表编号功能 ✨ 新增
│   │   ├── sdt.go           # 结构化文档标签 ✨ 新增
│   │   ├── field.go         # 域字段功能 ✨ 新增
│   │   ├── properties.go    # 文档属性管理 ✨ 新增
│   │   ├── errors.go        # 错误定义和处理
│   │   ├── logger.go        # 日志系统
│   │   ├── doc.go           # 包文档
│   │   ├── document_test.go # 文档操作单元测试
│   │   ├── table_test.go    # 表格功能单元测试
│   │   └── page_test.go     # 页面设置单元测试 ✨ 新增
│   └── style/               # 样式管理系统
│       ├── style.go         # 样式核心定义
│       ├── api.go           # 快速API接口
│       ├── predefined.go    # 预定义样式常量
│       ├── api_test.go      # API测试
│       ├── style_test.go    # 样式系统测试
│       └── README.md        # 样式系统详细文档
├── examples/                 # 使用示例
│   ├── basic/               # 基础功能示例
│   │   └── basic_example.go
│   ├── formatting/          # 格式化示例
│   │   └── text_formatting_example.go
│   ├── style_demo/          # 样式系统演示
│   │   └── style_demo.go
│   ├── table/               # 表格功能示例
│   │   └── table_example.go
│   ├── table_layout/        # 表格布局和尺寸示例
│   │   └── main.go
│   ├── table_style/         # 表格样式和外观示例
│   │   └── main.go
│   ├── cell_advanced/       # 单元格高级功能示例
│   │   └── main.go
│   ├── page_settings/       # 页面设置示例 ✨ 新增
│   │   └── main.go
│   ├── advanced_features/   # 高级功能综合示例 ✨ 新增
│   │   └── main.go
│   ├── basic_usage.go       # 基础使用示例
│   └── output/             # 示例输出文件目录
├── test/                    # 集成测试文件
│   ├── document_test.go     # 文档操作集成测试
│   ├── text_formatting_test.go # 文本格式化集成测试
│   └── table_style_test.go  # 表格样式功能集成测试
├── .gitignore              # Git忽略文件配置
├── go.mod                  # Go模块定义
├── LICENSE                 # MIT许可证
└── README.md              # 项目说明文档

功能特性

✅ 已实现功能

文档基础操作

• 创建新的 Word 文档
• 读取和解析现有文档 ✨ 重大改进
  • 动态元素解析: 支持段落、表格、节属性等多种元素类型
  • 结构化解析: 保持文档元素的原始顺序和层次结构
  • 完整XML解析: 使用流式解析，支持复杂的嵌套结构
  • 错误恢复: 智能跳过未知元素，确保解析稳定性
  • 性能优化: 内存友好的增量解析，适用于大型文档
• 文档保存和压缩
• ZIP文件处理和OOXML结构解析

文本和段落操作

• 文本内容的添加和修改
• 段落创建和管理
• 文本格式化（字体、大小、颜色、粗体、斜体）
• 段落对齐（左对齐、居中、右对齐、两端对齐）
• 行间距和段间距设置
• 首行缩进和左右缩进
• 混合格式文本（一个段落中多种格式）

样式管理系统

• 预定义样式库: 18种Word内置样式
  • 标题样式（Heading1-Heading9）- 支持导航窗格识别
  • 正文样式（Normal）
  • 文档标题和副标题（Title、Subtitle）
  • 引用样式（Quote）
  • 列表段落样式（ListParagraph）
  • 代码相关样式（CodeBlock、CodeChar）
  • 字符样式（Emphasis、Strong）
• 样式继承机制: 完整的样式继承和属性合并
• 自定义样式: 快速创建和应用自定义样式
• 样式查询API: 按类型查询、样式验证、批量操作
• 快速应用API: 便捷的样式操作接口

页面设置功能 ✨ 新增

• 页面大小设置（A4、Letter、Legal、A3、A5等标准尺寸）
• 自定义页面尺寸（毫米单位，支持任意尺寸）
• 页面方向设置（纵向/横向）
• 页面边距设置（上下左右边距，毫米单位）
• 页眉页脚距离设置
• 装订线宽度设置
• 完整页面设置API和配置结构
• 页面设置验证和错误处理
• 页面设置的保存和加载支持

表格功能

• 表格创建和初始化
  • 创建指定行列数的表格
  • 设置表格初始数据
  • 表格插入到文档指定位置
  • 新增：默认表格样式（参考Word标准格式）
    • 默认单线边框（single边框样式）
    • 标准边框粗细（4 * 1/8磅）
    • 自动调整布局（autofit）
    • 标准单元格边距（108 dxa）
    • 支持样式覆盖和自定义
• 表格结构管理
  • 插入行（指定位置、末尾、开头）
  • 删除行（单行、多行、指定范围）
• 表格复制和剪切
• 表格删除和清空

• 单元格内容管理
  • 单元格文本设置和获取
  • 单元格富文本格式支持
  • 单元格内容清空和重置
• 单元格合并功能
  • 横向合并（合并列）
  • 纵向合并（合并行）
  • 区域合并（多行多列）
  • 取消合并操作
  • 合并状态查询
• 单元格格式设置
  • 单元格文字格式（字体、大小、颜色）
  • 单元格对齐方式（水平、垂直对齐）
  • 单元格文字方向和旋转
  • 单元格内边距设置

• 表格尺寸控制
  • 表格总宽度设置（固定宽度、相对宽度、自动宽度）
  • 列宽设置（固定宽度、相对宽度、自动调整）
  • 行高设置（固定高度、最小高度、自动调整）
  • 单元格尺寸精确控制
• 表格对齐和定位
  • 表格页面对齐（左对齐、居中、右对齐）
  • 表格文字环绕设置
  • 表格相对定位
• 表格分页控制
  • 表格跨页处理
  • 标题行重复显示
  • 表格分页符控制
  • 避免分页的行设置

• 数据导入导出
  • 二维数组数据绑定
  • 表格数据提取为数组
  • 批量数据填充

• 表格查找和定位
  • 按索引获取表格
  • 表格位置信息获取
• 单元格访问接口
  • 按行列索引访问
• 单元格遍历迭代器 ✨ 新实现
  • 单元格迭代器（CellIterator）
  • 按顺序遍历所有单元格
  • 迭代器重置和位置跟踪
  • 迭代进度计算
  • 单元格信息结构（CellInfo）
  • ForEach批量处理方法
  • 按行遍历（ForEachInRow）
  • 按列遍历（ForEachInColumn）
  • 获取单元格范围（GetCellRange）
  • 条件查找单元格（FindCells）
  • 按文本查找单元格（FindCellsByText）
  • 精确匹配和模糊匹配支持

• 表格整体样式
  • 预定义表格样式模板
  • 自定义表格样式创建
  • 表格主题色彩应用
  • 表格样式继承和覆盖
• 表格边框设置
  • 外边框样式（线型、颜色、粗细）
  • 内边框样式（网格线设置）
  • 单元格边框独立设置
  • 边框部分应用（顶部、底部、左右）
  • 无边框表格支持
• 表格背景和填充
  • 表格背景色设置
  • 单元格背景色设置
  • 奇偶行颜色交替
  • 渐变背景支持（基础渐变）
  • 图案填充支持

🚧 规划中功能

表格功能完善

• 表格排序功能（Word内置排序）
  • 单列排序（升序、降序）
  • 多列排序
  • 保持标题行不参与排序
• 表格标题和说明
  • 表格标题设置（表格上方、下方）
  • 表格标题编号自动生成
  • 表格描述和备注
• 嵌套表格支持
  • 单元格内嵌套表格
  • 嵌套表格独立样式
• 表格模板功能
  • 常用表格模板库
  • 自定义模板保存
  • 模板快速应用
• 表格访问增强
  • 按标题查找表格
  • 按范围批量访问

图片功能

• 图片插入
• 图片大小调整
• 图片位置设置
• 多种图片格式支持（JPG、PNG、GIF）

高级功能 ✨ 已实现

• 页眉页脚 ✨ 新实现
  • 默认页眉页脚设置
  • 首页不同页眉页脚
  • 奇偶页不同页眉页脚
  • 页眉页脚中的页码显示
  • 页眉页脚的格式化支持
  • 页眉页脚的文本内容设置
  • 页眉页脚引用和关系管理
• 文档属性设置 ✨ 新实现
  • 标题、作者、主题设置
  • 关键字、描述、类别设置
  • 创建时间、修改时间管理
  • 文档统计信息（字数、段落数等）
  • 自动统计信息更新
• 列表和编号 ✨ 新实现
  • 无序列表（多种项目符号：圆点、空心圆、方块、短横线、箭头）
  • 有序列表（数字、字母、罗马数字）
  • 多级列表支持（最多9级）
  • 自定义列表样式
  • 列表编号重新开始
  • 多级列表批量创建
  • 列表缩进级别控制
• 目录生成 ✨ 新实现
  • 自动生成目录
  • 基于标题样式的目录条目
  • 目录级别控制（1-9级）
  • 页码显示和超链接支持
  • 目录更新功能
  • 带书签的标题支持
  • 目录样式自定义
  • 标题统计和列表功能
• 脚注和尾注 ✨ 新实现
  • 脚注添加和管理
  • 尾注添加和管理
  • 多种编号格式支持（数字、字母、罗马数字、符号）
  • 脚注/尾注的删除和更新
  • 自定义脚注配置
  • 脚注位置设置（页面底部、文本下方、节末尾、文档末尾）
  • 脚注重启规则（连续、每节重启、每页重启）
  • 脚注数量统计
• 结构化文档标签（SDT） ✨ 新实现
  • 目录SDT结构创建
  • SDT属性和内容管理
  • SDT占位符和文档部件支持
  • 目录条目SDT嵌套
• 域字段功能 ✨ 新实现
  • 超链接域字段
  • 页码引用域字段
  • 域字符和指令文本
  • 域字段的开始、分隔、结束标记
• 页码设置（已集成到页眉页脚功能中）

使用示例

查看 examples/ 目录下的示例代码：

• examples/basic/ - 基础功能演示
• examples/style_demo/ - 样式系统演示
• examples/table/ - 表格功能演示
• examples/table_layout/ - 表格布局和尺寸演示
• examples/table_style/ - 表格样式和外观演示
• examples/cell_advanced/ - 单元格高级功能演示
• examples/cell_iterator/ - 单元格迭代器功能演示 ✨ 新增
• examples/formatting/ - 格式化演示
• examples/page_settings/ - 页面设置演示 ✨ 新增
• examples/advanced_features/ - 高级功能综合演示 ✨ 新增
  • 页眉页脚功能演示
  • 目录生成和管理演示
  • 脚注尾注功能演示
  • 列表和编号演示
  • 结构化文档标签演示

运行示例：

# 运行基础功能演示
go run ./examples/basic/

# 运行样式演示
go run ./examples/style_demo/

# 运行表格演示
go run ./examples/table/

# 运行表格布局和尺寸演示
go run ./examples/table_layout/

# 运行表格样式演示
go run ./examples/table_style/

# 运行单元格高级功能演示
go run ./examples/cell_advanced/

# 运行单元格迭代器功能演示
go run ./examples/cell_iterator/

# 运行格式化演示  
go run ./examples/formatting/

# 运行页面设置演示
go run ./examples/page_settings/

# 运行高级功能综合演示
go run ./examples/advanced_features/

贡献指南

欢迎提交 Issue 和 Pull Request！在提交代码前请确保：

1. 代码符合 Go 代码规范
2. 添加必要的测试用例
3. 更新相关文档
4. 确保所有测试通过

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。