报表定义类型

报表定义 ReportDocument 的全部类型，按 @xihan-report/core 的源码列出。当前 schema 版本 REPORT_SCHEMA_VERSION 为 1。

报表定义是纯 JSON：数据集只描述字段与参数，不含数据；数据由取数回调按请求交回。各对象都可以带 extensions，放扩展自己的数据，见扩展数据。「中文名」是设计器属性面板里的叫法，详见属性。

报表与参数

ParameterOption {#parameteroption}

参数的一个候选项。

字段	类型	必填	中文名	说明
value	ScalarValue	是	数值	取值，类型与参数一致：date 写 YYYY-MM-DD，datetime 写不带时区的 YYYY-MM-DDTHH:mm[:ss]。
label	string	可省	—	显示的文字；不写按取值显示。
disabled	boolean	可省	—	在参数栏里列出但不能选；宿主或缺省值给了这个取值照样认。

ReportParameter {#reportparameter}

报表参数：报表使用者填写，经绑定传给数据集参数或筛选条件。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
name	string	是	名称	参数名，在报表内唯一。
type	FieldType	是	类型
title	string	可省	标题
required	boolean	可省	必填	必须给值。
multiple	boolean	可省	多选	接受多个值。
defaultValue	ParameterValue	可省	缺省值	缺省值。
options	readonly ParameterOption[]	可省	候选项	固定的候选项。

ReportDocument {#reportdocument}

报表文档：纯 JSON。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
schemaVersion	typeof REPORT_SCHEMA_VERSION	是	—	报表定义的版本，写 REPORT_SCHEMA_VERSION。
id	string	是	—	报表身份。
title	string	可省	标题
description	string	可省	说明
parameters	readonly ReportParameter[]	可省	参数绑定
datasets	readonly DatasetSchema[]	是	—	报表用到的数据集：只描述字段与参数，数据由取数回调交回。
body	ReportBody	是	—	报表的主体：明细表、分组报表、交叉表、看板，或扩展登记的视图。

数据集与取数

DatasetField {#datasetfield}

数据集里的一个字段。写了 formula 的是计算字段，以同一行的字段与报表参数（$名字）为变量逐行求值，不由使用方提供。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
name	string	是	名称	字段名：数据行里的键，在数据集内唯一；不以 $ 开头。
type	FieldType	是	类型
title	string	可省	标题	显示的标题，缺省同 name。
formula	string	可省	公式	计算字段的表达式；求值能力由 ExpressionEngine 提供。

DatasetParameter {#datasetparameter}

数据集接受的一个参数：取数时由使用方的数据源解释。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
name	string	是	名称	参数名，在数据集内唯一。
type	FieldType	是	类型
title	string	可省	标题
required	boolean	可省	必填	取数时必须给值。
multiple	boolean	可省	多选	接受多个值。

DatasetSchema {#datasetschema}

报表引用的一个数据集。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
id	string	是	—	数据集身份，在报表内唯一，也是取数请求里的 dataset。
title	string	可省	标题
fields	readonly DatasetField[]	是	—	数据集的字段。
parameters	readonly DatasetParameter[]	可省	参数绑定

DatasetQueryDimension {#datasetquerydimension}

取数请求里的一个维度：按 field 分组，写了 bucket 时按日期粒度取键。

字段	类型	必填	中文名	说明
id	string	是	—	维度 id：交回的聚合行里以它为键。
field	string	是	字段
bucket	DateBucket	可省	日期粒度

DatasetQueryMeasure {#datasetquerymeasure}

取数请求里的一个度量：对 field 做 aggregate；count 不写 field 时数行。

字段	类型	必填	中文名	说明
id	string	是	—	度量 id：交回的聚合行里以它为键。
field	string	可省	字段
aggregate	AggregateKind	是	聚合

DatasetQuery {#datasetquery}

视图需要的聚合：使用方可以照此在后端聚合，返回 aggregated 数据。已聚合数据的每行以维度 id 与度量 id 为键。

字段	类型	必填	中文名	说明
dimensions	readonly DatasetQueryDimension[]	是	—	按哪些维度分组。
measures	readonly DatasetQueryMeasure[]	是	—	每组要算的度量。
rollups	readonly (readonly string[])[]	是	—	不可累加的度量（avg、distinctCount）要单独给出的汇总分组：每项是一组维度 id，空数组是总计。没有不可累加的度量时为空。

DatasetRequest {#datasetrequest}

取数请求：core 按视图与参数取值算出，使用方据此取数。

字段	类型	必填	中文名	说明
dataset	string	是	数据集	数据集 id。
parameters	ParameterValues	是	参数绑定	数据集参数的取值：已按绑定解析，未给值的参数不出现。
filter	FilterGroup | null	是	筛选	已代入参数的筛选；引用了计算字段时为 null，由 core 在取回的行上筛选。
sort	readonly RowSortRule[] | null	是	排序	明细视图的排序；聚合视图为 null。
limit	number | null	是	行数上限	明细视图的行数上限；没有上限为 null。
query	DatasetQuery | null	是	—	视图需要的聚合；明细视图或引用了计算字段时为 null，此时只能返回明细行。

DatasetRows {#datasetrows}

明细行：core 负责计算字段、筛选、分组与聚合。

字段	类型	必填	中文名	说明
kind	'rows'	是	—	交回明细行。
rows	readonly DataRow[]	是	—	明细行：以字段名为键；core 在这些行上筛选、聚合与计算。

DatasetRollup {#datasetrollup}

一条汇总行：按 dimensions 分组的汇总值，键同已聚合行。

字段	类型	必填	中文名	说明
dimensions	readonly string[]	是	—	分组的维度 id；空数组是总计。
row	DataRow	是	—	这一组的汇总值：以度量 id 为键。

DatasetAggregated {#datasetaggregated}

已聚合数据：使用方按请求里的 query 在后端聚合并筛选过。rows 以维度 id 与度量 id 为键；不可累加度量的汇总值由 rollups 给出。

字段	类型	必填	中文名	说明
kind	'aggregated'	是	—	交回按请求聚合好的行。
rows	readonly DataRow[]	是	—	每组一行：以维度 id 与度量 id 为键。
rollups	readonly DatasetRollup[]	可省	—	请求的 rollups 里每个分组的汇总行；请求里 rollups 为空时不写。

DatasetData {#datasetdata}

使用方交回的数据。

取其一：DatasetRows、DatasetAggregated。

视图与看板

DataBinding {#databinding}

视图取数的数据集与参数绑定。

字段	类型	必填	中文名	说明
dataset	string	是	数据集	数据集 id。
parameters	Readonly<Record<string, Operand>>	可省	参数绑定	数据集参数名到操作数：字面值或报表参数。

ColumnSummary {#columnsummary}

汇总：对列的字段做聚合，或以其它列的汇总值与报表参数（$名字）为变量求公式。

类型：{ readonly aggregate: AggregateKind } | { readonly formula: string }

TableColumn {#tablecolumn}

表格的一列。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
id	string	是	—	列身份，在视图内唯一。
field	string	是	字段	数据集字段名。
title	string	可省	标题
format	FormatSpec	可省	格式
width	number	可省	列宽	列宽（px）。
align	'start' | 'center' | 'end'	可省	对齐
sticky	'start' | 'end'	可省	冻结	横向滚动时固定在行首侧或行尾侧。
summary	ColumnSummary	可省	—	汇总：分组报表的组小计与总计、明细表的合计行。

TableView {#tableview}

明细表：逐行列出数据。

继承 DataBinding、ReportExtensible 的字段。

字段	类型	必填	中文名	说明
type	'table'	是	类型
columns	readonly TableColumn[]	是	—	各列，从左到右。
filter	FilterGroup	可省	筛选
sort	readonly RowSortRule[]	可省	排序
limit	number	可省	行数上限	行数上限，在排序之后截取。

GroupLevel {#grouplevel}

分组报表的一级分组。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
id	string	是	—	分组身份，在视图内唯一。
field	string	是	字段	数据集字段名。
bucket	DateBucket	可省	日期粒度
title	string	可省	标题
format	FormatSpec	可省	格式
sort	AxisSort	可省	排序	组的次序：by 写带汇总的列 id 时按该列的组小计排；缺省按键升序。
header	boolean	可省	组头	显示组头，缺省 true。
subtotal	boolean	可省	组小计	显示组小计，缺省 true。

GroupView {#groupview}

分组报表：多级分组，组内列出明细，组尾写小计，末尾写总计。

继承 DataBinding、ReportExtensible 的字段。

字段	类型	必填	中文名	说明
type	'group'	是	类型
groups	readonly GroupLevel[]	是	—	各级分组，由外到内。
columns	readonly TableColumn[]	是	—	明细行与组小计的各列，从左到右。
filter	FilterGroup	可省	筛选
sort	readonly RowSortRule[]	可省	排序	组内明细行的次序。
detail	boolean	可省	列出明细	列出明细行，缺省 true；false 时只有组头与小计。
grandTotal	boolean	可省	总计	写总计，缺省 true。

CrosstabTotals {#crosstabtotals}

交叉表一条轴上的汇总。

字段	类型	必填	中文名	说明
subtotals	boolean	可省	—	除最内层外，每层维度的成员之后写小计，缺省 false。
grandTotal	boolean	可省	总计	轴的末尾写总计，缺省 true。

CrosstabView {#crosstabview}

交叉表：行维度与列维度交叉，格子里写度量。

继承 DataBinding、ReportExtensible 的字段。

字段	类型	必填	中文名	说明
type	'crosstab'	是	类型
rows	readonly Dimension[]	是	—	行维度，由外到内。
columns	readonly Dimension[]	是	—	列维度，由外到内。
measures	readonly Measure[]	是	—	每个格子里的度量。
filter	FilterGroup	可省	筛选
rowTotals	CrosstabTotals	可省	—	行方向（行维度）的小计与总计。
columnTotals	CrosstabTotals	可省	—	列方向（列维度）的小计与总计。
measuresOn	'columns' | 'rows'	可省	度量排在	多个度量排在列方向还是行方向，缺省 columns。

DashboardGrid {#dashboardgrid}

看板网格。

字段	类型	必填	中文名	说明
columns	number	是	—	列数。
rowHeight	number	是	—	一行的高度（px）。

CardLayout {#cardlayout}

卡片在网格上的位置与大小，单位是格。

字段	类型	必填	中文名	说明
x	number	是	横坐标
y	number	是	纵坐标
w	number	是	—	宽，单位是格。
h	number	是	—	高，单位是行。

CardBase {#cardbase}

卡片的共有属性。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
id	string	是	—	卡片身份，在看板内唯一。
title	string	可省	标题
description	string	可省	说明
layout	CardLayout	是	布局

ChartCard {#chartcard}

图表卡片。

继承 CardBase、DataBinding 的字段。

字段	类型	必填	中文名	说明
kind	'chart'	是	—	图表卡片。
query	ReportQuery	是	—	取数的聚合查询：图表的维度与度量都引用它的 id。
chart	ChartSpec	是	—	图表配置。

MetricCard {#metriccard}

指标卡片。

继承 CardBase、DataBinding 的字段。

字段	类型	必填	中文名	说明
kind	'metric'	是	—	指标卡片。
query	ReportQuery	是	—	取数的聚合查询：指标取它的总计，迷你图取它的分组。
metric	MetricSpec	是	—	指标配置。

TableCard {#tablecard}

表格卡片：内嵌一个明细表、分组报表或交叉表。

继承 CardBase 的字段。

字段	类型	必填	中文名	说明
kind	'table'	是	—	表格卡片。
view	TableView | GroupView | CrosstabView	是	—	卡片里的明细表、分组报表或交叉表，带自己的数据集与筛选。

ExtensionCard {#extensioncard}

扩展登记的卡片：kind 是带点的种类名。取数部分按种类声明的形状写：同图表卡片的 dataset、parameters 与 query，或同表格卡片的 view，或不取数；其余字段归种类自己。

继承 CardBase、Partial<DataBinding> 的字段。

字段	类型	必填	中文名	说明
kind	ReportExtensionKind	是	—	扩展登记的种类名。
query	ReportQuery	可省	—	取数形状为 query 的种类：聚合查询。
view	DataView	可省	—	取数形状为 view 的种类：明细表、分组报表或交叉表。
[key: string]	unknown	是	—	种类自己的其余字段，由种类的 validate 校验。

DashboardCard {#dashboardcard}

看板上的一张卡片：图表、指标、表格，或扩展登记的种类。

取其一：ChartCard、MetricCard、TableCard、ExtensionCard。

LinkTarget {#linktarget}

联动的一个目标：在目标卡片上按字段筛选。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
card	string	是	源卡片	目标卡片 id。
field	string	是	字段	目标卡片数据集的字段名。

DashboardLink {#dashboardlink}

筛选联动：在源卡片上选中的取值，成为目标卡片在对应字段上的 in 条件。源维度带日期粒度时，目标字段按同一粒度取键再比较。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
id	string	是	—	联动身份，在看板内唯一。
card	string	是	源卡片	源卡片 id。
dimension	string	是	源维度	源卡片上发出取值的维度：图表与指标卡片是查询的维度 id，分组报表是分组 id，交叉表是行或列维度 id，明细表是列 id。
targets	readonly LinkTarget[]	是	目标

DashboardView {#dashboardview}

看板：网格上排列的卡片。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
type	'dashboard'	是	类型
grid	DashboardGrid	是	—	网格的列数与行高。
cards	readonly DashboardCard[]	是	—	看板上的卡片，位置与大小写在各自的 layout 上。
links	readonly DashboardLink[]	可省	—	卡片之间的筛选联动。

ExtensionView {#extensionview}

扩展登记的主体视图：type 是带点的种类名。取数部分按种类声明的形状写：同图表卡片的 dataset、parameters 与 query，或不取数；其余字段归种类自己。

继承 Partial<DataBinding>、ReportExtensible 的字段。

字段	类型	必填	中文名	说明
type	ReportExtensionKind	是	类型
query	ReportQuery	可省	—	取数形状为 query 的种类：聚合查询。
[key: string]	unknown	是	—	种类自己的其余字段，由种类的 validate 校验。

ReportBody {#reportbody}

报表的主体。

取其一：TableView、GroupView、CrosstabView、DashboardView、ExtensionView。

DataView {#dataview}

可以直接取数计算的视图。

取其一：TableView、GroupView、CrosstabView。

查询

AggregateKind {#aggregatekind}

转导出自 @xihan-ui/viz。取值见常量 AGGREGATE_KINDS：

取值	中文名
sum	求和
avg	平均
count	计数
min	最小
max	最大
distinctCount	去重计数

DateBucket {#datebucket}

日期粒度：把日期取成分组键。year → 2026，quarter → 2026-Q4，month → 2026-10，week → 2026-W42（ISO 周），day → 2026-10-16，hour → 2026-10-16T08。

取值见常量 DATE_BUCKETS：

取值	中文名
year	年
quarter	季度
month	月
week	周
day	日
hour	小时

AxisSort {#axissort}

成员的次序：按键，或按某个度量在该成员上的汇总值。

字段	类型	必填	中文名	说明
by	string	可省	—	度量 id（分组报表里是带汇总的列 id）；不写按键。
direction	SortDirection	可省	方向	缺省 asc。
nulls	NullsPosition	可省	—	缺省 last。

Dimension {#dimension}

维度：按字段分组。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
id	string	是	—	维度身份：查询结果里的键，与同一查询的度量 id 共用命名空间。
field	string	是	字段	数据集字段名。
bucket	DateBucket	可省	日期粒度	日期粒度。
title	string	可省	标题
format	FormatSpec	可省	格式
sort	AxisSort	可省	排序	成员次序，缺省按键升序。

MeasureBase {#measurebase}

共有的度量属性。

继承 ReportExtensible 的字段。

字段	类型	必填	中文名	说明
id	string	是	—	度量身份：查询结果里的键，与同一查询的维度 id 共用命名空间。
title	string	可省	标题
format	FormatSpec	可省	格式

AggregateMeasure {#aggregatemeasure}

聚合度量：对字段做聚合；count 不写 field 时数行。

继承 MeasureBase 的字段。

字段	类型	必填	中文名	说明
aggregate	AggregateKind	是	聚合
field	string	可省	字段

FormulaMeasure {#formulameasure}

公式度量：在聚合之后，以同一查询其它度量的值与报表参数（$名字）为变量求值。

继承 MeasureBase 的字段。

字段	类型	必填	中文名	说明
formula	string	是	公式

Measure {#measure}

度量：聚合度量或公式度量。

取其一：AggregateMeasure、FormulaMeasure。

QuerySortRule {#querysortrule}

查询结果行的一条排序规则。

字段	类型	必填	中文名	说明
key	string	是	—	维度 id 或度量 id。
direction	SortDirection	可省	方向	缺省 asc。
nulls	NullsPosition	可省	—	缺省 last。

ReportQuery {#reportquery}

聚合查询：按维度分组、计算度量，结果每个维度组合一行。

字段	类型	必填	中文名	说明
dimensions	readonly Dimension[]	是	—	按哪些维度分组；不写维度时结果只有总计。
measures	readonly Measure[]	是	—	每组要算的度量。
filter	FilterGroup	可省	筛选
sort	readonly QuerySortRule[]	可省	排序	结果行的次序；不写按维度依次升序。
limit	number	可省	行数上限	结果行数上限，在排序之后截取。

筛选与排序

ParameterRef {#parameterref}

引用一个报表参数的值。

字段	类型	必填	中文名	说明
parameter	string	是	—	报表参数名：取数时换成参数的取值。

Operand {#operand}

操作数：字面值、字面值数组，或报表参数。

类型：ScalarValue | readonly ScalarValue[] | ParameterRef

FilterOperator {#filteroperator}

转导出自 @xihan-ui/viz。取值见常量 FILTER_OPERATORS：

取值	中文名
eq	—
neq	—
gt	—
gte	—
lt	—
lte	—
between	—
in	—
notIn	—
contains	—
notContains	—
startsWith	—
endsWith	—
isEmpty	—
isNotEmpty	—

NullsPosition {#nullsposition}

转导出自 @xihan-ui/viz。取值见常量 NULLS_POSITIONS：

取值	中文名
first	最前
last	最后

SortDirection {#sortdirection}

转导出自 @xihan-ui/viz。取值见常量 SORT_DIRECTIONS：

取值	中文名
asc	升序
desc	降序

FilterCondition {#filtercondition}

一个筛选条件。

字段	类型	必填	中文名	说明
id	string	是	—	条件身份，在所在筛选树内唯一。
field	string	是	字段	数据集字段名。
bucket	DateBucket	可省	日期粒度	先把字段值按日期粒度取键再比较。
operator	FilterOperator	是	—	运算符，见 FilterOperator；isEmpty、isNotEmpty 不要操作数，between 要两个值，in、notIn 要一组值。
value	Operand	可省	数值	操作数；isEmpty / isNotEmpty 不写。
ignoreCase	boolean	可省	—	字符串运算符忽略大小写。

FilterGroup {#filtergroup}

条件组：and 全部满足，or 任一满足。

字段	类型	必填	中文名	说明
logic	'and' | 'or'	是	—	and 是全部满足，or 是任一满足。
conditions	readonly FilterNode[]	是	—	条件与子组；组里的条件都不参与（空数组，或操作数都为空）时整组不筛选。

FilterSubgroup {#filtersubgroup}

嵌套在条件组里的子组。

继承 FilterGroup 的字段。

字段	类型	必填	中文名	说明
id	string	是	—	子组身份，在所在筛选树内唯一。

FilterNode {#filternode}

条件组里的一项：条件或子组。

取其一：FilterCondition、FilterSubgroup。

RowSortRule {#rowsortrule}

明细行的一条排序规则。

字段	类型	必填	中文名	说明
field	string	是	字段	数据集字段名。
direction	SortDirection	可省	方向	缺省 asc。
nulls	NullsPosition	可省	—	缺省 last。

图表

ChartTone {#charttone}

语气：XiHan.UI 的 Tone。

类型：Tone

ChartPalette {#chartpalette}

顺序色阶的色板，与 XiHan.UI 的 ChartPalette 一致。

类型：'red' | 'orange' | 'amber' | 'yellow' | 'lime' | 'green' | 'teal' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'pink' | 'gray'

ChartSymbol {#chartsymbol}

散点形状：XiHan.UI 图表引擎的 SymbolName。

类型：SymbolName

ChartSize {#chartsize}

尺寸档。

类型：'sm' | 'md' | 'lg'

CartesianSeriesSpecBase {#cartesianseriesspecbase}

笛卡尔图系列的共有属性。

字段	类型	必填	中文名	说明
id	string	是	—	系列身份，在图内唯一。
name	string	可省	名称	图例与提示框里的名字，缺省取度量标题。
slot	number	可省	色槽	固定色槽 1–8。
tone	ChartTone	可省	语气	语义系列的语气。

CartesianBarSeriesSpec {#cartesianbarseriesspec}

柱系列。

继承 CartesianSeriesSpecBase 的字段。

字段	类型	必填	中文名	说明
mark	'bar'	是	标记
x	string	是	横坐标	自变量：维度 id。
y	string | readonly [string, string]	是	纵坐标	数值：度量 id；写成 [下, 上] 是浮动柱。
shape	'bar' | 'lollipop'	可省	形状
stack	string	可省	堆叠组
stackOffset	'none' | 'expand' | 'diverging'	可省	堆叠方式
labels	'none' | 'inside' | 'end'	可省	标签

CartesianLineSeriesSpec {#cartesianlineseriesspec}

折线系列。

继承 CartesianSeriesSpecBase 的字段。

字段	类型	必填	中文名	说明
mark	'line'	是	标记
x	string	是	横坐标	自变量：维度 id。
y	string | readonly [string, string]	是	纵坐标	数值：度量 id；写成 [下, 上] 是区间带。
curve	'linear' | 'monotone' | 'step' | 'step-before' | 'step-after'	可省	曲线
area	boolean	可省	面积
stack	string	可省	堆叠组
stackOffset	'none' | 'expand' | 'silhouette' | 'wiggle'	可省	堆叠方式
symbols	'auto' | 'always' | 'none'	可省	数据点
connectNulls	boolean	可省	连接空值
labels	'none' | 'end'	可省	标签
endLabel	boolean	可省	末端标签

CartesianScatterSeriesSpec {#cartesianscatterseriesspec}

散点系列：每个维度组合一个点。

继承 CartesianSeriesSpecBase 的字段。

字段	类型	必填	中文名	说明
mark	'scatter'	是	标记
x	string	是	横坐标	横坐标：维度 id 或度量 id。
y	string	是	纵坐标	纵坐标：度量 id。
size	string	可省	尺寸	气泡大小：度量 id。
symbol	ChartSymbol	可省	点形状
jitter	number	可省	抖动
color	string	可省	颜色度量	按值着色：度量 id。

CartesianSeriesSpec {#cartesianseriesspec}

柱线图的一条系列：柱、折线或散点。

取其一：CartesianBarSeriesSpec、CartesianLineSeriesSpec、CartesianScatterSeriesSpec。

CartesianAxisSpec {#cartesianaxisspec}

坐标轴；时间值写 ISO 8601 字符串。

字段	类型	必填	中文名	说明
scale	'band' | 'point' | 'linear' | 'log' | 'sqrt' | 'pow' | 'symlog' | 'time' | 'utc'	可省	刻度	比例尺；不写按数据推断：带柱或非数值的自变量用 band，日期用 time，数值用 linear。
domain	readonly (string | number)[]	可省	—	类目轴的显式顺序。
min	number | string	可省	—	下界；时间轴写 ISO 8601 字符串。
max	number | string	可省	—	上界；时间轴写 ISO 8601 字符串。
nice	boolean	可省	—	两端取整到刻度上，数值轴缺省为真。
zero	boolean	可省	—	数值轴包含 0；有柱系列时总是包含。
ticks	number	可省	—	刻度数量提示。
format	FormatSpec	可省	格式	刻度标签的格式。
title	string	可省	标题	轴标题。
grid	boolean	可省	—	画网格线；不写时数值轴画、类目轴不画。
labelOverflow	'auto' | 'rotate' | 'truncate' | 'wrap'	可省	—	刻度标签放不下时：自动、旋转、截断或折行。
reverse	boolean	可省	—	反向。
exponent	number	可省	—	pow 轴的指数，正数，缺省 1。
constant	number	可省	—	symlog 轴 sign(x) · log1p(|x| / c) 里的 c，正数，缺省 1；越小越接近对数，越大越接近线性。
timeZone	string	可省	—	时间轴按哪个时区（IANA 名）排刻度、写标签；不写时 time 轴按运行环境所在时区，utc 轴按 UTC。
minSize	number	可省	—	这根轴（刻度、标签与标题）至少占的厚度（px）：上下叠放的几张图写同一个值，绘图区的左边就对齐。
ordinal	boolean	可省	—	只用于横轴：数据点等距排列，跳过没有数据的时段；比例尺须为 time、utc 或 linear。
fit	'all' | 'window'	可省	—	只用于纵轴：定义域按全部数据（all，缺省）还是只按缩放窗口里露出的数据（window）算。

CartesianAnnotationSpec {#cartesianannotationspec}

注释；axis 的 x 是自变量轴，y 是数值轴。series 写系列 id。

类型：| { readonly kind: 'line', readonly axis: 'x' | 'y', readonly value: number | string, readonly label?: string } | { readonly kind: 'band', readonly axis: 'x' | 'y', readonly from: number | string, readonly to: number | string, readonly label?: string } | { readonly kind: 'point', readonly series: string, readonly at: 'max' | 'min' | 'last' | { readonly x: number | string }, readonly label?: string } | { readonly kind: 'average', readonly series: string, readonly label?: string } | { readonly kind: 'trend', readonly series: string, readonly method: 'linear' | 'moving-average', readonly window?: number, readonly label?: string }

CartesianChartSpec {#cartesianchartspec}

笛卡尔图：柱、折线、面积、散点。

字段	类型	必填	中文名	说明
type	'cartesian'	是	类型
series	readonly CartesianSeriesSpec[]	是	—	各系列：柱、折线与散点可以混排。
splitBy	string	可省	拆分系列	拆分维度：每个系列按这个维度的每个成员各展开一条。
orientation	'vertical' | 'horizontal'	可省	方向
xAxis	CartesianAxisSpec	可省	—	横轴（自变量轴）；orientation 为 horizontal 时画在左侧。
yAxis	CartesianAxisSpec	可省	—	纵轴（数值轴）。
renderer	'svg' | 'canvas' | 'auto'	可省	渲染方式
trigger	'axis' | 'item'	可省	提示框触发
totals	boolean	可省	显示合计
tooltipOrder	'series' | 'descending' | 'ascending'	可省	提示框排序
palette	ChartPalette	可省	色板
annotations	readonly CartesianAnnotationSpec[]	可省	标注
zoom	'none' | 'x' | 'y' | 'xy'	可省	缩放
brush	'none' | 'x' | 'y' | 'xy'	可省	刷选

PieChartSpec {#piechartspec}

饼图：每个维度成员一个扇区。

字段	类型	必填	中文名	说明
type	'pie'	是	类型
nameField	string	是	名称维度	扇区名：维度 id。
valueField	string	是	数值度量	数值：度量 id。
variant	'pie' | 'donut'	可省	形态
rose	boolean	可省	玫瑰图
sweep	'full' | 'half'	可省	扇区范围
sort	'none' | 'descending'	可省	排序
maxSlices	number	可省	最多扇区数
labels	'none' | 'inside' | 'outside'	可省	标签
labelContent	'name-share' | 'name-value' | 'name' | 'share' | 'value'	可省	标签内容
format	NumericFormatSpec	可省	格式

FunnelChartSpec {#funnelchartspec}

漏斗图：每个维度成员一个阶段。

字段	类型	必填	中文名	说明
type	'funnel'	是	类型
nameField	string	是	名称维度	阶段名：维度 id。
valueField	string	是	数值度量	数值：度量 id。
shape	'trapezoid' | 'bar'	可省	形状
align	'center' | 'start'	可省	对齐
direction	'down' | 'up'	可省	方向
conversion	'previous' | 'first' | 'none'	可省	转化率
labels	'inside' | 'outside'	可省	标签
palette	ChartPalette	可省	色板
format	NumericFormatSpec	可省	格式

RadarIndicatorSpec {#radarindicatorspec}

雷达图的一个指标。

字段	类型	必填	中文名	说明
key	string	是	—	度量 id。
label	string	可省	—	轴上的名字；不写取度量的标题。
min	number	可省	—	这根轴的下界；不写按数据算。
max	number	可省	—	这根轴的上界；不写按数据算。

RadarChartSpec {#radarchartspec}

雷达图：每个维度成员一个实体，每个指标一根轴。

字段	类型	必填	中文名	说明
type	'radar'	是	类型
nameField	string	是	名称维度	实体名：维度 id。
indicators	readonly RadarIndicatorSpec[]	是	指标
shape	'polygon' | 'circle'	可省	形状
area	boolean	可省	面积
scale	'shared' | 'independent'	可省	刻度
curve	'linear' | 'catmull-rom'	可省	曲线
rings	number	可省	环数
ringLabels	boolean	可省	环标签
format	NumericFormatSpec	可省	格式

SankeyChartSpec {#sankeychartspec}

桑基图：每个维度组合一条流带。

字段	类型	必填	中文名	说明
type	'sankey'	是	类型
sourceField	string	是	源维度	源节点：维度 id。
targetField	string	是	目标维度	目标节点：维度 id。
valueField	string	是	数值度量	流量：度量 id。
orientation	'horizontal' | 'vertical'	可省	方向
nodeAlign	'justify' | 'start' | 'end' | 'center'	可省	节点对齐
linkColor	'neutral' | 'source' | 'target' | 'gradient'	可省	连线颜色
nodeSort	'auto' | 'input'	可省	节点排序
format	NumericFormatSpec	可省	格式

HeatmapChartSpecBase {#heatmapchartspecbase}

热力图共有的属性。

字段	类型	必填	中文名	说明
type	'heatmap'	是	类型
valueField	string	是	数值度量	数值：度量 id。
levels	number	可省	层级
thresholds	readonly number[]	可省	分档阈值
scale	'sequential' | 'diverging'	可省	刻度
midpoint	number	可省	中点
continuous	boolean	可省	连续色阶
tone	ChartTone	可省	语气
palette	ChartPalette	可省	色板
size	ChartSize	可省	尺寸

HeatmapDateChartSpec {#heatmapdatechartspec}

日期热力图：calendar 连续周列，month 按自然月分块。

继承 HeatmapChartSpecBase 的字段。

字段	类型	必填	中文名	说明
variant	'calendar' | 'month'	是	形态
dateField	string	是	日期维度	日期：维度 id，键为 YYYY-MM-DD。
startDate	string	可省	开始日期	区间起点（含），YYYY-MM-DD；不写取数据里最早的日期。
endDate	string	可省	结束日期	区间终点（含），YYYY-MM-DD；不写取数据里最晚的日期。
firstDayOfWeek	number	可省	每周第一天	周首日，0 = 星期日。

HeatmapMatrixChartSpec {#heatmapmatrixchartspec}

矩阵热力图：行列各是一个维度。

继承 HeatmapChartSpecBase 的字段。

字段	类型	必填	中文名	说明
variant	'matrix'	是	形态
rowField	string	是	行维度	行：维度 id。
columnField	string	是	列维度	列：维度 id。

HeatmapChartSpec {#heatmapchartspec}

热力图：日历（含按月）或矩阵。

取其一：HeatmapDateChartSpec、HeatmapMatrixChartSpec。

HierarchyChartSpec {#hierarchychartspec}

层级图：维度依次是由上到下的层。

字段	类型	必填	中文名	说明
type	'hierarchy'	是	类型
levels	readonly string[]	是	层级	各层：维度 id，由上到下。
valueField	string	是	数值度量	数值：度量 id。
layout	'treemap' | 'sunburst' | 'icicle' | 'pack'	可省	布局
tile	'squarify' | 'binary' | 'slice-dice'	可省	切分方式
depth	number	可省	展开层数
colorBy	'branch' | 'value' | 'uniform'	可省	着色依据
palette	ChartPalette	可省	色板
orientation	'vertical' | 'horizontal'	可省	方向
format	NumericFormatSpec	可省	格式

ChartSpec {#chartspec}

图表配置，按 type 分。

取其一：CartesianChartSpec、PieChartSpec、FunnelChartSpec、RadarChartSpec、SankeyChartSpec、HeatmapChartSpec、HierarchyChartSpec。

SparklineSpec {#sparklinespec}

迷你图：指标卡片里的走势。

字段	类型	必填	中文名	说明
x	string	是	横坐标	横坐标：维度 id。
y	string	是	纵坐标	数值：度量 id。
variant	'line' | 'area' | 'bar' | 'win-loss'	可省	形态
curve	'linear' | 'monotone'	可省	曲线
markers	'none' | 'last' | 'extremes'	可省	—	标出哪些点：不标、末点或最高最低点。
band	readonly [number, number]	可省	—	参考带 [下界, 上界]。
reference	number | 'mean' | 'median'	可省	—	参考线：固定值，或按数据算出的均值 / 中位数。
tone	ChartTone	可省	语气

MetricSpec {#metricspec}

指标卡片：一个汇总值，可带对比与走势。

字段	类型	必填	中文名	说明
value	string	是	数值	显示的值：度量 id，取查询的总计。
baseline	string	可省	基准值	对比基准：度量 id，取查询的总计；与 value 比出涨跌。
prefix	string	可省	前缀
suffix	string	可省	后缀
format	NumericFormatSpec	可省	格式
size	ChartSize	可省	尺寸
tone	ChartTone	可省	语气
sparkline	SparklineSpec	可省	—	迷你图；不写不画。

取值

ScalarValue {#scalarvalue}

JSON 标量：模板里能写下的单个值。

类型：JsonPrimitive

JsonValue {#jsonvalue}

转导出自 @xihan-ui/core/json。

DataRow {#datarow}

一行数据：字段名到值。core 只读不写。

类型：Readonly<Record<string, unknown>>

ParameterValue {#parametervalue}

参数的取值：单值，或多选参数的值数组。

类型：ScalarValue | readonly ScalarValue[]

ParameterValues {#parametervalues}

一组参数取值：参数名到值。

类型：Readonly<Record<string, ParameterValue>>

FieldType {#fieldtype}

字段类型。date 是日期（YYYY-MM-DD），datetime 是日期时间；两者的值可以是 ISO 8601 字符串、毫秒时间戳或 Date。

取值见常量 FIELD_TYPES：

取值	中文名
string	文本
number	数值
boolean	布尔
date	日期
datetime	日期时间

值格式

DateFormatSpec {#dateformatspec}

转导出自 @xihan-ui/expression。

FormatRounding {#formatrounding}

转导出自 @xihan-ui/expression。

FormatSpec {#formatspec}

转导出自 @xihan-ui/expression。

NumberFormatSpec {#numberformatspec}

转导出自 @xihan-ui/expression。

PercentFormatSpec {#percentformatspec}

转导出自 @xihan-ui/expression。

RmbUpperFormatSpec {#rmbupperformatspec}

转导出自 @xihan-ui/expression。

NumericFormatSpec {#numericformatspec}

图表数值用的格式说明：数字或百分比。

取其一：NumberFormatSpec、PercentFormatSpec。

扩展数据

ReportExtensionKind {#reportextensionkind}

扩展登记的卡片与视图种类名：扩展 id 的末段、一个点、名字，如 gantt.timeline。内置种类不带点。

类型：${string}.${string}

ReportExtensionData {#reportextensiondata}

对象上各扩展自己的数据：键是扩展 id，值归那个扩展；校验只查它与每一块都是对象，里面不看。

类型：Readonly<Record<string, JsonObject>>

ReportExtensible {#reportextensible}

能带扩展数据的对象：文档、数据集、字段、参数、视图、卡片、各列表项与联动。

字段	类型	必填	中文名	说明
extensions	ReportExtensionData	可省	—	各扩展自己的数据：键是扩展 id，值是 JSON 对象；编辑与剪贴板原样带过去。