PHPExcel 样式数组速查：applyFromArray() 全量键名映射与源码级解析

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数组键映射属性值类型fillgetFill()样式数组见 PHPExcel_Style_FillfontgetFont()样式数组见 PHPExcel_Style_FontbordersgetBorders()样式数组见 PHPExcel_Style_BordersalignmentgetAlignment()样式数组见 PHPExcel_Style_AlignmentnumberformatgetNumberFormat()样式数组见 PHPExcel_Style_NumberFormatprotectiongetProtection()样式数组见 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填充数组键映射属性typesetFillType()rotationsetRotation()startcolorgetStartColor()endcolorgetEndColor()colorgetStartColor()实现见 Classes/PHPExcel/Style/Fill.phptype、rotation走 setterstartcolor、endcolor、color三个键的值都是颜色数组其中color与startcolor等价都作用于getStartColor()。type常用取值PHPExcel_Style_Fill::FILL_SOLID实心、FILL_NONE无填充默认、FILL_GRADIENT_LINEAR、FILL_GRADIENT_PATH、FILL_PATTERN_*系列setFillType()默认参数即FILL_NONEFill.php。color/startcolor/endcolor值形如array(rgb FFCCFF)或array(argb FFCCFFCC)见 Examples/23sharedstyles.php。PHPExcel_Style_Font字体数组键映射属性namesetName()boldsetBold()italicsetItalic()underlinesetUnderline()strikesetStrikethrough()colorgetColor()sizesetSize()superScriptsetSuperScript()subScriptsetSubScript()实现见 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传字体名如Arialsize传数值磅值。PHPExcel_Style_Borders边框集合数组键映射属性allbordersgetLeft();getRight();getTop();getBottom()leftgetLeft()rightgetRight()topgetTop()bottomgetBottom()diagonalgetDiagonal()verticalgetVertical()horizontalgetHorizontal()diagonaldirectionsetDiagonalDirection()outlinesetOutline()实现见 Classes/PHPExcel/Style/Borders.php 起。allborders是快捷键值会同时应用给左/右/上/下四条边框left、right、top、bottom、diagonal、vertical、horizontal的值是“边框数组”见下节 Border。PHPExcel_Style_Border单条边框数组键映射属性stylesetBorderStyle()colorgetColor()实现见 Classes/PHPExcel/Style/Border.php 起。style常用常量PHPExcel_Style_Border::BORDER_THIN细线、BORDER_MEDIUM中粗线、BORDER_DASHDOT点划线、BORDER_DOUBLE、BORDER_NONE等。color同样是颜色数组。PHPExcel_Style_Alignment对齐数组键映射属性horizontalsetHorizontal()verticalsetVertical()rotationsetTextRotation()wrapsetWrapText()shrinkToFitsetShrinkToFit()indentsetIndent()实现见 Classes/PHPExcel/Style/Alignment.php 起。注意这里的rotation映射到setTextRotation()文本旋转角度与 Fill 的rotation含义不同wrap、shrinkToFit传布尔值horizontal/vertical使用常量如PHPExcel_Style_Alignment::HORIZONTAL_CENTER、VERTICAL_CENTER。PHPExcel_Style_NumberFormat数字格式数组键映射属性codesetFormatCode()实现见 Classes/PHPExcel/Style/NumberFormat.php 起。code传入格式字符串例如0.00、yyyy-mm-dd、0.00%或内置常量PHPExcel_Style_NumberFormat::FORMAT_DATE_YYYYMMDD2等。PHPExcel_Style_Protection保护数组键映射属性lockedsetLocked()hiddensetHidden()实现见 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、leftinside→ 展开为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），仅供参考