03 样式系统 - ZeroHawkeye/wordZero GitHub Wiki

样式系统

WordZero 提供了完整的样式系统，包括18种预定义样式、自定义样式创建和样式继承机制。本章将详细介绍如何使用和管理样式。

🎨 样式概述

样式类型

WordZero 支持四种类型的样式：

段落样式 (Paragraph): 控制段落的格式，如对齐、间距、缩进等
字符样式 (Character): 控制字符的格式，如字体、大小、颜色等
表格样式 (Table): 控制表格的外观和格式
编号样式 (Numbering): 控制列表和编号的格式

样式管理器

每个文档都有一个样式管理器，用于管理文档中的所有样式：

doc := document.New()
styleManager := doc.GetStyleManager()

// 创建快速样式API（推荐）
quickAPI := style.NewQuickStyleAPI(styleManager)

📋 预定义样式

WordZero 提供18种预定义样式，满足大部分文档需求：

基础样式

import "github.com/ZeroHawkeye/wordZero/pkg/style"

// 文档标题和副标题
title := doc.AddParagraph("文档标题")
title.SetStyle(style.StyleTitle)

subtitle := doc.AddParagraph("副标题")
subtitle.SetStyle(style.StyleSubtitle)

// 正文样式
content := doc.AddParagraph("正文内容")
content.SetStyle(style.StyleNormal)

标题样式系列

// 九级标题样式
h1 := doc.AddParagraph("一级标题")
h1.SetStyle(style.StyleHeading1)

h2 := doc.AddParagraph("二级标题") 
h2.SetStyle(style.StyleHeading2)

h3 := doc.AddParagraph("三级标题")
h3.SetStyle(style.StyleHeading3)

// 继续到 StyleHeading9
h9 := doc.AddParagraph("九级标题")
h9.SetStyle(style.StyleHeading9)

特殊样式

// 引用样式
quote := doc.AddParagraph("这是一段引用文字")
quote.SetStyle(style.StyleQuote)

// 代码块样式
code := doc.AddParagraph("func main() { fmt.Println(\"Hello\") }")
code.SetStyle(style.StyleCodeBlock)

// 列表段落样式
listItem := doc.AddParagraph("• 列表项内容")
listItem.SetStyle(style.StyleListParagraph)

// 强调样式
emphasis := doc.AddParagraph("重要信息")
emphasis.SetStyle(style.StyleEmphasis)

// 强烈强调样式
strong := doc.AddParagraph("非常重要的信息")
strong.SetStyle(style.StyleStrongEmphasis)

🔍 样式查询和信息

获取样式信息

// 获取所有样式信息
allStyles := quickAPI.GetAllStylesInfo()
fmt.Printf("文档包含 %d 个样式\n", len(allStyles))

// 按类型获取样式信息
paragraphStyles := quickAPI.GetParagraphStylesInfo()
characterStyles := quickAPI.GetCharacterStylesInfo()
headingStyles := quickAPI.GetHeadingStylesInfo()

// 打印样式信息
for _, info := range paragraphStyles {
    fmt.Printf("样式ID: %s, 名称: %s, 描述: %s\n", 
        info.ID, info.Name, info.Description)
}

检查样式是否存在

// 检查样式是否存在
exists := quickAPI.StyleExists("Heading1")
if !exists {
    fmt.Println("样式不存在")
}

// 获取特定样式
styleObj, err := quickAPI.GetStyle("Heading1")
if err != nil {
    log.Printf("获取样式失败: %v", err)
}

🛠️ 自定义样式

创建自定义段落样式

// 创建新的段落样式
customStyleID := "MyCustomParagraph"
customStyleName := "我的自定义段落"

err := quickAPI.CreateParagraphStyle(customStyleID, customStyleName, &style.ParagraphStyleOptions{
    FontName:      "Arial",
    FontSize:      12,
    FontColor:     "000080", // 深蓝色
    Bold:          true,
    Alignment:     "center",
    SpaceBefore:   240, // 段前间距（缇）
    SpaceAfter:    120, // 段后间距（缇）
    LineSpacing:   360, // 行间距（缇）
})

if err != nil {
    log.Printf("创建样式失败: %v", err)
}

// 使用自定义样式
para := doc.AddParagraph("使用自定义样式的段落")
para.SetStyleByID(customStyleID)

创建自定义字符样式

// 创建字符样式
charStyleID := "MyHighlight"
charStyleName := "高亮文本"

err := quickAPI.CreateCharacterStyle(charStyleID, charStyleName, &style.CharacterStyleOptions{
    FontName:    "Courier New",
    FontSize:    10,
    FontColor:   "FF0000", // 红色
    Bold:        true,
    Italic:      true,
    Underline:   true,
    Highlight:   "yellow",
})

if err != nil {
    log.Printf("创建字符样式失败: %v", err)
}

🔗 样式继承

WordZero 支持样式继承，允许基于现有样式创建新样式：

// 基于Heading1创建自定义标题样式
customHeadingID := "MyHeading"
customHeadingName := "我的标题"

err := quickAPI.CreateStyleWithInheritance(
    customHeadingID, 
    customHeadingName,
    "Heading1", // 基于的样式ID
    &style.StyleOptions{
        FontColor: "008000", // 绿色
        FontSize:  16,
        Italic:    true,
    },
)

if err != nil {
    log.Printf("创建继承样式失败: %v", err)
}

