XCharts 版本演进全解析:从 v0.1.0 到 master 的功能地图与升级指南

原创2026-10-13 09:36:50227 阅读
文章标签:图表库数据可视化UI组件游戏开发

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)是功能分水岭:

  • 新增 Line3DChart 3D 折线图、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 甘特图、CandlestickChart K线图(#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(minZoomRatio L360、filterAxisRange L333、onStartEndChanged L426)
  • DataZoom 窗口计算与缩放逻辑:DataZoomHandler.cs(L498-L531)
  • Label 显隐控制与固定坐标:LabelStyle.cs(fixedX/fixedY L347-L359、showCondition/showFilter/showThreshold L367-L401)
  • Axis 主轴、点击回调与类目间距:Axis.cs(onLabelClick L125、mainAxis L308、minCategorySpacing L433)
  • 数据批量加载:Serie.cs(LoadData,批量创建 SerieData 并统一标记脏数据,适合大数据量初始化)
  • 图表级 API:BaseChart.API.cs(TriggerTooltip L717、ResetChartStatus L769)

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 家族)。对于开发者而言,更新日志不仅是"看版本号",更是一份配置参数迁移地图——结合本文给出的源码行号,你可以快速在新版本代码库中定位任何参数的实现与行为,从而在升级与二次开发中少走弯路。

登录后查看全文
XCharts