 全量键名映射与源码级解析)
PHPExcel 样式数组速查：applyFromArray() 全量键名映射与源码级解析
【免费下载链接】PHPExcelARCHIVED项目地址: https://gitcode.com/gh_mirrors/ph/PHPExcel
导读
本文是 PHPExcel Developer Documentation 的附录篇（对应仓库 Documentation/markdown/Overview/11-Appendices.md），完整整理 PHPExcel 中PHPExcel_Style及各样式子组件applyFromArray()方法所支持的全部数组键名。当你在生成报表时希望用一段结构化数组一次性完成字体、填充、边框、对齐、数字格式、保护等样式的批量设置，而不是逐个调用setXxx()方法，本文给出的键名映射表就是你的标准参考。读完后你将掌握：每个键对应的 setter/getter 属性、嵌套子数组的写法、边框高级模式（advanced mode）的边界处理逻辑，以及如何在非 supervisor 对象上直接应用样式数组。
说明：原附录开头的 Credits 小节指向外部站点（codeplex 链接原文），仅供获取贡献者名单，与核心技术无关，此处不再展开；仓库本体代码版权与许可信息见 Classes/PHPExcel/Style.php 头部注释及 license.md。
applyFromArray() 的两种工作模式
在给出键名映射表之前，先理解applyFromArray()的调用路径，这决定了数组键如何被消费。入口实现在 Classes/PHPExcel/Style.php，签名如下：
public function applyFromArray($pStyles = null, $pAdvanced = true)第二个参数$pAdvanced默认true，仅在 supervisor 样式对象上且传入borders键时生效（即“高级模式”，专门处理边框的分区推导），其余场景走“简单模式”（simple mode）。两种模式都会在$pStyles不是数组时抛出PHPExcel_Exception("Invalid style array passed.")（Style.php），因此任何键值必须以数组形式传入。
非 supervisor：直接透传子组件
当调用对象不是 supervisor（例如new PHPExcel_Style()创建的独立样式对象，或通过$cell->getStyle()取得的真实样式）时，方法会依次把数组分发给对应的子组件：
if (array_key_exists('fill', $pStyles)) { $this->getFill()->applyFromArray($pStyles['fill']); } if (array_key_exists('font', $pStyles)) { $this->getFont()->applyFromArray($pStyles['font']); } if (array_key_exists('borders', $pStyles)) { $this->getBorders()->applyFromArray($pStyles['borders']); } if (array_key_exists('alignment', $pStyles)) { $this->getAlignment()->applyFromArray($pStyles['alignment']); } if (array_key_exists('numberformat', $pStyles)) { $this->getNumberFormat()->applyFromArray($pStyles['numberformat']); } if (array_key_exists('protection', $pStyles)) { $this->getProtection()->applyFromArray($pStyles['protection']); } if (array_key_exists('quotePrefix', $pStyles)) { $this->quotePrefix = $pStyles['quotePrefix']; }（源码见 Classes/PHPExcel/Style.php）
可以看到，六个子组件键映射到各自的getXxx()取值，其值必须是“另一个样式数组”，再递归交给子组件的applyFromArray()；唯一的例外是quotePrefix，它直接赋值给样式对象本身的属性。
supervisor：克隆-应用-去重
当对象是 supervisor（典型场景：$objPHPExcel->getActiveSheet()->getStyle('A1:B2')返回的样式代理）时，流程变为：
- 通过
getSelectedCells()取得当前选中的单元格区域； - 按列/行/单元格三种选择类型收集旧的 XF 索引（
$oldXfIndexes，见 Style.php）； - 克隆每个受影响的样式对象并应用数组，然后通过
getHashCode()去重：若工作簿中已存在相同哈希的样式，则复用其索引；否则addCellXf()新增（Style.php）； - 最后把新 XF 索引写回对应列/行/单元格维度（Style.php）。
这正是 PHPExcel 的“共享样式”内存优化机制——相同样式只保存一份 XF 记录，配合__clone()深拷贝（见 Classes/PHPExcel/Style/Supervisor.php），大量单元格套用相同样式不会线性消耗内存。
PHPExcel_Style 顶层键名映射
下表来自附录原文，列出PHPExcel_Style::applyFromArray()的顶层键（11-Appendices.md）：
| 数组键 | 映射属性 | 值类型 |
|---|---|---|
fill | getFill() | 样式数组（见 PHPExcel_Style_Fill） |
font | getFont() | 样式数组（见 PHPExcel_Style_Font） |
borders | getBorders() | 样式数组（见 PHPExcel_Style_Borders） |
alignment | getAlignment() | 样式数组（见 PHPExcel_Style_Alignment） |
numberformat | getNumberFormat() | 样式数组（见 PHPExcel_Style_NumberFormat） |
protection | getProtection() | 样式数组（见 PHPExcel_Style_Protection） |
规则（附录原文）：若“映射属性”列指向 setter，则该键的值被直接应用；若指向 getter，则该键的值作为另一个样式数组被传递。表中除numberformat、protection外的四列均指向 getter。此外从 Style.php 可知顶层键还支持quotePrefix（布尔值，直接赋值）。
配套示例（getStyle()返回 supervisor，因此是高级模式可用的完整写法）：
$objPHPExcel->getActiveSheet()->getStyle('B2')->applyFromArray( array( 'font' => array( 'name' => 'Arial', 'bold' => true, 'italic' => false, 'underline' => PHPExcel_Style_Font::UNDERLINE_DOUBLE, 'strike' => false, 'color' => array('rgb' => '808080') ), 'borders' => array( 'bottom' => array( 'style' => PHPExcel_Style_Border::BORDER_DASHDOT, 'color' => array('rgb' => '808080') ), 'top' => array( 'style' => PHPExcel_Style_Border::BORDER_DASHDOT, 'color' => array('rgb' => '808080') ) ), 'quotePrefix' => true ) );（示例出自 Classes/PHPExcel/Style.php 的 docblock）
子组件键名映射全表
以下各表均为附录原文完整继承，同时补充了源码中可确认的默认值与取值范围。
PHPExcel_Style_Fill（填充）
| 数组键 | 映射属性 |
|---|---|
type | setFillType() |
rotation | setRotation() |
startcolor | getStartColor() |
endcolor | getEndColor() |
color | getStartColor() |
实现见 Classes/PHPExcel/Style/Fill.php：type、rotation走 setter；startcolor、endcolor、color三个键的值都是颜色数组，其中color与startcolor等价（都作用于getStartColor()）。
type常用取值：PHPExcel_Style_Fill::FILL_SOLID（实心）、FILL_NONE（无填充，默认）、FILL_GRADIENT_LINEAR、FILL_GRADIENT_PATH、FILL_PATTERN_*系列；setFillType()默认参数即FILL_NONE（Fill.php）。color/startcolor/endcolor值形如array('rgb' => 'FFCCFF')或array('argb' => 'FFCCFFCC')（见 Examples/23sharedstyles.php）。
PHPExcel_Style_Font（字体）
| 数组键 | 映射属性 |
|---|---|
name | setName() |
bold | setBold() |
italic | setItalic() |
underline | setUnderline() |
strike | setStrikethrough() |
color | getColor() |
size | setSize() |
superScript | setSuperScript() |
subScript | setSubScript() |
实现见 Classes/PHPExcel/Style/Font.php。color键的值是颜色数组，交给getColor()->applyFromArray()；其余键均为直接 setter。补充要点：
underline使用常量：PHPExcel_Style_Font::UNDERLINE_NONE、UNDERLINE_DOUBLE、UNDERLINE_SINGLE等；bold、italic、strike、superScript、subScript传布尔值；name传字体名（如'Arial'），size传数值（磅值）。
PHPExcel_Style_Borders（边框集合）
| 数组键 | 映射属性 |
|---|---|
allborders | getLeft();getRight();getTop();getBottom() |
left | getLeft() |
right | getRight() |
top | getTop() |
bottom | getBottom() |
diagonal | getDiagonal() |
vertical | getVertical() |
horizontal | getHorizontal() |
diagonaldirection | setDiagonalDirection() |
outline | setOutline() |
实现见 Classes/PHPExcel/Style/Borders.php 起。allborders是快捷键，值会同时应用给左/右/上/下四条边框；left、right、top、bottom、diagonal、vertical、horizontal的值是“边框数组”（见下节 Border）。
PHPExcel_Style_Border（单条边框）
| 数组键 | 映射属性 |
|---|---|
style | setBorderStyle() |
color | getColor() |
实现见 Classes/PHPExcel/Style/Border.php 起。style常用常量：PHPExcel_Style_Border::BORDER_THIN（细线）、BORDER_MEDIUM（中粗线）、BORDER_DASHDOT（点划线）、BORDER_DOUBLE、BORDER_NONE等。color同样是颜色数组。
PHPExcel_Style_Alignment（对齐）
| 数组键 | 映射属性 |
|---|---|
horizontal | setHorizontal() |
vertical | setVertical() |
rotation | setTextRotation() |
wrap | setWrapText() |
shrinkToFit | setShrinkToFit() |
indent | setIndent() |
实现见 Classes/PHPExcel/Style/Alignment.php 起。注意这里的rotation映射到setTextRotation()（文本旋转角度，与 Fill 的rotation含义不同）；wrap、shrinkToFit传布尔值；horizontal/vertical使用常量如PHPExcel_Style_Alignment::HORIZONTAL_CENTER、VERTICAL_CENTER。
PHPExcel_Style_NumberFormat（数字格式）
| 数组键 | 映射属性 |
|---|---|
code | setFormatCode() |
实现见 Classes/PHPExcel/Style/NumberFormat.php 起。code传入格式字符串，例如'0.00'、'yyyy-mm-dd'、'0.00%'或内置常量PHPExcel_Style_NumberFormat::FORMAT_DATE_YYYYMMDD2等。
PHPExcel_Style_Protection（保护）
| 数组键 | 映射属性 |
|---|---|
locked | setLocked() |
hidden | setHidden() |
实现见 Classes/PHPExcel/Style/Protection.php 起。两者均传布尔值；locked常用常量PHPExcel_Style_Protection::PROTECTION_PROTECTED/PROTECTION_UNPROTECTED。保护效果需结合工作表/单元格的锁定状态才能生效。
边框高级模式：allborders / outline / inside 的分区推导
这是applyFromArray()最复杂的部分，也是$pAdvanced参数存在的意义。当 supervisor 对象收到含borders键的数组时（Style.php），会先把三个“快捷键”展开：
allborders→ 同时展开为outline与inside（仅对未显式设置的组件生效）；outline→ 展开为top、right、bottom、left；inside→ 展开为vertical与horizontal。
if (isset($pStyles['borders']['allborders'])) { foreach (array('outline', 'inside') as $component) { if (!isset($pStyles['borders'][$component])) { $pStyles['borders'][$component] = $pStyles['borders']['allborders']; } } unset($pStyles['borders']['allborders']); } if (isset($pStyles['borders']['outline'])) { foreach (array('top', 'right', 'bottom', 'left') as $component) { if (!isset($pStyles['borders'][$component])) { $pStyles['borders'][$component] = $pStyles['borders']['outline']; } } unset($pStyles['borders']['outline']); } if (isset($pStyles['borders']['inside'])) { foreach (array('vertical', 'horizontal') as $component) { if (!isset($pStyles['borders'][$component])) { $pStyles['borders'][$component] = $pStyles['borders']['inside']; } } unset($pStyles['borders']['inside']); }（Classes/PHPExcel/Style.php）
随后，高级模式会把选中区域切分为最多 3×3 个“区域”（region，依据行列数min(..., 3)截断），逐个计算每个区域与选区边缘的相对位置：紧贴选区外缘的区域继承top/right/bottom/left边，内部交界的边缘则按vertical/horizontal（或已展开的inside值）填充；每个区域以简单模式（applyFromArray($regionStyles, false)，见 Style.php）递归应用。这样做的好处是：对A1:C3这类多行多列区域只需一组边框数组，就能自动生成正确的“外框 + 内分隔线”，无需手工为每条边写数组。
结合实例：共享样式的数组化应用
仓库示例 Examples/23sharedstyles.php 展示了非 supervisor 路径的典型用法——创建两个独立的PHPExcel_Style对象，用数组批量配置后复用：
$sharedStyle1 = new PHPExcel_Style(); $sharedStyle1->applyFromArray( array('fill' => array( 'type' => PHPExcel_Style_Fill::FILL_SOLID, 'color' => array('argb' => 'FFCCFFCC') ), 'borders' => array( 'bottom' => array('style' => PHPExcel_Style_Border::BORDER_THIN), 'right' => array('style' => PHPExcel_Style_Border::BORDER_MEDIUM) ) ));（Examples/23sharedstyles.php）
该示例通过setSharedStyle()把同一样式对象赋给多个单元格，配合工作簿级的 XF 去重机制实现内存节省——这正是applyFromArray()数组键设计与 supervisor 克隆流程协同工作的实际场景。更多综合用法还可参考 Examples/05featuredemo.inc.php 与 Examples/22heavilyformatted.php。
小结与使用建议
| 场景 | 推荐写法 |
|---|---|
| 给区域套用整套样式 | getStyle('A1:D4')->applyFromArray([...])（supervisor，可走高级模式） |
| 边框快捷设置 | 用allborders/outline/inside键 |
| 复用同一样式 | new PHPExcel_Style()+applyFromArray()+setSharedStyle() |
| 颜色统一写法 | array('rgb' => 'RRGGBB')或array('argb' => 'AARRGGBB') |
最后提醒三点：一是键名区分大小写且必须与表内拼写一致（如numberformat、quotePrefix），源码使用array_key_exists()精确匹配；二是传给applyFromArray()的非数组参数会直接抛异常；三是numberformat、protection等键虽在附录表格中标注为 getter 映射，实际应用时仍需以对应子组件的键（code、locked/hidden）组成内层数组。掌握这份键名映射表，就能用一份结构清晰的数组完成绝大多数单元格样式设置，让报表生成代码更简洁、更易维护。
【免费下载链接】PHPExcelARCHIVED项目地址: https://gitcode.com/gh_mirrors/ph/PHPExcel
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
