# 二维原生图表

从 `fsys.openXml` **0.12.0** 起，`builder` 支持 `kind="chart"`，生成真实 ChartML 图表和独立的内嵌 XLSX。无需 Office/WPS、.NET 或临时工作簿文件；不是截图、普通形状柱条或只有显示缓存的图表。

## 最小示例

```aardio
import fsys.openXml.pptx.builder;
var values=[12,0,null,20,null];
values@={length=5}; // 明确保留尾部缺值
var slides=[{shapes=[{
    kind="chart";name="Sales";
    x=50;y=60;width=860;height=420;
    chart={
        type="column";
        title="销售情况";
        categories=["一月","二月","三月","四月","五月"];
        series=[{name="销量";values=values;color="4472C4"}];
        legend=false;dataLabels="value";
        fontSize=14;numberFormat="0";
        axisMin=0;axisMax=30;majorUnit=10;
    };
}]}];
var report,err=fsys.openXml.pptx.builder.check(slides);
if(!report) return null,err;
if(!report.ok) return null,report.issues;
return fsys.openXml.pptx.builder.write("/native-chart.pptx",slides);
```

`chart` 内的未支持参数明确报错，不会把 `stacked/secondaryAxis/formula` 等当作已经生效。形状的位置/尺寸为 point；图表样式放在 `chart` 表内，形状本身不支持旋转/翻转/阴影/超链接/圆角。

## 图表与数据

| type | 范围 |
|---|---|
| `column` | 二维簇状柱状图，可多个系列 |
| `bar` | 二维簇状条形图，可多个系列；首类别置顶 |
| `line` | 等距分类轴的普通折线，可多个系列；缺值断线 |
| `pie` | 单系列二维饼图；非负且至少一个正值 |

- `categories`：非空字符串数组，允许空字符串标签，但不接受 null 标签。最多1000项。
- `series`：1～32个 `{name,values,color}`，`name` 为字符串，`color` 为 `RRGGBB`；默认配色轮换。
- `values`：与类别等长的数值/null数组；不隐式把字符串、false 或空串转成数值。有限数值范围为 ±1e100，总槽位不超过10000。
- **0 是真实数值；null 是缺值。** 工作簿不写缺值数值格，缓存保持完整点数和原始索引。类别不会因缺值左移。
- 长度使用 `table.len(values)`，遍历使用 `table.eachIndex(values)`，不用 `#values` 或默认迭代器截断稀疏数组。尾部 null 或全空数组用 `values@={length=N}` 明确长度。
- 类别/系列名称以字符串写入工作簿，即使以 `=` 开头也不会生成 Excel 公式；文字中的 `_xHHHH_` 序列按字面保存。

## 样式参数

| 字段 | 默认/说明 |
|---|---|
| `title` | 空字符串；非空时显示图表标题 |
| `legend` | `"bottom"`；可 `false/true/bottom/top/left/right`，true等价bottom |
| `dataLabels` | false；true等价value；可value/percent，percent仅饼图 |
| `numberFormat` | `"General"`；同时用于数值缓存、工作簿数值格与值轴/数值标签 |
| `fontSize` | 14pt，1～200；标题为该字号+4pt，不继承页面正文字号 |
| `fontName` | options.fontName 或 Microsoft YaHei；可另设 fontNameLatin/Ea/Cs |
| `color` | 文本色 `334155`；`lang` 继承options.lang，默认zh-CN |
| `background` | false透明；可显式RRGGBB |
| `axisMin/axisMax` | 不设时应用自动选择；允许0，min必须小于max；非饼图 |
| `majorUnit` | 正数，非饼图 |
| `gapWidth` | 150，0～500；仅柱/条图 |
| `marker` | true；仅折线图，false不显示标记点 |
| `firstSliceAngle` | 0，0～360；仅饼图 |
| `categoryColors` | 与类别等长的颜色数组；仅饼图 |

## 工作簿与编辑

每图一个独立 `Data` 工作表：A列分类，B列起为系列，第一行为系列名称。名称/类别/数值引用、缓存和工作簿均由同一份数据生成；图表关系指向包内工作簿，不连接外部数据。

使用 Office/WPS 的“编辑数据”修改。已有 `editor.copySlide` 可独立克隆这些图表和工作簿。本轮**没有增加原生 `setChartData` 或任意已有图表的保真编辑 API**；修改生成源数据后重生成，或使用应用的编辑数据功能。

本机 PowerPoint 16 已实际验证：四种类型、显示与字体、激活内嵌工作簿、修改数据、图表刷新、保存及重新打开。COM 自动化时先 Calculate/Refresh、处理消息后再关闭工作簿，不能仅以“工作簿保存成功”推断图表缓存已同步。用户于2026年10月8日确认五页图表示例在 Office/WPS 实测正常，编辑数据正常，第5页的0/null显示正确；未提供图表验收的WPS版本，不外推为所有版本或旧Office均已验证。

## 预检与边界

- `builder.check` 校验图表数据与外部几何越界，**不模拟图表内部轴标签、图例、百分比标签的排版，也不报告其相互遮挡**。留出足够空间，必要时用真实应用渲染检查。
- 不支持组合、堆叠/百分比堆叠、次轴、3D、散点/气泡、日期轴、平滑线、趋势线、公式/外链、图表元素分组动画。整图可沿用整形状动画。
- `pptx.read` 仍不是图表语义读取器，不把图表缓存内容混入正文读取。
- 小型内嵌包使用公共 `zlib.zip.packStore`（STORE、内存打包）；外层 PPTX 仍压缩。需要随库配套新版 zlib.zip。

完整五页演示：`~/examples/File/OpenXML/pptx-charts.aardio`，数据在 `.pptx-charts/slides.aardio`。第5页专门检验0、中间缺值和尾部缺值。示例数据均为虚构。