Go-Excelize API源码阅读（十九）——SetHeaderFooter

Go-Excelize API源码阅读（十九）——SetHeaderFooter

开源摘星计划（WeOpen Star） 是由腾源会 2022 年推出的全新项目，旨在为开源人提供成长激励，为开源项目提供成长支持，助力开发者更好地了解开源，更快地跨越鸿沟，参与到开源的具体贡献与实践中。

不管你是开源萌新，还是希望更深度参与开源贡献的老兵，跟随“开源摘星计划”开启你的开源之旅，从一篇学习笔记、到一段代码的提交，不断挖掘自己的潜能，最终成长为开源社区的“闪亮之星”。

我们将同你一起，探索更多的可能性！

项目地址： WeOpen-Star：https://github.com/weopenprojects/WeOpen-Star

一、Go-Excelize简介

Excelize 是 Go 语言编写的用于操作 Office Excel 文档基础库，基于 ECMA-376，ISO/IEC 29500 国际标准。可以使用它来读取、写入由 Microsoft Excel™ 2007 及以上版本创建的电子表格文档。支持 XLAM / XLSM / XLSX / XLTM / XLTX 等多种文档格式，高度兼容带有样式、图片(表)、透视表、切片器等复杂组件的文档，并提供流式读写 API，用于处理包含大规模数据的工作簿。可应用于各类报表平台、云计算、边缘计算等系统。使用本类库要求使用的 Go 语言为 1.15 或更高版本。

二、 SetHeaderFooter

func (f *File) SetHeaderFooter(sheet string, settings *FormatHeaderFooter) error
1

该API的作用是根据给定的工作表名称和控制字符设置工作表的页眉和页脚。

页眉和页脚包含如下字段：

接下来是OddHeader, OddFooter, EvenHeader, EvenFooter, FirstFooter, FirstHeader这六个字符串字段的格式代码。

//     Formatting Code        | Description
//    ------------------------+-------------------------------------------------------------------------
//     &&                     | The character "&"
//                            |
//     &font-size             | Size of the text font, where font-size is a decimal font size in points
//                            |
//     &"font name,font type" | A text font-name string, font name, and a text font-type string,
//                            | font type
//                            |
//     &"-,Regular"           | Regular text format. Toggles bold and italic modes to off
//                            |
//     &A                     | Current worksheet's tab name
//                            |
//     &B or &"-,Bold"        | Bold text format, from off to on, or vice versa. The default mode is off
//                            |
//     &D                     | Current date
//                            |
//     &C                     | Center section
//                            |
//     &E                     | Double-underline text format
//                            |
//     &F                     | Current workbook's file name
//                            |
//     &G                     | Drawing object as background
//                            |
//     &H                     | Shadow text format
//                            |
//     &I or &"-,Italic"      | Italic text format
//                            |
//     &K                     | Text font color
//                            |
//                            | An RGB Color is specified as RRGGBB
//                            |
//                            | A Theme Color is specified as TTSNNN where TT is the theme color Id,
//                            | S is either "+" or "-" of the tint/shade value, and NNN is the
//                            | tint/shade value
//                            |
//     &L                     | Left section
//                            |
//     &N                     | Total number of pages
//                            |
//     &O                     | Outline text format
//                            |
//     &P[[+|-]n]             | Without the optional suffix, the current page number in decimal
//                            |
//     &R                     | Right section
//                            |
//     &S                     | Strikethrough text format
//                            |
//     &T                     | Current time
//                            |
//     &U                     | Single-underline text format. If double-underline mode is on, the next
//                            | occurrence in a section specifier toggles double-underline mode to off;
//                            | otherwise, it toggles single-underline mode, from off to on, or vice
//                            | versa. The default mode is off
//                            |
//     &X                     | Superscript text format
//                            |
//     &Y                     | Subscript text format
//                            |
//     &Z                     | Current workbook's file path
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

下面是笔者翻译的版本：

