diff --git a/Documentation~/zh/changelog.md b/Documentation~/zh/changelog.md index a6301656..4c634e2e 100644 --- a/Documentation~/zh/changelog.md +++ b/Documentation~/zh/changelog.md @@ -76,6 +76,7 @@ slug: /changelog ## master +* (2024.09.27) 完善`5分钟教程` * (2024.09.24) 完善`Legend`的`formatter`对多Serie的支持 (#332) * (2024.09.22) 调整`Documentation`文档显示样式 * (2024.09.09) 增加`numericFormatter`对`date`和`time`的支持 diff --git a/Documentation~/zh/img/tutorial01_axisdata.png b/Documentation~/zh/img/tutorial01_axisdata.png new file mode 100644 index 00000000..8c4910af Binary files /dev/null and b/Documentation~/zh/img/tutorial01_axisdata.png differ diff --git a/Documentation~/zh/img/tutorial01_seriedata.png b/Documentation~/zh/img/tutorial01_seriedata.png new file mode 100644 index 00000000..167d02ac Binary files /dev/null and b/Documentation~/zh/img/tutorial01_seriedata.png differ diff --git a/Documentation~/zh/tutorial01.md b/Documentation~/zh/tutorial01.md index 0c2b382e..9c83fa1e 100644 --- a/Documentation~/zh/tutorial01.md +++ b/Documentation~/zh/tutorial01.md @@ -6,84 +6,124 @@ slug: /tutorial01 # 教程:5分钟上手 XCharts 3.0 -> 注:本教程适用XCharts 3.x版本,2.x版本请看 [教程:5分钟上手XCharts 2.0](https://github.com/XCharts-Team/XCharts/blob/2.0/Doc/教程:5分钟上手XCharts.md) +> Note:本教程仅适用XCharts 3.x版本,2.x版本请看 [教程:5分钟上手XCharts 2.0](https://github.com/XCharts-Team/XCharts/blob/2.0/Doc/教程:5分钟上手XCharts.md) -## 使用 XCharts 前需要掌握什么 +## XCharts的前提条件 -- 会简单使用Unity -- 了解UGUI,会使用UGUI -- 了解Unity的MonoBehavior脚本用法,知道怎么挂脚本,用代码操作脚本 +XCharts是一个Unity图表插件,目前只能在Unity平台使用。 -## 获取和导入 XCharts +使用XCharts前,你需要: -XCharts可通过以下任意一种方式导入到项目: +- 掌握Unity的基本用法。 +- 掌握UGUI制作UI的基本用法。 +- 了解Unity的MonoBehavior脚本用法,知道怎么挂脚本和用代码操作脚本。 -- 直接将XCharts源码到项目 +如果你刚接触Unity,建议先学习Unity相关的基础教程再使用XCharts。 - 下载好XCharts源码后,直接将XCharts目录拷贝到Unity项目工程的Assets目录下。 +## XCharts的获取和导入 -- 通过`Assets/Import Package`导入XCharts +XCharts主要通过Github来维护更新和发布,可以到Github主页进行下载获取源码和Pacakge,Github主页:https://github.com/XCharts-Team。 - 下载好XCharts的.unitypackage文件后,打开Unity,菜单栏 Assets-->Import Package-->选中.unitypackage导入即可开始使用XCharts。 +对于无Github访问条件的用户,可以访问[【国内镜像】](https://gitee.com/monitor1394/unity-ugui-XCharts)进行下载。国内镜像的版本更新可能会相对滞后。 -- 通过`Package Manager`导入XCharts +XCharts可通过以下任意一种方式导入到你的项目: - 对于Unity 2018.3以上版本,可通过 Package Manager来导入XCharts,打开Package Manager后,通过 `Add package form git URL...`,输入XCharts3.0的GitHub URL: `https://github.com/XCharts-Team/XCharts.git#3.0` 稍等片刻后即可使用XCharts。 +### 直接将XCharts源码拷贝到项目 - 也可以直接将package加入到`manifest.json`文件:打开`Packages`目录下的`manifest.json`文件,在`dependencies`下加入: +下载好XCharts源码后,直接将XCharts目录拷贝到Unity项目工程的Assets目录下。编译通过后即可使用。 - ``` json - "com.monitor1394.xcharts": "https://github.com/XCharts-Team/XCharts.git#3.0", - ``` +### 通过Import Package导入XCharts - 如需更新`XCharts`,删除`manifest.json`文件(部分Unity版本可能是packages-lock.json文件)的`lock`下的`com.monitor1394.xcharts`相关内容即会重新下载编译。 +下载好XCharts的.unitypackage文件后,打开Unity,菜单栏 Assets-->Import Package-->选中下载好的.unitypackage进行导入。导入完成并通过编译后即可开始使用XCharts。 -- 建议先导入XCharts的守护程序(非必须) +### 通过Package Manager导入XCharts - 守护程序[XCharts-Daemon](https://github.com/XCharts-Team/XCharts-Daemon)可以确保更新时编译正常,当本地开启TextMeshPro或NewInputSystem时将会非常有用。将XCharts-Daemon导入项目后,在更新XCharts时守护程序会自动根据本地TMP等的开启情况刷新asmdef,确保编译正常,不用手动去解决,方便CI-CD等自动化流程执行。 +对于2018.3以上的Unity版本,可通过Package Manager来导入XCharts,打开Package Manager后,通过 `Add package form git URL...`,输入XCharts的GitHub URL: `https://github.com/XCharts-Team/XCharts.git` 编译通过后即可使用XCharts。 -## 添加一个简单图表 +对于部分Unity版本,也可以直接将package加入到`manifest.json`文件:打开`Packages`目录下的`manifest.json`文件,在`dependencies`下加入: -在`Hierarchy`视图下右键`UI->XCharts->LineChart`或菜单栏`GameObject`下拉选择`XCharts->LineChart`,即可快速创建一个默认的折线图出来: +>"com.monitor1394.xcharts": "https://github.com/XCharts-Team/XCharts.git", + +如需更新`XCharts`,删除`manifest.json`文件(部分Unity版本可能是packages-lock.json文件)的`lock`下的`com.monitor1394.xcharts`相关内容即会重新下载编译。 + +### 建议导入XCharts的守护程序 + +守护程序[XCharts-Daemon](https://github.com/XCharts-Team/XCharts-Daemon)可以确保更新时编译正常,当本地开启TextMeshPro或NewInputSystem时将会非常有用。将XCharts-Daemon导入项目后,在更新XCharts时守护程序会自动根据本地TMP等的开启情况刷新XCharts的asmdef,确保编译正常,不用手动去解决,方便CI/CD等自动化流程执行。 + +XCharts-Daemon的导入方式可参考刚才的XCharts导入方式。可以通过源码或Package的方式导入项目,XCharts-Daemon的Github URL:https://github.com/XCharts-Team/XCharts-Daemon.git + +## XCharts的基本使用 + +导入XCharts并编译通过后,Unity编辑器的菜单栏会显示XCharts,这时可以开始使用XCharts了。 + +>Note:Unity的菜单栏出现XCharts菜单时才表示XCharts可用。 + +### 添加一个简单图表 + +在`Hierarchy`视图下右键`UI->XCharts->LineChart`或菜单栏`XCharts`下拉选择`LineChart`,即可快速创建一个默认的折线图出来: ![linechart1](img/tutorial01_linechart1.png) -## 添加多个Seire +如需在某个节点下创建图表,可以选中节点右键`UI->XCharts->LineChart`即可在节点下创建图表。 + +### 修改图表数据 + +刚创建的图表,它的数据可以在Inspector视图面板上进行修改。 + +对于X轴数据,可通过:`XAxis->Data`展开后进行增删和修改: + +![op_axisdata](img/tutorial01_axisdata.png) + +对于Serie数据,可通过:`Serie->Data`展开后进行增删和修改: + +![op_seriedata](img/tutorial01_seriedata.png) + +Serie支持多维数据,一般折线图只用到二维数据:第一维表示X轴类目数据的编号,第二维表示对应的数值。 + +### 添加多个Seire 在`Inspector`视图,找到`LineChart`的面板,通过`Add Serie`按钮,可以添加第二条`Line`折线: ![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-系列) + +### 添加其他主组件 默认图表没有`Legend`,需要`Legend`组件可通过`Add Component`按钮添加: ![op_addcomponent](img/tutorial01_addcomponent.png) -## 添加Serie组件 +>Note:主组件通过`Add Component`按钮添加。[XCharts有哪些主组件?](https://xcharts-team.github.io/docs/configuration/#maincomponent-主组件) -Serie只自带了几个常见的组件,其他组件按需额外添加。比如,需要给折线图区域填充颜色,可单独给`Serie`添加`AreaStyle`组件: +### 添加Serie组件 + +Serie只自带了几个常见的组件,其他组件用到时需额外添加。比如,需要给折线图进行区域填充颜色,可单独给`Serie`添加`AreaStyle`组件: ![op_addseriecomponent](img/tutorial01_addseriecomponent.png) ![linechart3](img/tutorial01_linechart3.png) -## 添加SerieData组件 +>Note:Serie组件通过Serie右边的按钮添加。[XCharts有哪些Serie组件?](https://xcharts-team.github.io/docs/configuration/#iseriecomponent-可添加到serie的组件) -如果需要个性化定制每个数据项的配置,可以单独给每个`SerieData`添加`Component`。比如我们给折线图的第二个数据单独显示`Label`: +### 添加SerieData组件 + +如果需要个性化定制每个数据项的配置,可以单独给每个`SerieData`添加组件。比如我们给折线图的第二个数据单独显示`Label`: ![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的组件) -XCharts经过不断的迭代优化,目前已有多达几十种的主组件和子组件,每个组件有几个至几十个不等的可配置参数,以支持各种灵活而复杂的功能。 +### 更多组件和配置参数 -首次使用XCharts,可在 `Inspector` 视图添加各种图表,给图表添加或调整里面组件,`Game` 视图会实时反馈调整后的效果,以熟悉各种组件的使用。各个组件的详细参数说明可查阅[XCharts配置项手册](configuration.md)。 +XCharts经过不断的迭代优化,目前已有多达几十种的主组件和子组件,每个组件有几个到几十个的可配置参数,用来支持多样化的功能。 -## 如何快速调整参数 +首次使用XCharts,建议亲自去测试下各个图表各个组件的实际效果。`Inspector` 视图可以直接添加各种图表,各种组件以及调整各个配置参数,`Game` 视图会实时反馈调整后的效果。各个组件的详细参数说明可查阅[XCharts配置项手册](configuration.md)。 -`XCharts`是配置和数据来驱动的。想要什么效果,只需要去调整对应组件下的配置参数就可以,不需要去改`Hierarchy`视图下的节点,因为那些节点是由`XCharts`内部根据配置和数据生成的,即使改了也会在刷新时还原回来。 +### 如何快速调整参数 + +XCharts是数据和参数驱动的。想要什么效果,只需要去调整对应组件下的配置参数就可以,不能去改`Hierarchy`视图下的节点,因为那些节点是由XCharts内部根据配置和数据生成的,即使改了也会在刷新时被还原掉。 如何快速定位你想要改的效果所对应的组件,这就需要对组件有一定的了解。比如我们想要让X轴的轴线末端显示箭头,如何定位?第一步,X轴定位到`XAxis0`;第二步,轴线定位到`AxisLine`;最后,再去看`AxisLine`组件下有没有这样的参数可以实现这个效果,对于不太确定的参数可以查阅[XCharts配置项手册](configuration.md)。 @@ -93,9 +133,9 @@ XCharts经过不断的迭代优化,目前已有多达几十种的主组件和 2. 如果`Serie`的`ItemStyle`配置有非`0000`颜色值,则优先用这个颜色值。 3. 否则颜色值取自主题`Theme`的`Color Palette`。 -通常颜色值为0000时表示用主题默认颜色,配置为0或null时表示用主题默认配置。 +>Note:通常颜色值为0000时表示用主题默认颜色;其他参数为0或null时表示用主题默认配置;设置颜色时注意透明度。 -## 用代码添加折线图 +### 用代码添加折线图 给`gameObject`挂上`LineChart`脚本: @@ -143,13 +183,21 @@ var yAxis = chart.EnsureChartComponent(); yAxis.type = Axis.AxisType.Value; ``` -清空默认数据,添加`Line`类型的`Serie`用于接收数据: +清空所有默认数据(包含Serie),添加`Line`类型的`Serie`用于接收数据: ```csharp chart.RemoveData(); chart.AddSerie("line"); ``` +如果Serie是固定的,建议只是清空数据,不用把Serie也清掉: + +```csharp +chart.ClearData(); +``` + +这样可以提前在UI上设置好Serie的配置参数。 + 添加10个数据: ```csharp @@ -164,30 +212,26 @@ for (int i = 0; i < 10; i++) ![tutorial01_linechart_simple](img/tutorial01_linechart_simple.png) -如果一个Chart里面有多个系列时,则Axis的data只需要加一次,不要多个循环加重复了。记住:Axis的数据个数要和Serie的数据个数一致。 +如果一个Chart里面有多个系列时,则Axis的data只需要加一次,不要多个循环加重复了。 + +>记住:Axis的数据个数要和Serie的数据个数一致。 完整代码请查阅`Examples`:`Example13_LineSimple.cs` 你还可以用代码控制更多的参数,`Examples`下还有更多的其他例子,凡是`Inspector`上看到的可配置的参数,都可以通过代码来设置。[XCharts配置项手册](configuration.md)里面的所有参数都是可以通过代码控制的。 -另外,除非定制,建议调用`Chart`下提供的`public`接口,特别是数据相关操作部分。这些接口内部会做一些关联处理,比如刷新图表等。常见的接口有: +### 设置默认字体 -1. `chart.ClearData()`:清空图表数据(不移除Series) -2. `chart.RemoveData()`:清除图表数据(会移除所有Serie) -3. `chart.AddSerie()`:添加Serie -4. `chart.AddXAxisData()`:添加X轴数据 -5. `chart.AddData()`:添加Serie数据 -6. `chart.UpdateData()`:更新Serie数据 -7. `chart.UpdateXAxisData()`:更新X轴数据 -8. `chart.UpdateDataName()`:更新Serie数据的名字 +XCharts默认使用的是Unity默认字体`Arial`,在WebGL平台上可能无法显示中文。在将XCharts用在你的项目时,建议先设置好字体: -XCharts内部有自动刷新机制,但也是在一定条件才会触发。如果自己调用了内部组件的接口,碰到组件没有刷新,确实找不到原因的话,可以用以下两个接口强制刷新: +- 找到`XCharts/Resources/XCSetting.asset`文件,修改里面的`Font`并保存。 +- 找到`XCharts/Resources/XCTheme-Default.asset`和`XCharts/Resources/XCTheme-Default.asset`两个字体配置,点击`Sync Font from Setting`和`Sync Font to Sub Theme`按钮将字体同步到主题配置文件上。 -1. `chart.RefreshAllComponent()`:刷新图表组件,会重新初始化所有组件,不建议频繁待用。 -2. `chart.RefreshChart()`:刷新图表绘制,只刷新绘制部分,不会刷新组件文本,位置等部分。 -3. 各个组件也可以通过`SetAllDirty()`只刷新自己。 +字体设置好后,新创建的图表就会用新设置的字体了。对于旧图表,可以点击`Rebuild Chart Object`进行刷新。 -## 使用TextMeshPro +>Note:使用XCharts前建议先设置好字体;更新XCharts时注意设置的字体可能被还原的问题。 + +### 使用TextMeshPro XCharts支持TextMeshPro,但默认是不开启的,需要自己手动切换。可通过以下方式开启和关闭: @@ -206,10 +250,29 @@ XCharts支持TextMeshPro,但默认是不开启的,需要自己手动切换 `3.8.0`版本后增加[XCharts-Daemon](https://github.com/XCharts-Team/XCharts-Daemon)守护程序,将XCharts-Daemon导入项目后,在更新XCharts时守护程序会自动根据本地开启的TMP情况刷新asmdef,确保编译正常。 -## 用代码改图表参数 +## XCharts的代码控制 `Inspector`上看到的所有参数都可以用代码来修改,关键是要定位好你要改的参数是在组件上、还是Serie上、还是在具体的数据项SerieData上。 +另外,除非定制,建议调用`Chart`下提供的`public`接口,特别是数据相关和列表的操作。这些接口内部会做一些关联处理,比如刷新图表等。常见的接口有: + +1. `chart.ClearData()`:清空图表数据(不移除Series) +2. `chart.RemoveData()`:清除图表数据(会移除所有Serie) +3. `chart.AddSerie()`:添加Serie +4. `chart.AddXAxisData()`:添加X轴数据 +5. `chart.AddData()`:添加Serie数据 +6. `chart.UpdateData()`:更新Serie数据 +7. `chart.UpdateXAxisData()`:更新X轴数据 +8. `chart.UpdateDataName()`:更新Serie数据的名字 + +XCharts内部有自动刷新机制,但也是在一定条件才会触发。如果自己调用了内部组件的接口,碰到组件没有刷新,确实找不到原因的话,可以用以下两个接口强制刷新: + +1. `chart.RefreshAllComponent()`:刷新图表组件,会重新初始化所有组件,不建议频繁待用。 +2. `chart.RefreshChart()`:刷新图表绘制,只刷新绘制部分,不会刷新组件文本,位置等部分。 +3. 各个组件也可以通过`SetAllDirty()`只刷新自己。 + +>Note:用API去操作数据和各种list,而不是直接访问list进行处理 + ### 改主组件上的参数 需要先获取组件,再修改里面的参数: