CORE
图表
docx 和 pptx 共享的图表组件 — 支持 12 种图表类型
@office-open/core 提供了 @office-open/docx 和 @office-open/pptx 共享的图表组件。图表通过 ChartSpaceOptions 定义，由 chartSpaceDesc 描述符进行序列化和解析。图表数据由 ChartCollection 管理。
#图表类型
type 属性选择图表类型：
| 类型 | 值 | 说明 |
|---|---|---|
| 柱状图 | "column" | 垂直柱状 |
| 条形图 | "bar" | 水平柱状 |
| 折线图 | "line" | 带可选标记的折线系列 |
| 饼图 | "pie" | 饼图 |
| 面积图 | "area" | 填充面积系列 |
| 散点图 | "scatter" | XY 散点图 |
| 圆环图 | "doughnut" | 环形图 |
| 雷达图 | "radar" | 雷达/蜘蛛图 |
| 气泡图 | "bubble" | 气泡图（需 xValues/yValues/bubbleSize） |
| 股票图 | "stock" | 股价图（高低收） |
| 曲面图 | "surface" | 3D 曲面图 |
| 复合饼图 | "ofPie" | 饼图-饼图或条形-饼图（ofPieType 控制） |
设置 threeD: true 可将 column、bar、line、pie、area 转为 3D 变体。
#ChartSpaceOptions
ChartSpaceOptions 是图表的选项接口。它指定图表类型、标题、坐标轴和数据：
import type { ChartSpaceOptions } from "@office-open/core";
const chartOptions: ChartSpaceOptions = {
title: "营收",
type: "bar",
categories: ["Q1", "Q2", "Q3", "Q4"],
series: [{ name: "2024", values: [10, 20, 30, 40] }],
};
#选项
| 选项 | 类型 | 说明 |
|---|---|---|
type | ChartType | 图表类型字符串（见上表） |
categories | string[] | 类别标签 |
series | ChartSeriesData[] | ScatterSeriesData[] | 系列数据 |
title | string | 图表标题 |
showLegend | boolean | 是否显示图例（默认：true） |
style | number | 样式预设（2–48） |
threeD | boolean | 启用 3D 渲染 |
#chartSpaceDesc
chartSpaceDesc 是 CustomDescriptor<ChartSpaceOptions>，负责图表 XML（c:chartSpace）的序列化和解析。docx 和 pptx 包内部使用此描述符：
import { chartSpaceDesc } from "@office-open/core";
import { stringify, parse } from "@office-open/core/descriptor";
// 序列化图表选项为 XML
const xml = stringify(chartSpaceDesc, chartOptions, writeCtx);
// 解析图表 XML 回选项对象
const options = parse(chartSpaceDesc, chartElement, readCtx);
#ChartCollection
ChartCollection 管理文档或演示文稿中的多个图表。它按 ID 存储 ChartData 条目：
import { ChartCollection } from "@office-open/core";
const charts = new ChartCollection();
charts.addChart("chart1", { key: "chart1", chartSpaceXml: xml });
#ChartData
| 属性 | 类型 | 说明 |
|---|---|---|
key | string | 唯一图表 ID |
chartSpaceXml | string | 序列化的图表 XML |
#系列数据
每种图表类型接受系列数据，包含类别标签和值。标准系列使用 ChartSeriesData：
const series: ChartSeriesData[] = [
{ name: "产品 A", values: [10, 20, 15] },
{ name: "产品 B", values: [5, 12, 8] },
];
#ChartSeriesData
| 选项 | 类型 | 说明 |
|---|---|---|
name | string | 系列名称 |
values | number[] | 数据值 |
trendlines | TrendlineOptions[] | 系列趋势线 |
errorBars | ErrorBarOptions | 误差线配置 |
dataLabels | DataLabelsOptions | 数据标签配置 |
散点图使用 ScatterSeriesData —— XY 数值轴、无气泡大小：
| 选项 | 类型 | 说明 |
|---|---|---|
name | string | 系列名称 |
xValues | number[] | X 坐标 |
yValues | number[] | Y 坐标 |
气泡图在其上扩展 BubbleSeriesData：
| 选项 | 类型 | 说明 |
|---|---|---|
bubbleSize | number[] | 气泡大小 |
#坐标轴
使用坐标轴的图表（柱状、折线、面积、散点）会根据图表类型自动创建坐标轴。传入 axes: AxisOptions[] 可显式控制——网格线、刻度、缩放范围、数字格式以及每轴 shapeProperties 均可往返保真。
#往返字段
解析源文件时携带、而新建图表通常省略的字段。parse 时记录、stringify 时重新发射，往返的图表因此保留工作表链接与渲染标志：
- 数据引用：
nameFormula/valueFormula（系列）、categoryFormula（图表）保存c:f工作表公式；formatCode/categoryFormatCode保留缓存数字格式。 - 数值类别：
numericCategories: true将c:cat切换为c:numRef形态（数值格式轴）。 - 头部元素：
date1904、lang、roundedCorners、autoTitleDeleted。 - 组级标志：
varyColors、markers（折线）、shape（3D 柱形）、组级dataLabels，以及逐字的axisIds引用序列（旧版文件会写悬空的axId val="0"）。 - 形状属性：图表空间、每个系列与每个坐标轴上的
shapeProperties。 - 标题占位：
title: ""往返裸<c:title/>（无文本的自动标题）。
#在文档中使用
图表通常通过文档/演示文稿 API 创建，而非直接使用。参见：