Go Excelize 怎么复用单元格样式而不重复创建

我在做 Excel 报表导出时遇到过一个很隐蔽的问题：数据行并不多，工作簿里的样式定义却随着循环不断增长。回头看代码，问题通常不是 SetCellStyle 调得太多，而是每次循环都重新调用 NewStyle。Excelize 的正确分工是“样式创建一次，样式 ID 多次绑定”：先在当前工作簿中拿到一个样式 ID，再把它复用到多个单元格或区域。

官方地址：https://github.com/xuri/excelize

API 文档：https://pkg.go.dev/github.com/xuri/excelize/v2

最小可复用方案是：为相同语义的格式准备一个缓存键，第一次使用时调用一次 NewStyle，保存返回的 style ID；之后只从缓存取 ID，再交给 SetCellStyle、SetRowStyle 或 SetColStyle。style ID 只属于创建它的那个工作簿，不能拿到另一个工作簿继续用。

我第一次遇到的问题：循环里创建了太多“相同”样式

最初的写法很直观：遍历数据行，遇到一行就拼出一个 excelize.Style，调用 NewStyle，再给这一行设置样式。单看结果，表格颜色和字体都正确；但这段代码把“定义格式”和“使用格式”绑在了一起。只要循环次数上升，创建动作就会跟着上升。

我现在会先问两个问题：这组格式是不是由表头、正文、金额列等固定语义决定的？不同单元格之间真正变化的是格式，还是只有值和坐标变化？如果变化的只是坐标，就不该重复创建样式；如果确实有颜色、字体或数字格式差异，才应该拆成另一个缓存键。

先区分创建样式和绑定样式

NewStyle 接收一个 *excelize.Style，并在当前 File 中返回 style ID。这个 ID 不是全局编号，也不是可以脱离工作簿保存的通用格式对象。SetCellStyle 接收工作表名、左上角单元格、右下角单元格和 style ID，作用是把已经存在的样式应用到区域。

这两个动作可以拆成下面的关系：Style 定义决定创建内容，工作簿决定 style ID 的归属，缓存保存复用入口，区域绑定函数负责使用。把它们拆开后，循环里只剩下写值和绑定 ID。

package main

import (
	"fmt"

	"github.com/xuri/excelize/v2"
)

func main() {
	f := excelize.NewFile()
	defer func() {
		// 关闭工作簿并把错误留给调用方处理，避免资源悄悄丢失。
		if err := f.Close(); err != nil {
			fmt.Println("close workbook:", err)
		}
	}()

	// 样式定义只描述格式，不包含单元格坐标和业务值。
	styleID, err := f.NewStyle(&excelize.Style{
		Font: &excelize.Font{Bold: true, Color: "1F4E78"},
		Fill: excelize.Fill{Type: "pattern", Color: []string{"D9EAF7"}, Pattern: 1},
	})
	if err != nil {
		// 创建失败时不能拿无效 ID 继续写表格。
		fmt.Println("create style:", err)
		return
	}

	// 同一个 ID 可以绑定到多个单元格，而不必再次 NewStyle。
	if err := f.SetCellStyle("Sheet1", "A1", "C1", styleID); err != nil {
		fmt.Println("bind style:", err)
		return
	}
}

这里真正值得复用的是 styleID，不是把 excelize.Style 指针塞进每个业务对象。写入的值、单元格坐标和样式 ID 是三个独立维度；只要格式不变，前两个维度变化也不影响样式复用。

我的稳定做法：为样式语义建立缓存

在只有表头和正文两种格式的报表里，可以直接用两个变量保存 ID；一旦导出模块增加金额、日期、警告等格式，我更倾向于把样式创建集中到一个工厂中。缓存键要表达业务语义，例如 header、body、amount，而不是把行号拼进键里。行号属于位置，不属于样式。

type styleCache struct {
	ids map[string]int
}

func newStyleCache() *styleCache {
	// 每个工作簿创建自己的缓存，避免把别的工作簿的 ID 带进来。
	return &styleCache{ids: make(map[string]int)}
}

func (c *styleCache) getOrCreate(f *excelize.File, key string, style *excelize.Style) (int, error) {
	if id, ok := c.ids[key]; ok {
		// 命中缓存时只复用现有 ID，不重复创建工作簿样式。
		return id, nil
	}

	id, err := f.NewStyle(style)
	if err != nil {
		// 创建失败不写入缓存，下一次调用仍可修复或重试。
		return 0, err
	}
	c.ids[key] = id
	return id, nil
}

这个缓存有一个很重要的边界：它必须和 *excelize.File 一起拥有生命周期。官方 API 文档明确说明，同一个 style ID 不能跨不同工作簿使用，所以不能做成进程级全局缓存，再把 ID 分发给多个导出任务。

把同一个 style ID 应用到单元格或区域

我会按覆盖范围选绑定函数。需要精确控制局部区域时用 SetCellStyle；一整行使用相同格式时可考虑 SetRowStyle；整列规则稳定时再考虑 SetColStyle。三者共享的是 style ID，区别只是绑定范围。

