XCharts 版本演进全解析:从 v0.1.0 到 master 的功能地图与升级指南
XCharts 版本演进全解析:从 v0.1.0 到 master 的功能地图与升级指南
本文以 XCharts 官方更新日志为主体脉络,系统梳理 Unity 数据可视化图表插件 XCharts 自 2018 年首个版本至今的功能演进、核心模块能力与破坏性变更,并结合仓库源码定位关键参数与接口的真实实现位置。读完本文,你将能:快速了解 XCharts 各版本的能力边界、读懂
DataZoom/LabelStyle/Axis等高频配置参数的设计意图、在升级时避开float → double、minShowNum → minZoomRatio等迁移坑,并知道去哪一行源码查找对应实现。
XCharts 是一套面向 Unity 的数据可视化图表插件,覆盖 LineChart、BarChart、PieChart、RadarChart、ScatterChart、HeatmapChart、PolarChart、CandlestickChart 等内置图表,以及 UITable、UIText、UIToggle、UISlider、UIStatistic 等扩展 UI 组件。其版本史本身就是一份"配置参数与 API 演进"的活教材。
一、版本脉络总览:读懂更新日志的结构
Documentation~/zh/changelog.md 按时间倒序记录了所有已发布版本,从最早的 v0.1.0(2018.09.05)一直延伸到当前 master 分支(2026.07 仍在持续更新)。目录锚点依次覆盖:
master(开发分支)- 3.x 系列:
v3.0.0至v3.15.0(含 9 个 preview 版本) - 2.x 系列:
v2.0.0至v2.8.1 - 1.x 系列:
v1.0.0至v1.6.3 - 早期版本:
v0.1.0、v0.5.0、v0.8.0至v0.8.3
注意:
v2.8.2同时存在于中英文日志中,但 zh 版目录锚点未列出它,正文中保留有对应条目。
从 v3.0.0 开始,日志为每个版本增加了"版本要点(Highlights)"与"日志详情(Details)"分层结构;部分版本还带有"升级注意"(如 v3.5.0 文档目录调整、v2.3.0 数据类型升级)。读懂这些分层,可以快速定位"这个版本我该关注什么"。
二、master 开发分支:近期能力速览(2026)
master 分支记录了尚未打 tag 的最新进展,重点集中在数据交互回调、时间轴/DataZoom 优化与 Chart JSON 序列化:
| 能力方向 | 变更内容 | 源码佐证 |
|---|---|---|
| 数据生命周期 | 新增 Serie.LoadData() 批量加载接口;修复 ClearData 后 Legend 显示异常 (#366) |
Serie.cs |
| 交互回调 | DataZoom.onStartEndChanged、Tooltip.onActive / onPosition 回调 |
DataZoom.cs、Tooltip.cs |
| 坐标轴范围 | DataZoom.filterAxisRange 控制轴范围是否受缩放窗口影响;优化 Axis 自动分割策略 |
DataZoom.cs、AxisContext.cs |
| 标签控制 | LabelStyle 新增 showCondition、showFilter、showThreshold、minGap 控制标签显隐与防密集 |
LabelStyle.cs |
| 布局能力 | Legend.width / height 固定宽高;Chart 支持 JSON 导出导入 |
Legend.cs |
| 扩展组件 | UITable 排序、万级数据量优化;Sankey 线条 tooltip 触发 |
— |
2.1 LabelStyle 标签显隐三件套
showCondition(值条件:Always / GreaterThan / LessThan)、showFilter(数据形态:All / Peak / Valley,仅在局部波峰/波谷显示)、showThreshold(阈值,默认 0)三者配合,可实现"只有满足阈值的数据点才显示标签"或"只在波峰波谷显示标签"的精细控制;minGap(源码中为 showMinGap,默认 0 关闭)则会在与上一个标签距离过近时隐藏 y 值较小的标签,避免密集数据下标签互相覆盖。
2.2 DataZoom 回调与范围过滤
onStartEndChanged 回调在拖动、滚轮缩放、双指缩放改变窗口范围时触发(见 DataZoomHandler.cs 的调用链);filterAxisRange 决定坐标轴最大最小值是否随缩放窗口变化——为 true 时轴刻度适配当前窗口,为 false 时轴始终显示全量数据范围,适合需要固定坐标尺度的场景。
三、v3.15.0:时间轴、柱图朝向与样式交互的集中升级
v3.15.0 是本仓库 3.x 系列的最新正式版(2026.03.01 发布),版本要点与日志详情给出了完整的配置项清单:
3.1 时间轴与缩放
DataZoom.minZoomRatio:新增的最小缩放比例(范围 0f-1f),替代旧的minShowNum。源码中旧参数已被标记为<a href="https://link.gitcode.com/i/27eaf04931cf07acf9e85d1497771333" target="_blank">Obsolete("Use \"minZoomRatio\" instead", true)]([DataZoom.cs),新参数的含义是"缩放区域组件的最小缩放比例",当窗口范围小于minZoomRatio × 网格宽高时阻止继续缩小(DataZoomHandler.cs)。Chart.useUtc:控制时间轴显示时间是否使用 UTC。在 AxisHandler.cs 等处,GetLabelName与GetFormatterDateTime均以!chart.useUtc决定是否做本地时区转换。- 修复
Axis Time时间轴在大年份(>2038)与DataZoom缩放下的显示异常,优化Candlestick对时间轴的支持。
3.2 柱图与坐标轴
Axis.mainAxis:设置主轴,控制柱图朝向(X 主轴 = 垂直柱,Y 主轴 = 水平柱)。BaseChart.Component.cs通过axis.show && axis.mainAxis查找主轴(BaseChart.Component.cs)。Serie.ignoreZeroOccupy:设置 0 数据的 Bar 是否占位(#286),对应BarHandler.cs中柱条宽度与高度的计算分支(BarHandler.cs)。AxisLine.startExtendLength/endExtendLength:设置轴线首尾的延长线长度(AxisLine.cs)。AxisLabel.showZeroLabel:设置是否显示 0 刻度;Axis.onLabelClick提供刻度标签点击回调(Axis.cs,回调在 AxisHandler.cs 中触发)。
3.3 样式与交互
Pie.pieType:支持实心饼图与线框柄图(#349)。Legend.itemInactiveOpacity:非激活状态(图例点击隐藏后)的颜色透明度(#343,Legend.cs)。Animation.Exchange:排序交换动画;LabelStyle.fixedX/fixedY固定 label 坐标(LabelStyle.cs)。Serie.Label.formatter支持{index}通配符;ItemStyle.backgroundGap设置数据项背景间隙(ItemStyle.cs)。Comment.layer层级设置、UITable的Title/Viewport、UIStatistic.desc描述文本等扩展组件增强。
四、v3.14.0 ~ v3.11.0:动画、排序与 3D 坐标系的演进
4.1 v3.14.0(2025.03.15)
Bar.realtimeSort:实时排序功能,对应 Bar.cs 中useSortData => realtimeSort的排序开关。Animation.speed:指定动画速度。Tooltip.itemFormatter支持\n换行、columnGapWidths设置列文本间隙。Axis.Label.formatter支持{index}、{index-1}、{-index}、{-index-1}通配符({-index}表示从最后一个数据项倒数的 index)。- 修复
SaveAsImage保存图片不支持透明度的问题(#337)。
4.2 v3.13.0(2025.01.01)
扩展 UI 组件家族成型:新增 UIText、UIToggle、UISlider,重构 UIProgress。SymbolStyle 新增 borderWidth、emptyColor 与 size2(长方形标记);Tooltip.itemFormatter 支持 {f0};删除 TextStyle 无用配置项 tmpAlignment。
4.3 v3.12.x:数值格式化的日期时间化
v3.12.0(2024.09.30)新增 Ring.radiusGradient 渐变方向、AreaStyle.origin 区域填充起始位置,以及 numericFormatter 对 date/time 的支持——日期时间类数据可直接通过数值格式化串输出。v3.12.1 侧重折线图数据密集时的绘制优化与 Unity6 代码警告清理。
4.4 v3.11.x:3D 与关系图的引入
v3.11.0(2024.06.16)是功能分水岭:
- 新增
Line3DChart3D 折线图、GraphChart关系图,新增 3D 坐标系支持(含类目轴)。 Tooltip.triggerOn设置触发条件;Tooltip的Corss重命名为Cross。Axis.minCategorySpacing设置类目轴默认最小类目间距(Axis.cs)。- 修复
Tooltip每帧产生 GC 的问题(#311,由 @stefanbursuc 贡献)。
4.5 时间轴细节优化
v3.11.2 集中优化 Axis 为 Time 时间轴时的分割、移动与 Tooltip 默认效果,修复微信小游戏平台的 Tooltip 兼容问题(#326)。
五、v3.10.x ~ v3.6.0:双类目轴、桑基图与交互回调的丰富
5.1 v3.10.0(2024.02.01)
- 双类目轴支持:
Bar、Line均支持 X 轴和 Y 轴同时为Category类目轴;新增{y}通配符获取 Y 轴类目名。 - 快捷创建图表菜单:一键创建几十种图表;
Background组件支持圆角和边框(borderStyle)。 - 新增
SankeyChart桑基图(配合Serie.Link添加节点边关系)、UIImage图片组件、BorderStyle边框样式。 - 新增
ResetChartStatus()主动重置图表状态、Serie.minShowLabel隐藏小于指定值的 label。 Legend新增TextLimit限制图例文本长度。
5.2 v3.9.0(2023.12.01)
Axis新增Animation支持数据变更动画;对数轴支持子刻度(MinorTick)。MarkLine.onTop控制是否显示在最上层;SerieData可单独添加Label。UITable获得轮播功能(CarouselStyle)、数据操作接口(GetData()、GetContent()、AddColumn()、UpdateColumn())、RefreshTable()与onTableClick回调;RowStyle/ColumnStyle/SeparatorStyle重构。- 取消
Legend的formatter,统一由LabelStyle提供。
5.3 v3.8.x:动画系统重构与符号扩展
v3.8.0(2023.09.03)重构了 Animation 动画系统,新增 Addition(新增动画)与 Interaction(交互动画)配置;Symbol 新增 EmptyTriangle、EmptyDiamond、Plus、Minus 四种标记;LabelLine.lineEndX 可固定引导线 X 位置;新增 GridLayout 网格布局组件管理多个 GridCoord;Tooltip 新增 Auto 类型自动设置显示/触发类型。v3.8.1 增加 Pie.radiusGradient 半径方向渐变与 Line 平滑曲线的 Dash 虚线支持。
5.4 v3.7.0 ~ v3.6.0
- v3.7.0:
Axis.MinMaxAuto范围类型、Line的Clip支持、HelpDoc帮助文档跳转、BaseChart.TriggerTooltip()接口(BaseChart.API.cs)。 - v3.6.0:新增
InputSystem支持(by @Bian-Sh)、VR等其他非鼠标输入方式的 Point 位置获取(by @Ambitroc)、UITable/UIStatistic等扩展 UI 组件、ItemStyle.MarkColor、通配符{h}(显示当前颜色值)。新增onSerieClick、onSerieDown、onSerieEnter、onSerieExit回调;DataZoom.startLock/endLock支持锁定边界;AreaStyle.toTop控制渐变是到顶部还是实际位置。升级注意:部分 API 有调整,需按编译提示更换接口。
六、v3.5.0 ~ v3.0.0:3.x 时代的框架奠基
6.1 v3.5.0(2022.12.01)
DataZoom 框选支持(MarqueeStyle)、Bar 最大宽度 barMaxWidth、Pie.LabelLine 支持 Symbol。升级注意:文档目录结构调整,升级前建议先备份、删除原 XCharts 再升级。
6.2 v3.4.0 ~ v3.3.0
- v3.4.0:
Axis.indicatorLabel(单独指示文本样式,移除Tooltip.indicatorLabelStyle,#226)、Serie.markColor标识颜色(#229)、RadarCoord.startAngle、DataZoom对数值轴的支持、Line.SmoothLimit、Animation.UnscaledTime(是否受 TimeScale 影响,#223)。 - v3.3.0:新增
HeatmapChart热力图(heatmapType支持Data/Count两种映射、symbol自定义图案)、PolarChart对Bar/Heatmap的支持、SaveAsImage()接口、SerieSymbol.minSize/maxSize、AxisSplitLine.showStartLine/showEndLine、formatter对{d3}维度百分比的支持。
6.3 v3.2.0:三态交互与次刻度
Serie支持高亮、淡出、选中三态配置:EmphasisStyle、BlurStyle、SelectStyle(移除旧的Emphasis、EmphasisItemStyle等组件,去掉AreaStyle.highlightColor/highlightToColor)。Axis支持MinorTick次刻度与MinorSplitLine次分割线。Serie.colorBy取色策略、Radar.smooth平滑曲线、AreaStyle.innerFill凸多边形填充、DataZoom对时间轴的支持。
6.4 v3.1.0 ~ v3.0.1
v3.1.0 增加 Settings.axisMaxSplitNumber 轴最大分隔段数、AxisName.onZero(#207)、Tooltip.itemFormatter 的 {c0} 维度显示(#205)、Since 特性(用于标识配置参数从哪个版本开始支持)、Painter 绘制层细分(Top 细分为 Upper 和 Top)、TextStyle 对 TMP Sprite Asset 的支持。
v3.0.0 是 3.x 的开山版本,官方总结为"更健壮的底层框架、更强大的性能、更小的序列化文件、更灵活的组件插拔、更高效的二次开发",新增 Time 时间轴、SingleAxis 单轴、Comment 文本组件、Widgets 小组件、多种坐标系(Grid/Polar/Radar/SingleAxis)、多种动画方式、国际化支持与多种扩展图表。随后 9 个 preview 版本依次补齐 Bar 的 clip(#196)、Line 的 Dash/Dot(#197)、Label.rotate 旋转、Line.EndLabel、VisualMap.workOnLine/workOnArea(#191)、Liquid 圆角矩形水位图、ItemStyle.BorderGap 等能力。
七、v2.x:从工具库到成熟插件的过渡
7.1 v2.8.x ~ v2.6.0
- v2.8.0:新增
Debug调试信息面板。 - v2.8.1:
Legend.onLegendClick、onLegendEnter、onLegendExit委托回调。 - v2.7.0:
chartName重复检测(#183)、Zebra斑马柱图优化。 - v2.6.0:
Symbol新增EmptyRect、EmptyTriangle、EmptyDiamond;Radar的AxisLine/SplitLine可单独控制;Formatter.{c}通配符修复(#175)。
7.2 v2.5.0 ~ v2.3.0:float 到 double 的关键升级
- v2.5.0:
Tooltip.positionFunction位置委托、{e}通配符(#170)。 - v2.4.0:
Serie.ignoreLineBreak(忽略数据连线断开/连接,#164)、Animation.alongWithLinePath轨迹匀速动画、Legend.textAutoColor(#163)。 - v2.3.0(重点升级版本):
- 数据存储由
float全面升级为double。升级注意明确指出:由于float隐式转double可能有精度问题,建议此前为float的数据类型手动改为double。这一变更在后续所有版本中持续生效,也是自定义代码迁移时最需要注意的破坏性变更。 - 新增
MarkLine标线(#142)、Serie.iconStyle统一配置图标、DataZoom.supportInsideScroll/supportInsideDrag/orient、AxisLabel.showStartLabel/showEndLabel、AxisLabel/SerieLabel的formatter委托(#145)。
- 数据存储由
7.3 v2.2.x ~ v2.0.0
- v2.2.x:
TextStyle的alignment/autoWrap/autoAlign、Axis.iconStyle与icons、Serie/Axis的insertDataToHead、GanttChart抽离为扩展模块、VisualMap的Piecewise分段配色、LiquidChart方形水位图、Settings.reversePainter。 - v2.1.0:
Theme重构(#118)、GanttChart甘特图、CandlestickChartK线图(#124)、PieChart.minAngle最小扇区角度(#117)、自定义绘制回调onCustomDrawBeforeSerie/onCustomDrawAfterSerie/onCustomDrawTop、DataZoom数值轴支持(#71)。 - v2.0.0:
AxisLine.OnZero修复(#116)、Category轴在BoundaryGap与AlignWithLabel组合下的刻度修复(#115)。
八、v1.x 与 v0.x:早期能力的诞生地
1.x 时代奠定了绝大多数核心组件的形态:
- v1.6.3:修复
Animation不启用时更新数据导致图表一直刷新的问题。 - v1.6.1:
Remove All Chart Object一键移除子节点;LineStyle.toColor/toColor2水平渐变;PieChart.onPointerClickPie、BarChart.onPointerClickBar点击回调。 - v1.6.0:将绘制相关的
Color改为Color32以减少隐式转换(官方提示自定义颜色可能丢失,可参考问答 29 升级);新增LiquidChart水位图、PolarChart极坐标图表、SerieAnimation动画完成回调。 - v1.5.x:
Background背景组件、chartName别名(XChartMgr.Instance.GetChart(chartName)获取)、Serie.large/largeThreshold性能模式、numericFormatter数值格式化(去掉forceENotation)、Convert XY Axis互换 XY 轴、Axis.inverse坐标轴反转、Axis.ceilRate取整倍率、Serie.avoidLabelOverlap防标签堆叠(#56)、Tooltip.alwayShow。 - v1.4.0:
Check warning检测、ItemStyle.cornerRadius圆角柱图/圆角矩形、BarChart.barType胶囊柱状图、Serie.radarType多圈/单圈雷达图。 - v1.3.0:
RingChart环形图、Serie.clip裁剪、TextLimit文本自适应、Radar.splitLine。 - v1.2.0:对数轴
Log支持、AxisLabel整数格式化({value:f0})、DataZoom.minShowNum(最小显示数据个数——注意它正是后来被minZoomRatio取代的参数)。 - v1.1.0:
GaugeChart仪表盘、数据更新动画serie.animation.dataChangeEnable、圆环圆角arcShaped。 - v1.0.x:版本检测(
Component -> XCharts -> Check For Update)、Package Manager 安装支持、Bar的barType斑马柱状图与barPercentStack百分比堆叠、RadarChart/ScatterChart/HeatmapChart/VisualMap/Settings等组件陆续诞生、Hierarchy右键快捷创建图表(XCharts->LineChart)。
0.x 时代则是原型期:v0.1.0(2018.09.05)发布,v0.5.0 增加 DataZoom 区域缩放、stepType 阶梯线、InSameBar 非堆叠同柱、crossLabel 十字准星、AxisMinMaxType;v0.8.x 增加 ScatterChart、EffectScatter、南丁格尔玫瑰图(Radius/Area)、SerieLabel 饼图标签、多饼图/多雷达图支持,并开始提供代码 API 注释文档。
九、面向开发者的升级清单与源码定位
9.1 破坏性变更一览
| 版本 | 变更 | 迁移提示 |
|---|---|---|
| v2.3.0 | 数据存储 float → double |
自定义代码中的 float 数据手动改为 double |
| v1.6.0 | 绘制相关 Color → Color32 |
自定义颜色可能丢失,参考官方 FAQ 升级 |
| v3.5.0 | 文档目录结构调整 | 升级前备份并删除原 XCharts |
| v3.15.0 | DataZoom.minShowNum → minZoomRatio |
旧参数已标记 <a href="https://link.gitcode.com/i/949971ad8b20e7edad9ec431111fc850" target="_blank">Obsolete],按编译提示替换([DataZoom.cs) |
| v3.9.0 | Legend.formatter 取消 |
改用 LabelStyle.formatter |
| v3.2.0 | Emphasis 系列组件移除 |
改用 EmphasisStyle/BlurStyle/SelectStyle |
| v3.4.0 | Tooltip.indicatorLabelStyle 移除 |
改用 Axis.indicatorLabel |
9.2 常用源码入口
- DataZoom 参数与回调:DataZoom.cs(
minZoomRatioL360、filterAxisRangeL333、onStartEndChangedL426) - DataZoom 窗口计算与缩放逻辑:DataZoomHandler.cs(L498-L531)
- Label 显隐控制与固定坐标:LabelStyle.cs(
fixedX/fixedYL347-L359、showCondition/showFilter/showThresholdL367-L401) - Axis 主轴、点击回调与类目间距:Axis.cs(
onLabelClickL125、mainAxisL308、minCategorySpacingL433) - 数据批量加载:Serie.cs(
LoadData,批量创建 SerieData 并统一标记脏数据,适合大数据量初始化) - 图表级 API:BaseChart.API.cs(
TriggerTooltipL717、ResetChartStatusL769)
9.3 如何阅读本文之外的更多细节
- 完整的中英文对照更新日志:中文版 与 英文版。
- 配置项逐参数手册:configuration.md;API 接口说明:api.md。
- 从零创建第一个图表的实操:tutorial01.md;常见问题: faq.md。
- 代码示例:
Examples目录下的Example00_CheatSheet.cs、Example10_LineChart.cs、Example20_BarChart.cs、Example30_PieChart.cs等覆盖了主要图表类型的代码动态创建方式。
十、结语
从 2018 年的 v0.1.0 到 2026 年的 master,XCharts 的版本演进清晰地呈现出一条主线:底层框架持续重构(float→double、Color→Color32、组件化/Handler 化),交互与动画能力不断丰富(三态样式、交互动画、实时排序、框选缩放),图表类型与坐标系持续扩展(3D、关系图、桑基图、双类目轴),扩展 UI 组件从无到有(UITable 家族)。对于开发者而言,更新日志不仅是"看版本号",更是一份配置参数迁移地图——结合本文给出的源码行号,你可以快速在新版本代码库中定位任何参数的实现与行为,从而在升级与二次开发中少走弯路。