08 高级功能 - ZeroHawkeye/wordZero GitHub Wiki
高级功能
WordZero 提供了多种高级功能，包括目录生成、脚注尾注、列表编号、结构化文档标签和域字段等。本章将详细介绍这些高级功能的使用方法。
📑 目录生成
自动目录生成
WordZero 可以根据文档中的标题自动生成目录：
package main
import (
"github.com/ZeroHawkeye/wordZero/pkg/document"
"github.com/ZeroHawkeye/wordZero/pkg/style"
)
func main() {
doc := document.New()
// 添加标题，用于生成目录
title := doc.AddParagraph("WordZero 使用手册")
title.SetStyle(style.StyleTitle)
// 添加多级标题
chapter1 := doc.AddParagraph("第一章 基础功能")
chapter1.SetStyle(style.StyleHeading1)
section1 := doc.AddParagraph("1.1 文档创建")
section1.SetStyle(style.StyleHeading2)
subsection1 := doc.AddParagraph("1.1.1 新建文档")
subsection1.SetStyle(style.StyleHeading3)
// 添加内容
content := doc.AddParagraph("这里是具体的内容描述...")
content.SetStyle(style.StyleNormal)
// 生成目录（在文档开头插入）
config := &document.TOCConfig{
Title: "目录",
MaxLevel: 3,
ShowPageNum: true,
RightAlign: true,
UseHyperlink: true,
DotLeader: true,
}
err := doc.GenerateTOC(config)
if err != nil {
log.Printf("生成目录失败: %v", err)
}
doc.Save("toc_demo.docx")
}
目录配置选项
// 默认目录配置
config := document.DefaultTOCConfig()
// 自定义目录配置
customConfig := &document.TOCConfig{
Title: "Contents", // 目录标题
MaxLevel: 2, // 只显示1-2级标题
ShowPageNum: true, // 显示页码
RightAlign: true, // 页码右对齐
UseHyperlink: true, // 使用超链接
DotLeader: true, // 使用点状引导线
}
err := doc.GenerateTOC(customConfig)
📝 脚注和尾注
添加脚注
// 在段落中添加脚注
para := doc.AddParagraph("")
para.AddFormattedText("这是需要注释的文本", nil)
// 添加脚注
footnoteID, err := para.AddFootnote("这是脚注内容，会显示在页面底部。")
if err != nil {
log.Printf("添加脚注失败: %v", err)
}
para.AddFormattedText("继续的文本内容。", nil)
添加尾注
// 添加尾注（显示在文档末尾）
para := doc.AddParagraph("")
para.AddFormattedText("这个概念需要详细说明", nil)
endnoteID, err := para.AddEndnote("这是尾注内容，会显示在文档或章节的末尾。")
if err != nil {
log.Printf("添加尾注失败: %v", err)
}
脚注和尾注样式
// 设置脚注样式
footnoteConfig := &document.FootnoteConfig{
NumberFormat: document.FootnoteNumDecimal, // 数字格式：1, 2, 3...
StartNumber: 1, // 起始编号
RestartEach: document.FootnoteRestartPage, // 每页重新编号
}
doc.SetFootnoteConfig(footnoteConfig)
// 设置尾注样式
endnoteConfig := &document.EndnoteConfig{
NumberFormat: document.EndnoteNumRoman, // 罗马数字：i, ii, iii...
StartNumber: 1, // 起始编号
}
doc.SetEndnoteConfig(endnoteConfig)
🔢 列表和编号
有序列表
// 创建编号列表
numbering := doc.CreateNumbering(&document.NumberingConfig{
Format: document.NumberingDecimal, // 1, 2, 3...
StartAt: 1, // 起始编号
Alignment: document.AlignLeft, // 对齐方式
})
// 添加列表项
items := []string{
"第一项内容",
"第二项内容",
"第三项内容",
}
for _, item := range items {
para := doc.AddParagraph(item)
para.SetNumbering(numbering, 0) // 0表示第一级
}
无序列表
// 创建项目符号列表
bulletNumbering := doc.CreateNumbering(&document.NumberingConfig{
Format: document.NumberingBullet, // 项目符号
Symbol: "•", // 自定义符号
Alignment: document.AlignLeft,
})
bulletItems := []string{
"项目符号列表项1",
"项目符号列表项2",
"项目符号列表项3",
}
for _, item := range bulletItems {
para := doc.AddParagraph(item)
para.SetNumbering(bulletNumbering, 0)
}
多级列表
// 创建多级列表
multiLevelItems := []struct {
text string
level int
}{
{"一级列表项1", 0},
{"二级列表项1.1", 1},
{"二级列表项1.2", 1},
{"三级列表项1.2.1", 2},
{"一级列表项2", 0},
{"二级列表项2.1", 1},
}
for _, item := range multiLevelItems {
para := doc.AddParagraph(item.text)
para.SetNumbering(numbering, item.level)
}
🏷️ 结构化文档标签 (SDT)
创建文本输入控件
// 创建文本输入SDT
textSDT := &document.SDTConfig{
Type: document.SDTText,
Placeholder: "请在此输入您的姓名",
Title: "姓名",
Tag: "name_field",
}
err := doc.AddSDT(textSDT)
if err != nil {
log.Printf("添加SDT失败: %v", err)
}
创建下拉列表控件
// 创建下拉列表SDT
dropdownSDT := &document.SDTConfig{
Type: document.SDTDropDown,
Title: "选择部门",
Tag: "department_field",
Options: []document.SDTOption{
{Display: "技术部", Value: "tech"},
{Display: "销售部", Value: "sales"},
{Display: "人事部", Value: "hr"},
{Display: "财务部", Value: "finance"},
},
}
err := doc.AddSDT(dropdownSDT)
创建日期选择控件
// 创建日期选择SDT
dateSDT := &document.SDTConfig{
Type: document.SDTDate,
Title: "入职日期",
Tag: "hire_date",
DateFormat: "yyyy-MM-dd",
}
err := doc.AddSDT(dateSDT)
🔗 域字段
插入日期字段
// 插入当前日期
para := doc.AddParagraph("文档创建日期：")
para.AddDateField("yyyy年MM月dd日")
// 插入当前时间
timePara := doc.AddParagraph("创建时间：")
timePara.AddTimeField("HH:mm:ss")
插入文档属性字段
// 插入文档标题
titlePara := doc.AddParagraph("文档标题：")
titlePara.AddDocPropertyField("Title")
// 插入作者
authorPara := doc.AddParagraph("作者：")
authorPara.AddDocPropertyField("Author")
// 插入文档主题
subjectPara := doc.AddParagraph("主题：")
subjectPara.AddDocPropertyField("Subject")
自定义域字段
// 插入自定义域
para := doc.AddParagraph("页码：")
para.AddCustomField("PAGE") // 插入页码域
para2 := doc.AddParagraph("总页数：")
para2.AddCustomField("NUMPAGES") // 插入总页数域
📋 完整高级功能示例
package main
import (
"fmt"
"log"
"github.com/ZeroHawkeye/wordZero/pkg/document"
"github.com/ZeroHawkeye/wordZero/pkg/style"
)
func main() {
// 创建文档
doc := document.New()
fmt.Println("创建高级功能演示文档...")
// 1. 设置文档属性
doc.SetDocumentProperty("Title", "WordZero高级功能演示")
doc.SetDocumentProperty("Author", "WordZero项目组")
doc.SetDocumentProperty("Subject", "展示WordZero的高级功能")
// 2. 添加封面页
title := doc.AddParagraph("WordZero 高级功能演示")
title.SetStyle(style.StyleTitle)
// 插入文档属性
authorPara := doc.AddParagraph("")
authorPara.AddFormattedText("作者：", nil)
authorPara.AddDocPropertyField("Author")
authorPara.SetAlignment(document.AlignCenter)
datePara := doc.AddParagraph("")
datePara.AddFormattedText("创建日期：", nil)
datePara.AddDateField("yyyy年MM月dd日")
datePara.SetAlignment(document.AlignCenter)
// 3. 添加分页
// 注意：AddPageBreak() 方法在最新版本中已移除
// 目前需要通过段落属性设置分页
// doc.AddPageBreak()
// 4. 生成目录
tocConfig := &document.TOCConfig{
Title: "目录",
MaxLevel: 3,
ShowPageNum: true,
UseHyperlink: true,
}
err := doc.GenerateTOC(tocConfig)
if err != nil {
log.Printf("生成目录失败: %v", err)
}
// 再添加一页内容
// 注意：AddPageBreak() 方法在最新版本中已移除
// doc.AddPageBreak()
// 5. 添加正文内容
chapter1 := doc.AddParagraph("第一章 基础功能")
chapter1.SetStyle(style.StyleHeading1)
section1 := doc.AddParagraph("1.1 文档操作")
section1.SetStyle(style.StyleHeading2)
// 添加脚注示例
footnotePara := doc.AddParagraph("")
footnotePara.AddFormattedText("WordZero是一个强大的文档处理库", nil)
footnoteID, _ := footnotePara.AddFootnote("WordZero项目开源地址：https://github.com/ZeroHawkeye/wordZero")
footnotePara.AddFormattedText("，提供了完整的Word文档操作功能。", nil)
subsection1 := doc.AddParagraph("1.1.1 创建和保存")
subsection1.SetStyle(style.StyleHeading3)
content1 := doc.AddParagraph("文档创建是WordZero的基础功能，支持多种保存格式。")
content1.SetStyle(style.StyleNormal)
// 6. 添加列表示例
section2 := doc.AddParagraph("1.2 支持的功能")
section2.SetStyle(style.StyleHeading2)
// 创建编号列表
numbering := doc.CreateNumbering(&document.NumberingConfig{
Format: document.NumberingDecimal,
StartAt: 1,
})
features := []string{
"文档创建和保存",
"文本格式化",
"表格操作",
"图片插入",
"样式管理",
}
for _, feature := range features {
para := doc.AddParagraph(feature)
para.SetNumbering(numbering, 0)
}
// 7. 添加第二章
chapter2 := doc.AddParagraph("第二章 高级功能")
chapter2.SetStyle(style.StyleHeading1)
section3 := doc.AddParagraph("2.1 目录和索引")
section3.SetStyle(style.StyleHeading2)
tocDesc := doc.AddParagraph("目录功能可以自动扫描文档中的标题，生成带有页码的目录列表。")
tocDesc.SetStyle(style.StyleNormal)
// 添加尾注示例
endnotePara := doc.AddParagraph("")
endnotePara.AddFormattedText("目录生成基于XML标准", nil)
endnoteID, _ := endnotePara.AddEndnote("Office Open XML标准由Microsoft开发，现已成为国际标准ISO/IEC 29500。")
endnotePara.AddFormattedText("，确保与Microsoft Word完全兼容。", nil)
// 8. 添加SDT示例
section4 := doc.AddParagraph("2.2 交互式控件")
section4.SetStyle(style.StyleHeading2)
sdtDesc := doc.AddParagraph("结构化文档标签（SDT）允许在文档中插入交互式控件：")
sdtDesc.SetStyle(style.StyleNormal)
// 文本输入控件
doc.AddParagraph("姓名：")
textSDT := &document.SDTConfig{
Type: document.SDTText,
Placeholder: "请输入您的姓名",
Title: "姓名输入框",
Tag: "name_field",
}
doc.AddSDT(textSDT)
// 下拉列表控件
doc.AddParagraph("部门：")
dropdownSDT := &document.SDTConfig{
Type: document.SDTDropDown,
Title: "部门选择",
Tag: "dept_field",
Options: []document.SDTOption{
{Display: "技术部", Value: "tech"},
{Display: "销售部", Value: "sales"},
{Display: "人事部", Value: "hr"},
},
}
doc.AddSDT(dropdownSDT)
// 9. 添加页脚信息
err = doc.AddFooterWithPageNumber(document.HeaderFooterTypeDefault, "WordZero - ", true)
if err != nil {
log.Printf("添加页脚失败: %v", err)
}
// 10. 保存文档
err = doc.Save("advanced_features_demo.docx")
if err != nil {
log.Fatalf("保存文档失败: %v", err)
}
fmt.Println("✅ 高级功能演示文档创建完成！")
fmt.Println("文档包含：")
fmt.Println("- 自动生成的目录")
fmt.Println("- 脚注和尾注")
fmt.Println("- 编号列表")
fmt.Println("- 结构化文档标签")
fmt.Println("- 域字段")
fmt.Println("- 文档属性")
}
🎯 高级功能配置选项
目录配置
type TOCConfig struct {
Title string // 目录标题
MaxLevel int // 最大显示级别
ShowPageNum bool // 显示页码
RightAlign bool // 页码右对齐
UseHyperlink bool // 使用超链接
DotLeader bool // 点状引导线
}
编号配置
type NumberingConfig struct {
Format NumberingFormat // 编号格式
StartAt int // 起始编号
Alignment AlignType // 对齐方式
Symbol string // 自定义符号（用于项目符号）
}
SDT配置
type SDTConfig struct {
Type SDTType // 控件类型
Title string // 标题
Tag string // 标签
Placeholder string // 占位符
Options []SDTOption // 选项（下拉列表用）
DateFormat string // 日期格式
}
💡 高级功能最佳实践
1. 目录生成
// ✅ 推荐：在添加所有标题后生成目录
// 先添加完整的文档结构
doc.AddParagraph("第一章...").SetStyle(style.StyleHeading1)
// ... 添加更多内容
// 最后生成目录
doc.GenerateTOC(config)
2. 脚注使用
// ✅ 适当使用脚注，不要过多
para.AddFormattedText("重要概念", nil)
para.AddFootnote("简短的解释或引用")
3. 列表格式
// ✅ 使用一致的列表样式
numbering := doc.CreateNumbering(&document.NumberingConfig{
Format: document.NumberingDecimal,
StartAt: 1,
})
// 为所有相关列表项使用同一个编号配置
⚠️ 注意事项
- 目录更新: 在Word中打开文档后需要更新目录字段
- 脚注编号: 脚注编号会自动管理，无需手动设置
- SDT兼容性: 确保目标Word版本支持SDT功能
- 域字段: 某些域字段需要在Word中按F9更新
下一步
学习了高级功能后，您可以继续：
高级功能让您的文档更加专业和功能丰富，合理使用这些功能能够创建出色的文档！