//     Formatting Code        | Description
//    ------------------------+-------------------------------------------------------------------------
//     &&                     | 字符"&"
//                            |
//     &font-size             | 代表以磅为单位的十进制文本字体大小
//                            |
//     &"font name,font type" | 文本字体名称字符串，字体名称，以及文本字体类型字符串，
//                            | 字体类型
//                            |
//     &"-,Regular"           | 常规文本格式。粗体和斜体模式默认为关闭状态
//                            |
//     &A                     | 当前工作表名称
//                            |
//     &B or &"-,Bold"        | 粗体文本格式，从关闭转变到开启，或者反过来。默认模式是关闭
//                            |
//     &D                     | 当前的日期
//                            |
//     &C                     | 中间部分
//                            |
//     &E                     | 使用双下划线
//                            |
//     &F                     | 当前的工作簿文件名称
//                            |
//     &G                     | 将该对象设置为背景
//                            |
//     &H                     | 文字阴影
//                            |
//     &I or &"-,Italic"      | 文字斜体
//                            |
//     &K                     | 字体颜色
//                            |
//                            | 例如格式为 RRGGBB 的 RGB 颜色
//                            |
//                            | 一个主题色被指定为TTSNNN，其中TT是主题色ID，S是色调/阴影值的 "+"或"-"，NNN是色调/阴影值。
//                            |
//     &L                     | 左侧部分
//                            |
//     &N                     | 页面总数
//                            |
//     &O                     | 大纲文本格式
//                            |
//     &P[[+|-]n]             | 如果没有可选的后缀，当前的页码，默认为十进制。
//                            |
//     &R                     | 右侧部分
//                            |
//     &S                     | 文本删除线
//                            |
//     &T                     | 当前时间
//     &U                     | 单下划线文本格式. 如果双下划线模式启用了，
//                            | 在一个章节中的下划线会关闭双下划线模式。
//                            | 否则，它将切换单下线模式，从关闭到开启，或者反过来。
//                            | 默认模式是关闭。
//                            |
//     &X                     | 上标格式
//                            |
//     &Y                     |	下标格式
//                            |
//     &Z                     | 当前工作簿文件路径
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

注释给了一个例子：

// For example:
//
//    err := f.SetHeaderFooter("Sheet1", &excelize.FormatHeaderFooter{
//        DifferentFirst:   true,
//        DifferentOddEven: true,
//        OddHeader:        "&R&P",
//        OddFooter:        "&C&F",
//        EvenHeader:       "&L&P",
//        EvenFooter:       "&L&D&R&T",
//        FirstHeader:      `&CCenter &"-,Bold"Bold&"-,Regular"HeaderU+000A&D`,
//    })
1
2
3
4
5
6
7
8
9
10
11

根据上面的格式代码详解，我们可以清楚的知道：
DifferentFirst: true代表的是第一页有页眉和页脚。
DifferentOddEven: true代表奇数和偶数页页眉和页脚是不同的。
OddHeader: "&R&P"代表奇数页的页眉右侧部分为当前十进制的页码。
OddFooter: "&C&F"代表奇数页的页脚中心部分为当前工作簿的文件名。
EvenHeader: "&L&P"代表偶数页的页眉左侧部分为当前十进制的页码。
EvenFooter: "&L&D&R&T"代表偶数页页脚的左侧部分为当前日期，右侧部分为当前时间。

FirstHeader:   `&CCenter &"-,Bold"Bold&"-,Regular"HeaderU+000A&D`  
1

上面这段代表第一页页眉中心部分第一行为"Center Bold Header"，第二行为日期。
第一页没有设置页脚。

说明了该API的所有参数之后，我们来看看源码：

func (f *File) SetHeaderFooter(sheet string, settings *FormatHeaderFooter) error {
	ws, err := f.workSheetReader(sheet)
	if err != nil {
		return err
	}
	if settings == nil {
		ws.HeaderFooter = nil
		return err
	}

	v := reflect.ValueOf(*settings)

	for i := 4; i < v.NumField()-1; i++ {
		if len(utf16.Encode([]rune(v.Field(i).String()))) > MaxFieldLength {
			return newFieldLengthError(v.Type().Field(i).Name)
		}
	}
	ws.HeaderFooter = &xlsxHeaderFooter{
		AlignWithMargins: settings.AlignWithMargins,
		DifferentFirst:   settings.DifferentFirst,
		DifferentOddEven: settings.DifferentOddEven,
		ScaleWithDoc:     settings.ScaleWithDoc,
		OddHeader:        settings.OddHeader,
		OddFooter:        settings.OddFooter,
		EvenHeader:       settings.EvenHeader,
		EvenFooter:       settings.EvenFooter,
		FirstFooter:      settings.FirstFooter,
		FirstHeader:      settings.FirstHeader,
	}
	return err
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

先是读取工作表，然后判断参数settings是不是为空，如果为空，就给HeaderFooter赋值为nil 然后结束。

如果不是，那么就使用反射来检查OddHeader, OddFooter, EvenHeader, EvenFooter,FirstFooter, FirstHeader这六个字段。

然后检查没有问题后就将settings参数内的值赋给HeaderFooter。

三、结语

这里是老岳，这是Go语言相关源码的解读第十九篇，我会不断努力，给大家带来更多类似的文章，恳请大家不吝赐教。