更新文档

2026-05-28 12:08:46 +00:00 · 2024-10-28 22:25:14 +08:00
parent dc254fb722
commit 143a037761
11 changed files with 219 additions and 192 deletions
--- a/Documentation~/zh/api.md
+++ b/Documentation~/zh/api.md
@@ -2347,7 +2347,7 @@ public void UpdateYAxisIcon(int index, Sprite icon, int yAxisIndex = 0)

 ## BaseGraph

-class in XCharts.Runtime / 继承自: [MaskableGraphic](https://docs.unity3d.com/ScriptReference/30_search.html?q=maskablegraphic),[IPointerDownHandler](https://docs.unity3d.com/ScriptReference/30_search.html?q=ipointerdownhandler),[IPointerUpHandler](https://docs.unity3d.com/ScriptReference/30_search.html?q=ipointeruphandler),[](#) / 子类: [BaseChart](#basechart),[UIComponent](#uicomponent) 
+class in XCharts.Runtime / 继承自: [MaskableGraphic](https://docs.unity3d.com/ScriptReference/30_search.html?q=maskablegraphic),[IPointerDownHandler](https://docs.unity3d.com/ScriptReference/30_search.html?q=ipointerdownhandler),[IPointerUpHandler](https://docs.unity3d.com/ScriptReference/30_search.html?q=ipointeruphandler), / 子类: [BaseChart](#basechart),[UIComponent](#uicomponent) 

 ### BaseGraph.chartHideFlags

@@ -5858,7 +5858,7 @@ class in  / 子类: [XLog](#xlog)

 ## ObjectPool&lt;T&gt; where T

-class in XCharts.Runtime / 继承自: [new()](#new())
+class in XCharts.Runtime / 继承自: new()

 ### ObjectPool&lt;T&gt; where T.countActive

--- a/Documentation~/zh/faq.md
+++ b/Documentation~/zh/faq.md
@@ -5,162 +5,123 @@ slug: /faq

 # 常见问题

-[FAQ 1：如何调整坐标轴与背景的边距？](#如何调整坐标轴与背景的边距)  
-[FAQ 2：如何让初始动画重新播放？](#如何让初始动画重新播放)  
-[FAQ 3：如何自定义折线图饼图的颜色？](#如何自定义折线图饼图的颜色)  
-[FAQ 4：如何给坐标轴上的文本加上单位？](#如何给坐标轴上的文本加上单位)  
-[FAQ 5：如何让柱形图的柱子堆叠显示？](#如何让柱形图的柱子堆叠显示)  
-[FAQ 6：如何让柱形图的柱子同柱但不重叠？](#如何让柱形图的柱子同柱但不重叠)  
-[FAQ 7：如何调整柱形图的柱子宽度和间距？](#如何调整柱形图的柱子宽度和间距)  
-[FAQ 8：如何调整柱形图单个柱子的颜色？](#如何调整柱形图单个柱子的颜色)  
-[FAQ 9：如何调整图表的对齐方式？](#如何调整图表的对齐方式)  
-[FAQ 10：可以显示超过1000以上的大数据吗？](#可以显示超过1000以上的大数据吗)  
-[FAQ 11：折线图可以画虚线、点线、点划线吗？](#折线图可以画虚线点线点划线吗)  
-[FAQ 12：如何限定Y轴的值范围？](#如何限定y轴的值范围)  
-[FAQ 13：如何自定义数值轴刻度大小？](#如何自定义数值轴刻度大小)  
-[FAQ 14：如何在数据项顶上显示文本？](#如何在数据项顶上显示文本)  
-[FAQ 15：如何给数据项自定义图标？](#如何给数据项自定义图标)  
-[FAQ 16：锯齿太严重，如何让图表更顺滑？](#锯齿太严重如何让图表更顺滑)  
-[FAQ 17：为什么鼠标移上图表Tooltip不显示？](#为什么鼠标移上图表tooltip不显示)  
-[FAQ 18：如何取消Tooltip的竖线？](#如何取消tooltip的竖线)  
-[FAQ 19：如何自定义Tooltip的显示内容？](#如何自定义tooltip的显示内容)  
-[FAQ 20：如何让y轴显示多位小数？](#如何让y轴显示多位小数)  
-[FAQ 21：如何用代码动态更新数据？](#如何用代码动态更新数据)  
-[FAQ 22：如何显示图例？为什么有时候图例无法显示？](#如何显示图例为什么有时候图例无法显示)  
-[FAQ 23：如何做成预设？](#如何做成预设)  
-[FAQ 24：如何在图表上画点画线等自定义内容？](#如何在图表上画点画线等自定义内容)  
-[FAQ 25：如何实现心电图类似的数据移动效果？](#如何实现心电图类似的数据移动效果)  
-[FAQ 26：如何使用背景组件？有什么条件限制？](#如何使用背景组件有什么条件限制)  
-[FAQ 27：Mesh can not have more than 65000 vertices？](#mesh_cannot_have_more_than_65000_vertices)  
-[FAQ 28：为什么serie里设置的参数运行后又被重置了?](#为什么serie里设置的参数运行后又被重置了)  
-[FAQ 29：如何修改serie的symbol的颜色?](#如何修改serie的symbol的颜色)  
-[FAQ 30：导入或更新XCharts时TMP报错如何处理？](#导入或更新xcharts时tmp报错怎么办)  
-[FAQ 31：支持空数据吗？如何实现折线图断开的效果?](#支持空数据吗如何实现折线图断开的效果)  
-[FAQ 32：2.x版本升级3.x版本时常见的问题有哪些？](#xcharts2升级xcharts3时常见的问题有哪些)  
-[FAQ 33：折线图如何两边不留空白而从0坐标开始显示？](#折线图如何两边不留空白而从0坐标开始显示)  
-[FAQ 34：如何设置部分Serie不显示Tooltip？](#如何设置部分serie不显示tooltip)  
-
-## 如何调整坐标轴与背景的边距
+## FAQ 1：如何调整坐标轴与背景的边距？

 调整`Grid`组件，可调整上下左右边距。

-## 如何让初始动画重新播放
+## FAQ 2：如何让初始动画重新播放？

 调用`chart.AnimationReset()`接口。

-## 如何自定义折线图饼图的颜色
+## FAQ 3：如何自定义折线图饼图的颜色？

 通过`Theme`的`colorPalette`调整，或者部分`Serie`下的`LineStyle`和`ItemStyle`。

-## 如何给坐标轴上的文本加上单位
+## FAQ 4：如何给坐标轴上的文本加上单位？

 通过`formatter`和`numericFormatter`参数，在`Legend`、`Axis`的`AxisLabel`、`Tooltop`、`Serie`的`Label`都提供该参数的配置。

-## 如何让柱形图的柱子堆叠显示
+## FAQ 5：如何让柱形图的柱子堆叠显示？

 设置`Serie`下的`stack`，`stack`相同的`serie`会堆叠显示在一个柱子上。

-## 如何让柱形图的柱子同柱但不重叠
+## FAQ 6：如何让柱形图的柱子同柱但不重叠？

 设置`Serie`下的`barGap`为`-1`，`stack`为空。

-## 如何调整柱形图的柱子宽度和间距
+## FAQ 7：如何调整柱形图的柱子宽度和间距？

 调整`Serie`下的`barWidth`和`barGap`，多个`serie`时最后一个`serie`的`barWidth`和`barGap`有效。

-## 如何调整柱形图单个柱子的颜色
+## FAQ 8：如何调整柱形图单个柱子的颜色？

 可通过调整单个`Data`下的`ItemStyle`调整，也可以通过两个`serie`同柱不堆叠来实现，通过设置数据项为`0`来达到类似效果。

-## 如何调整图表的对齐方式
+## FAQ 9：如何调整图表的对齐方式？

 调整RectTransform的锚点，和UGUI的其他组件的用法一致。

-## 可以显示超过1000以上的大数据吗
+## FAQ 10：可以显示超过1000以上的大数据吗？

 可以。但`UGUI`对单个`Graphic`限制`65000`个顶点，所以太多的数据不一定能显示完全。可通过设置采样距离`sampleDist`开启采样简化过密曲线。也可以通过设置一些参数来减少图表的顶点数有助于显示更多数据。如缩小图表的尺寸，关闭或减少坐标轴的客户端绘制，关闭`Serie`的`symbol`和`label`显示等。折线图的普通线图`Normal`比平滑线图`Smooth`占用顶点数更少。`1.5.0`以上版本可以设置`large`和`largeThreshold`参数来开启性能模式。

-## 折线图可以画虚线点线点划线吗
+## FAQ 11：折线图可以画虚线、点线、点划线吗？

 可以。通过`Serie`下的`lineType`选择线条样式。当要显示的数据过多（成千以上）数据间过密时建议使用`Normal`或者`Step`样式。

-## 如何限定y轴的值范围
+## FAQ 12：如何限定Y轴的值范围？

 设置`Axis`下的`minMaxType`为`Custom`，自定义`min`和`max`。

-## 如何自定义数值轴刻度大小
+## FAQ 13：如何自定义数值轴刻度大小？

 默认时通过`Axis`下的`splitNumer`进行自动划分。也可以设置`interval`自定义刻度大小。

-## 如何在数据项顶上显示文本
+## FAQ 14：如何在数据项顶上显示文本？

 通过设置`Serie`下的`Label`。3.0版本需要先添加`LabelStyle`组件。

-## 如何给数据项自定义图标
+## FAQ 15：如何给数据项自定义图标？

 通过设置`Serie`的`data`下的数据项可单独设置`icon`相关参数。

-## 锯齿太严重如何让图表更顺滑
+## FAQ 16：锯齿太严重，如何让图表更顺滑？

 开启抗锯齿设置（在`Unity`里设置）。调整UI渲染模式为`Camera`模式，开启`MSAA`，设置`4`倍或更高抗锯齿。

-## 为什么鼠标移上图表tooltip不显示
+## FAQ 17：为什么鼠标移上图表Tooltip不显示？

 确认`Tooltip`是否开启；确认父节点是否关闭了鼠标事件。

-## 如何取消tooltip的竖线
+## FAQ 18：如何取消Tooltip的竖线？

 设置`Tooltip`的`type`为`None`。或者调整`lineStyle`的参数。

-## 如何自定义tooltip的显示内容
+## FAQ 19：如何自定义Tooltip的显示内容？

 自定义总的内容可以通过`Tooltip`的`formatter`。如果只是想调整所有的`serie`的显示格式可以用`itemFormatter`和`titleFormatter`结合。如果想每个`serie`的显示格式不一样，可以定制`serie`的`itemStyle`里的`tooltipFormatter`。具体的用法请查阅[XCharts配置项手册](https://xcharts-team.github.io/docs/configuration#Tooltip-itemFormatter)。

-## 如何让y轴显示多位小数
+## FAQ 20：如何让y轴显示多位小数？

 设置`Axis`下的`AxisLabel`中的`formatter`为`{value:f1}`或`{value:f2}`。`1.5.0`及以上版本通过`numericFormatter`设置。

-## 如何用代码动态更新数据
+## FAQ 21：如何用代码动态更新数据？

 请查阅`Example`下的代码，`Example13_LineSimple.cs`就是一个简单添加数据构建折线图的例子，其他`Demo`也都是通过代码控制不同的组件实现不同的功能，相关API请查看文档：[XChartsAPI接口](api.md)  。

-## 如何显示图例为什么有时候图例无法显示
+## FAQ 22：如何显示图例？为什么有时候图例无法显示？

 首先，你的`serie`里的`name`需有值不为空。然后开启`Legend`显示，里面的`data`可以默认为空，表示显示所有的图例。如果你只想显示部分`serie`的图例，在`data`中填入要显示的图例的`name`即可。如果`data`中的值都不是系列的`name`，那图例就不会显示。

-## 如何做成预设
+## FAQ 23：如何做成预设？

 做成prefab前，执行一下`Rebuild Chart Object`重新刷新节点，避免有冗余的节点存在。

-## 如何在图表上画点画线等自定义内容
+## FAQ 24：如何在图表上画点画线等自定义内容？

 `XCharts`有自定义绘制回调`onCustomDraw`，具体可参考`Example12_CustomDrawing.cs`

-## 如何实现心电图类似的数据移动效果
+## FAQ 25：如何实现心电图类似的数据移动效果？

 参考`Example`目录下的`Example_Dynamic.cs`。主要通过设置`maxCache`参数实现。`axis`和`serie`都设置相同的`maxCache`。`maxCache`可固定数据个数，当数据超过设定时会先删除第一个在添加新数据，实现数据移动效果。

-## 如何使用背景组件有什么条件限制
+## FAQ 26：如何使用背景组件？有什么条件限制？

 设置`background`组件的`show`为`true`。

-## 区域折线图在用半透明颜色时有时候会一条叠加的线
-
-这是区域折线图绘制的bug。可以用浅的不透的颜色替代半透明颜色。
-
-## mesh_cannot_have_more_than_65000_vertices
+## FAQ 27：Mesh can not have more than 65000 vertices？

 这是`UGUI`对单个`Graphic`的顶点数限制。`XCharts`是将图形绘制在单个`Graphic`上，所以也会有这个限制。解决的办法可以参考：[FAQ 10：可以显示超过1000以上的大数据吗？](#可以显示超过1000以上的大数据吗)  

-## 为什么serie里设置的参数运行后又被重置了
+## FAQ 28：为什么serie里设置的参数运行后又被重置了？

 检测下代码里是否调用了`RemoveData()`并重新添加`Serie`了。如果想保留`Serie`的配置可以只`ClearData()`，然后重新添加数据。

-## 如何修改serie的symbol的颜色
+## FAQ 29：如何修改serie的symbol的颜色？

 `Symbol` 的颜色是使用的 `ItemStyle` 的 `color`。

-## 导入或更新xcharts时tmp报错怎么办
+## FAQ 30：导入或更新XCharts时TMP报错如何处理？

 XCharts默认时不开启TMP，所以asmdef上没有TMP的引用。当本地开启TMP后再更新XCharts可能会出现这个问题。可通过以下两种方式解决：

@@ -169,19 +130,23 @@ XCharts默认时不开启TMP，所以asmdef上没有TMP的引用。当本地开

 `3.8.0`版本后增加[XCharts-Daemon](https://github.com/XCharts-Team/XCharts-Daemon)守护程序，将XCharts-Daemon导入项目后，在更新XCharts时守护程序会自动根据本地开启的TMP情况刷新asmdef，确保编译正常。

-## 支持空数据吗如何实现折线图断开的效果
+## FAQ 31：支持空数据吗？如何实现折线图断开的效果？

 `Serie`的`data`是`double`类型，所以无法表示空数据。可通过开启`Serie`的`ignore`和指定`ignoreValue`来达到空数据的效果。也可以每个`SerieData`设置`ignore`参数。忽略数据后断开还是连接可设置`ignoreLineBreak`参数。

-## xcharts2升级xcharts3时常见的问题有哪些
+## FAQ 32：2.x版本升级3.x版本时常见的问题有哪些？

 1. 'XCharts.Runtime.XChartsMgr' is missing the class attribute 'ExtensionOfNativeClass'!
 3.x版本时不需要挂载XChartsMgr，直接删掉场景上的`_xcharts_`节点即可。

-## 折线图如何两边不留空白而从0坐标开始显示
+## FAQ 33：折线图如何两边不留空白而从0坐标开始显示？

 设置X轴的`boundaryGap`参数。

-## 如何设置部分serie不显示tooltip
+## FAQ 34：如何设置部分Serie不显示Tooltip？

 `serie`的`itemStyle`的`itemFormatter`设置为`-`可以忽略`tooltip`。
+
+## FAQ 35：区域折线图在用半透明颜色时有时候会一条叠加的线
+
+这是区域折线图绘制的bug。可以用浅的不透的颜色替代半透明颜色。
--- a/Documentation~/zh/tutorial01.md
+++ b/Documentation~/zh/tutorial01.md
@@ -6,7 +6,11 @@ slug: /tutorial01

 # 教程：5分钟上手 XCharts 3.0

-> Note：本教程仅适用XCharts 3.x版本，2.x版本请看 [教程：5分钟上手XCharts 2.0](https://github.com/XCharts-Team/XCharts/blob/2.0/Doc/教程：5分钟上手XCharts.md)
+:::warning
+
+Note：本教程仅适用XCharts 3.x版本，2.x版本请看 [教程：5分钟上手XCharts 2.0](https://github.com/XCharts-Team/XCharts/blob/2.0/Doc/教程：5分钟上手XCharts.md)
+
+:::

 ## XCharts的前提条件

@@ -54,7 +58,11 @@ XCharts-Daemon的导入方式可参考刚才的XCharts导入方式。可以通

 导入XCharts并编译通过后，Unity编辑器的菜单栏会显示XCharts，这时可以开始使用XCharts了。

->Note：Unity的菜单栏出现XCharts菜单时才表示XCharts可用。
+:::tip
+
+Unity的菜单栏出现XCharts菜单时才表示XCharts可用。
+
+:::

 ### 添加一个简单图表

@@ -85,7 +93,11 @@ Serie支持多维数据，一般折线图只用到二维数据：第一维表示
 ![op_addserie](img/tutorial01_addserie.png)
 ![linechart2](img/tutorial01_linechart2.png)

->Note：Serie通过`Add Serie`按钮添加。可添加不同类型的Serie。[XCharts有哪些Serie？](https://xcharts-team.github.io/docs/configuration#serie-系列)
+:::tip
+
+Serie通过`Add Serie`按钮添加。可添加不同类型的Serie。[XCharts有哪些Serie？](https://xcharts-team.github.io/docs/configuration#serie-系列)
+
+:::

 ### 添加其他主组件

@@ -93,7 +105,11 @@ Serie支持多维数据，一般折线图只用到二维数据：第一维表示

 ![op_addcomponent](img/tutorial01_addcomponent.png)

->Note：主组件通过`Add Component`按钮添加。[XCharts有哪些主组件？](https://xcharts-team.github.io/docs/configuration/#maincomponent-主组件)
+:::tip
+
+主组件通过`Add Component`按钮添加。[XCharts有哪些主组件？](https://xcharts-team.github.io/docs/configuration/#maincomponent-主组件)
+
+:::

 ### 添加Serie组件

@@ -102,7 +118,11 @@ Serie只自带了几个常见的组件，其他组件用到时需额外添加。
 ![op_addseriecomponent](img/tutorial01_addseriecomponent.png)
 ![linechart3](img/tutorial01_linechart3.png)

->Note：Serie组件通过Serie右边的按钮添加。[XCharts有哪些Serie组件？](https://xcharts-team.github.io/docs/configuration/#iseriecomponent-可添加到serie的组件)
+:::tip
+
+Serie组件通过Serie右边的按钮添加。[XCharts有哪些Serie组件？](https://xcharts-team.github.io/docs/configuration/#iseriecomponent-可添加到serie的组件)
+
+:::

 ### 添加SerieData组件

@@ -111,7 +131,11 @@ Serie只自带了几个常见的组件，其他组件用到时需额外添加。
 ![op_addseriedatacomponent](img/tutorial01_addseriedatacomponent.png)
 ![linechart4](img/tutorial01_linechart4.png)

->Note：SerieData组件通过展开SerieData后Component右边的按钮添加。[XCharts有哪些SerieData组件？](https://xcharts-team.github.io/docs/configuration/#iseriedatacomponent-可添加到seriedata的组件)
+:::tip
+
+SerieData组件通过展开SerieData后Component右边的按钮添加。[XCharts有哪些SerieData组件？](https://xcharts-team.github.io/docs/configuration/#iseriedatacomponent-可添加到seriedata的组件)
+
+:::

 ### 更多组件和配置参数

@@ -131,7 +155,11 @@ XCharts是数据和参数驱动的。想要什么效果，只需要去调整对
 2. 如果`Serie`的`ItemStyle`配置有非`0000`颜色值，则优先用这个颜色值。
 3. 否则颜色值取自主题`Theme`的`Color Palette`。

->Note：通常颜色值为0000时表示用主题默认颜色；其他参数为0或null时表示用主题默认配置；设置颜色时注意透明度。
+:::tip
+
+通常颜色值为0000时表示用主题默认颜色；其他参数为0或null时表示用主题默认配置；设置颜色时注意透明度。
+
+:::

 ### 用代码添加折线图

@@ -212,7 +240,11 @@ for (int i = 0; i < 10; i++)

 如果一个Chart里面有多个系列时，则Axis的data只需要加一次，不要多个循环加重复了。

->记住：Axis的数据个数要和Serie的数据个数一致。
+:::danger
+
+请确保Axis的数据个数和Serie的数据个数一致。
+
+:::

 完整代码请查阅`Examples`：`Example13_LineSimple.cs`  

@@ -227,7 +259,11 @@ XCharts默认使用的是Unity默认字体`Arial`，在WebGL平台上可能无

 字体设置好后，新创建的图表就会用新设置的字体了。对于旧图表，可以点击`Rebuild Chart Object`进行刷新。

->Note：使用XCharts前建议先设置好字体；更新XCharts时注意设置的字体可能被还原的问题。
+:::warning
+
+使用XCharts前建议先设置好字体；更新XCharts时注意设置的字体可能被还原的问题。
+
+:::

 ### 使用TextMeshPro

@@ -269,7 +305,11 @@ XCharts内部有自动刷新机制，但也是在一定条件才会触发。如
 2. `chart.RefreshChart()`：刷新图表绘制，只刷新绘制部分，不会刷新组件文本，位置等部分。
 3. 各个组件也可以通过`SetAllDirty()`只刷新自己。

->Note：用API去操作数据和各种list，而不是直接访问list进行处理
+:::danger
+
+用API去操作数据和各种list，而不是直接访问list进行处理
+
+:::

 ### 改主组件上的参数

@@ -286,7 +326,11 @@ xAxis.boundaryGap = true;
 xAxis.type = Axis.AxisType.Category;
 ```

-> 注：低版本没有`EnsureChartComponent()`接口时，用`GetOrAddChartComponent()`
+:::note
+
+低版本没有`EnsureChartComponent()`接口时，用`GetOrAddChartComponent()`
+
+:::

 ### 改Serie的参数