func applyReportStyles(f *excelize.File) error {
	cache := newStyleCache()
	bodyID, err := cache.getOrCreate(f, "body", &excelize.Style{
		Alignment: &excelize.Alignment{Vertical: "center"},
	})
	if err != nil {
		return fmt.Errorf("create body style: %w", err)
	}

	amountID, err := cache.getOrCreate(f, "amount", &excelize.Style{
		NumFmt: 4, // 保留数字格式，让金额列按统一规则显示。
	})
	if err != nil {
		return fmt.Errorf("create amount style: %w", err)
	}

	// 局部区域用 SetCellStyle；它会覆盖目标区域已有的单元格样式。
	if err := f.SetCellStyle("Sheet1", "A2", "F100", bodyID); err != nil {
		return fmt.Errorf("apply body range: %w", err)
	}

	// 金额列只绑定自己的格式，不在每一行重新创建 style。
	if err := f.SetColStyle("Sheet1", "F", amountID); err != nil {
		return fmt.Errorf("apply amount column: %w", err)
	}
	return nil
}

这段示例里，bodyID 和 amountID 都是同一个工作簿产生的 ID。需要留意覆盖关系：如果后面再对 F 列绑定金额样式，它可能覆盖前面给 F2:F100 设定的正文样式。样式复用解决的是“不要重复创建”，不等于可以忽略区域之间的覆盖顺序。

对比三种策略：什么时候该缓存，什么时候该拆分

我实际会把候选方案分成三种，而不是把“样式越少越好”当成唯一目标。

对我来说，第二种通常是默认选择：先按业务语义缓存；如果发现某个语义还需要红色告警、负数格式或特殊边框，再把这些差异明确写进键。不要为了复用而把所有单元格强行套成一个样式。

缓存键怎么设计才不会越用越乱

缓存键要回答“这个样式为什么和另一个样式不同”。如果差异来自数字格式，键里就应该有 amount 或 date；如果差异来自状态颜色，应该有 warning 或 success。不要使用 row-12、cell-F8 这种只描述位置的键，因为位置变化时它们会制造大量没有意义的样式分支。

也不要只用一个短字符串却在内部偷偷改变 Style 定义。相同键必须对应相同格式，否则缓存命中后，调用方会以为拿到的是旧规则，实际却无法判断哪一次定义生效。更稳妥的方式是让创建入口负责定义键和 Style，业务循环只负责取 ID。

几个容易踩到的边界

• style ID 不跨工作簿。每次调用 excelize.NewFile() 后，都应创建新的缓存并重新生成 ID。
• 绑定会覆盖。SetCellStyle 不会把新旧样式字段自动合并；如果单元格原本有边框，后续绑定一个没有边框的样式，不能假定边框会被保留。
• 创建错误和绑定错误要分开返回。NewStyle 成功只代表拿到了 ID，工作表名、区域范围和覆盖关系仍要在绑定阶段处理。
• 格式相同才复用。不要为了减少 ID 而忽略表头、金额和警告状态的真实显示差异。
• 不要把未执行示例写成性能结论。样式数量、文件体积和导出耗时应由项目自己的日志或测试测量，本文只给出代码组织方法。

我的选择结论：先按语义缓存，再按范围绑定

如果只是一次性生成一个很小的工作簿，直接创建少量样式并不会马上造成问题；但只要有循环导出、多个工作表或可配置的报表模板，我会把 NewStyle 收拢到工作簿级缓存，把 SetCellStyle 等函数留在写入阶段。这样更容易看出哪些格式真的不同，也不必在每个循环分支里维护重复的样式定义。

这个方案适合希望控制导出结构、又不想把 Excelize 封装成庞大模板系统的 Go 项目。它不替你决定单元格应该显示什么，也不会自动解决区域覆盖顺序；它只把“样式创建”和“样式使用”分开，让复用边界变得清楚。

常见问题

是不是调用一次 SetCellStyle 就只能给一个单元格用？

不是。SetCellStyle 接收左上角和右下角单元格，可以绑定一个区域；同一个 style ID 也可以被多次调用，绑定到不同区域。

把 Style 结构体复制一份，能不能代替缓存 style ID？

不能代替。复制 Style 只能得到另一份描述，真正绑定时仍要通过当前工作簿创建并取得 style ID。复用的核心是不要为同一格式重复调用 NewStyle。

可以把 style ID 放进全局变量吗？

除非全局变量只服务于一个不会重建的工作簿，否则不建议。style ID 属于生成它的工作簿，导出任务之间应隔离缓存和文件对象。

整列和局部单元格都要格式时，应该先调用哪个？

没有脱离表格布局的固定答案。先画清楚哪些范围会重叠，再把更具体的局部规则放在能明确覆盖它的位置，并检查绑定函数的覆盖语义；不要把调用顺序当成隐含的样式合并机制。