元素使用指南:从 addChart 到样式配置与 Word2007 输出原理)
后端【免费下载链接】PHPWordA pure PHP library for reading and writing word processing documents项目地址https://gitcode.com/gh_mirrors/ph/PHPWord点击查看免费下载在 Word 文档中直接生成饼图、柱状图、折线图等原生图表是 PHPWord 的一项重要能力。本文围绕 PHPWord 的 Chart 元素展开讲解如何通过addChart()在节Section中插入图表、如何为图表配置 12 种类型与丰富的样式选项、如何添加多系列数据并结合仓库源码剖析图表在 Word2007 格式.docx中的底层写入机制。读完本文你将能够独立编写出带样式化图表的 Word 文档并理解图表 XML 的生成链路。快速上手添加一张图表在 PHPWord 中向文档添加图表非常简洁。核心调用位于 AbstractContainer 提供的魔术方法addChart()其完整签名如下/** * method Chart addChart(string $type, array $categories, array $values, array $style null, $seriesName null) */一个最基本的示例来自 图表元素文档?php $categories array(A, B, C, D, E); $series array(1, 3, 2, 5, 4); $chart $section-addChart(line, $categories, $series, $style);四个核心参数的含义参数类型说明$typestring图表类型如line、pie、bar等见下文类型清单$categoriesarray分类轴X 轴/类目标签如[A, B, C, D, E]$valuesarray与分类一一对应的数值序列如[1, 3, 2, 5, 4]$stylearray可选的样式数组缺省时使用默认样式$seriesNamemixed可选的系列名称第 5 个参数会写入图例底层实现中Chart 构造函数 会依次完成三件事校验并设置类型、以第一组数据初始化系列、将样式数组应用到Style\Chart对象。addChart()返回的是Chart元素对象后续可以通过$chart-getStyle()链式修改样式也可以通过$chart-addSeries()追加更多数据系列。支持的图表类型Chart::setType() 内部维护了一份类型白名单非法值会被安全回退为默认的pie$enum [pie, doughnut, line, bar, stacked_bar, percent_stacked_bar, column, stacked_column, percent_stacked_column, area, radar, scatter];结合 Word2007 图表 Part 写入器 中的类型映射表各类型对应的 OOXML 图表与关键特性如下类型底层 OOXML 图表关键特性piepieChart饼图支持按值着色doughnutdoughnutChart环形图默认洞径hole75不支持 3DbarbarChartbarDirbar横向条形图clustered分组stacked_barbarChart横向堆叠条形图percent_stacked_barbarChart横向百分比堆叠条形图columnbarChartbarDircol纵向柱状图clustered分组stacked_columnbarChart纵向堆叠柱状图percent_stacked_columnbarChart纵向百分比堆叠柱状图linelineChart折线图含类别轴与数值轴areaareaChart面积图groupingstandardradarradarChart雷达图radarStylestandard不支持 3DscatterscatterChart散点图scatterStylemarker不支持 3D两点补充其一3D 选项只对pie、bar、column、line、area生效——写入器在类型名后拼接3D如pie3DChart而doughnut、radar、scatter带有no3d标志不会被渲染为 3D其二bar/column系列在非clustered分组下会写入c:overlap val100即堆叠效果。添加多系列数据折线图、柱状图、散点图等通常需要对比多组数据。通过 Chart::addSeries() 可以追加系列$chart-addSeries($categories, $series2); // 追加第二组数据 $chart-addSeries($categories, $series3, 第三系列); // 追加带名称的系列每次调用都会向$series数组追加一条记录包含categories、values、name三项。其中name非空时写入器会为该系列生成c:tx系列标题在 Word 图例中显示为系列名。每个系列在 XML 中通过c:idx与c:order标记索引与绘制顺序多个系列之间互不影响。图表样式配置详解图表样式全部封装在 Style\Chart 中文档 Styles Chart 列出的选项如下下表补充了各选项的默认值与对应的 setter 方法样式键setter 方法取值 / 默认值说明widthsetWidth()intEMU默认1000000图表宽度单位为 EMUheightsetHeight()intEMU默认1000000图表高度单位为 EMU3dset3d()bool默认false是否 3D仅适用于 pie、bar、line、areacolorssetColors()array默认[]图表配色列表按顺序循环赋给各数据点titlesetTitle()string图表标题showLegendsetShowLegend()bool默认false是否显示图例legendPositionsetLegendPosition()r默认、b、t、l、tr图例位置右、下、上、左、右上categoryLabelPositionsetCategoryLabelPosition()nextTo默认、low、high分类轴标签位置valueLabelPositionsetValueLabelPosition()nextTo默认、low、high数值轴标签位置categoryAxisTitlesetCategoryAxisTitle()string分类轴标题valueAxisTitlesetValueAxisTitle()string数值轴标题majorTickMarkPossetMajorTickPosition()in、out、cross、none默认主刻度线位置showAxisLabelssetShowAxisLabels()bool默认false是否显示轴线标签gridXsetShowGridX()bool默认false是否显示 X 轴网格线gridYsetShowGridY()bool默认false是否显示 Y 轴网格线样式既可以在addChart()时以数组传入也可以在拿到$chart对象后链式设置两种方式等价// 方式一构造时传入样式数组 $section-addChart(bar, $categories, $series, [ width 5000000, height 3000000, 3d true, title 季度销量, showLegend true, legendPosition t, ]); // 方式二通过返回的对象链式设置 $chart $section-addChart(bar, $categories, $series); $chart-getStyle() -setWidth(Converter::inchToEmu(3)) -setHeight(Converter::inchToEmu(2)) -set3d(true) -setTitle(季度销量) -setShowLegend(true) -setLegendPosition(t);尺寸单位EMU 与 Converter 换算width/height的单位是 EMUEnglish Metric Unit英制公制单位1 英寸 914400 EMU。手工换算繁琐PHPWord 在 Shared\Converter 中提供了便捷转换方法use PhpOffice\PhpWord\Shared\Converter; Converter::cmToEmu(5); // 厘米转 EMU5cm ≈ 1,800,000 Converter::inchToEmu(2.5); // 英寸转 EMU2.5in ≈ 2,286,000 Converter::pixelToEmu(300); // 像素转 EMU按 96 DPI Converter::pointToEmu(72); // 磅转 EMU默认的1000000EMU 约等于 1.09 英寸约 2.78 厘米实际使用时建议总是显式指定尺寸。数据标签选项dataLabelOptions除文档列出的选项外Style\Chart 还内置了一组数据标签开关通过setDataLabelOptions()按需打开只会修改已定义的键不会新增键选项键默认值含义showValtrue显示数值showCatNametrue显示分类名showLegendKeyfalse显示图例项标记showSerNamefalse显示系列名showPercentfalse显示百分比showLeaderLinesfalse显示引导线showBubbleSizefalse显示气泡大小$chart-getStyle()-setDataLabelOptions([showPercent true, showVal false]);这些选项最终会写入每个系列下的c:dLbls节点。完整实战示例仓库中的 Sample_32_Chart.php 覆盖了全部 12 种图表类型并演示了 2D/3D 与多系列组合是官方推荐的一站式参考。下面是浓缩后的可运行骨架?php require_once vendor/autoload.php; use PhpOffice\PhpWord\PhpWord; use PhpOffice\PhpWord\Shared\Converter; $phpWord new PhpWord(); $section $phpWord-addSection(); $categories [A, B, C, D, E]; $series1 [1, 3, 2, 5, 4]; $series2 [3, 1, 7, 2, 6]; // 2D 折线图 $chart $section-addChart(line, $categories, $series1, [ width Converter::inchToEmu(2.5), height Converter::inchToEmu(2), showLegend true, legendPosition t, showAxisLabels true, gridX true, gridY true, ]); $chart-addSeries($categories, $series2); // 追加第二条折线 // 3D 饼图带自定义配色 $chart $section-addChart(pie, $categories, $series1, [ width Converter::cmToEmu(5), height Converter::cmToEmu(4), 3d true, title 3D 饼图, ]); $chart-getStyle()-setColors([FF0000, 00FF00, 0000FF, FFFF00, FF00FF]); // 堆叠柱状图 $chart $section-addChart(stacked_column, $categories, $series1); $chart-addSeries($categories, $series2); $chart-getStyle()-setShowLegend(true)-setLegendPosition(b); $writer \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, Word2007); $writer-save(chart.docx);示例中展示了几个实用技巧用addSeries()做多系列对比、用Converter换算 EMU 尺寸、用setColors()为饼图数据点逐个配色颜色按顺序循环分配。底层原理图表如何写入 .docx理解输出链路有助于排查问题。图表写入 Word2007 涉及三个环节1. 容器引用。图表是集合关联元素collectionRelation true会被登记到PhpWord::getCharts()集合中由 Word2007 写入器 统一处理。每个图表按顺序生成word/charts/chart1.xml、chart2.xml……并在[Content_Types].xml中登记chart类型、在word/_rels/document.xml.rels中登记对应的rId关系。2. 文档内嵌引用。Word2007 元素写入器 Chart 在正文段落中写入一个内联 Drawingw:p w:r w:drawing wp:inline其中wp:extent的cx/cy正是样式里的width/heightEMUc:chart节点通过r:id指向集合关系中分配好的rId从而把正文与图表 XML 文件关联起来。3. 图表 XML 生成。Word2007 图表 Part 写入器 负责生成c:chartSpace根节点先按类型写出标题c:title无标题时写c:autoTitleDeleted、图例c:legend、绘图区c:plotArea与图表主体节点如c:pieChart、c:barChart随后为每个系列写出c:ser含分类c:cat、数值c:val、系列名c:tx、标签c:dLbls最后按需写出分类轴与数值轴c:catAx/c:valAx含轴标题、刻度位置、标签位置与网格线。该写入器同时负责把样式选项翻译为 OOXML 属性showGridX/showGridY决定c:majorGridlines是否输出showAxisLabels决定c:tickLblPos使用nextTo/low/high还是nonemajorTickMarkPos映射到c:majorTickMarkcolors则逐点生成c:dPt c:spPr a:solidFill a:srgbClr。测试验证与注意事项仓库通过 Writer/Word2007/Element/ChartTest.php 对图表输出做了系统性验证可作为自定义图表功能的自检参照类型覆盖遍历pie、doughnut、bar、line、area、scatter、radar等类型断言生成的 XML 中存在对应的/c:chartSpace/c:chart/c:plotArea/c:{type}Chart路径3D 与配色验证set3d(true)后生成pie3DChart且setColors()的色值按序出现在a:srgbClr节点中系列名称addChart(..., seriesname)会生成带系列名的c:tx输出转义分类/数值文本会受Settings::isOutputEscapingEnabled()影响——启用时以writeElement安全转义禁用时以writeRaw原样写入见 Part/Chart.php 的writeSeriesItem。使用中的几个注意点图表仅在 Word2007.docx写入器下生成原生图表HTML、RTF、ODText、PDF 等写入器不输出图表 XML分类数组与数值数组长度需保持一致否则 Word 打开时可能提示图表数据异常未设置标题时写入器会自动写c:autoTitleDeleted val1避免出现默认Chart Title占位文案3D 对doughnut、radar、scatter不生效源码中带no3d标志如需立体效果请选择 pie/bar/column/line/area。至此从一行addChart()到样式细节、多系列数据再到.docx内部的 XML 生成链路你已经掌握了 PHPWord 图表功能的完整用法。更多组合方式可以直接参考 Sample_32_Chart.php 与 Style\Chart 源码。赞分享后端【免费下载链接】PHPWordA pure PHP library for reading and writing word processing documents项目地址https://gitcode.com/gh_mirrors/ph/PHPWord点击查看免费下载相关推荐三分钟让视频流畅开播ZLMediaKit流媒体服务器实战上手指南三分钟让视频流畅开播ZLMediaKit流媒体服务器实战上手指南 深夜十一点你架好摄像头画面却迟迟出不来延迟高、协议乱、播放器一片黑。如果你也卡在直播后端Chart.js 折线图Line Chart完全指南数据集属性、样式配置与插值原理Chart.js 折线图Line Chart完全指南数据集属性、样式配置与插值原理 折线图Line Chart是 Chart.js 中最常用的图表类型图表库前端数据可视化突破性Unity卡通渲染方案UniToon如何重塑游戏视觉表现突破性Unity卡通渲染方案UniToon如何重塑游戏视觉表现 UniToon是一款革命性的基于物理的Unity卡通着色器专为游戏开发设计。这款开源着色器完上一篇WebToApp CI测试门禁i18n一致性与配置漂移如何被自动化测试抓住下一篇终极指南如何用一个免费开源软件统一控制所有品牌RGB灯光创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考