SpreadJS 页眉页脚配置指南：占位符与奇偶页详解

一、为什么页眉页脚配置总让人头疼？

作为开发者，你可能遇到过这些场景：

• 需要导出带页码的财务报表，但 &P 写在哪里才能生效？
• 想在首页显示特殊标题，却发现所有页面都一样
• 设置了字体颜色，结果整行文字都变了色

页眉页脚看似简单，但占位符的组合规则、优先级、样式作用域，稍不注意就会踩坑。本文帮你一次性理清。

二、核心概念：三层结构

SpreadJS 的页眉页脚配置遵循 位置 → 类型 → 内容 的三层结构：

位置层：left | center | right
  ↓
类型层：header | footer
  ↓
内容层：文本 + 占位符

基础示例：

sheet.printInfo().pageHeaderFooter({
    normal: {
        header: {
            center: "第 &P 页"
        }
    }
})

这段代码里，normal表示在所有页面上应用这个设置；header代表页眉（对应的页脚是footer）；center表示中间位置（还有left和right）；最关键的是&P，它代表当前页码，我们叫它占位符——打印时会自动替换成实际的页码。

三、占位符速查表

3.1 数据占位符

3.2 样式占位符

除了数据，页眉页脚的文字样式也能控制：

四、样式作用域规则

样式占位符有个特点：前面的设置会影响后面的文字。举个例子：

&26西&"宋体"安&K0000FF葡&U萄&B城&I你&S好

这段文本的效果是：

• &26让后面所有文字变成26号字
• &"宋体"从"安"字开始应用宋体
• &K0000FF从"葡"字开始变成蓝色
• 后面的样式依次类推

最终效果如下：

五、首页与奇偶页设置

5.1 三种模式

SpreadJS和Excel一样，支持三种页眉页脚模式：

1. Normal：所有页面统一设置（默认）
2. First：仅第一页特殊设置
3. Odd/Even：奇数页和偶数页分别设置

5.2 启用特殊模式

要启用首页不同和奇偶页，需要先开启开关：

// 首页不同
sheet.printInfo().differentFirstPage(true)
// 奇偶页不同
sheet.printInfo().differentOddAndEvenPages(true)

5.3 优先级规则

这三种模式有优先级：

• First 优先级最高（首页永远用首页设置）
• Odd/Even 优先级次之
• Normal 优先级最低（兜底用）

5.4 完整示例

如果想同时设置首页、奇数页、偶数页，可以这样写：

// 先开启两个开关
sheet.printInfo().differentFirstPage(true)
sheet.printInfo().differentOddAndEvenPages(true)

// 再分别设置
sheet.printInfo().pageHeaderFooter({
    first: {
        header: {
            center: "&30合同封面", // 封面页：大号字体
        }
    },
    odd: {
        header: {
            left: "工作表：&A",
            center: "第&P/&N页"
        }
    },
    even: {
        header: {
            center: "偶数页 第&P/&N页",
            right: "导出日期：&D"
        }
    },
})

六、总结

页眉页脚看着简单，但真要灵活运用起来，还是有不少细节需要注意：

1. 占位符是核心：&P、&N、&D这些占位符是动态内容的关键，记不住的话建议收藏备用。
2. 样式有作用范围：样式占位符从设置位置开始，一直影响到后面的文字，这点和CSS的继承有点像。
3. 开关要先开：想用首页或奇偶页不同，别忘了先调用differentFirstPage(true)或differentOddAndEvenPages(true)。
4. 优先级别搞反：首页 > 奇偶页 > 普通页，这个顺序决定了最终显示哪个设置。
5. 调试小技巧：设置完之后，可以用SpreadJS的打印预览功能先看看效果，避免直接导出PDF后才发现问题。

掌握这些要点后，无论是做报表导出、合同打印，还是其他需要页眉页脚的场景，你都能轻松应对了。