📖 完整示例

以下是一个展示样式系统的完整示例：

package main

import (
    "fmt"
    "log"
    
    "github.com/ZeroHawkeye/wordZero/pkg/document"
    "github.com/ZeroHawkeye/wordZero/pkg/style"
)

func main() {
    // 创建文档和样式API
    doc := document.New()
    styleManager := doc.GetStyleManager()
    quickAPI := style.NewQuickStyleAPI(styleManager)
    
    fmt.Println("WordZero 样式系统演示")
    
    // 1. 使用预定义样式创建文档结构
    title := doc.AddParagraph("样式系统演示文档")
    title.SetStyle(style.StyleTitle)
    
    subtitle := doc.AddParagraph("展示WordZero的强大样式功能")
    subtitle.SetStyle(style.StyleSubtitle)
    
    // 2. 创建章节
    chapter1 := doc.AddParagraph("第一章 预定义样式")
    chapter1.SetStyle(style.StyleHeading1)
    
    section1 := doc.AddParagraph("1.1 基础样式")
    section1.SetStyle(style.StyleHeading2)
    
    content1 := doc.AddParagraph("WordZero提供了丰富的预定义样式，包括标题、正文、引用等。")
    content1.SetStyle(style.StyleNormal)
    
    // 3. 添加引用
    quote := doc.AddParagraph("样式是文档格式化的基础，合理使用样式可以提高文档的专业性和可读性。")
    quote.SetStyle(style.StyleQuote)
    
    // 4. 添加代码示例
    codeTitle := doc.AddParagraph("1.2 代码示例")
    codeTitle.SetStyle(style.StyleHeading2)
    
    code := doc.AddParagraph(`doc := document.New()
para := doc.AddParagraph("Hello, WordZero!")
para.SetStyle(style.StyleNormal)`)
    code.SetStyle(style.StyleCodeBlock)
    
    // 5. 创建自定义样式
    chapter2 := doc.AddParagraph("第二章 自定义样式")
    chapter2.SetStyle(style.StyleHeading1)
    
    // 创建自定义段落样式
    err := quickAPI.CreateParagraphStyle("CustomInfo", "信息提示", &style.ParagraphStyleOptions{
        FontName:    "Microsoft YaHei",
        FontSize:    11,
        FontColor:   "0066CC",
        Bold:        true,
        Alignment:   "left",
        SpaceBefore: 120,
        SpaceAfter:  120,
    })
    
    if err != nil {
        log.Printf("创建自定义样式失败: %v", err)
    } else {
        // 使用自定义样式
        info := doc.AddParagraph("这是使用自定义样式的信息提示段落。")
        info.SetStyleByID("CustomInfo")
    }
    
    // 6. 样式统计信息
    chapter3 := doc.AddParagraph("第三章 样式统计")
    chapter3.SetStyle(style.StyleHeading1)
    
    allStyles := quickAPI.GetAllStylesInfo()
    statsText := fmt.Sprintf("本文档共使用了 %d 个样式，其中包括预定义样式和自定义样式。", len(allStyles))
    stats := doc.AddParagraph(statsText)
    stats.SetStyle(style.StyleNormal)
    
    // 7. 保存文档
    err = doc.Save("style_demo.docx")
    if err != nil {
        log.Fatalf("保存文档失败: %v", err)
    }
    
    fmt.Println("✅ 样式演示文档创建完成！")
}

🎯 完整样式列表

样式常量	样式名称	类型	用途
`StyleTitle`	Title	段落	文档主标题
`StyleSubtitle`	Subtitle	段落	文档副标题
`StyleHeading1-9`	Heading 1-9	段落	九级标题
`StyleNormal`	Normal	段落	正文段落
`StyleQuote`	Quote	段落	引用文字
`StyleCodeBlock`	Code Block	段落	代码块
`StyleListParagraph`	List Paragraph	段落	列表项
`StyleEmphasis`	Emphasis	字符	强调文本
`StyleStrongEmphasis`	Strong Emphasis	字符	强烈强调

💡 样式最佳实践

1. 使用预定义样式

// ✅ 推荐：使用预定义样式
para.SetStyle(style.StyleHeading1)

// ❌ 不推荐：手动设置格式
para.AddFormattedText("标题", &document.TextFormat{
    Bold: true,
    FontSize: 16,
})

2. 样式命名规范

// ✅ 好的样式名称
quickAPI.CreateParagraphStyle("CompanyHeading", "公司标题", options)
quickAPI.CreateCharacterStyle("TechnicalTerm", "技术术语", options)

// ❌ 不好的样式名称
quickAPI.CreateParagraphStyle("Style1", "样式1", options)

3. 样式继承利用

// ✅ 利用继承减少重复定义
quickAPI.CreateStyleWithInheritance("CustomHeading", "自定义标题", "Heading1", options)

⚠️ 注意事项

样式ID唯一性: 自定义样式的ID必须在文档中唯一
样式应用顺序: 先创建样式，再应用到段落
样式存在性: 使用样式前检查样式是否存在
错误处理: 样式操作可能失败，需要适当的错误处理

下一步

掌握样式系统后，您可以继续学习：

文本格式化 - 更精细的文本格式控制
表格操作 - 表格样式的应用
页面设置 - 页面级别的样式设置

样式系统是创建专业文档的基础，合理使用样式能大大提高文档的质量和一致性！