拼ui 一些业务逻辑x实现
This commit is contained in:
FloatGaming
@@ -0,0 +1,62 @@
|
||||
# Free vs Pro 划分与发布规则
|
||||
|
||||
本文用于固化 EasyChart 的 Free/Pro 划分口径、工程结构与发布导出规则，防止后续开发过程出现边界漂移。
|
||||
|
||||
## 1. 总体策略（结论）
|
||||
|
||||
- 两个独立包：Free 包 / Pro 包
|
||||
- Pro 包包含 Free 全量（Pro 为 superset）
|
||||
- Free 遇到 Pro-only 资产/配置：允许直接报错（不做降级兼容）
|
||||
|
||||
## 2. 功能边界（Scheme 2）
|
||||
|
||||
### 2.1 Free 包必须包含
|
||||
|
||||
- 基础 2D 图表类型与常用工作流（运行时可用 + 编辑器可配置/预览）
|
||||
- `EasyChartLibraryWindow`（LibraryWindow）
|
||||
- 运行时数据注入能力（例如 `ChartFeed` / `ApplyJson`）
|
||||
|
||||
### 2.2 Pro 包增量方向（优先级）
|
||||
|
||||
- A：新增图表类型
|
||||
- Gauge / Funnel / BoxPlot / Candlestick(K线) / Treemap / Sunburst 等
|
||||
- B：3D 图表
|
||||
- 3D Bar / 3D Scatter / 3D Surface 等
|
||||
- C：2D 高级视觉效果
|
||||
- 贴图 UV 动画、特效类渲染能力等
|
||||
|
||||
### 2.3 2D 高级效果具体划分
|
||||
|
||||
- Free：Bar 头部圆角、hover 效果
|
||||
- Pro：贴图 UV 动画（以及后续更复杂的材质/特效能力）
|
||||
|
||||
## 3. 工程结构（asmdef / 目录）
|
||||
|
||||
当前工程采用 asmdef 拆分，保证 Free 不依赖 Pro，便于导出两个包。
|
||||
|
||||
- `Assets/EasyChart/Scripts/Runtime/` -> `EasyChart.Runtime`
|
||||
- `Assets/EasyChart/Scripts/Editor/` -> `EasyChart.Editor`（Editor-only，引用 `EasyChart.Runtime`）
|
||||
- `Assets/EasyChart/EasyChartPro/Scripts/Runtime/` -> `EasyChart.Pro.Runtime`（引用 `EasyChart.Runtime`）
|
||||
- `Assets/EasyChart/EasyChartPro/Scripts/Editor/` -> `EasyChart.Pro.Editor`（Editor-only，引用 `EasyChart.Editor` + `EasyChart.Pro.Runtime`）
|
||||
|
||||
约束：
|
||||
|
||||
- Pro-only 代码必须放在 `EasyChartPro/**` 下。
|
||||
- Free 的 asmdef 不得引用任何 `EasyChart.Pro.*` asmdef。
|
||||
|
||||
## 4. 发布/导出规则
|
||||
|
||||
### 4.1 Free 包
|
||||
|
||||
- 导出包含：`Assets/EasyChart/**`
|
||||
- 导出排除：`Assets/EasyChart/EasyChartPro/**`（以及未来所有 `*Pro` 资源目录，例如 `TexturesPro/**`, `ShadersPro/**`, `DemoPro/**`）
|
||||
|
||||
### 4.2 Pro 包
|
||||
|
||||
- 全量导出 `Assets/EasyChart/**`（包含 `Scripts` + `EasyChartPro`）
|
||||
|
||||
## 5. 报错策略（Free 遇到 Pro-only）
|
||||
|
||||
- 允许直接报错，但要求错误信息可定位：
|
||||
- 运行时：明确 `Debug.LogError` 指出需要 Pro
|
||||
- 编辑器：避免空引用，尽量显示可读提示
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: a681a95db0eb16e4ea4dffa668c74252
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/FreeProSplit.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,66 @@
|
||||
# EasyChart Lite License
|
||||
|
||||
**Version 1.0 | Effective Date: February 2026**
|
||||
|
||||
---
|
||||
|
||||
## License Grant
|
||||
|
||||
This license ("License") is a legal agreement between you ("Licensee") and the author of EasyChart ("Licensor") for the use of EasyChart Lite ("Software").
|
||||
|
||||
By downloading, installing, or using the Software, you agree to be bound by the terms of this License.
|
||||
|
||||
---
|
||||
|
||||
## Permitted Uses
|
||||
|
||||
You are granted a **non-exclusive, worldwide, royalty-free license** to:
|
||||
|
||||
1. **Use** the Software in unlimited personal and commercial projects
|
||||
2. **Modify** the Software for your own use within your projects
|
||||
3. **Distribute** the Software as part of your compiled/built applications
|
||||
4. **Create** derivative works for your own projects
|
||||
|
||||
---
|
||||
|
||||
## Restrictions
|
||||
|
||||
You are **NOT permitted** to:
|
||||
|
||||
1. **Resell** the Software as a standalone product or asset
|
||||
2. **Redistribute** the Software source code in any form (modified or unmodified) as a separate product
|
||||
3. **Sublicense** the Software to third parties
|
||||
4. **Create** competing products based on the Software for sale or distribution
|
||||
5. **Remove** or alter any copyright notices or license information
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Use Case | Allowed |
|
||||
|----------|---------|
|
||||
| Use in free games/apps | ✅ Yes |
|
||||
| Use in commercial games/apps | ✅ Yes |
|
||||
| Modify for your own projects | ✅ Yes |
|
||||
| Include in compiled builds | ✅ Yes |
|
||||
| Resell as an asset/plugin | ❌ No |
|
||||
| Redistribute source code | ❌ No |
|
||||
| Create competing products for sale | ❌ No |
|
||||
|
||||
---
|
||||
|
||||
## Disclaimer
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
---
|
||||
|
||||
## Contact
|
||||
|
||||
For licensing inquiries or to obtain a different license, please contact the author.
|
||||
|
||||
---
|
||||
|
||||
© 2026 EasyChart. All rights reserved.
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 44fa988e007f0d1429ca6f0a65fa7d20
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/LICENSE.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,8 @@
|
||||
fileFormatVersion: 2
|
||||
guid: dd54aa9e788d95c4499f10623eb08009
|
||||
folderAsset: yes
|
||||
DefaultImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 148e5f1517e95fa42993d4a1ebc0fa09
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/00-Index.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 299fc7dc221a59a4fad4edda9fea1eaf
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/00-WorkflowAndLibrary.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 37c6e7aafd75b4748b496352b7b1a1be
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/02-EditorWorkflow.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: e9e15b5df5bb2ed4dafeb470f1ceae35
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/06-FAQ.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 43e2bb9a9c3bd5a478d0e44c26b17428
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/10-LineChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: e2a9d1a1934fa1945b2f8d8959a4411e
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/11-BarChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 0f82323d21320024cb5cb55a18633b25
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/12-ScatterChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 460d2ef1b24b2e646aedf814c3ada1a9
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/13-HeatmapChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 51eacb7284fc0844790aa4af3dcd70c8
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/14-RadarChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 07c495578f8bef343a24d37fb5537fbc
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/16-RingChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 4c0a2c5642d640c429d22f7bb4dffde0
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/33-UGUIWorkflow.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 4dafffa5cb75bd34d95c2040d36e9e13
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/34-RuntimeDataInjectionUIToolKit.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: a6503bc50a2dfeb4e94f95d517585a37
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/35-RuntimeDataInjectionUGUI.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,8 @@
|
||||
fileFormatVersion: 2
|
||||
guid: f64036de3e264084abf850902d1824e8
|
||||
folderAsset: yes
|
||||
DefaultImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
@@ -0,0 +1,73 @@
|
||||
# Quick Overview
|
||||
|
||||
This manual is intended for a workflow where you configure charts (the `ChartProfile` asset) in the Unity Editor via **`EasyChartLibraryWindow`**.
|
||||
|
||||
- Menu entry: `EasyChart/Library Editor`
|
||||
- Manual viewer: `EasyChart/Manual`
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
### A. Getting Started & Workflows
|
||||
|
||||
- [Quick overview](./00_00-Index.md)
|
||||
- [Quick start: create your first chart in 2 minutes](./00_01-QuickStart.md)
|
||||
- [UIToolKit workflow (recommended)](./00_02-WorkflowAndLibrary.md)
|
||||
- [UGUI workflow](./00_03-UGUIWorkflow.md)
|
||||
- [Runtime data injection (UIToolKit)](./00_04-RuntimeDataInjectionUIToolKit.md)
|
||||
- [Runtime data injection (UGUI)](./00_05-RuntimeDataInjectionUGUI.md)
|
||||
|
||||
### B. Editor & Panels
|
||||
|
||||
- [Editor workflow and panels](./01_01-EditorWorkflow.md)
|
||||
- [Library panel (asset tree)](./01_02-LibraryPanel.md)
|
||||
- [JSON Injection panel](./01_03-JsonInjectionPanel.md)
|
||||
- [Preview panel](./02_04-PreviewPanel.md)
|
||||
- [Inspector panel](./02_05-InspectorPanel.md)
|
||||
- [Series panel](./02_06-SeriesPanel.md)
|
||||
|
||||
### C. Series Configuration (Goal-Oriented)
|
||||
|
||||
- [Line chart](./03_01-LineChart.md)
|
||||
- [Bar chart](./03_02-BarChart.md)
|
||||
- [Scatter chart](./03_03-ScatterChart.md)
|
||||
- [Heatmap chart](./03_04-HeatmapChart.md)
|
||||
- [Radar chart](./03_05-RadarChart.md)
|
||||
- [Pie chart](./03_06-PieChart.md)
|
||||
- [Ring chart](./03_07-RingChart.md)
|
||||
|
||||
### D. Reference (Lookup by Field)
|
||||
|
||||
- [Common recipes](./04_08-CommonRecipes.md)
|
||||
- [FAQ (fastest troubleshooting path)](./04_09-FAQ.md)
|
||||
|
||||
### E. Updates & Roadmap
|
||||
|
||||
- [Roadmap / update plan](./05_01-UpdatePlan.md)
|
||||
|
||||
---
|
||||
|
||||
## Conventions & Terminology
|
||||
|
||||
- **ChartProfile**: A chart configuration asset (reusable; previewable in the editor).
|
||||
- **Series / Serie**: A data series (e.g. one line in a line chart, or one group of bars in a bar chart).
|
||||
- **SeriesData**: The set of data points in a series.
|
||||
- **Axis**: Axis configuration (`AxisType=Category/Value`).
|
||||
- **Category**: Category axis (uses the `labels` list).
|
||||
- **Value**: Value axis (continuous numeric range).
|
||||
|
||||
---
|
||||
|
||||
## Recommended Project Structure
|
||||
|
||||
Recommended to create a dedicated folder in your project for chart assets:
|
||||
|
||||
- `Assets/EasyChart/Library/Custom/`: your own `ChartProfile` assets
|
||||
- `Assets/EasyChart/Docs/Manual/`: this manual (Markdown chapters)
|
||||
|
||||
---
|
||||
|
||||
## Manual Version
|
||||
|
||||
- This manual will be kept in sync with EasyChart field and editor feature updates.
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 11aa7e499832b984d9612138369fe18c
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/00_00-Index.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,93 @@
|
||||
# Quick Start: Create Your First Chart in 2 Minutes
|
||||
|
||||
Goal of this chapter: follow the fastest recommended EasyChart path to complete the loop of **Edit → Export → Use in UI**.
|
||||
|
||||
---
|
||||
|
||||
## Open the Editor Window
|
||||
|
||||
In the Unity menu bar, choose:
|
||||
|
||||
- `EasyChart/Library Editor`
|
||||
|
||||
You will see a window with sections like a library tree, configuration panels, and a preview area (later chapters explain each area).
|
||||
|
||||
---
|
||||
|
||||
## Clone a Library (Recommended)
|
||||
|
||||
If you want to get started quickly and keep a consistent style, it's recommended to:
|
||||
|
||||
- Select an existing Library from the top toolbar (e.g. a built-in Demo library)
|
||||
- Click **Clone** on the toolbar to create your personal library (e.g. `MyLibrary`)
|
||||
|
||||
This way, all subsequent changes happen in your own library, avoiding modifications to the original examples.
|
||||
|
||||
---
|
||||
|
||||
## Clone a ChartProfile (Recommended)
|
||||
|
||||
In the library tree, find a chart (`ChartProfile`) close to what you want, then right-click:
|
||||
|
||||
- `Clone`
|
||||
|
||||
After cloning, you'll get a new Profile (a "variant" of the original). Select it, and the Inspector on the right will show all editable settings.
|
||||
|
||||
---
|
||||
|
||||
## Modify Settings and Save
|
||||
|
||||
Minimal recommended changes:
|
||||
|
||||
- `coordinateSystem`: make sure it matches your intended Series (e.g. Line/Bar/Scatter use `Cartesian2D`)
|
||||
- `series`: confirm `type` is correct, and fill in `seriesData`
|
||||
- `axes`: at minimum, make sure X/Y axis types match the meaning of your data
|
||||
|
||||
After editing, click the save button on the top toolbar (if your version has it), or let Unity auto-save the asset.
|
||||
|
||||
---
|
||||
|
||||
## Export to UXML (Reusable in UI Builder)
|
||||
|
||||
The recommended workflow is exporting the Profile to a reusable `.uxml`:
|
||||
|
||||
- Right-click your Profile in the tree
|
||||
- Choose `Export to UXML`
|
||||
|
||||
The exported UXML will be placed under:
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/` (Mirror/Backup operations also manage exported assets under this root)
|
||||
|
||||
---
|
||||
|
||||
## Use It in the QuickStart Scene via UIDocument + UI Builder
|
||||
|
||||
Open the demo scene:
|
||||
|
||||
- `Assets/EasyChart/Demo/Scenes/EasyChart_QuickStart.unity`
|
||||
|
||||
Then in the Project window, locate:
|
||||
|
||||
- `Assets/EasyChart/Demo/UIToolKit/NewUXMLTemplate.uxml`
|
||||
|
||||
Double-click to open it (or open with UI Builder). Next:
|
||||
|
||||
- Drag the chart `.uxml` you just exported into the hierarchy of `NewUXMLTemplate.uxml`
|
||||
- Save the UXML
|
||||
- Make sure the `UIDocument` in the scene references your updated `NewUXMLTemplate.uxml`
|
||||
|
||||
Run the scene, and you should see the chart rendered in the UI Toolkit UI.
|
||||
|
||||
---
|
||||
|
||||
## Alternative: Export as a UGUI Prefab
|
||||
|
||||
If you prefer a UGUI (Canvas/RectTransform) workflow, you can also export the selected Profile as a UGUI prefab in the Library Editor and place it directly into your scene UI (exact menu entry and details depend on your current version).
|
||||
|
||||
---
|
||||
|
||||
## What to Read Next
|
||||
|
||||
- To understand the recommended UI Toolkit workflow: `00_02-WorkflowAndLibrary.md`
|
||||
- To use charts with UGUI (Canvas/RectTransform): `00_03-UGUIWorkflow.md`
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 2b29849ac25f2d84d966fd376339a0e6
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/00_01-QuickStart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,428 @@
|
||||
# UI Toolkit Workflow (Recommended)
|
||||
|
||||
Goal of this chapter: explain the overall recommended EasyChart approach (primarily for UI Toolkit):
|
||||
|
||||
1. Edit `ChartProfile` in the editor with **`EasyChartLibraryWindow`**
|
||||
2. **Export** `ChartProfile` **to `.uxml`** as your chart library assets
|
||||
3. Compose pages in UI Toolkit using **UI Builder** / UXML, enabling fast UI assembly
|
||||
|
||||
This chapter focuses on **UI Toolkit (recommended)**. If you need the UGUI (Canvas/RectTransform) workflow, see:
|
||||
|
||||
- `00_03-UGUIWorkflow.md`
|
||||
|
||||
## 0. Why the UI Toolkit workflow is recommended
|
||||
|
||||
The key idea is to separate the "chart configuration source" (`ChartProfile`) from the "UI artifact" (exported UXML).
|
||||
|
||||
- `ChartProfile`: defines what the chart looks like, which axes it uses, what Series it has, and how data should be interpreted. This is best maintained centrally in the editor.
|
||||
- Exported `.uxml`: places the chart into a page as a UI Toolkit component. This is best suited for reuse, composition, and version control.
|
||||
|
||||
What you get:
|
||||
|
||||
- Reusable configuration (multiple pages can share one chart style)
|
||||
- Composable pages (drag & drop in UI Builder; no need to rebuild UI from scratch each time)
|
||||
- Clearer collaboration (Profile as the "source", UXML as the "product/component library")
|
||||
|
||||
---
|
||||
|
||||
## 1. Why export to UXML
|
||||
|
||||
In a project, `ChartProfile` describes "what the chart looks like", "which axes it uses", "which Series it has", and "how data points are interpreted".
|
||||
|
||||
After exporting to `.uxml`, you get a reusable UI asset for UI Toolkit:
|
||||
|
||||
- Can be dragged directly in UI Builder
|
||||
- Can be reused by multiple pages (same chart style)
|
||||
- Can be managed by version control and asset pipelines (your "chart library")
|
||||
|
||||
---
|
||||
|
||||
## 2. Recommended workflow (from configuration to page)
|
||||
|
||||
### Step 1: Clone your working library and charts (recommended)
|
||||
|
||||
- Open from the Unity menu: `EasyChart/Library Editor`
|
||||
|
||||
Recommended process:
|
||||
|
||||
- **Clone Library**: clone your own Library first (avoid modifying the built-in demo library directly)
|
||||
- **Clone ChartProfile**: in your library tree, right-click a Profile close to your target look, then choose `Clone` to create a variant
|
||||
- Modify in the Inspector on the right:
|
||||
- `coordinateSystem`
|
||||
- `series`
|
||||
- `axes`
|
||||
|
||||
> Recommendation: keep your own Profiles under `Assets/EasyChart/Library/Custom/` (or a team-agreed folder).
|
||||
|
||||
### Step 2: Export to UXML (generate library assets)
|
||||
|
||||
You can export from the Library Editor:
|
||||
|
||||
- For a Profile: `Export to UXML`
|
||||
- For a folder:
|
||||
- `Export Folder to UXML (Mirror)`
|
||||
- `Export Folder to UXML (Backup)`
|
||||
- For all:
|
||||
- `Export All UXML (Mirror)`
|
||||
- `Export All UXML (Backup)`
|
||||
|
||||
Export root folder:
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/`
|
||||
|
||||
With multiple Libraries, the usual structure is:
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/<LibraryName>/...`
|
||||
|
||||
The `_Backups` subfolder is used for backup exports (and some JSON backups generated during exporting):
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/<LibraryName>/_Backups/...`
|
||||
|
||||
The exported UXML usually looks like:
|
||||
|
||||
- A `<ec:ChartElement profile-name="..." />`
|
||||
- `profile-name` corresponds to the ChartProfile key (usually the asset file name)
|
||||
- Width/height styles for the chart are written into the UXML as well
|
||||
|
||||
> Key point: treat exported `.uxml` as **reusable chart components**, not something you hand-write for every UI.
|
||||
|
||||
### Mirror vs Backup (which one should you use?)
|
||||
|
||||
- **Mirror**:
|
||||
- used to "mirror the current Profile state into UXML"
|
||||
- typically overwrites exports with the same name, and may remove stale files that no longer exist (keep the mirror consistent)
|
||||
- **Backup**:
|
||||
- used to "export a snapshot" by time/tag
|
||||
- not recommended as the primary path that your pages reference (better for history/rollback)
|
||||
|
||||
### Step 3: Compose pages in UI Builder
|
||||
|
||||
In UI Builder:
|
||||
|
||||
- Open your page UXML
|
||||
- Drag the exported chart `.uxml` from the Project window
|
||||
- Combine it with other UI (Label, Button, ListView, etc.) into a full page
|
||||
|
||||
For the quickest export-pipeline verification, you can use the demo scene and template:
|
||||
|
||||
- Scene: `Assets/EasyChart/Demo/Scenes/EasyChart_QuickStart.unity`
|
||||
- Template: `Assets/EasyChart/Demo/UIToolKit/NewUXMLTemplate.uxml`
|
||||
|
||||
Drag the exported chart `.uxml` into `NewUXMLTemplate.uxml`, then make sure the `UIDocument` in the scene references that template.
|
||||
|
||||
#### Exact steps in UI Builder (recommended order)
|
||||
|
||||
1. Open UI Builder (or double-click your page `.uxml`).
|
||||
2. In the Project window, locate the exported chart `.uxml` (usually under `Assets/EasyChart/LibraryUxml/<LibraryName>/...`).
|
||||
3. Drag the `.uxml` into the page hierarchy (recommended to put it inside a container `VisualElement`).
|
||||
4. Save the page UXML.
|
||||
5. Back in the scene, make sure `UIDocument` references the page `.uxml` you just saved.
|
||||
|
||||
#### What's inside an exported chart UXML
|
||||
|
||||
Exported `.uxml` typically contains an `EasyChart.ChartElement` with attributes like:
|
||||
|
||||
- `profile-name`: usually the ChartProfile asset file name (key)
|
||||
- `profile-guid`: a more stable way to locate the asset
|
||||
|
||||
Therefore:
|
||||
|
||||
- If you only modify the Profile, the page will not change automatically: you need to re-export (Mirror) so the UXML gets updated.
|
||||
- If you rename the Profile asset, the exported `profile-name` will also change (so keep naming stable when possible).
|
||||
|
||||
### Step 4: Load/replace data at runtime (depends on your product)
|
||||
|
||||
`ChartProfile`/UXML defines the "style and structure", while your data usually comes from business logic.
|
||||
|
||||
- Static display: fill data directly in the Profile `seriesData`
|
||||
- Dynamic display: write/replace `seriesData` at runtime (and keep `SeriesData.id` stable)
|
||||
|
||||
---
|
||||
|
||||
## 3. Folder layout recommendations for your chart library
|
||||
|
||||
Recommended to separate the "source configuration" and the "exported artifacts":
|
||||
|
||||
- `Assets/EasyChart/Library/Custom/`: the `ChartProfile` assets you maintain
|
||||
- `Assets/EasyChart/LibraryUxml/`: exported UXML (both Mirror and Backup exports live under this root)
|
||||
|
||||
When using multiple Libraries, exported assets are typically organized by library name:
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/<LibraryName>/...`
|
||||
|
||||
Recommended conventions:
|
||||
|
||||
- **Maintain Profiles only under `Assets/EasyChart/Library/...`** (as the source of truth)
|
||||
- **Pages reference only Mirror exports** (as your component library)
|
||||
- Treat Backup exports purely as **historical snapshots**
|
||||
|
||||
> Benefits:
|
||||
> - Your configuration source stays readable and editable
|
||||
> - Exported artifacts are reusable, composable, and can be used directly in UI Builder
|
||||
|
||||
---
|
||||
|
||||
## 4. Common issues & troubleshooting
|
||||
|
||||
- **Can't find the exported chart UXML in UI Builder**
|
||||
- First check whether files were generated under `Assets/EasyChart/LibraryUxml/`
|
||||
- If you use multiple Libraries, check under `Assets/EasyChart/LibraryUxml/<LibraryName>/`
|
||||
- Mirror/Backup exports may appear under `_Backups`; pages should not reference files under `_Backups`
|
||||
|
||||
- **The page references the UXML, but nothing shows at runtime**
|
||||
- Make sure the scene `UIDocument` references the page `.uxml` you edited
|
||||
- In the Library Editor, use Preview to verify the Profile renders correctly (rule out Profile configuration issues first)
|
||||
|
||||
- **You modified the Profile but the page didn't change**
|
||||
- The Profile is the "source"; the page references exported UXML
|
||||
- After modifying a Profile, re-export (Mirror), then return to the page and refresh/save
|
||||
|
||||
- **The component is visible in UI Builder, but still doesn't show at runtime**
|
||||
- First verify the scene `UIDocument` truly references the intended page (not an older page)
|
||||
- Then verify the Profile renders correctly in the Library Editor Preview
|
||||
|
||||
---
|
||||
|
||||
## 5. What to read next
|
||||
|
||||
- To quickly complete a single chart end-to-end: `00_01-QuickStart.md`
|
||||
- To use charts with UGUI (Canvas/RectTransform): `00_03-UGUIWorkflow.md`
|
||||
|
||||
---
|
||||
|
||||
## 6. Editor workflow & panels quick reference (Library Editor)
|
||||
|
||||
This section consolidates the editor workflow and panel explanations that were previously spread across multiple chapters, serving as a quick reference when working in `EasyChart/Library Editor`.
|
||||
|
||||
### 6.1 What are you editing? (ChartProfile)
|
||||
|
||||
The chart selected in the Library Editor is essentially a `ChartProfile` asset.
|
||||
|
||||
- It's a reusable configuration: the same Profile can be referenced by multiple scenes/prefabs.
|
||||
- It's previewable: changes in the editor can be previewed immediately.
|
||||
|
||||
### 6.2 Main areas of the Library Editor
|
||||
|
||||
You can think of the window as four areas:
|
||||
|
||||
- Left: Library (asset tree)
|
||||
- Center: Preview
|
||||
- Right: Inspector (configuration)
|
||||
- Right: Series (series and data)
|
||||
|
||||
Additionally, there is usually a JSON Injection panel on the left.
|
||||
|
||||
### 6.3 Library panel (asset tree)
|
||||
|
||||
Overview:
|
||||
|
||||
- Displays folders and `ChartProfile` (`.asset`) files in a tree.
|
||||
- Selecting a `ChartProfile` drives binding and refresh for Inspector/Series/Preview.
|
||||
- Supports create/rename/delete, drag-move, and sorting.
|
||||
|
||||
Selection logic:
|
||||
|
||||
- Selecting a folder: clears the Inspector/Series panels (no Profile to edit).
|
||||
- Selecting a ChartProfile: binds the right panels to that Profile.
|
||||
|
||||
Common actions (title bar and right-click menu; may vary by version):
|
||||
|
||||
- Folder: New Folder / New Chart / Export Folder to UXML (Mirror/Backup) / Rename / Delete
|
||||
- ChartProfile: Export to UXML / Clone / Rename / Delete
|
||||
|
||||
### 6.4 Preview panel
|
||||
|
||||
Preview renders the currently selected `ChartProfile` directly, so you can validate changes while editing.
|
||||
|
||||
Common issues:
|
||||
|
||||
- Preview is empty: make sure there is at least 1 `Serie` and its `seriesData` is not empty.
|
||||
- Data exists but looks wrong: verify CoordinateSystem matches the SeriesType, and axis ranges are not excluding your data.
|
||||
|
||||
### 6.5 Inspector panel
|
||||
|
||||
Inspector edits the serialized fields of the Profile (coordinate system, axes, grid, interaction, legend, etc.), and drives Preview updates.
|
||||
|
||||
Tip:
|
||||
|
||||
- If some field changes appear to have no effect, confirm the page references the exported UXML, not the Profile directly.
|
||||
|
||||
### 6.6 Series panel
|
||||
|
||||
The Series panel edits `ChartProfile.series` from a "chart-structure" perspective:
|
||||
|
||||
- Add/remove/reorder series
|
||||
- Choose `type` for each serie and edit `settings`
|
||||
- Edit `seriesData` (data points)
|
||||
|
||||
### 6.7 JSON Injection panel
|
||||
|
||||
Purpose: represent the current Profile as copyable JSON, and support parsing JSON to write back into the current Profile.
|
||||
|
||||
Recommended workflow:
|
||||
|
||||
1. Generate example JSON from the current Profile
|
||||
2. Copy it into an external editor for batch edits
|
||||
3. Paste it back and ApplyToChart
|
||||
|
||||
---
|
||||
|
||||
## 7. Axes & ranges (Axis & Range)
|
||||
|
||||
### 7.1 AxisType: Category vs Value
|
||||
|
||||
- Category: use `labels` to define discrete categories (A/B/C, or Mon/Tue/Wed).
|
||||
- Value: continuous numeric range (0~100, -3~3, 0~1e6).
|
||||
|
||||
#### 7.1.1 When to use Category
|
||||
|
||||
- The X axis is a sequence of text labels
|
||||
- You want points to land on `labels[i]`
|
||||
- Typical: bar charts (one bar group per category), line charts (aligned by categories)
|
||||
|
||||
Key points for Category:
|
||||
|
||||
- `labels[0]` corresponds to category index `0`
|
||||
- `labels[1]` corresponds to category index `1`
|
||||
|
||||
#### 7.1.2 When to use Value
|
||||
|
||||
- X or Y is a continuous numeric value (timestamp, money, temperature, etc.)
|
||||
- You want to scale/pan the axis by numeric values
|
||||
|
||||
Key points for Value:
|
||||
|
||||
- Axis range is usually computed by auto range (if enabled)
|
||||
- You can lock only one side (e.g. fix min=0 and keep max auto)
|
||||
|
||||
### 7.2 Category axis: labels and LabelPlacement
|
||||
|
||||
`labels` determines the number of categories and the label text.
|
||||
|
||||
`LabelPlacement` affects alignment:
|
||||
|
||||
- `Tick`: labels align to tick marks; better for Line/Scatter.
|
||||
- `CellCenter`: labels align to the center of a cell; better for Bar/Heatmap.
|
||||
|
||||
Common symptom:
|
||||
|
||||
- Bars appear between two labels: set `LabelPlacement` to `CellCenter`.
|
||||
|
||||
### 7.3 Value axis: autoRangeMin / autoRangeMax
|
||||
|
||||
If the range is "locked" and data is not visible, revert to full auto range first:
|
||||
|
||||
- Enable `autoRangeMin/autoRangeMax`
|
||||
|
||||
After it's visible, add business constraints gradually (e.g. make bar chart Y start at 0).
|
||||
|
||||
#### 7.3.1 Common template: Y axis starts at 0
|
||||
|
||||
- `axisType = Value`
|
||||
- Fix `minValue = 0`
|
||||
- `autoRangeMax = true`
|
||||
|
||||
#### 7.3.2 Common template: lock only Max (e.g. percentages)
|
||||
|
||||
- Fix `maxValue = 100`
|
||||
- `autoRangeMin = true`
|
||||
|
||||
### 7.4 rounding / unit / labelFormat
|
||||
|
||||
- rounding: snap the range to "nicer" numbers.
|
||||
- unit: display unit scaling (K/M, ten-thousand/million, etc.).
|
||||
- labelFormat: control number formatting (N0/N2/F1/percent, etc.).
|
||||
|
||||
#### 7.4.1 Unit display (showUnit / unitText)
|
||||
|
||||
When values are large (e.g. 10,000+), a common approach is showing a unit at the end of the axis (e.g. "k", "M").
|
||||
|
||||
#### 7.4.2 Quick troubleshooting
|
||||
|
||||
- Labels misaligned / bars centered between labels: check Category axis `LabelPlacement`
|
||||
- Range looks weird (too large/too small): check if min/max is locked; check rounding/unit
|
||||
- Too many decimals in ticks: set `labelFormat`
|
||||
|
||||
---
|
||||
|
||||
## 8. Series and data (Serie / SeriesData)
|
||||
|
||||
### 8.1 Serie (one series)
|
||||
|
||||
Each element in `ChartProfile.series` is a `Serie`:
|
||||
|
||||
- `name`
|
||||
- `type`
|
||||
- `visible`
|
||||
- `settings`
|
||||
- `labelSettings`
|
||||
- `seriesData`
|
||||
|
||||
Note: `settings` is usually a polymorphic object (`SerializeReference`). When you change `type`, the editor will try to preserve the last used settings for each type (better editing experience).
|
||||
|
||||
### 8.2 SeriesData (one data point)
|
||||
|
||||
Common `SeriesData` fields:
|
||||
|
||||
- `id`: stable identifier (tooltip/hover/hidden state).
|
||||
- `x`: X coordinate or Category index.
|
||||
- `value`: main value.
|
||||
- `y`: second dimension (scatter/heatmap, etc.).
|
||||
- `z`: third dimension (e.g. sizeMapping).
|
||||
- `name`: point name (often used by Radar/Pie/Ring).
|
||||
- `useColor` + `color`: point-level color override.
|
||||
|
||||
If interactions are enabled, keep `SeriesData.id` stable to avoid generating a new set of ids on every data refresh.
|
||||
|
||||
### 8.3 Matching SerieType and coordinate system
|
||||
|
||||
- Cartesian2D: Line/Bar/Scatter/Heatmap
|
||||
- Polar2D: Radar
|
||||
|
||||
It's not recommended to mix Polar and Cartesian series in a single (non-Pie) ChartProfile. If you do mix them, be careful about whether axes/grid semantics remain consistent.
|
||||
|
||||
### 8.4 Common data patterns (by type)
|
||||
|
||||
#### 8.4.1 Line
|
||||
|
||||
- Common: Category X + Value Y
|
||||
- Data point: `x=category index`, `value=value`
|
||||
- Continuous: Value X + Value Y
|
||||
- Data point: `x=x value`, `value=y value`
|
||||
|
||||
#### 8.4.2 Bar
|
||||
|
||||
- Category X + Value Y
|
||||
- One point per bar: `x=category index`, `value=bar height`
|
||||
- Grouped: multiple Bar series share the same Category X
|
||||
- Stacked: series with `stacked=true` and the same `stackGroup` will stack
|
||||
|
||||
#### 8.4.3 Scatter
|
||||
|
||||
- Common: X=Value, Y=Value
|
||||
- Recommended to explicitly write `x/y` for data points
|
||||
|
||||
#### 8.4.4 Heatmap
|
||||
|
||||
- Triplet: `x=column index`, `y=row index`, `value=intensity`
|
||||
|
||||
#### 8.4.5 Radar
|
||||
|
||||
- Typical: `x=dimension index`, `value=value of that dimension`, `name=dimension label`
|
||||
|
||||
### 8.5 Common data pitfalls (symptom-driven)
|
||||
|
||||
- Category chart uses Category axis on X, but point `x` is not 0/1/2...
|
||||
- Symptom: points/bars don't align with labels
|
||||
- Fix: ensure `x=category index`, or change X axis to Value
|
||||
|
||||
- NaN/Infinity appears
|
||||
- Symptom: chart doesn't render, range explodes
|
||||
- Fix: filter invalid values at the data source
|
||||
|
||||
- Chart is not visible (but `seriesData` is not empty)
|
||||
- Check: coordinate system matches (Cartesian vs Polar)
|
||||
- Check: AxisType matches your data meaning
|
||||
|
||||
- Interactions/tooltip mapping feels wrong
|
||||
- Check: `SeriesData.id` is stable (don't randomly regenerate ids on each refresh)
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 0bbaa7b4363982f4ebefccc797cd0dcd
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/00_02-WorkflowAndLibrary.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,129 @@
|
||||
# UGUI Workflow
|
||||
|
||||
Goal of this chapter: use EasyChart with a UGUI workflow (Canvas/RectTransform), and understand the choice between two rendering modes:
|
||||
|
||||
- `ScreenSpaceOverlay`: best visual quality (no RenderTexture), but typically visible only in the Game view
|
||||
- `WorldSpace`: visible in both Scene/Game views (uses RenderTexture), suitable for 3D world-space UI
|
||||
|
||||
---
|
||||
|
||||
## 1. Recommended approach: UGUIChartBridge
|
||||
|
||||
Recommended component: `UGUIChartBridge`.
|
||||
|
||||
Its role is:
|
||||
|
||||
- Still uses **UI Toolkit `ChartElement`** as the core chart renderer
|
||||
- Bridges the chart so it "fits" onto a target UGUI `RectTransform`
|
||||
|
||||
So you get the best of both:
|
||||
|
||||
- Chart capability + UI Toolkit rendering
|
||||
- UGUI scene/prefab layout workflow and habits
|
||||
|
||||
---
|
||||
|
||||
## 2. Common prerequisites
|
||||
|
||||
No matter which mode you choose, prepare the following first:
|
||||
|
||||
- A `ChartProfile` to display (recommended: clone one from `EasyChart/Library Editor` and modify it)
|
||||
- A `PanelSettings` asset, and assign it to `UGUIChartBridge` via `Panel Settings Asset`
|
||||
|
||||
> Note: providing `Panel Settings Asset` is usually better for font rendering and overall stability.
|
||||
|
||||
---
|
||||
|
||||
## 3. Screen Space Overlay (recommended for HUD/panels)
|
||||
|
||||
### Use cases
|
||||
|
||||
- HUD, UI panels, dialogs
|
||||
- You care most about clarity and visual quality
|
||||
|
||||
### Characteristics
|
||||
|
||||
- No RenderTexture
|
||||
- Typically visible only in the Game view
|
||||
|
||||
### Setup steps (overview)
|
||||
|
||||
1. Create a `Canvas`
|
||||
2. Under the Canvas, create a node with `RectTransform` (`Image` or an empty GameObject both work)
|
||||
3. Add `UGUIChartBridge`
|
||||
4. Configure:
|
||||
- `Profile`
|
||||
- `Panel Settings Asset`
|
||||
- `Render Mode = ScreenSpaceOverlay`
|
||||
- `Sort Order` (controls overlay order; effective only in Screen Space Overlay mode)
|
||||
|
||||
Key points:
|
||||
|
||||
- This mode renders the chart inside a runtime-created/reused `UIDocument`.
|
||||
- If the chart is covered by other UI, increase `Sort Order` first.
|
||||
|
||||
---
|
||||
|
||||
## 4. World Space (recommended for 3D world-space panels)
|
||||
|
||||
### Use cases
|
||||
|
||||
- Billboards/screens/panels inside a 3D world
|
||||
- You want to see the result in the Scene view as well
|
||||
|
||||
### Characteristics
|
||||
|
||||
- Uses RenderTexture
|
||||
- Usually visible in both Scene and Game views
|
||||
- Visual quality can be affected by RenderTexture resolution
|
||||
|
||||
### Setup steps (overview)
|
||||
|
||||
1. Create a `Canvas`
|
||||
2. Set `Render Mode = World Space`
|
||||
3. Under the Canvas, create a node with `RectTransform` (recommended: `RawImage`)
|
||||
4. Add `UGUIChartBridge`
|
||||
5. Configure:
|
||||
- `Profile`
|
||||
- `Panel Settings Asset`
|
||||
- `Render Mode = WorldSpace`
|
||||
|
||||
Key points:
|
||||
|
||||
- World Space mode creates and maintains a `RenderTexture` and displays it via `RawImage`.
|
||||
- Clarity is strongly tied to the `RenderTexture` resolution, which usually comes from the target `RectTransform` width/height.
|
||||
- If the chart looks blurry, make the target `RectTransform` larger first (e.g. 600x400+).
|
||||
|
||||
---
|
||||
|
||||
## 5. Mode selection (quick conclusion)
|
||||
|
||||
- Prefer **ScreenSpaceOverlay** when:
|
||||
- you're building traditional UI (HUD/panels)
|
||||
- clarity is your top priority
|
||||
|
||||
- Prefer **WorldSpace** when:
|
||||
- your chart needs to appear in a 3D world
|
||||
- you want it visible in the Scene view
|
||||
|
||||
---
|
||||
|
||||
## 6. Common issues & troubleshooting
|
||||
|
||||
- **Not visible at runtime**
|
||||
- Make sure the target `RectTransform` size is not 0
|
||||
- Make sure `Profile` is assigned, and the Profile renders correctly in Library Editor Preview
|
||||
- If fonts look wrong, check whether `Panel Settings Asset` is missing
|
||||
|
||||
- **Blurry chart in World Space mode**
|
||||
- Increase the target `RectTransform` size (this increases RenderTexture resolution)
|
||||
- Avoid frequent aggressive scaling at runtime (may trigger RenderTexture resizing)
|
||||
|
||||
---
|
||||
|
||||
## 7. Alternative: export as a UGUI Prefab
|
||||
|
||||
If your version provides `Export UGUI Prefab`:
|
||||
|
||||
- You can export the Profile to a UGUI prefab and use it directly under a Canvas
|
||||
- Coverage for interaction/compatibility depends on the exporter version
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: f9cd0878be8f4f3478a0d1f8b33871b8
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/00_03-UGUIWorkflow.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,182 @@
|
||||
# Runtime Data Injection (UI Toolkit)
|
||||
|
||||
This chapter explains how to inject data into `ChartElement` at runtime in a UI Toolkit workflow.
|
||||
|
||||
Related component: `EasyChartDataSource`
|
||||
|
||||
---
|
||||
|
||||
## 1. When should you use this approach?
|
||||
|
||||
- Your chart is built with UI Toolkit (`UIDocument` + UXML + `ChartElement`)
|
||||
- You want a set of injection APIs that are easier to call from gameplay/business logic (labels / values / x-y / pie / ring)
|
||||
- Or you want to inject a JSON payload directly (`ChartFeed`)
|
||||
|
||||
---
|
||||
|
||||
## 2. Quick start (recommended flow)
|
||||
|
||||
1. Prepare a `UIDocument` in the scene, and make sure there is a `ChartElement` in your UXML.
|
||||
2. Add `EasyChartDataSource` to the same GameObject that has the `UIDocument`.
|
||||
3. Fill in the Inspector fields:
|
||||
- `uiDocument`
|
||||
- `chartElementName` (default: `main-chart`, matches the `name` of the `ChartElement` in UXML)
|
||||
- `profile` (optional, but strongly recommended: lets style/Series type come from an editor-authored `ChartProfile`)
|
||||
4. At runtime, call from code:
|
||||
- `SetCategoryLabels(...)`
|
||||
- `SetSeriesValues(...)` / `SetSeriesXY(...)`
|
||||
- or `ApplyJson(...)`
|
||||
|
||||
Internally, the component will:
|
||||
|
||||
- Find the target `ChartElement` from `UIDocument.rootVisualElement`
|
||||
- Initialize chart data from `profile` when needed
|
||||
- Modify `ChartElement.Data` and call `RefreshData()`
|
||||
|
||||
---
|
||||
|
||||
## 3. Inspector fields
|
||||
|
||||
Key fields of `EasyChartDataSource`:
|
||||
|
||||
- `uiDocument`
|
||||
- Points to the current UI `UIDocument`.
|
||||
- If not set, the script will try `GetComponent<UIDocument>()`.
|
||||
|
||||
- `chartElementName`
|
||||
- The `name` of the target `ChartElement` (the UXML/USS name). Default is `main-chart`.
|
||||
- If you want JSON `chartId/chartName` to locate the chart automatically, keep the `ChartElement.name` consistent with those values (see section 5).
|
||||
|
||||
- `profile`
|
||||
- Optional.
|
||||
- If set, the component assigns `ChartElement.Profile = profile` to initialize/preserve styles, Series structure, etc.
|
||||
|
||||
- `playAnimationOnRefresh`
|
||||
- After each injection, call `RefreshData(..., playAnimation: playAnimationOnRefresh)`.
|
||||
|
||||
- `allowCreateSeriesFromFeed`
|
||||
- When injecting via JSON (`ApplyJson`), if a series in the feed does not match any existing Serie:
|
||||
- `false` (default): do not create new Serie; only update matched ones.
|
||||
- `true`: allow creating new Serie from the feed (may rebuild renderers).
|
||||
|
||||
---
|
||||
|
||||
## 4. Common injection APIs (without JSON)
|
||||
|
||||
### 4.1 Set category axis labels
|
||||
|
||||
`SetCategoryLabels(labels, axisId = AxisId.XBottom)`
|
||||
|
||||
- Sets the axis to Category and overwrites `labels`.
|
||||
|
||||
### 4.2 Single-series Y values (auto x=0..n-1)
|
||||
|
||||
`SetSeriesValues("Sales", values)`
|
||||
|
||||
- Finds/creates a Serie by default (default type is Line; it does not force the type to change).
|
||||
- Writes to `SeriesData.value` and sets `SeriesData.x` to the index.
|
||||
|
||||
### 4.3 XY points
|
||||
|
||||
`SetSeriesXY("Scatter", x, y)`
|
||||
|
||||
- Writes `x[]` into `SeriesData.x` and `y[]` into `SeriesData.value`.
|
||||
|
||||
### 4.4 Pie / Ring injection
|
||||
|
||||
- `SetPie(serieName, names, values)`
|
||||
- Forces the Serie type to `Pie`.
|
||||
- Uses `SeriesData.name` as slice name and `SeriesData.value` as slice value.
|
||||
|
||||
- `SetRing(serieName, names, percents)`
|
||||
- Forces the Serie type to `RingChart`.
|
||||
- Uses `SeriesData.name` as ring name and `SeriesData.value` as progress value.
|
||||
|
||||
---
|
||||
|
||||
## 5. JSON injection (ChartFeed)
|
||||
|
||||
You can call: `ApplyJson(json)`
|
||||
|
||||
This method parses JSON into `ChartFeed` and applies it to `ChartElement.Data`.
|
||||
|
||||
### 5.1 `ChartFeed` schema
|
||||
|
||||
```json
|
||||
{
|
||||
"chartId": "optional",
|
||||
"chartName": "optional",
|
||||
"axes": [
|
||||
{
|
||||
"axisId": "XBottom",
|
||||
"labels": ["Mon", "Tue", "Wed"]
|
||||
}
|
||||
],
|
||||
"series": [
|
||||
{
|
||||
"serieId": "optional",
|
||||
"name": "optional",
|
||||
"type": "Line",
|
||||
"datas": [
|
||||
{ "x": 0, "value": 12 },
|
||||
{ "x": 1, "value": 18 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
See the runtime code `Scripts/Runtime/Feed/ChartFeed.cs` for the exact fields.
|
||||
|
||||
### 5.2 ChartElement lookup rules (`chartId` / `chartName`)
|
||||
|
||||
Internally, `ApplyJson` tries:
|
||||
|
||||
- If `chartId` is provided: `rootVisualElement.Q<ChartElement>(chartId)` first
|
||||
- Else if `chartName` is provided: try `Q<ChartElement>(chartName)`
|
||||
- If still not found: fall back to `chartElementName` (default `main-chart`)
|
||||
|
||||
Therefore:
|
||||
|
||||
- If you only have one chart, keeping the default is fine.
|
||||
- If you have multiple `ChartElement` in one UI, it's recommended to align each chart's `name` with the feed `chartId` or `chartName`.
|
||||
|
||||
### 5.3 Series matching and type override
|
||||
|
||||
`ApplyJson` checks whether the JSON contains `"type":`. If present, it assumes you want to allow type override (`allowTypeOverride=true`).
|
||||
|
||||
Serie matching rules:
|
||||
|
||||
- If `serieId` is not empty: match by `Serie.id`
|
||||
- Else if `name` is not empty: match by `Serie.name`
|
||||
- Else (index mode): match by feed index (i-th to i-th)
|
||||
|
||||
When no Serie can be matched:
|
||||
|
||||
- `allowCreateSeriesFromFeed=false` (default): the feed series is skipped (no creation).
|
||||
- `allowCreateSeriesFromFeed=true`: create a new Serie using the feed `type/name/serieId`.
|
||||
|
||||
For matched Serie:
|
||||
|
||||
- Only when `allowTypeOverride=true` and it's not index mode, overriding `id/name/type` is allowed.
|
||||
|
||||
---
|
||||
|
||||
## 6. Common issues & troubleshooting
|
||||
|
||||
- **Not visible / TryGetChart failed**
|
||||
- Make sure `uiDocument` is assigned correctly
|
||||
- Make sure the `ChartElement` `name` in UXML matches `chartElementName`
|
||||
|
||||
- **JSON parse failed**
|
||||
- When `EasyChartDataSource` parses JSON:
|
||||
- it tries Newtonsoft first (if `Newtonsoft.Json` exists in your project)
|
||||
- otherwise falls back to Unity `JsonUtility`, normalizing string forms like `type/axisId` into enum integers before parsing
|
||||
- Recommendation: start from a known-good JSON (e.g. generated from the editor JSON panel) and modify it.
|
||||
|
||||
- **Series mismatch after injection / updated the wrong line**
|
||||
- Prefer `serieId` for stable matching.
|
||||
- If you only use `name` and there are multiple series with the same name, the script uses the first one and logs a warning.
|
||||
|
||||
- **JSON wanted to add a Serie but none was added**
|
||||
- Enable `allowCreateSeriesFromFeed`.
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: ad05086ead6baa54ea109ad556ef4642
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/00_04-RuntimeDataInjectionUIToolKit.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,155 @@
|
||||
# Runtime Data Injection (UGUI)
|
||||
|
||||
Related scripts: `UGUIRuntimeJsonInjection`, `UGUIRuntimeJsonInjectionEditor`
|
||||
|
||||
This chapter explains how to inject data into charts at runtime via JSON in a UGUI workflow (`UGUIChartBridge`).
|
||||
|
||||
---
|
||||
|
||||
## 1. When should you use this approach?
|
||||
|
||||
- You have JSON coming from a server/business layer (or you want to quickly edit JSON at runtime)
|
||||
- You want an editor-like workflow: "Generate example → Modify → Apply" (similar to the `JSON Injection` panel)
|
||||
- You already configured the chart structure (style/axes/Series types) via `ChartProfile`
|
||||
|
||||
This injector is primarily designed for **updating data**. Structural changes (e.g. adding Series, force-overriding Series types) are not its main goal.
|
||||
|
||||
---
|
||||
|
||||
## 2. Quick start (recommended flow)
|
||||
|
||||
1. Set up `UGUIChartBridge` in the scene (and make sure `Profile` is assigned).
|
||||
2. Add `UGUIRuntimeJsonInjection` to the same GameObject.
|
||||
3. Click **Generate Example JSON** to generate sample JSON that matches your current Profile.
|
||||
4. Modify the data in the `JSON Content` text box.
|
||||
5. Click **Apply JSON to Chart**.
|
||||
|
||||
Internally, the component will:
|
||||
|
||||
- Parse JSON → convert to `ChartFeed`
|
||||
- Apply `ChartFeed` to `UGUIChartBridge.Profile`
|
||||
- Call `_bridge.Refresh()` to redraw
|
||||
|
||||
---
|
||||
|
||||
## 3. Component and Inspector fields
|
||||
|
||||
`UGUIRuntimeJsonInjection` must be on the same GameObject as `UGUIChartBridge` (the script has `[RequireComponent(typeof(UGUIChartBridge))]`).
|
||||
|
||||
### 3.1 JSON Generation Settings
|
||||
|
||||
- **Example Mode (`ChartJsonExampleMode`)**
|
||||
- Controls the format when generating example JSON.
|
||||
- Generally recommended to start with `Standard` or `Standard_Axis` (more intuitive).
|
||||
|
||||
- **Data Mode (`ChartJsonDatasMode`)**
|
||||
- Controls how `datas` is represented.
|
||||
- `Standard`: `datas` is an array of objects (e.g. `{ "x": 0, "value": 12 }`).
|
||||
- `Values`: `datas` is an array of raw numbers (shorter).
|
||||
- Note: this format requires the "flexible parser" in `ChartJsonUtils` (reflection-based parsing via Newtonsoft). If your project does not include Newtonsoft (`Newtonsoft.Json` / `Unity.Newtonsoft.Json`), parsing may fail.
|
||||
- Therefore **`Standard` is recommended by default**, unless you're sure Newtonsoft is available.
|
||||
|
||||
- **API Envelope (`UseApiEnvelope`)**
|
||||
- When generating example JSON, whether to wrap it with an API envelope:
|
||||
- `{ "code": 200, "message": "success", "data": { ...the real ChartFeed... } }`
|
||||
- When applying, it will also try to extract `data` automatically.
|
||||
|
||||
- **Auto Generate (`AutoGenerateJson`)**
|
||||
- Automatically regenerates example JSON when you change `Example Mode / Data Mode / API Envelope`.
|
||||
|
||||
### 3.2 JSON Content
|
||||
|
||||
- **JSON Content (`JsonContent`)**
|
||||
- The JSON string to inject.
|
||||
- If empty, clicking Apply will log a warning and return.
|
||||
|
||||
---
|
||||
|
||||
## 4. JSON format (ChartFeed)
|
||||
|
||||
The underlying data model is `ChartFeed`:
|
||||
|
||||
```json
|
||||
{
|
||||
"chartId": "optional",
|
||||
"chartName": "optional",
|
||||
"axes": [
|
||||
{
|
||||
"axisId": "XBottom",
|
||||
"labels": ["Mon", "Tue", "Wed"]
|
||||
}
|
||||
],
|
||||
"series": [
|
||||
{
|
||||
"serieId": "optional",
|
||||
"name": "optional",
|
||||
"type": "Line",
|
||||
"datas": [
|
||||
{ "x": 0, "value": 12 },
|
||||
{ "x": 1, "value": 18 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Field-to-code mapping notes:
|
||||
|
||||
- `chartId` / `chartName`
|
||||
- In the `UGUIRuntimeJsonInjection` injection path, it **will not overwrite** the Profile `chartId/chartName` (it calls `ChartJsonUtils.ApplyFeedToProfile(profile, feed)` with `allowMetaOverwrite=false`).
|
||||
- But these fields can help other injectors (e.g. `EasyChartDataSource`) locate a `ChartElement` by name/ID in the UI tree.
|
||||
|
||||
- `axes[]`
|
||||
- `axisId` is the `AxisId` enum (e.g. `XBottom`, `XTop`, `YLeft`, `YRight`).
|
||||
- If `labels` exists, that axis is treated as Category and labels are overwritten.
|
||||
|
||||
- `series[]`
|
||||
- **Matching priority**:
|
||||
- If `serieId` is provided: match by `Serie.id`
|
||||
- Else if `name` is provided: match by `Serie.name`
|
||||
- Else (both `serieId` and `name` are empty): match by index (feed 0 -> profile 0)
|
||||
- `type`
|
||||
- Mainly used when generating example JSON.
|
||||
- In the current injection path:
|
||||
- For existing matched Serie: it **will not force the type to change** (meta overwrite is not allowed).
|
||||
- For newly created Serie in "index mode + feed exceeds Profile series count": it will use the feed `type` as the new Serie type.
|
||||
- `datas[]` for each point:
|
||||
- numeric `x/y/z/value`
|
||||
- optional `id/name`
|
||||
- optional `useColor/color`
|
||||
|
||||
---
|
||||
|
||||
## 5. What happens when you apply? (injection flow)
|
||||
|
||||
When you click **Apply JSON to Chart**:
|
||||
|
||||
1. If the JSON is wrapped in an API envelope (contains `data`), it first tries to extract the object under `data`.
|
||||
2. Calls `ChartJsonUtils.TryDeserializeFeed(json, out feed)` to deserialize into `ChartFeed`.
|
||||
- Tries Newtonsoft first (if available); otherwise falls back to Unity `JsonUtility`.
|
||||
- String values like `type: "Line"` / `axisId: "XBottom"` are normalized to enum values in the fallback path before parsing.
|
||||
3. Calls `ChartJsonUtils.ApplyFeedToProfile(_bridge.Profile, feed)` to write the feed back into the Profile.
|
||||
4. Calls `_bridge.Refresh()` to redraw.
|
||||
|
||||
---
|
||||
|
||||
## 6. Common issues & troubleshooting
|
||||
|
||||
- **Click Apply does nothing / console warns: No UGUIChartBridge or ChartProfile found**
|
||||
- Make sure the object has `UGUIChartBridge`
|
||||
- Make sure `UGUIChartBridge.Profile` is assigned
|
||||
|
||||
- **Error: Failed to parse JSON**
|
||||
- Generate a known-good JSON first, then modify it.
|
||||
- If your API response has an outer wrapper, enable `API Envelope`, or ensure the JSON `data` field contains the `ChartFeed`.
|
||||
|
||||
- **JSON applied but data didn't change / only partially changed**
|
||||
- Check how `series` is matched (`serieId` / `name` / index mode).
|
||||
- If you use `serieId/name` matching: make sure the corresponding Serie exists in the Profile (this injection path won't auto-create new Serie in this mode).
|
||||
- If you use "index mode" (both `serieId` and `name` are empty):
|
||||
- When feed `series[]` count **exceeds** the Profile series count, it will auto-create additional Serie.
|
||||
- If you don't want auto-creation, provide an explicit `name` or `serieId` for each serie.
|
||||
|
||||
- **After injecting in Play Mode, the Profile asset became dirty**
|
||||
- Injection essentially "applies the feed to the `ChartProfile`". If you drag the asset directly into the bridge, runtime changes may mark the asset dirty.
|
||||
- If you don't want to modify the asset, instantiate a runtime copy of the Profile and inject into that copy.
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 9b5cedc13ea816948a0163432c6dafd9
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/00_05-RuntimeDataInjectionUGUI.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,168 @@
|
||||
# Editor Workflow and Panel Guide
|
||||
|
||||
This chapter helps you understand **what to edit where** in `EasyChart/Library Editor`, and the common editing workflows (create, clone, preview, export).
|
||||
|
||||
---
|
||||
|
||||
## 1. What are you editing? (ChartProfile)
|
||||
|
||||
The chart selected in the Library Editor is essentially a `ChartProfile` asset.
|
||||
|
||||
- It is a **reusable configuration**: the same Profile can be referenced by multiple scenes/prefabs.
|
||||
- It is a **previewable configuration**: after modifying it in the editor, you can see the preview update immediately.
|
||||
|
||||
Recommendation: put your own Profiles under `Assets/EasyChart/Library/Custom/` (or a folder agreed by your team).
|
||||
|
||||
---
|
||||
|
||||
## 2. The three core areas of the Library Editor
|
||||
|
||||
Although UI details may change slightly across versions, you can understand the overall layout like this:
|
||||
|
||||
### 2.1 Left: Library Tree
|
||||
|
||||
This shows the folder structure where chart assets (`ChartProfile`) are located.
|
||||
|
||||
Common actions:
|
||||
|
||||
- Right-click a folder:
|
||||
- `New Folder...`: create a subfolder
|
||||
- `New Chart...`: create a new `ChartProfile`
|
||||
- Right-click a chart:
|
||||
- `Clone`: duplicate a new Profile (to create variants)
|
||||
- `Export to UXML`: export (if your workflow needs to sync/export configuration into UXML)
|
||||
- `Ping`: locate the asset in the Project window
|
||||
- `Rename...` / `Delete`
|
||||
|
||||
> Tip: use `Clone` to create variants like "same chart with different colors / different data scale", instead of configuring from scratch.
|
||||
|
||||
### 2.2 Right: Inspector
|
||||
|
||||
This is where you do most of your editing.
|
||||
|
||||
It typically includes:
|
||||
|
||||
- **Basic settings**:
|
||||
- `coordinateSystem`
|
||||
- `padding` (if present)
|
||||
- `animationDuration` (if present)
|
||||
- **Series list**: each Serie represents a line, a group of bars, a scatter series, etc.
|
||||
- **Axes**:
|
||||
- choose which `XAxisId/YAxisId` to use
|
||||
- configure display/labels/range/ticks of the corresponding `AxisConfig`
|
||||
- **Legend / Tooltip / Grid**: if your version exposes these settings
|
||||
|
||||
> Practical tip: configure `coordinateSystem`, `Series`, and `Axes` first. The rest is "nice to have".
|
||||
|
||||
### 2.3 Preview
|
||||
|
||||
Use it to check:
|
||||
|
||||
- whether data exists
|
||||
- whether axis ranges are correct
|
||||
- whether labels are crowded/misaligned
|
||||
- Tooltip / Legend interactions (if enabled)
|
||||
|
||||
When preview looks wrong, troubleshoot in this order:
|
||||
|
||||
1. Is `coordinateSystem` correct?
|
||||
2. Does `series` contain at least 1 serie and data points?
|
||||
3. Does the axis `axisType` match the meaning of your data `x/y`?
|
||||
4. Is the Value axis range locked manually (`autoRangeMin/autoRangeMax`)?
|
||||
|
||||
### 2.4 JSON Injection
|
||||
|
||||
Below the left panel there is a **JSON Injection** area, used to:
|
||||
|
||||
- quickly generate an "injection JSON example" for the selected `ChartProfile`
|
||||
- apply your pasted/edited JSON back to the selected Profile (`ApplyToChart`)
|
||||
|
||||
Common controls:
|
||||
|
||||
- **API Envelope**: whether to wrap with `{ code, message, data }`.
|
||||
- When enabled: generated JSON will be wrapped; parsing can also recognize it and automatically extract `data`.
|
||||
- **Feed Mode**: the structure/field completeness of the example JSON (to support different injection protocols).
|
||||
- **Datas Format**: the point format inside the `datas` field (e.g. compact arrays, or more readable objects).
|
||||
- **ApplyToChart**: parse JSON from the text box and write it back into the selected `ChartProfile`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Recommended editing flow (from zero to reusable)
|
||||
|
||||
### Step 1: Create or select a ChartProfile
|
||||
|
||||
- New: right-click the target folder and choose `New Chart...`
|
||||
- Existing: click to select in the left tree
|
||||
|
||||
If you prefer the "clone first, then modify" approach (recommended):
|
||||
|
||||
- First, use **Clone** in the top toolbar to create your own Library
|
||||
- Then in your own library, right-click a Profile -> `Clone` to create variants
|
||||
|
||||
### Step 2: Decide the coordinate system
|
||||
|
||||
- `Cartesian2D`: Line/Bar/Scatter/Heatmap
|
||||
- `Polar2D`: Radar
|
||||
|
||||
> Tip: decide the coordinate system first, then choose SeriesType, to avoid style/axis confusion after switching later.
|
||||
|
||||
### Step 3: Configure Series
|
||||
|
||||
- Add Series
|
||||
- Set `type`
|
||||
- Fill `seriesData`
|
||||
|
||||
Tip: start with a small number of points (3–8) to validate the look, then scale up.
|
||||
|
||||
### Step 4: Configure Axes
|
||||
|
||||
Most common combination:
|
||||
|
||||
- X: Category
|
||||
- put text into `labels`
|
||||
- Y: Value
|
||||
- enable auto range (default)
|
||||
|
||||
When you want more professional axis formatting:
|
||||
|
||||
- Use `labelFormat` (e.g. `F1`, `N0`)
|
||||
- Use `autoRangeMin/autoRangeMax` to lock only one side of the range
|
||||
- If the Value axis needs a unit:
|
||||
- `showUnit=true`
|
||||
- `unitText="items"/"10k"`
|
||||
- use `unitLabelStyle` to adjust font/color/position
|
||||
|
||||
### Step 5: Clone variants (recommended)
|
||||
|
||||
When you need multiple versions of the same chart (colors, font size, slightly different axis display):
|
||||
|
||||
- Right-click the chart -> `Clone`
|
||||
- Modify only the differences
|
||||
|
||||
This keeps style consistent and is easier for version management.
|
||||
|
||||
When you want to use the chart in UI:
|
||||
|
||||
- UI Toolkit: export to UXML, then compose the page in UI Builder (see demo scene `Assets/EasyChart/Demo/Scenes/EasyChart_QuickStart.unity` and template `Assets/EasyChart/Demo/UIToolKit/NewUXMLTemplate.uxml`)
|
||||
- UGUI: export to a UGUI prefab and use it in a Canvas/RectTransform workflow
|
||||
|
||||
---
|
||||
|
||||
## 4. Common pitfalls (quick diagnosis)
|
||||
|
||||
- **Nothing shows up**
|
||||
- Is `seriesData` empty?
|
||||
- Does `AxisType` match the meaning of your data (does the Category axis have labels)?
|
||||
|
||||
- **Value axis looks weird (range too large/too small)**
|
||||
- Check `autoRangeMin/autoRangeMax`
|
||||
- Check whether rounding/unit snapped the range to an unsuitable unit
|
||||
|
||||
- **Bars and labels are misaligned**
|
||||
- Check `LabelPlacement` (Tick vs CellCenter)
|
||||
|
||||
---
|
||||
|
||||
## Next
|
||||
|
||||
- `00_02-WorkflowAndLibrary.md`: axis types, label placement, auto range, rounding, and unit display are merged into section 7
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: b670d01dcf088d140acda07de2d3964f
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/01_01-EditorWorkflow.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,162 @@
|
||||
# Library Panel (Asset Tree)
|
||||
|
||||
This chapter explains the **Library** panel on the left side of `Unity Easy Chart/Library Editor`. It manages your chart assets (`ChartProfile`) and folder structure, and determines which Profile the panels on the right are currently editing.
|
||||
|
||||
---
|
||||
|
||||
## Feature Overview
|
||||
|
||||
- **Structure Display**: shows folders and `ChartProfile` (`.asset`) under the library root in a tree.
|
||||
- **Selection Drives Editing**: selecting a `ChartProfile` triggers:
|
||||
- Inspector binds to that Profile
|
||||
- Series binds to that Profile `series`
|
||||
- Preview refresh
|
||||
- JSON Injection generates example JSON (and can Apply back to that Profile)
|
||||
- **Asset Management**: create/rename/delete, drag-move, expand/collapse, etc.
|
||||
|
||||
---
|
||||
|
||||
## UI Structure
|
||||
|
||||
The header bar at the top of the Library panel typically contains (left to right):
|
||||
|
||||
- **Library**: title.
|
||||
- **(Current Library Name)**: shows the selected library/root name (useful if you have multiple libraries).
|
||||
- **Menu**: entry for common actions (similar to right-click, but centralized).
|
||||
- **Help**: opens this chapter.
|
||||
|
||||
In the global window toolbar at the top, on the right side of the Library dropdown you may see:
|
||||
|
||||
- **+**: add a new Library.
|
||||
- **-**: delete the current Library.
|
||||
- **Clone**: duplicate the current Library (see below).
|
||||
|
||||
Below the header is:
|
||||
|
||||
- **TreeView**:
|
||||
- folders
|
||||
- `ChartProfile` assets (chart configuration assets)
|
||||
|
||||
---
|
||||
|
||||
## Selection Logic (Important)
|
||||
|
||||
- **When a Folder is Selected**:
|
||||
- Inspector/Series on the right are cleared (no Profile to edit).
|
||||
- JSON Injection switches to a "no selected Profile" example or keeps the current example (implementation-dependent).
|
||||
- **When a ChartProfile is Selected**:
|
||||
- Inspector/Series immediately bind to the Profile's serialized data.
|
||||
- Any field change triggers a delayed Preview refresh (`delayCall`).
|
||||
|
||||
Tip: if the right panels are empty, first confirm a `ChartProfile` (not a folder) is selected on the left.
|
||||
|
||||
---
|
||||
|
||||
## Common Actions (Header Menu)
|
||||
|
||||
Clicking **Menu** (the small menu icon) opens an action menu. Common items include:
|
||||
|
||||
- **New Chart**: create a new `ChartProfile` under the target folder.
|
||||
- **New Folder**: create a new folder under the target folder.
|
||||
- **Refresh**: rescan and rebuild the tree (useful after manual moves/copies in the Project view).
|
||||
- **Expand All**: expand all folders.
|
||||
- **Collapse All**: collapse all folders.
|
||||
- **Rename / Delete**: rename/delete the currently selected item.
|
||||
- If the library root is selected, these are typically disabled.
|
||||
- **Export UGUI Prefab** (available when a Profile is selected): export the selected Profile as a UGUI prefab (for runtime display).
|
||||
|
||||
### How the Target Folder is Determined
|
||||
|
||||
**New Chart / New Folder** create assets under the "target folder":
|
||||
|
||||
- If a **folder** is selected: the target is that folder.
|
||||
- If a **ChartProfile** is selected: the target is usually the Profile's parent folder.
|
||||
- If nothing is selected or unclear: the target usually falls back to the library root.
|
||||
|
||||
---
|
||||
|
||||
## Clone Library
|
||||
|
||||
When you need to duplicate a full chart library (including Profiles and UXML) into a new library (for branching/versions/theme variants), use **Clone** in the top toolbar.
|
||||
|
||||
### Entry and Usage
|
||||
|
||||
- Click the **Clone** icon to the right of the Library dropdown.
|
||||
- Enter the new library name and confirm.
|
||||
|
||||
### What Gets Cloned
|
||||
|
||||
- `Assets/EasyChart/Library/<CurrentLibrary>` is copied to `Assets/EasyChart/Library/<NewLibrary>`.
|
||||
- `Assets/EasyChart/LibraryUxml/<CurrentLibrary>` is copied to `Assets/EasyChart/LibraryUxml/<NewLibrary>` (if the source UXML folder exists).
|
||||
|
||||
### Limitations and Naming Rules
|
||||
|
||||
- The `<Root>` library cannot be cloned.
|
||||
- The new name is sanitized (invalid filename characters removed); blank names are ignored.
|
||||
- If the target library already exists (folder already exists), it will prompt and cancel.
|
||||
|
||||
### After Cloning
|
||||
|
||||
- Automatically switches the current Library selection to the new library.
|
||||
- Refreshes the Library dropdown and tree view, and triggers refresh for right panels/preview.
|
||||
|
||||
---
|
||||
|
||||
## Common Actions (Context Menu)
|
||||
|
||||
You can also **right-click** items in the tree:
|
||||
|
||||
### Right-click a Folder
|
||||
|
||||
- **New Folder...**: create a subfolder.
|
||||
- **New Chart...**: create a new `ChartProfile` in that folder.
|
||||
- **Export Folder to UXML (Mirror/Backup)**: export the folder contents to UXML (backup/distribution/versioning).
|
||||
- **Rename...**: rename the folder.
|
||||
- **Delete**: delete the folder (destructive; be careful).
|
||||
|
||||
### Right-click a ChartProfile
|
||||
|
||||
- **Export to UXML**: export UXML for the current Profile.
|
||||
- **Clone**: clone a new Profile (quickly derive a similar chart).
|
||||
- **Rename...**: rename the asset (also tries to sync-update `profile.name` / `profile.chartName`).
|
||||
- **Ping**: locate the asset in the Project view.
|
||||
- **Delete**: delete the asset.
|
||||
|
||||
---
|
||||
|
||||
## Drag-move and Sorting
|
||||
|
||||
The Library tree supports dragging folders or `ChartProfile`:
|
||||
|
||||
- **Drag a ChartProfile onto a folder**: triggers `AssetDatabase.MoveAsset` to move the `.asset` into the target folder.
|
||||
- **Drag a folder onto a folder**: moves the whole folder under the target folder.
|
||||
|
||||
Notes:
|
||||
|
||||
- If the target is invalid (dragging into itself/child folder), it will be rejected (cursor shows Rejected).
|
||||
- After moving, the tree refreshes automatically.
|
||||
|
||||
---
|
||||
|
||||
## Rename (Double-click and Inline Editing)
|
||||
|
||||
**Double-clicking** a tree item enters inline rename (equivalent to running Rename).
|
||||
|
||||
Internally, names are sanitized (invalid filename characters removed). If the new name is blank or unchanged, rename is canceled.
|
||||
|
||||
---
|
||||
|
||||
## Common Issues & Troubleshooting
|
||||
|
||||
- **Right panels are empty**:
|
||||
- First confirm a `ChartProfile` (not a folder) is selected.
|
||||
- **Renamed but chartName didn't update**:
|
||||
- ChartProfile may have additional sync logic; verify the `Chart Name` field in Inspector.
|
||||
- **Drag failed**:
|
||||
- Common causes: dragging onto itself/child folder, or a name conflict at target path.
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- Click the rightmost **Help** icon in the header to open this chapter.
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 4260ec2e45b714e48a5196263b82348e
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/01_02-LibraryPanel.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,138 @@
|
||||
# JSON Injection Panel
|
||||
|
||||
This chapter explains the **JSON Injection** panel at the bottom-left of `Unity Easy Chart/Library Editor`.
|
||||
|
||||
Its purpose is to represent the current `ChartProfile` configuration (or externally imported configuration) as readable/copyable JSON, and supports **ApplyToChart** to parse the JSON and write it back into the selected Profile.
|
||||
|
||||
---
|
||||
|
||||
## Location and purpose
|
||||
|
||||
- **Location**: below the Library panel (tree view).
|
||||
- **Main uses**:
|
||||
- **Export**: convert the selected `ChartProfile` into example JSON (Feed)
|
||||
- **Edit**: manually edit the JSON in the text box
|
||||
- **Import/Apply**: click **ApplyToChart** to parse and apply JSON into the selected `ChartProfile`
|
||||
|
||||
Use cases:
|
||||
|
||||
- **Debugging**: quickly validate whether a specific field takes effect.
|
||||
- **Batch edits**: copy JSON to an external editor (multi-cursor/find-replace), then paste back and Apply.
|
||||
- **Integrations**: e.g. your toolchain/scripts generate a Feed and you Apply it in the editor.
|
||||
|
||||
---
|
||||
|
||||
## Controls (header bar)
|
||||
|
||||
The header bar typically contains (left to right):
|
||||
|
||||
- **Min/Max** (label changes)
|
||||
- Toggles panel height.
|
||||
- `Min`: collapse to a smaller height (more like an auxiliary tool).
|
||||
- `Max`: expand to a larger height (better for long JSON).
|
||||
|
||||
- **ApplyToChart** (icon button)
|
||||
- Attempts to parse the JSON in the text box as a Feed and apply it to the selected `ChartProfile`.
|
||||
- On success it will:
|
||||
- mark the asset dirty and call `SaveAssets()`
|
||||
- refresh the Series list
|
||||
- refresh Preview
|
||||
|
||||
- **Help** (icon button)
|
||||
- Opens this chapter.
|
||||
|
||||
---
|
||||
|
||||
## Controls (button row)
|
||||
|
||||
Below the header there is a row of buttons (may wrap):
|
||||
|
||||
- **API Envelope** (icon toggle)
|
||||
- Controls whether the example JSON is wrapped in an "API response" envelope.
|
||||
- Useful when you want to send the Feed directly to an HTTP API/service.
|
||||
- Toggling regenerates the example and overwrites the text box (see "overwrite rules").
|
||||
|
||||
- **Feed Mode** (dropdown)
|
||||
- Controls which levels/fields are included in the example JSON.
|
||||
- Options come from an internal enum (common ones include):
|
||||
- `Lite`
|
||||
- `Standard / ID`
|
||||
- `Standard / Default`
|
||||
- `Standard / With Axes`
|
||||
- `Full`
|
||||
- General recommendations:
|
||||
- **Quickly inspect structure**: use `Lite`
|
||||
- **Need stable references**: use `Standard / ID`
|
||||
- **Need to include axes config**: use `Standard / With Axes`
|
||||
- **Need full copy/migration**: use `Full`
|
||||
|
||||
- **Datas Format** (dropdown)
|
||||
- Controls the output format of `seriesData` (data points).
|
||||
- Common options:
|
||||
- `Values`: more compact, mostly "values only".
|
||||
- `Standard`: default format, good for editing and Apply.
|
||||
- `Full`: more complete (may include more fields/structure), good for migration/restoration.
|
||||
|
||||
- **Copy** (icon button)
|
||||
- Copies the current text box content to the clipboard.
|
||||
|
||||
---
|
||||
|
||||
## Text box and "overwrite rules" (important)
|
||||
|
||||
The JSON text box is editable. To prevent your manual edits from being overwritten automatically, the panel has a "dirty" flag logic:
|
||||
|
||||
- **As soon as you manually change the text box**, it is considered "user modified" (dirty).
|
||||
- When dirty:
|
||||
- the editor will not automatically overwrite your content with example JSON.
|
||||
- However, switching the following options will **force overwrite** (and clear dirty):
|
||||
- `API Envelope`
|
||||
- `Feed Mode`
|
||||
- `Datas Format`
|
||||
- or when switching the selected Profile (resets to that Profile's example)
|
||||
|
||||
Recommendation:
|
||||
|
||||
- If you plan to do major edits:
|
||||
- Copy to an external editor first
|
||||
- Paste back and Apply when done
|
||||
|
||||
---
|
||||
|
||||
## ApplyToChart behavior and notes
|
||||
|
||||
- **ApplyToChart modifies the selected `ChartProfile` asset**.
|
||||
- If JSON parsing fails, an error is logged to the Console:
|
||||
- `ApplyToChart failed: invalid JSON or unsupported format.`
|
||||
- In `Full` mode, more meta/structural information may be overwritten (IDs/config, etc.), which is more powerful but also more dangerous.
|
||||
|
||||
Recommendations:
|
||||
|
||||
- Before applying, make sure:
|
||||
- the correct `ChartProfile` is selected on the left
|
||||
- JSON format is valid (brackets/commas)
|
||||
- you understand what the current Feed Mode will overwrite
|
||||
|
||||
---
|
||||
|
||||
## Recommended workflows
|
||||
|
||||
### 1) Export from current Profile and tweak
|
||||
|
||||
- Select a `ChartProfile`
|
||||
- Choose appropriate `Feed Mode` / `Datas Format`
|
||||
- Copy to an external editor for tweaks
|
||||
- Paste back
|
||||
- ApplyToChart
|
||||
|
||||
### 2) Import configuration from external sources
|
||||
|
||||
- Paste external JSON into the text box
|
||||
- ApplyToChart
|
||||
- Fine-tune further in Inspector / Series
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- Click the rightmost **Help** icon in the header to open this chapter.
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 6c519df14f129ed4d94055b6ee239d3a
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/01_03-JsonInjectionPanel.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,78 @@
|
||||
# Preview Panel
|
||||
|
||||
This chapter explains the **Preview** panel at the top of the middle area in `Unity Easy Chart/Library Editor`.
|
||||
|
||||
The purpose of Preview is to render the currently selected `ChartProfile` directly, so you can see results immediately while editing.
|
||||
|
||||
---
|
||||
|
||||
## When does Preview refresh
|
||||
|
||||
Preview refresh is **delayed** (to avoid excessive redraw while you are continuously dragging/typing):
|
||||
|
||||
- When you modify any bound field in **Inspector** or **Series**, it triggers `ScheduleUpdatePreview()`.
|
||||
- When you click **ApplyToChart** in **JSON Injection**, it triggers a refresh.
|
||||
- When you switch to another `ChartProfile` in the left **Library** tree, Preview refreshes to the new Profile.
|
||||
|
||||
Implementation-wise, the refresh is scheduled via `EditorApplication.delayCall`, so you may feel it updates "a moment after" your change. This is expected.
|
||||
|
||||
---
|
||||
|
||||
## What does Preview display
|
||||
|
||||
- Preview draws using a runtime chart component (e.g. `ChartElement`).
|
||||
- Preview reads data from the currently selected `ChartProfile` and renders it.
|
||||
|
||||
You can think of Preview as:
|
||||
|
||||
- **what you edit is what it renders**
|
||||
- **what you see is (mostly) the runtime effect**
|
||||
|
||||
---
|
||||
|
||||
## Common issues and troubleshooting
|
||||
|
||||
### 1) Preview is empty
|
||||
|
||||
Check first:
|
||||
|
||||
- Is a `ChartProfile` selected?
|
||||
- Is there at least one `Serie`?
|
||||
- Is `seriesData` empty (no data points)?
|
||||
|
||||
### 2) Data exists but looks wrong / not visible
|
||||
|
||||
Common causes:
|
||||
|
||||
- **Coordinate system and SeriesType mismatch**: e.g. the Profile is `Polar2D` but the Series type is not Radar.
|
||||
- **Axis range and data range mismatch**: e.g. all values are outside the axis range.
|
||||
- **Category axis visible count (VisibleCount) is too small**: only a small segment is shown.
|
||||
|
||||
### 3) Console shows "Preview refresh failed"
|
||||
|
||||
If an exception occurs during refresh, the Console logs:
|
||||
|
||||
- `[EasyChartLibraryWindow] Preview refresh failed: ...`
|
||||
|
||||
This usually means:
|
||||
|
||||
- some configuration combination is invalid
|
||||
- or some field value is unexpected (e.g. null / NaN)
|
||||
|
||||
Recommended handling:
|
||||
|
||||
- revert the most recent change first
|
||||
- then re-apply changes step by step to locate which field triggers the exception
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
- Preview only focuses on rendering results. Structural issues usually need to be fixed in **Inspector/Series/JSON Injection**.
|
||||
- If you modify many fields in a short time, Preview may refresh only after your last change (for performance).
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- Click the rightmost **Help** icon in the title bar to open this chapter.
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 0d724273b42b2b94fba94bc277901cd7
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/02_04-PreviewPanel.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,201 @@
|
||||
# Inspector Panel
|
||||
|
||||
This chapter explains the **Inspector** panel at the bottom of the middle area in `Unity Easy Chart/Library Editor`.
|
||||
|
||||
Inspector is designed to edit the serialized fields of the currently selected `ChartProfile` from a "configuration" perspective (coordinate system, axes, grid, interactions, legend, etc.), and drive the Preview to update.
|
||||
|
||||
---
|
||||
|
||||
## Panel structure overview
|
||||
|
||||
After you select a `ChartProfile` in the left Library tree, Inspector builds a set of foldouts (Foldout), typically including:
|
||||
|
||||
- **Chart Settings**: basic chart settings (e.g. background, name)
|
||||
- **Coordinate System**: coordinate system selection and related options
|
||||
- **Axis Settings**: axis configuration (X/Y or Angle/Radius)
|
||||
- **Grid Settings**: grid-related configuration
|
||||
- **Hover Settings**: hover/tooltip related configuration
|
||||
- **Legend Settings**: legend configuration
|
||||
|
||||
Tip:
|
||||
|
||||
- If you select a folder instead of a `ChartProfile`, Inspector will be empty (this is expected).
|
||||
|
||||
---
|
||||
|
||||
## Chart Settings (common)
|
||||
|
||||
### Chart Name
|
||||
|
||||
Inspector contains a `Chart Name` text field (from `ChartProfile.chartName`). It is not only a display name, it also participates in asset renaming:
|
||||
|
||||
- When you type a new name and then **lose focus** or press **Enter**:
|
||||
- the editor attempts to rename the `.asset` file to that name
|
||||
- and tries to keep `profile.name` and `profile.chartName` in sync
|
||||
|
||||
Notes:
|
||||
|
||||
- The name will be sanitized for filenames (invalid characters are removed/replaced).
|
||||
- If renaming fails (e.g. name conflict), an Error dialog is shown and the field is reverted.
|
||||
|
||||
### Background
|
||||
|
||||
`Background` is usually a sub-foldout that contains background color/alpha fields (depending on version).
|
||||
|
||||
---
|
||||
|
||||
## Coordinate System
|
||||
|
||||
This area shows the `coordinateSystem` selector.
|
||||
|
||||
The coordinate system affects:
|
||||
|
||||
- available Series types/semantics (e.g. Polar2D is commonly Radar; Pie is a special layout)
|
||||
- whether Axis Settings shows Cartesian (X/Y) or Polar (Angle/Radius) configuration
|
||||
|
||||
Recommendation:
|
||||
|
||||
- decide the coordinate system before you start configuring, to avoid large adjustments later.
|
||||
|
||||
---
|
||||
|
||||
## Axis Settings
|
||||
|
||||
### Axis selection (X Axis / Y Axis)
|
||||
|
||||
In Cartesian mode, the top provides X/Y axis dropdowns:
|
||||
|
||||
- **X Axis**: e.g. `XBottom` / `XTop`
|
||||
- **Y Axis**: e.g. `YLeft` / `YRight`
|
||||
|
||||
When the selection changes, it will:
|
||||
|
||||
- ensure the axes list contains an element for that AxisId (auto-create if needed)
|
||||
- refresh the Axis field UI below
|
||||
- trigger a Preview refresh
|
||||
|
||||
### Common fields of a single Axis
|
||||
|
||||
Each Axis configuration typically contains:
|
||||
|
||||
- `axisType`: Category / Value, etc.
|
||||
- `visible`: whether to show
|
||||
- `color` / `width`: axis line style
|
||||
|
||||
#### LabelTexts (Category axis labels)
|
||||
|
||||
Inspector provides `LabelTexts` (internal field name `labels`) to configure category labels.
|
||||
|
||||
#### Range
|
||||
|
||||
Common fields include:
|
||||
|
||||
- `minValue` / `maxValue`
|
||||
- `autoRangeMin` / `autoRangeMax`
|
||||
- `autoRangeRounding`
|
||||
- `autoRangeUnit`
|
||||
|
||||
#### Ticks / VisibleCount
|
||||
|
||||
If the axis supports auto ticks:
|
||||
|
||||
- When `autoTicks` is enabled, it shows `splitCount`.
|
||||
- For **Category Axis**, this field is displayed as **VisibleCount** (number of visible categories).
|
||||
|
||||
#### Category Auto Scroll
|
||||
|
||||
If the axis supports category scrolling, common fields include:
|
||||
|
||||
- `categoryAutoScroll`: whether to auto scroll (marquee effect).
|
||||
- `categorySmoothScroll`: whether to scroll smoothly.
|
||||
- `categoryScrollInterval`: scroll interval.
|
||||
- `categoryScrollStep`: scroll step per tick.
|
||||
|
||||
#### Unit (unit display)
|
||||
|
||||
Common fields:
|
||||
|
||||
- `showUnit`: whether to show unit.
|
||||
- `unitText`: unit text (e.g. `ms`/`%`/`MB`).
|
||||
- `unitLabelStyle`: unit label style.
|
||||
|
||||
---
|
||||
|
||||
## Polar Axis
|
||||
|
||||
When `coordinateSystem = Polar2D`, Axis Settings shows `polarAxes`:
|
||||
|
||||
- **Angle Axis** (angleAxis)
|
||||
- **Radius Axis** (radiusAxis)
|
||||
|
||||
Common field meanings are similar to Cartesian:
|
||||
|
||||
- `labels`: angle/dimension labels (Radar dimension names typically come from here).
|
||||
- `visible/color/width`: axis line style.
|
||||
- `showLabels/fontSize/labelColor/labelPosition/labelOffset`: label display controls.
|
||||
- `autoRangeMin/autoRangeMax/minValue/maxValue`: radius axis range.
|
||||
- `autoTicks/splitCount`: tick count.
|
||||
|
||||
---
|
||||
|
||||
## Grid Settings (fields, Cartesian2D only)
|
||||
|
||||
Grid Settings is visible in Cartesian2D. Key fields come from `cartesianGrid`:
|
||||
|
||||
- **xGridColor / xGridLineWidth**: X-direction grid line color and width.
|
||||
- **yGridColor / yGridLineWidth**: Y-direction grid line color and width.
|
||||
|
||||
If you need dashed lines:
|
||||
|
||||
- `xGridDashed` / `yGridDashed`: enable dashed.
|
||||
- `xGridDashLength` / `yGridDashLength`: dash segment length.
|
||||
- `xGridDashGap` / `yGridDashGap`: dash gap.
|
||||
- `xGridDashOffset` / `yGridDashOffset`: dash offset.
|
||||
|
||||
---
|
||||
|
||||
## Hover Settings (fields, Cartesian2D only)
|
||||
|
||||
Hover Settings is visible in Cartesian2D. Key fields come from `hover`:
|
||||
|
||||
- **cursorLineColor**: hover cursor line color.
|
||||
- **cursorLineWidth**: line width.
|
||||
- **cursorLineDashed**: dashed or not.
|
||||
- **cursorLineDashLength / cursorLineDashGap / cursorLineDashOffset**: dash parameters.
|
||||
|
||||
---
|
||||
|
||||
## Legend Settings (fields)
|
||||
|
||||
Legend Settings comes from `legendSettings` (it may be auto-hidden in some cases; see below).
|
||||
|
||||
- **enabled**: whether to show legend.
|
||||
- **position**: legend position (Top/Bottom/Left/Right).
|
||||
- **fontSize / color**: text size and color.
|
||||
- **backgroundColor**: legend background color.
|
||||
- **itemSpacing**: spacing between legend items.
|
||||
- **offset**: offset relative to the edge.
|
||||
- When offset is default, a common offset is applied based on position (e.g. Bottom defaults to `y=-30`).
|
||||
|
||||
---
|
||||
|
||||
## Legend Settings (may be auto-hidden)
|
||||
|
||||
When the chart is a "pure Pie series" (only Pie/Ring/Pie3D, with no non-Pie series), Legend Settings may be hidden automatically.
|
||||
|
||||
This avoids showing meaningless or conflicting legend configuration in some layouts.
|
||||
|
||||
---
|
||||
|
||||
## Editing tips and troubleshooting
|
||||
|
||||
- **When making many changes**: use `Save` in the top toolbar to save the asset.
|
||||
- **When changing key structure** (e.g. coordinate system, axis type, Series Type):
|
||||
- after the change, check whether Preview refreshes correctly
|
||||
- if inconsistent, try switching selection to trigger a rebuild
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- Click the rightmost **Help** icon in the title bar to open this chapter.
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 5a262ad8814ea474da864e1e0d337a54
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/02_05-InspectorPanel.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,166 @@
|
||||
# Series Panel (Data and Series)
|
||||
|
||||
This chapter explains the **Series** panel on the right side of `Unity Easy Chart/Library Editor`.
|
||||
|
||||
The Series panel edits `ChartProfile.series` from a "chart structure" perspective: you can add/remove/reorder series, set each Serie's type and parameters, and directly edit `seriesData` (data points).
|
||||
|
||||
---
|
||||
|
||||
## Panel structure overview
|
||||
|
||||
After you select a `ChartProfile`, the Series panel shows:
|
||||
|
||||
- a list of Serie cards (each card corresponds to `series[i]`)
|
||||
- a **+ Add Series** button at the bottom
|
||||
|
||||
Each Serie card typically consists of three parts:
|
||||
|
||||
- **Header**: fold toggle + title
|
||||
- **Body**: Name / Id / Type / Settings / Data
|
||||
- **Footer** (bottom-right controls): ↑ ↓ X
|
||||
|
||||
---
|
||||
|
||||
## Header: Collapse/Expand
|
||||
|
||||
- On the left side of the Header there is a small toggle:
|
||||
- `▼` means expanded
|
||||
- `▶` means collapsed
|
||||
- The fold state is remembered (stored by Profile + index) to reduce visual clutter for long configurations.
|
||||
|
||||
---
|
||||
|
||||
## Name and Serie Id
|
||||
|
||||
### Name
|
||||
|
||||
- The `Name` field displays and edits the name of the Serie.
|
||||
- When you change Name, the card title updates and triggers a Preview refresh.
|
||||
|
||||
### Serie Id (read-only)
|
||||
|
||||
If the Serie supports an `id` field, the panel shows:
|
||||
|
||||
- **Serie Id** (read-only text field)
|
||||
- **Copy** button to copy the id to the clipboard
|
||||
|
||||
This id is commonly used for:
|
||||
|
||||
- interaction/highlighting/external systems referencing a serie
|
||||
- keeping references stable (especially when you reorder/add/remove series)
|
||||
|
||||
---
|
||||
|
||||
## Type (series type) and compatibility tips
|
||||
|
||||
### Type dropdown
|
||||
|
||||
- `Type` is used to select the SerieType (Line/Bar/Scatter/Pie/Radar...).
|
||||
- The dropdown provides options based on the registry. If the current type is not in the list, it will be temporarily inserted to keep it visible.
|
||||
|
||||
### Compatibility warning
|
||||
|
||||
When the SeriesType is incompatible with the Profile `coordinateSystem`, the Series panel shows a warning message:
|
||||
|
||||
- rendering is still allowed (not forcibly blocked)
|
||||
- but it warns that axis/grid semantics may be inconsistent
|
||||
|
||||
Typical example:
|
||||
|
||||
- Profile is `Polar2D` but the SeriesType is Line/Bar (not recommended)
|
||||
|
||||
### Pro-only type restrictions
|
||||
|
||||
Some types are not available in the Free version (e.g. RingChart / HorizontalBar / Heatmap / Pie3D).
|
||||
|
||||
- When you try to select these types without Pro installed:
|
||||
- a hint text will be shown
|
||||
- and the dropdown will automatically revert to the previous type (it will not modify the asset)
|
||||
|
||||
---
|
||||
|
||||
## Settings (series parameters)
|
||||
|
||||
The Series panel shows a group of Settings for each serie:
|
||||
|
||||
- The root foldout name changes by type (e.g. `LineSettings` / `BarSettings` / `PieSettings` ...).
|
||||
- Some types have more detailed sub-foldouts (e.g. Ring layout/valueMapping, etc.).
|
||||
|
||||
Notes:
|
||||
|
||||
- Switching Type may trigger a "Settings instance replacement" (managedReference structure changes).
|
||||
- When replacement happens, the UI rebuild is delayed by one frame to avoid invalid serialized handles.
|
||||
|
||||
---
|
||||
|
||||
## Data: seriesData (data points)
|
||||
|
||||
The Series panel directly shows the `seriesData` array (Unity's default array editor).
|
||||
|
||||
- It is expanded by default (easier to edit).
|
||||
- When you add/remove/modify points, it triggers a Preview refresh.
|
||||
|
||||
Recommendation:
|
||||
|
||||
- If you have many data points, use the JSON Injection panel for batch editing.
|
||||
|
||||
---
|
||||
|
||||
## Footer: Reorder and delete (render order)
|
||||
|
||||
Each serie card has three buttons at the bottom-right:
|
||||
|
||||
- **↑**: move the serie up (`MoveArrayElement(index, index-1)`)
|
||||
- **↓**: move the serie down (`MoveArrayElement(index, index+1)`)
|
||||
- **X**: delete the serie (`DeleteArrayElementAtIndex(index)`)
|
||||
|
||||
Render order tip:
|
||||
|
||||
- Usually, **later series are drawn on top**.
|
||||
- So you can use ↑↓ to control overlap (e.g. points/lines on top of bars).
|
||||
|
||||
---
|
||||
|
||||
## + Add Series
|
||||
|
||||
Click **+ Add Series** at the bottom:
|
||||
|
||||
- Inserts a new element at the end of the `series` array.
|
||||
- Note: if there is already at least one serie, Unity's `InsertArrayElementAtIndex(arraySize)` will **duplicate the last element** (including type/settings).
|
||||
- If this is the first serie, a default type is chosen based on coordinate system:
|
||||
- Polar2D: defaults to Radar
|
||||
- otherwise: defaults to Line
|
||||
|
||||
After adding, it typically will:
|
||||
|
||||
- auto-fill a name (e.g. `Serie N`)
|
||||
- call `EnsureRuntimeData()`
|
||||
- refresh the Series list and Preview
|
||||
|
||||
---
|
||||
|
||||
## Recommended workflows
|
||||
|
||||
### 1) Create a basic chart from scratch
|
||||
|
||||
- + Add Series
|
||||
- Choose Line or Bar in Type
|
||||
- Add a few points in seriesData
|
||||
- Adjust axis range/visible count in Inspector
|
||||
|
||||
### 2) Adjust overlap
|
||||
|
||||
- Use ↑↓ to adjust series order
|
||||
- Observe layering changes in Preview
|
||||
|
||||
### 3) Large data / batch editing
|
||||
|
||||
- Switch `Datas Format` in JSON Injection
|
||||
- Copy to an external editor to batch-generate/replace data
|
||||
- Paste back and ApplyToChart
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- Click the rightmost **Help** icon in the title bar to open this chapter.
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 4ce98ab3f7ab88143bf05de78e49c2dc
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/02_06-SeriesPanel.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,111 @@
|
||||
# Line Chart (Line)
|
||||
|
||||
This chapter explains the key points of configuring a Line chart in EasyChart: how to set it up, how data is interpreted, and which fields affect rendering.
|
||||
|
||||
---
|
||||
|
||||
## 1. Use cases
|
||||
|
||||
- Trend changes (time series / category-based)
|
||||
- Comparing multiple curves (same X dimension)
|
||||
- Line styles such as smooth / step / straight
|
||||
|
||||
---
|
||||
|
||||
## 2. Minimum viable setup (checklist)
|
||||
|
||||
1. `ChartProfile.coordinateSystem = Cartesian2D`
|
||||
2. Axes (Axis Settings)
|
||||
- X: usually **Category** (fill `labels`) or **Value** (numeric X axis)
|
||||
- Y: usually **Value**
|
||||
3. Series (Series panel)
|
||||
- Add 1 `Serie`
|
||||
- `Serie.type = Line`
|
||||
- `Serie.seriesData` has at least 2 points (a line needs at least two points)
|
||||
|
||||
---
|
||||
|
||||
## 3. Inspector fields (what you see in panels)
|
||||
|
||||
- **ChartProfile / Coordinate System**
|
||||
- `coordinateSystem`
|
||||
|
||||
- **Axis Settings** (depends on coordinate system)
|
||||
- Cartesian: `cartesian.xAxisId / cartesian.yAxisId`
|
||||
- Axis list: `axes[]` (each Axis has `axisType/labels/min/max/autoRange/...`)
|
||||
|
||||
- **Series** (each curve)
|
||||
- `series[i].type = Line`
|
||||
- `series[i].settings`: actual type is `LineSettings`
|
||||
- `stroke`: line stroke (type/color/width/texture, etc.)
|
||||
- `point`: point marker style (toggle/size/texture, etc.)
|
||||
- `hover`: hover emphasis (enables pick radius / highlight)
|
||||
- `area`: area fill (fill under the line)
|
||||
- `series[i].labelSettings`: point labels (visibility/format/decimals/offset, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 4. SeriesData field interpretation (runtime behavior)
|
||||
|
||||
Line chart uses:
|
||||
|
||||
- **X coordinate**: `SeriesData.x`
|
||||
- **Y value**: `SeriesData.value`
|
||||
- `SeriesData.y` is **not used for rendering** in line charts (do not treat `y` as the Y value).
|
||||
|
||||
Two common patterns:
|
||||
|
||||
### 4.1 Category X + Value Y (most common)
|
||||
|
||||
- X axis: `AxisType.Category`
|
||||
- `AxisConfig.labels = ["A","B","C",...]`
|
||||
- Data points:
|
||||
- `x = category index` (0/1/2..., mapped into labels)
|
||||
- `value = numeric value`
|
||||
|
||||
### 4.2 Value X + Value Y (numeric X axis)
|
||||
|
||||
- X axis: `AxisType.Value`
|
||||
- Data points:
|
||||
- `x = X value`
|
||||
- `value = Y value`
|
||||
|
||||
> Additional note: when your axis dimensions are **X=Value, Y=Category**, runtime treats it as a transposed Cartesian layout (`transposed`) and swaps how X/Y are interpreted during rendering (useful for horizontal layouts).
|
||||
|
||||
---
|
||||
|
||||
## 5. Common style settings (LineSettings)
|
||||
|
||||
- **Line type**: `LineSettings.stroke.lineType`
|
||||
- `Straight`: straight lines
|
||||
- `Step`: step line
|
||||
- `Smooth`: smooth curve
|
||||
|
||||
- **Stroke width/color**: `LineSettings.stroke.width` / `LineSettings.stroke.color`
|
||||
|
||||
- **Point markers**: `LineSettings.point.show/size/textureFill`
|
||||
|
||||
- **Area fill**: `LineSettings.area.show` + `LineSettings.area.textureFill`
|
||||
|
||||
---
|
||||
|
||||
## 6. Common pitfalls and troubleshooting (by symptoms)
|
||||
|
||||
- **Line breaks / not visible**
|
||||
- Check whether `SeriesData.value` contains `NaN/Infinity`
|
||||
- A line needs at least 2 valid points
|
||||
|
||||
- **Points do not align with labels (Category X)**
|
||||
- Check that `x` is an index within 0..(labels.Count-1)
|
||||
- Do not write `x` as a category string (EasyChart uses index, not string)
|
||||
|
||||
- **I filled `y`, but the chart is wrong**
|
||||
- Line chart uses `value` as the Y value, not `y`
|
||||
|
||||
---
|
||||
|
||||
## 7. Further reading
|
||||
|
||||
- Axes/range, Series and data: `00_02-WorkflowAndLibrary.md`
|
||||
- Common recipes: `04_08-CommonRecipes.md`
|
||||
- FAQ: `04_09-FAQ.md`
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 3f6f8a04529522241b3aebdd60d113dc
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/03_01-LineChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,123 @@
|
||||
# Bar Chart (Bar)
|
||||
|
||||
This chapter explains bar charts in EasyChart: the data interpretation rules (`SeriesData.x/value`), how grouping/stacking really behaves, and commonly used style fields.
|
||||
|
||||
---
|
||||
|
||||
## 1. Use cases
|
||||
|
||||
- Category comparisons (compare values of A/B/C)
|
||||
- Grouped comparison (multiple Bar series side-by-side under the same category)
|
||||
- Stacked totals (stack bars within the same category)
|
||||
|
||||
---
|
||||
|
||||
## 2. Minimum viable setup (checklist)
|
||||
|
||||
1. `ChartProfile.coordinateSystem = Cartesian2D`
|
||||
2. Axes
|
||||
- X: usually `AxisType.Category` (fill `labels`)
|
||||
- Y: usually `AxisType.Value` (recommended to start from 0)
|
||||
3. Series
|
||||
- Add 1 `Serie`
|
||||
- `Serie.type = Bar`
|
||||
- `Serie.seriesData` has at least 1 point
|
||||
|
||||
---
|
||||
|
||||
## 3. Inspector fields
|
||||
|
||||
- **Axis Settings**
|
||||
- `cartesian.xAxisId / cartesian.yAxisId`
|
||||
- `axes[]` (AxisConfig for X/Y)
|
||||
|
||||
- **Series**
|
||||
- `series[i].type = Bar`
|
||||
- `series[i].settings`: actual type is `BarSettings`
|
||||
- `barWidth`
|
||||
- `stacked` / `stackGroup`
|
||||
- `barGap` / `categoryGap`
|
||||
- `cornerRadius` / `cornerSegments`
|
||||
- `textureFill` (color/texture)
|
||||
- `border` / `background`
|
||||
- `hover` (enables picking/highlight)
|
||||
|
||||
---
|
||||
|
||||
## 4. SeriesData field interpretation (runtime behavior)
|
||||
|
||||
Bar charts primarily use:
|
||||
|
||||
- **Category / horizontal position**: `SeriesData.x`
|
||||
- Runtime rounds `x` with `RoundToInt`, so **treat it as a category index**.
|
||||
|
||||
- **Bar height**: `SeriesData.value`
|
||||
|
||||
- `SeriesData.y` / `SeriesData.z` are **not used for rendering** in Bar charts (do not treat `y` as height).
|
||||
|
||||
---
|
||||
|
||||
## 5. Most common template: Category X + Value Y
|
||||
|
||||
### 5.1 X axis (Category)
|
||||
|
||||
- `AxisType = Category`
|
||||
- `labels = ["A","B","C",...]`
|
||||
- Recommended: `labelPlacement = CellCenter` (easier to center-align bars)
|
||||
|
||||
### 5.2 Data pattern
|
||||
|
||||
- `x = category index` (0/1/2...)
|
||||
- `value = bar height`
|
||||
|
||||
---
|
||||
|
||||
## 6. Grouped bars (multiple series side-by-side): the actual rule
|
||||
|
||||
Key points:
|
||||
|
||||
- multiple `Serie`, all `type=Bar`
|
||||
- all series share the same X categories (same labels)
|
||||
- each series uses the same `x` index to land in the same category
|
||||
|
||||
Spacing fields:
|
||||
|
||||
- `BarSettings.barGap`: gap between bar groups within a category
|
||||
- `BarSettings.categoryGap`: extra gap between categories (affects edge padding)
|
||||
|
||||
---
|
||||
|
||||
## 7. Stacked bars (stacked): the actual rule
|
||||
|
||||
Stacking happens between Bar series with the same stackGroup:
|
||||
|
||||
- `BarSettings.stacked = true`
|
||||
- `BarSettings.stackGroup = "Group1"`
|
||||
|
||||
Runtime stacking notes:
|
||||
|
||||
- for the same `x` (category index), it accumulates positive and negative values separately (positive/negative stacks are separate)
|
||||
- the top of each stacked segment = current accumulated base + `value`
|
||||
|
||||
---
|
||||
|
||||
## 8. Common pitfalls and troubleshooting
|
||||
|
||||
- **Bars appear between labels / not aligned**
|
||||
- Check X axis `labelPlacement` (recommend `CellCenter`)
|
||||
- Ensure `x` is an integer index (runtime rounds)
|
||||
|
||||
- **Bars do not start from 0**
|
||||
- Check whether Y axis (Value Axis) has `autoRangeMin` disabled and `minValue=0` locked
|
||||
|
||||
- **Stacking result is wrong**
|
||||
- Check that all series that should stack use the same `stackGroup`
|
||||
- Remember: positive and negative values stack separately
|
||||
|
||||
---
|
||||
|
||||
## 9. Further reading
|
||||
|
||||
- Axes/range, Series and data: `00_02-WorkflowAndLibrary.md`
|
||||
- Common recipes: `04_08-CommonRecipes.md`
|
||||
- FAQ: `04_09-FAQ.md`
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 21fda245bf059b246a9dd9a47a8474da
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/03_02-BarChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,107 @@
|
||||
# Scatter Chart (Scatter)
|
||||
|
||||
This chapter explains the data field conventions for Scatter charts in EasyChart, especially the compatibility behavior of `SeriesData.y/value`, and how the `z` dimension drives `sizeMapping`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Use cases
|
||||
|
||||
- Correlation analysis (two numeric dimensions X/Y)
|
||||
- Distribution visualization (point cloud)
|
||||
- Outlier detection
|
||||
|
||||
---
|
||||
|
||||
## 2. Minimum viable setup (checklist)
|
||||
|
||||
1. `ChartProfile.coordinateSystem = Cartesian2D`
|
||||
2. Axes
|
||||
- Common: X=Value, Y=Value
|
||||
3. Series
|
||||
- Add 1 `Serie`
|
||||
- `Serie.type = Scatter`
|
||||
- `Serie.seriesData` has at least 2 points
|
||||
|
||||
---
|
||||
|
||||
## 3. Inspector fields
|
||||
|
||||
- `series[i].type = Scatter`
|
||||
- `series[i].settings`: actual type is `ScatterSettings`
|
||||
- `point`: point style (visible/size/texture)
|
||||
- `hover`: hover highlight (enabled/pickRadius/scale, etc. depending on version)
|
||||
- `sizeMapping`: point size mapping
|
||||
|
||||
---
|
||||
|
||||
## 4. SeriesData field interpretation (runtime behavior)
|
||||
|
||||
Scatter chart uses:
|
||||
|
||||
- **X coordinate**: `SeriesData.x`
|
||||
- **Y coordinate**: prefers `SeriesData.y`
|
||||
- Compatibility: if `y == 0` and `value != 0`, runtime uses `value` as y
|
||||
- **Size mapping dimension**: `SeriesData.z` (when `sizeMapping.enabled=true`)
|
||||
|
||||
So there are two common patterns:
|
||||
|
||||
### 4.1 Recommended (explicit X/Y)
|
||||
|
||||
- `x = X value`
|
||||
- `y = Y value`
|
||||
|
||||
### 4.2 Compatibility (legacy data: use value as y)
|
||||
|
||||
- `x = X value`
|
||||
- `value = Y value`
|
||||
- `y = 0`
|
||||
|
||||
> Recommendation: for new data, write `y` directly to avoid mixing meanings with `value`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Standard template: Value X + Value Y
|
||||
|
||||
- X axis: `AxisType = Value`
|
||||
- Y axis: `AxisType = Value`
|
||||
- Data: use pattern 4.1 (x/y)
|
||||
|
||||
---
|
||||
|
||||
## 6. sizeMapping: actual behavior
|
||||
|
||||
When `ScatterSettings.sizeMapping.enabled = true`:
|
||||
|
||||
- point radius is mapped from `SeriesData.z`
|
||||
- mapping range: `minValue/maxValue` -> `minSize/maxSize`
|
||||
- if `clamp = true`, t is clamped to 0..1
|
||||
- `curve` applies a curve transform to t (non-linear mapping)
|
||||
|
||||
If sizeMapping "doesn't work", check first:
|
||||
|
||||
- did you actually set `z` values (default 0)
|
||||
- is `minValue/maxValue` equal (degenerates mapping)
|
||||
|
||||
---
|
||||
|
||||
## 7. Common pitfalls and troubleshooting
|
||||
|
||||
- **All points are on a horizontal line**
|
||||
- you may have filled only `value`, but also set `y` to a non-zero value (compatibility won't trigger)
|
||||
- recommend using `y` consistently as the Y coordinate
|
||||
|
||||
- **Hover does not respond**
|
||||
- `ScatterSettings.hover.enabled` must be enabled
|
||||
- too small `pickRadius` makes picking difficult
|
||||
|
||||
- **Points are too small / too large**
|
||||
- adjust `ScatterSettings.point.size`
|
||||
- or check `minSize/maxSize` in sizeMapping
|
||||
|
||||
---
|
||||
|
||||
## 8. Further reading
|
||||
|
||||
- Axes/range, Series and data: `00_02-WorkflowAndLibrary.md`
|
||||
- Common recipes: `04_08-CommonRecipes.md`
|
||||
- FAQ: `04_09-FAQ.md`
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 542aa64652c73f942b75583261cd6b10
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/03_03-ScatterChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,134 @@
|
||||
# Heatmap Chart (Heatmap)
|
||||
|
||||
This chapter explains the rules for Heatmaps in EasyChart: how coordinates/cells are mapped, how `SeriesData` fields are interpreted, and how the value-to-color range is calculated. It also notes that Heatmap is a Pro feature.
|
||||
|
||||
---
|
||||
|
||||
## 1. Use cases
|
||||
|
||||
- 2D matrix visualization (rows/columns)
|
||||
- Density/intensity visualization
|
||||
|
||||
---
|
||||
|
||||
## 2. Important note (Pro feature)
|
||||
|
||||
- The renderer for `SerieType.Heatmap` is registered by `EasyChartProBootstrap`.
|
||||
- If EasyChartPro is not installed/enabled, this serie may be treated as a "dynamic renderer" and attempted to be created, but it usually won't render.
|
||||
|
||||
---
|
||||
|
||||
## 3. Minimum viable setup (checklist)
|
||||
|
||||
1. `ChartProfile.coordinateSystem = Cartesian2D`
|
||||
2. Axes (Axis Settings)
|
||||
- Most common: X=Category (columns), Y=Category (rows)
|
||||
- X/Y can also use Value axes (see section 7)
|
||||
3. Series
|
||||
- Add 1 `Serie`
|
||||
- `Serie.type = Heatmap`
|
||||
- `Serie.seriesData` has at least 1 point
|
||||
|
||||
---
|
||||
|
||||
## 4. Inspector fields
|
||||
|
||||
- **Series**
|
||||
- `series[i].type = Heatmap`
|
||||
- `series[i].settings`: actual type is `HeatmapSettings`
|
||||
- `renderMode`: Grid / Gradient / Contour
|
||||
- `cellGapPx`
|
||||
- `xSplitCount` / `ySplitCount` (used when X/Y are Value axes)
|
||||
- `autoRange / minValue / maxValue`
|
||||
- `lowColor / midColor / highColor`
|
||||
- `clamp`
|
||||
- `influenceMode`: None / Bleed / Smooth
|
||||
- sub settings: `bleed / smooth / gradient / contour`
|
||||
|
||||
---
|
||||
|
||||
## 5. SeriesData field interpretation (runtime behavior)
|
||||
|
||||
Each Heatmap data point corresponds to one "cell/pixel area". Runtime uses:
|
||||
|
||||
- **X coordinate (column)**: `SeriesData.x`
|
||||
- **Y coordinate (row)**: `SeriesData.y`
|
||||
- **Intensity**: `SeriesData.value`
|
||||
- **Color override**: if `SeriesData.useColor = true`, runtime uses `SeriesData.color` directly and skips interpolation from `low/mid/high`.
|
||||
|
||||
> Note: Heatmap `x/y` do not accept string categories. With Category axes, you still use indices.
|
||||
|
||||
---
|
||||
|
||||
## 6. Standard template: 2D Category (X/Y) + value intensity (most common)
|
||||
|
||||
### 6.1 X axis (Category: columns)
|
||||
|
||||
- `AxisType = Category`
|
||||
- `labels = ["Col0","Col1",...]`
|
||||
|
||||
### 6.2 Y axis (Category: rows)
|
||||
|
||||
- `AxisType = Category`
|
||||
- `labels = ["Row0","Row1",...]`
|
||||
|
||||
### 6.3 Data pattern
|
||||
|
||||
- `x = column index` (runtime applies `RoundToInt`)
|
||||
- `y = row index` (runtime applies `RoundToInt`)
|
||||
- `value = intensity`
|
||||
|
||||
### 6.4 Important detail: cell count vs `labelPlacement` for Category axes
|
||||
|
||||
Runtime uses the axis `labelPlacement` to decide whether to split into `labels.Count` cells or `labels.Count-1` cells:
|
||||
|
||||
- `CategoryLabelPlacement.CellCenter`
|
||||
- X cell count = `labels.Count`
|
||||
- Y cell count = `labels.Count`
|
||||
|
||||
- Others (non CellCenter)
|
||||
- X cell count = `max(1, labels.Count - 1)`
|
||||
- Y cell count = `max(1, labels.Count - 1)`
|
||||
|
||||
This directly affects the valid range of indices you should write into `x/y`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Heatmap with Value axes (X/Y are numeric axes)
|
||||
|
||||
When X or Y uses `AxisType.Value`:
|
||||
|
||||
- Cell count no longer comes from labels. It comes from:
|
||||
- X: `HeatmapSettings.xSplitCount`
|
||||
- Y: `HeatmapSettings.ySplitCount`
|
||||
|
||||
- `SeriesData.x/y` are normalized using `_xMin/_xMax` and `_yMin/_yMax`, then mapped into cell indices.
|
||||
|
||||
This is suitable for intensity/density distribution over a continuous value range.
|
||||
|
||||
---
|
||||
|
||||
## 8. Common pitfalls and troubleshooting
|
||||
|
||||
- **All cells look the same / low contrast**
|
||||
- Check whether `HeatmapSettings.autoRange` is enabled
|
||||
- Or manually set `minValue/maxValue`
|
||||
- Also check whether all points have almost the same `value`
|
||||
|
||||
- **Colors do not follow low/mid/high**
|
||||
- Check whether some points set `useColor=true` (it overrides palette interpolation)
|
||||
|
||||
- **Cells are misaligned (out-of-range / off-by-one)**
|
||||
- Check whether Category axis `labelPlacement` is `CellCenter`
|
||||
- Use section 6.4 to determine correct cell count and index ranges
|
||||
|
||||
- **Cell gaps are too large/too tight**
|
||||
- Adjust `HeatmapSettings.cellGapPx`
|
||||
|
||||
---
|
||||
|
||||
## 9. Further reading
|
||||
|
||||
- Axes/range, Series and data: `00_02-WorkflowAndLibrary.md`
|
||||
- Common recipes: `04_08-CommonRecipes.md`
|
||||
- FAQ: `04_09-FAQ.md`
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 16dbae96d4b518240828a14e5919d1b7
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/03_04-HeatmapChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,110 @@
|
||||
# Radar Chart (Radar)
|
||||
|
||||
This chapter explains how Radar charts work in EasyChart: where dimension labels come from, how value ranges are calculated, and how data point order is interpreted, mapped to Inspector fields.
|
||||
|
||||
---
|
||||
|
||||
## 1. Use cases
|
||||
|
||||
- Multi-dimensional metric comparison
|
||||
- Ability/attribute radar
|
||||
|
||||
---
|
||||
|
||||
## 2. Minimum viable setup (checklist)
|
||||
|
||||
1. `ChartProfile.coordinateSystem = Polar2D`
|
||||
2. Series
|
||||
- Add 1 `Serie`
|
||||
- `Serie.type = Radar`
|
||||
- `Serie.seriesData` is recommended to have at least 3 points (with <= 2 dimensions, runtime will not draw / hover won't work)
|
||||
3. PolarAxes (recommended)
|
||||
- `polarAxes.angleAxis.labels`: dimension names
|
||||
- `polarAxes.radiusAxis`: value range (auto/manual)
|
||||
|
||||
---
|
||||
|
||||
## 3. Inspector fields
|
||||
|
||||
- **ChartProfile / Coordinate System**
|
||||
- `coordinateSystem = Polar2D`
|
||||
|
||||
- **PolarAxes** (recommended for configuring Radar axes)
|
||||
- `polarAxes.angleAxis.labels`: dimension labels
|
||||
- `polarAxes.radiusAxis.autoRangeMin/autoRangeMax/minValue/maxValue/autoRangeRounding/labelFormat/...`
|
||||
|
||||
- **Series**
|
||||
- `series[i].type = Radar`
|
||||
- `series[i].settings`: actual type is `RadarSettings`
|
||||
- `radar`: layout (startAngleDeg / clockwise / innerRadius / outerRadius / plot / background)
|
||||
- `stroke`: polyline style
|
||||
- `area`: area fill
|
||||
- `point`: point style (point visibility also affects hover pick radius)
|
||||
- `series[i].labelSettings`: data point labels (can show dimension name and value)
|
||||
|
||||
---
|
||||
|
||||
## 4. SeriesData field interpretation (runtime behavior)
|
||||
|
||||
Key point for Radar: **dimension order is defined by the index of items in the `seriesData` list**.
|
||||
|
||||
- **Value**: uses `SeriesData.value`
|
||||
- **Dimension index**: uses the position `i` in `seriesData` (0..dimensionCount-1)
|
||||
- `SeriesData.x` is **not used for positioning** in Radar rendering (do not rely on x to represent dimensions)
|
||||
|
||||
Where does dimensionCount come from:
|
||||
|
||||
1. Prefer `Data.PolarAxes.angleAxis.labels.Count`
|
||||
2. If angleAxis.labels is not configured, it uses labels from a Category Axis (see section 5)
|
||||
3. Otherwise, fall back to `seriesData.Count` (or the maximum count among multiple series)
|
||||
|
||||
---
|
||||
|
||||
## 5. Actual priority order for dimension labels
|
||||
|
||||
Runtime resolves dimension names in this priority order:
|
||||
|
||||
1. `polarAxes.angleAxis.labels[i]`
|
||||
2. `labels[i]` from a `AxisType.Category` axis in `axes[]`
|
||||
- it prefers the Category axis that matches `Data.XAxisId`
|
||||
3. `seriesData[i].name`
|
||||
4. If none exists, it shows `Dim i`
|
||||
|
||||
> Recommendation: for Radar, manage dimension names via `polarAxes.angleAxis.labels`. Use `SeriesData.name` as a fallback.
|
||||
|
||||
---
|
||||
|
||||
## 6. How radius value range is calculated
|
||||
|
||||
Radar radius range is calculated from `SeriesData.value`:
|
||||
|
||||
- By default, it computes auto range from values across all Radar series
|
||||
- If you configure `polarAxes.radiusAxis`:
|
||||
- `autoRangeMin/autoRangeMax` decides whether min/max are automatic
|
||||
- `minValue/maxValue` take effect when the corresponding auto range is disabled
|
||||
- `autoRangeRounding` rounds auto min/max to tens/hundreds/custom unit
|
||||
- `labelFormat` affects tooltip/label formatting
|
||||
|
||||
---
|
||||
|
||||
## 7. Common pitfalls and troubleshooting
|
||||
|
||||
- **Radar chart not visible**
|
||||
- Check `coordinateSystem` is `Polar2D`
|
||||
- Dimension count must be > 2 (labels or seriesData must be at least 3)
|
||||
|
||||
- **Dimensions do not match / order is wrong**
|
||||
- Radar does not use `x`. It uses `seriesData` list order as dimension order
|
||||
- Put points in `seriesData` in the intended dimension order
|
||||
|
||||
- **Hover is hard to trigger**
|
||||
- Radar pick radius is related to `RadarSettings.point.size`
|
||||
- If `point.show=false`, pick radius becomes 0 (almost impossible to hover)
|
||||
|
||||
---
|
||||
|
||||
## 8. Further reading
|
||||
|
||||
- Series and data: `00_02-WorkflowAndLibrary.md`
|
||||
- Common recipes: `04_08-CommonRecipes.md`
|
||||
- FAQ: `04_09-FAQ.md`
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: ab1dd2fe7e872d147a2d94687affecef
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/03_05-RadarChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,174 @@
|
||||
# Pie Chart (Pie)
|
||||
|
||||
This chapter explains how Pie charts work in EasyChart: how data fields are interpreted, how layout/aggregation/legend/interactions take effect, and which behaviors have hidden prerequisites, mapped to Inspector fields.
|
||||
|
||||
---
|
||||
|
||||
## 1. Use cases
|
||||
|
||||
- Showing proportions/composition
|
||||
- Emphasizing the share of each category in the whole
|
||||
|
||||
Not suitable for:
|
||||
|
||||
- Too many categories (usually > 8–12 becomes hard to read)
|
||||
- Precise comparison of tiny differences (a bar chart is usually better)
|
||||
|
||||
---
|
||||
|
||||
## 2. Minimum viable setup (checklist)
|
||||
|
||||
1. `coordinateSystem`: Pie does not rely on Cartesian/Polar coordinate systems (keep your Profile setting)
|
||||
2. Add 1 `Serie`:
|
||||
- `type = Pie`
|
||||
- `settings = PieSettings`
|
||||
- `seriesData` has at least 1 point
|
||||
3. Ensure each point has `value > 0`
|
||||
|
||||
> Note: Pie currently ignores points with `value <= 0`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Important limitations (runtime behavior)
|
||||
|
||||
- **Only the first visible Pie serie is drawn**: the renderer iterates `Data.Series`, finds the first visible serie with `type=Pie`, draws it, then `break`s.
|
||||
- Slice hidden state comes from `ChartInteractionState.HiddenPieSliceIds`, which is added/removed when clicking legend items.
|
||||
|
||||
---
|
||||
|
||||
## 4. SeriesData field interpretation (runtime behavior)
|
||||
|
||||
Pie mainly uses:
|
||||
|
||||
- `value`: numeric value (weight) of the slice
|
||||
- `name`: slice name (recommended)
|
||||
- `useColor + color`: per-slice custom color (optional)
|
||||
- `id`: stable slice identifier (for hidden/interaction state; keep it stable)
|
||||
|
||||
### 4.1 Recommended pattern: explicit name + value
|
||||
|
||||
- `SeriesData.name = "Apple"`
|
||||
- `SeriesData.value = 12`
|
||||
|
||||
### 4.2 Name fallback when name is empty
|
||||
|
||||
When `SeriesData.name` is empty, Pie may try to use **labels**, but with an important prerequisite:
|
||||
|
||||
- If `ChartData.CoordinateSystem == None` (typically pure Pie / no coordinate system), runtime **skips label fallback** and uses only `SeriesData.name`.
|
||||
|
||||
When coordinate system is not None, the fallback order is:
|
||||
|
||||
- Prefer Category axis labels that match `Data.Cartesian.xAxisId`
|
||||
- Otherwise, use labels from any Category axis
|
||||
- Final fallback: `Slice {index}`
|
||||
|
||||
> Therefore: if you do not want to depend on axis configuration, fill `SeriesData.name` directly.
|
||||
|
||||
### 4.3 Color source
|
||||
|
||||
- If `useColor=true` on the point: use `SeriesData.color`
|
||||
- Otherwise: use the built-in palette in order
|
||||
|
||||
---
|
||||
|
||||
## 5. Common settings (PieSettings)
|
||||
|
||||
Pie `settings` is `PieSettings`, mainly including:
|
||||
|
||||
- `layout`: layout (angle/radius/gaps/center offset, etc.)
|
||||
- `hover`: hover interaction (explode)
|
||||
- `aggregation`: aggregation (TopN + Others)
|
||||
- `legend`: Pie-specific legend settings (replaces global legend only for "pure Pie chart" cases)
|
||||
|
||||
### 4.1 layout (PieLayoutSettings)
|
||||
|
||||
Common fields:
|
||||
|
||||
- `startAngleDeg`: start angle (default -90 makes the first slice start at the top)
|
||||
- `clockwise`: clockwise/counter-clockwise
|
||||
- `angleRangeDeg`: angle range (default 360; use 180 for half-pie, etc.)
|
||||
- `outerRadius`: outer radius
|
||||
- `<= 0`: auto
|
||||
- `0~1`: normalized by control size
|
||||
- `> 1`: pixels
|
||||
- `innerRadius`: inner radius (Pie usually 0; >0 creates a hole, but RingChart is recommended for ring/progress style)
|
||||
- `innerRadiusColor`: inner fill color
|
||||
- `sliceGapPx`: gap between slices (pixels)
|
||||
- `sliceGapType`: gap mode (Radial/Translate/Uniform)
|
||||
- `cornerRadius`: corner radius (pixels, limited by slice thickness)
|
||||
- `plot.padding`: padding (avoid clipping slices/outside labels)
|
||||
- `plot.centerOffset`: center offset
|
||||
|
||||
### 4.2 hover (PieHoverSettings)
|
||||
|
||||
- `hover.enabled`: enable hover interaction
|
||||
- `hover.explodeType`:
|
||||
- `Translate`: translate the whole slice
|
||||
- `Pull`: pull out / stretch
|
||||
- `Color`: brighten
|
||||
- `Stroke`: stroke emphasis
|
||||
- `hover.explodeDistance`: translate/pull distance (pixels)
|
||||
|
||||
### 4.3 aggregation (PieAggregationSettings)
|
||||
|
||||
When there are many categories, you can merge small items into `Others`:
|
||||
|
||||
- `aggregation.enabled = true`
|
||||
- `keepTopN`: keep top N, merge the rest
|
||||
- `sortByValue`: sort by `value` before taking TopN
|
||||
- `othersName`: name for Others
|
||||
- `useOthersColor + othersColor`: Others color
|
||||
|
||||
> Note: aggregation only takes effect when `keepTopN > 0` and slice count exceeds N.
|
||||
|
||||
---
|
||||
|
||||
## 6. Legend (PieLegendSettings) and "hide slice" interaction
|
||||
|
||||
When the chart is a "pure Pie chart" (only Pie/RingChart/Pie3D and no other types):
|
||||
|
||||
- Legend prefers `PieSettings.legend` (or the legend on RingChartSettings/Pie3DSettings), instead of `ChartData.legend`.
|
||||
- Clicking a legend item toggles `HiddenPieSliceIds`:
|
||||
- normal slices: `SeriesData.id` (if empty, uses index string)
|
||||
- aggregated Others: always `__ec_pie_others__`
|
||||
|
||||
`PieLegendSettings.source` affects where legend items come from:
|
||||
|
||||
- `Slice`: one entry per slice (default)
|
||||
- `RingSlice`: provides label source for RingChart/RingSlice scenarios (prefers PolarAxes.angleAxis.labels)
|
||||
- `Series`: one entry per serie (not slice-level)
|
||||
|
||||
---
|
||||
|
||||
## 7. Labels (SerieLabelSettings)
|
||||
|
||||
Pie labels are controlled by `Serie.labelSettings`:
|
||||
|
||||
- `show`: whether to show
|
||||
- `fontSize / color / decimalPlaces`: font and value format
|
||||
- `showName`: whether to include slice name
|
||||
- `position`: `Outside/Inside/Center`
|
||||
- `offset`: offset
|
||||
|
||||
---
|
||||
|
||||
## 8. Common pitfalls (by symptoms)
|
||||
|
||||
- **Some slices are not visible**
|
||||
- Check whether the point `value` is `<= 0`
|
||||
|
||||
- **Slice name is not what I expect**
|
||||
- Recommended: fill `SeriesData.name` directly
|
||||
- If you rely on labels: ensure you have a Category axis with `labels`, and the order matches data point indices
|
||||
|
||||
- **Slice colors change each time / hard to control**
|
||||
- For slices that need fixed colors: set `useColor=true` + `color` on the point
|
||||
|
||||
- **Hidden/interaction state is unstable**
|
||||
- Ensure each point `SeriesData.id` is stable (do not regenerate ids on each refresh)
|
||||
|
||||
---
|
||||
|
||||
## 9. Next
|
||||
|
||||
- Ring chart (RingChart): `03_07-RingChart.md`
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 2bffa5abab7faa442b8f86f43817e37f
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/03_06-PieChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,170 @@
|
||||
# Ring Chart (RingChart)
|
||||
|
||||
This chapter explains what RingChart really means (it is not a donut pie), and aligns its `SeriesData` interpretation, `RingChartSettings` configuration, and Pro/base differences with runtime behavior.
|
||||
|
||||
---
|
||||
|
||||
## 1. What is RingChart? (very important)
|
||||
|
||||
In the current EasyChart implementation:
|
||||
|
||||
- `SerieType.RingChart` renders **multiple progress rings** (one ring per data point)
|
||||
- each ring is a **full 360° background ring + one progress arc**
|
||||
- it is not a pie chart that splits the circle into multiple slices
|
||||
|
||||
If you want a donut pie chart that shows composition:
|
||||
|
||||
- it is closer to `SerieType.Pie` + `layout.innerRadius > 0`
|
||||
- but you should choose based on intent:
|
||||
- composition/proportion: use Pie
|
||||
- multi-metric progress/completion: use RingChart
|
||||
|
||||
---
|
||||
|
||||
## 2. Important note (Pro feature)
|
||||
|
||||
- The renderer for `SerieType.RingChart` is registered by `EasyChartProBootstrap`.
|
||||
- Without Pro installed/enabled, this serie usually won't render.
|
||||
|
||||
---
|
||||
|
||||
## 3. Minimum viable setup (checklist)
|
||||
|
||||
1. Add 1 `Serie`
|
||||
- `type = RingChart`
|
||||
- `settings = RingChartSettings`
|
||||
- `seriesData` has at least 1 point
|
||||
2. Each point has `value > 0`
|
||||
|
||||
> Note: RingChart ignores points with `value <= 0`.
|
||||
|
||||
---
|
||||
|
||||
## 4. SeriesData field interpretation (runtime behavior)
|
||||
|
||||
RingChart mainly uses:
|
||||
|
||||
- `value`: the raw progress value
|
||||
- `name`: ring name
|
||||
- `useColor + color`: ring color (per-point override)
|
||||
- `id`: stable identifier (for legend/hidden state; keep it stable)
|
||||
|
||||
### 4.1 Percent mode (default): value supports both 0~1 and 0~100
|
||||
|
||||
When `RingChartSettings.valueMapping.mode = Percent` (default):
|
||||
|
||||
- `value <= 0`: the ring is filtered out
|
||||
- `0~1`: treated as ratio (0.72 = 72%)
|
||||
- `> 1`: treated as percent (72 = 72%, runtime divides by 100)
|
||||
|
||||
Recommendation: standardize one convention within your team (all 0~1 or all 0~100) to avoid mistakes.
|
||||
|
||||
### 4.2 Range mode: map value to 0..1
|
||||
|
||||
When `RingChartSettings.valueMapping.mode = Range`:
|
||||
|
||||
- It first determines the range `min/max`:
|
||||
- `autoRange=true`: compute from values across all rings
|
||||
- `autoRange=false`: use `minValue/maxValue`
|
||||
- Then it maps to `(value-min)/(max-min)` and clamps to 0..1
|
||||
|
||||
### 4.3 Name fallback when name is empty
|
||||
|
||||
When `SeriesData.name` is empty, RingChart tries to fall back to labels:
|
||||
|
||||
- If `ChartData.CoordinateSystem == None`: it won't use labels, and falls back to `Ring {i}`
|
||||
- Otherwise it prefers: `Data.PolarAxes.angleAxis.labels[i]`
|
||||
- Otherwise: labels from Cartesian/any Category axis `labels[i]`
|
||||
- Final fallback: `Ring {i}`
|
||||
|
||||
If you do not want to depend on PolarAxes configuration, fill `SeriesData.name` directly.
|
||||
|
||||
---
|
||||
|
||||
## 5. Inspector fields (RingChartSettings)
|
||||
|
||||
- `series[i].type = RingChart`
|
||||
- `series[i].settings`: actual type is `RingChartSettings`
|
||||
- `layout`: angles/radius/inner-outer ring/padding/center offset
|
||||
- `valueMapping`: Percent/Range mapping rules
|
||||
- `hover`: hover emphasis (Translate/Pull/Color/Stroke)
|
||||
- `legend`: RingChart legend settings (effective for pure Pie charts)
|
||||
- `showBackground/backgroundAlpha/backgroundColor`: background ring
|
||||
- `cornerRadius`: rounded cap
|
||||
- `ringGapPx`: gap between rings
|
||||
|
||||
### 5.1 layout (RingChartLayoutSettings)
|
||||
|
||||
Common fields:
|
||||
|
||||
- `startAngleDeg`: start angle
|
||||
- `clockwise`: clockwise/counter-clockwise
|
||||
- `angleRangeDeg`: default 360; use for half-ring progress, etc.
|
||||
- `outerRadius`: outer radius (<=0 auto; 0~1 normalized; >1 pixels)
|
||||
- `innerRadius`: inner radius (0~1 normalized or pixels)
|
||||
- `plot.padding`: padding (avoid clipping hover/labels)
|
||||
- `plot.centerOffset`: center offset
|
||||
|
||||
### 5.2 hover (PieHoverSettings)
|
||||
|
||||
- `hover.enabled`: enable
|
||||
- `hover.explodeType`:
|
||||
- `Translate`: translate the whole ring
|
||||
- `Pull`: pull/stretch
|
||||
- `Color`: brighten
|
||||
- `Stroke`: stroke emphasis
|
||||
- `hover.explodeDistance`: translate/pull distance (pixels)
|
||||
|
||||
### 5.3 Background ring and spacing
|
||||
|
||||
- `showBackground`: draw background ring
|
||||
- `backgroundAlpha`: background ring alpha (multiplied into final color alpha)
|
||||
- `backgroundColor`: background ring color (when alpha=0, it falls back to ring color)
|
||||
- `ringGapPx`: gap between rings
|
||||
- `cornerRadius`: rounded cap (limited by ring thickness)
|
||||
|
||||
---
|
||||
|
||||
## 6. Legend and hide interaction (shared HiddenPieSliceIds with Pie)
|
||||
|
||||
- RingChart shares `ChartInteractionState.HiddenPieSliceIds` with Pie.
|
||||
- Hidden key for each ring: prefer `SeriesData.id`, otherwise use the index string.
|
||||
- Legend label source is affected by `PieLegendSettings.source`:
|
||||
- `RingSlice` prefers `polarAxes.angleAxis.labels`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Labels (SerieLabelSettings)
|
||||
|
||||
RingChart labels also use `Serie.labelSettings`:
|
||||
|
||||
- `show`: whether to show
|
||||
- `showName`: whether to show name
|
||||
- `decimalPlaces`: decimals (note: this displays the raw `value`, not a percent text multiplied by 100)
|
||||
- `position`:
|
||||
- `Outside`: outside label + leader line
|
||||
- `Center`: centered on the ring
|
||||
|
||||
---
|
||||
|
||||
## 6. Common pitfalls (by symptoms)
|
||||
|
||||
- **I thought it was a donut pie, but it looks wrong**
|
||||
- This is a multi-ring progress chart: each point is one progress ring
|
||||
|
||||
- **Progress is wrong (e.g. I set 75 but it is almost full)**
|
||||
- `value>1` is treated as percent and divided by 100
|
||||
- For 75%: use `0.75` or `75`
|
||||
|
||||
- **Some rings are not visible**
|
||||
- Check whether `value <= 0` is being filtered
|
||||
|
||||
- **Interaction/hidden state is unstable**
|
||||
- Ensure `SeriesData.id` is stable
|
||||
|
||||
---
|
||||
|
||||
## 8. Further reading
|
||||
|
||||
- Pie (composition/proportion): `03_06-PieChart.md`
|
||||
- Series data structure: `00_02-WorkflowAndLibrary.md`
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: fbaf24c6bef7e9f4ba07bd263dbaf37c
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/03_07-RingChart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,224 @@
|
||||
|
||||
# Common Recipes
|
||||
|
||||
This chapter provides copy-ready recipes for common charts (Series + Axes + common pitfalls) to help you create and troubleshoot quickly.
|
||||
|
||||
---
|
||||
|
||||
## 0. Before you start: minimum checklist
|
||||
|
||||
When you see "nothing shows" or "it looks weird", check in this order:
|
||||
|
||||
1. Does `coordinateSystem` match the SeriesType (Cartesian2D vs Polar2D)
|
||||
2. Does `series` contain at least 1 serie, and does that serie have `seriesData.Count > 0`
|
||||
3. Do axis types match what your data means:
|
||||
- Category axis: `labels` is not empty, and data `x/y` are indices (0/1/2...)
|
||||
- Value axis: data `x/y` are continuous numeric values
|
||||
4. Do you have any NaN/Infinity
|
||||
5. Did you lock Value axis range (`autoRangeMin/autoRangeMax` or fixed min/max) so data is outside the range
|
||||
|
||||
---
|
||||
|
||||
## 1. Line chart (Line): Category X + numeric Y
|
||||
|
||||
### Target
|
||||
|
||||
- X: category labels (A/B/C/D)
|
||||
- Y: numeric values
|
||||
- line points aligned to categories
|
||||
|
||||
### Recipe
|
||||
|
||||
1. `coordinateSystem = Cartesian2D`
|
||||
2. X axis:
|
||||
- `axisType = Category`
|
||||
- `labels = [A, B, C, D]`
|
||||
- `LabelPlacement = Tick`
|
||||
3. Y axis:
|
||||
- `axisType = Value`
|
||||
- `autoRangeMin/autoRangeMax = true`
|
||||
4. Series:
|
||||
- `type = Line`
|
||||
- points: `x=category index`, `y=value`
|
||||
|
||||
Data example (conceptual):
|
||||
|
||||
```txt
|
||||
(x=0, y=10)
|
||||
(x=1, y=20)
|
||||
(x=2, y=15)
|
||||
(x=3, y=30)
|
||||
```
|
||||
|
||||
### Common pitfalls
|
||||
|
||||
- **Points do not align with labels**: check `x` starts from 0 and is within range (labels.Count)
|
||||
- **Line looks broken/jumpy**: check NaN/Infinity
|
||||
|
||||
---
|
||||
|
||||
## 2. Bar chart (Bar): centered categories + Y starts from 0
|
||||
|
||||
### Target
|
||||
|
||||
- one bar per category
|
||||
- labels centered under bars
|
||||
- Y axis starts from 0 to avoid misleading scaling
|
||||
|
||||
### Recipe
|
||||
|
||||
1. `coordinateSystem = Cartesian2D`
|
||||
2. X axis:
|
||||
- `axisType = Category`
|
||||
- fill `labels` with categories
|
||||
- `LabelPlacement = CellCenter`
|
||||
3. Y axis:
|
||||
- `axisType = Value`
|
||||
- force start at 0 (e.g. `minValue=0` + `autoRangeMax=true`, or equivalent)
|
||||
4. Series:
|
||||
- `type = Bar`
|
||||
- adjust bar width via `BarSettings.barWidth`
|
||||
|
||||
Data example:
|
||||
|
||||
```txt
|
||||
(x=0, y=12)
|
||||
(x=1, y=18)
|
||||
(x=2, y=9)
|
||||
```
|
||||
|
||||
### Common pitfalls
|
||||
|
||||
- **Bars appear between labels**: switch `LabelPlacement` to `CellCenter`
|
||||
- **Bars too dense/too sparse**: adjust `barWidth`, `barGap`, `categoryGap`
|
||||
|
||||
---
|
||||
|
||||
## 3. Grouped bars (Grouped Bar): multiple series share the same categories
|
||||
|
||||
### Recipe
|
||||
|
||||
- multiple `Serie`, all `type = Bar`
|
||||
- each Serie uses the same `x=category index` convention
|
||||
- use `Serie.name` as group name (used by legend/tooltip)
|
||||
|
||||
Example (conceptual):
|
||||
|
||||
```txt
|
||||
Serie A:
|
||||
(x=0, y=10) (x=1, y=12)
|
||||
Serie B:
|
||||
(x=0, y=8) (x=1, y=15)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Stacked bars (Stacked Bar): stacked + stackGroup
|
||||
|
||||
### Recipe
|
||||
|
||||
- Bar series that should stack:
|
||||
- `BarSettings.stacked = true`
|
||||
- `BarSettings.stackGroup = "Group1"` (same group stacks)
|
||||
|
||||
### Common pitfalls
|
||||
|
||||
- **Stack height looks wrong**: ensure all stacked series use exactly the same `stackGroup`
|
||||
|
||||
---
|
||||
|
||||
## 5. Scatter chart (Scatter): Value X/Y + hover + sizeMapping
|
||||
|
||||
### Target
|
||||
|
||||
- X/Y are continuous numeric values
|
||||
- point grows on hover
|
||||
- point size can be mapped by a dimension (sizeMapping)
|
||||
|
||||
### Recipe
|
||||
|
||||
1. `coordinateSystem = Cartesian2D`
|
||||
2. Set both X/Y axes to `Value`
|
||||
3. `type = Scatter`
|
||||
4. Data points: at least `x/value`, optionally use `z` as third dimension
|
||||
5. `ScatterSettings.hover.enabled = true`
|
||||
|
||||
### Common pitfalls
|
||||
|
||||
- **Points are too small**: increase `PointSettings.size`
|
||||
- **Hover does not respond**: check `HoverHighlightSettings.enabled` and `pickRadius`
|
||||
|
||||
---
|
||||
|
||||
## 6. Heatmap chart (Heatmap): (x, y, value) triplets
|
||||
|
||||
### Target
|
||||
|
||||
- X/Y are Category axes (2D labels)
|
||||
- color is determined by value
|
||||
|
||||
### Recipe
|
||||
|
||||
1. `coordinateSystem = Cartesian2D`
|
||||
2. X axis: Category + labels (column labels)
|
||||
3. Y axis: Category + labels (row labels)
|
||||
4. `type = Heatmap`
|
||||
5. Data points:
|
||||
- `x = column index`
|
||||
- `y = row index`
|
||||
- `value = intensity`
|
||||
|
||||
Example (conceptual):
|
||||
|
||||
```txt
|
||||
(x=0, y=0, value=0.2)
|
||||
(x=1, y=0, value=0.8)
|
||||
(x=0, y=1, value=0.5)
|
||||
```
|
||||
|
||||
### Common pitfalls
|
||||
|
||||
- **All cells look the same**: check `HeatmapSettings.autoRange/minValue/maxValue/clamp`
|
||||
- **Cells too small/too dense**: adjust `cellSizePx` / `cellGapPx`
|
||||
|
||||
---
|
||||
|
||||
## 7. Radar chart (Radar): dimension index + value
|
||||
|
||||
### Recipe
|
||||
|
||||
1. `coordinateSystem = Polar2D`
|
||||
2. `type = Radar`
|
||||
3. Data points:
|
||||
- `x = dimension index`
|
||||
- `value = numeric value`
|
||||
- `name = dimension name` (recommended for labels/tooltip)
|
||||
|
||||
Example:
|
||||
|
||||
```txt
|
||||
(x=0, value=72, name="Attack")
|
||||
(x=1, value=55, name="Defense")
|
||||
(x=2, value=90, name="Speed")
|
||||
```
|
||||
|
||||
### Common pitfalls
|
||||
|
||||
- **Radar labels are missing/messy**: ensure your dimension label source is consistent (do not depend on Cartesian axes)
|
||||
- **Radar not visible**: check `coordinateSystem` is Polar2D
|
||||
|
||||
---
|
||||
|
||||
## 8. Interaction/tooltip stability: SeriesData.id
|
||||
|
||||
If you enabled selection/tooltip/hover, it is generally recommended:
|
||||
|
||||
- keep each point `SeriesData.id` stable
|
||||
|
||||
> Otherwise, if you generate new ids every refresh, interaction state cannot be associated correctly.
|
||||
|
||||
---
|
||||
|
||||
## Next
|
||||
|
||||
- Next: `04_09-FAQ.md` (common issues + the fastest troubleshooting path)
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 3150243976518e347ac36c43af89f4fc
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/04_08-CommonRecipes.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,173 @@
|
||||
# FAQ (Common Issues and the Fastest Troubleshooting Path)
|
||||
|
||||
This chapter helps you locate the cause with the shortest path when you encounter "nothing shows", "wrong rendering", or "weird interactions".
|
||||
|
||||
---
|
||||
|
||||
## 0. Fast troubleshooting path (30-second version)
|
||||
|
||||
Check in order. This usually solves 80% of issues:
|
||||
|
||||
1. **Does coordinate system match SeriesType**
|
||||
- Cartesian2D: Line/Bar/Scatter/Heatmap
|
||||
- Polar2D: Radar
|
||||
|
||||
2. **Do you actually have data**
|
||||
- `series.Count > 0`
|
||||
- the serie has `seriesData.Count > 0`
|
||||
|
||||
3. **Do axis types match what your data means**
|
||||
- Category axis: `labels` is not empty; data `x/y` are indices (0/1/2...)
|
||||
- Value axis: `x/y` are continuous numeric values
|
||||
|
||||
4. **Any NaN / Infinity**
|
||||
|
||||
5. **Is data excluded by Value axis range**
|
||||
- Check if min/max are fixed
|
||||
- Check if `autoRangeMin/autoRangeMax` are disabled
|
||||
|
||||
---
|
||||
|
||||
## 1. I clicked Preview but nothing shows
|
||||
|
||||
### Possible causes
|
||||
|
||||
- `seriesData` is empty
|
||||
- `Serie.visible = false`
|
||||
- coordinate system does not match SerieType (e.g. Radar in Cartesian2D)
|
||||
- axis range does not include your data (common when Value axis range is locked manually)
|
||||
|
||||
### What to do
|
||||
|
||||
1. In the Inspector, find `series` and expand a Serie
|
||||
2. Check:
|
||||
- whether `visible` is true
|
||||
- whether `seriesData` has any elements
|
||||
3. Check the coordinate system:
|
||||
- Radar -> `coordinateSystem = Polar2D`
|
||||
- Line/Bar/Scatter/Heatmap -> `coordinateSystem = Cartesian2D`
|
||||
4. If you are using Value axes:
|
||||
- first disable any "fixed min/max" range settings
|
||||
- enable both `autoRangeMin/autoRangeMax`, confirm it renders, then lock step-by-step
|
||||
|
||||
---
|
||||
|
||||
## 2. Category axis has labels, but points/bars are not on labels
|
||||
|
||||
### Typical symptoms
|
||||
|
||||
- bars appear between two labels
|
||||
- line points do not align to A/B/C
|
||||
|
||||
### Quick conclusion
|
||||
|
||||
- With a Category axis, `x` (or `y`) should usually be the **category index** (0/1/2/...), not an arbitrary value.
|
||||
|
||||
### What to do
|
||||
|
||||
- Check your data points:
|
||||
- `labels[0]` corresponds to `x=0`
|
||||
- `labels[1]` corresponds to `x=1`
|
||||
- If you are making a bar chart:
|
||||
- set `LabelPlacement` to `CellCenter`
|
||||
|
||||
---
|
||||
|
||||
## 3. Value axis range is weird (too large/too small)
|
||||
|
||||
### Possible causes
|
||||
|
||||
- Value axis range is locked (min/max)
|
||||
- only one side is locked but the other side has extreme values
|
||||
- rounding/unit snapped the range to an unsuitable unit
|
||||
|
||||
### What to do
|
||||
|
||||
1. First, revert to full auto range and confirm it renders
|
||||
2. Then gradually add your constraints:
|
||||
- common for bar charts: `minValue=0` + `autoRangeMax=true`
|
||||
3. If you see lots of weird decimal ticks:
|
||||
- set `labelFormat` first
|
||||
|
||||
---
|
||||
|
||||
## 4. Line is broken / nothing renders
|
||||
|
||||
### Most common cause
|
||||
|
||||
- NaN / Infinity exists in your data
|
||||
|
||||
### What to do
|
||||
|
||||
- Filter at the data source:
|
||||
- `float.IsNaN(x/y/z)`
|
||||
- `float.IsInfinity(x/y/z)`
|
||||
|
||||
---
|
||||
|
||||
## 5. Bar chart and labels do not align
|
||||
|
||||
### Quick conclusion
|
||||
|
||||
- 99% of the time, `LabelPlacement` is not the right one
|
||||
|
||||
### What to do
|
||||
|
||||
- Bar: prefer `LabelPlacement = CellCenter`
|
||||
- Line/Scatter: prefer `LabelPlacement = Tick`
|
||||
|
||||
---
|
||||
|
||||
## 6. Heatmap is all one color / looks flat
|
||||
|
||||
### Possible causes
|
||||
|
||||
- `autoRange=false` but `minValue/maxValue` are unreasonable
|
||||
- `clamp=false` and extreme values stretch the color range
|
||||
- all data points have the same `value` (or all are 0)
|
||||
|
||||
### What to do
|
||||
|
||||
1. Enable `autoRange`
|
||||
2. Check whether data point `value` varies
|
||||
3. If you need a fixed range:
|
||||
- set `minValue/maxValue` reasonably
|
||||
|
||||
---
|
||||
|
||||
## 7. Radar labels are missing/messy
|
||||
|
||||
### Common cause
|
||||
|
||||
- dimension label sources are inconsistent
|
||||
|
||||
### Recommended approach
|
||||
|
||||
- For each Radar point:
|
||||
- `x = dimension index`
|
||||
- `value = numeric value`
|
||||
- `name = dimension name`
|
||||
|
||||
Also ensure Radar does not rely on Cartesian axis configuration to obtain labels.
|
||||
|
||||
---
|
||||
|
||||
## 8. tooltip/hover/selection points to the wrong item or state is unstable
|
||||
|
||||
### Common cause
|
||||
|
||||
- new point identifiers are generated on every refresh
|
||||
|
||||
### What to do
|
||||
|
||||
- keep each point `SeriesData.id` stable
|
||||
- avoid clearing and generating a completely new set of points with `Guid.NewGuid()` on every refresh
|
||||
|
||||
---
|
||||
|
||||
## 9. I don't know which chapter to read
|
||||
|
||||
- If you are in the workflow stage (create/clone/preview/export): see `01_01-EditorWorkflow.md`
|
||||
- If you are dealing with axes/range/alignment/unit/format: see section 7 of `00_02-WorkflowAndLibrary.md`
|
||||
- If you need the data conventions for a specific chart (SeriesData.x/y/z): see section 8 of `00_02-WorkflowAndLibrary.md`
|
||||
- If you just want copy-ready templates: see `04_08-CommonRecipes.md`
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 6d348b4bd3671b346ab70ccd28bc9abe
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/04_09-FAQ.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,172 @@
|
||||
# Roadmap / Update Plan
|
||||
|
||||
This chapter describes the overall direction and planned items for future EasyChart updates.
|
||||
|
||||
- This file is **not split by version phases** (more detailed planning can be added inside each chart type chapter later)
|
||||
- This file is organized by "capability categories" (you can treat it as a roadmap table of contents)
|
||||
|
||||
## Free / Pro split (release strategy)
|
||||
|
||||
### Free (standalone package)
|
||||
|
||||
- Positioning: cover the most common AssetStore use cases, forming a full loop of "configurable + previewable + runtime data injection".
|
||||
- Includes: existing basic 2D chart types, runtime injection (`ChartFeed` / `ApplyJson`), editor workflow such as `EasyChartLibraryWindow`.
|
||||
|
||||
### Pro (standalone package, includes all Free)
|
||||
|
||||
- Positioning: provide clear differentiated capabilities and a long-term expansion path on top of Free.
|
||||
- Includes: everything in Free + Pro incremental features (advanced effects / new chart types / 3D / tooling, etc.).
|
||||
|
||||
### Compatibility strategy
|
||||
|
||||
- When Free encounters Pro-only assets/configurations: it is allowed to fail with a direct error (no downgrade compatibility required).
|
||||
|
||||
### Pro initial selling points priority
|
||||
|
||||
- A: new chart types
|
||||
- B: 3D charts
|
||||
- C: advanced 2D visual effects (e.g. texture UV animation, special rendering effects)
|
||||
|
||||
---
|
||||
|
||||
## Appendix: version plan (tentative timeline)
|
||||
|
||||
> Note: the following is a tentative monthly/quarterly cadence. Specific dates can be refined after team capacity and release window are confirmed.
|
||||
|
||||
### 2026 Q1 (Jan–Mar): stabilization + complete Free loop
|
||||
|
||||
- 2026-01 (Free v1.0.x):
|
||||
- Fix/finalize: stability of JSON Injection panel and example generation/parsing (based on current TODO)
|
||||
- Docs & samples: align with the latest data structures and panel capabilities
|
||||
- 2026-02 (Free v1.1.0):
|
||||
- 2D UX improvements (Free scope): Bar rounded corners, hover effects (if not implemented yet, land in this version)
|
||||
- Editor UX: small workflow improvements in LibraryWindow (no Pro dependencies)
|
||||
- 2026-03 (Free v1.1.x):
|
||||
- Regression fixes + performance/GC optimization (large data refresh, tooltip/interaction stability)
|
||||
|
||||
### 2026 Q2 (Apr–Jun): Pro v1.0 (new chart types first)
|
||||
|
||||
Each series type adds an animation component collection, allowing effects such as Point blinking and TextureFill UV animation.
|
||||
- 2026-04 (Pro v1.0.0):
|
||||
- Finalize Pro package structure and release workflow (Pro includes all Free)
|
||||
- New chart types (batch 1): Gauge / Funnel (one or both depending on complexity)
|
||||
- 2026-05 (Pro v1.0.x):
|
||||
- New chart types (batch 2): BoxPlot / Candlestick (implement one with higher priority)
|
||||
- Improve Pro-only error hints and readable Editor-side error messages
|
||||
- 2026-06 (Free v1.2.0 + Pro v1.1.0):
|
||||
- Free: continue filling common 2D capabilities and stability
|
||||
- Pro: expand new chart types (Treemap / Sunburst research or first version)
|
||||
|
||||
### 2026 H2 (Jul–Dec): 3D roadmap and effects
|
||||
|
||||
- 2026 Q3 (Jul–Sep) (Pro v2.0 or v1.2+):
|
||||
- 3D charts (batch 1): 3D Bar / 3D Scatter (prioritize one to complete an end-to-end workflow)
|
||||
- 3D rendering pipeline and interaction foundations (iterate by minimum viable slices)
|
||||
- 2026 Q4 (Oct–Dec):
|
||||
- 3D Surface (research/experimental)
|
||||
- Advanced 2D visual effects (Pro): texture UV animation (and more complex effects later)
|
||||
- Tooling improvements: Theme / direct networking / automated tests (pick one as the main quality track)
|
||||
|
||||
---
|
||||
|
||||
## 1. Chart type expansion plan (Chart Types)
|
||||
|
||||
### 1.1 2D charts (enhancements to existing system)
|
||||
|
||||
- Goal: without adding too many `SerieType`, fill common expressions via settings/variants.
|
||||
- Candidate directions (examples):
|
||||
- Line: more line types/fills/annotations (richer markers/threshold lines, etc.), texture UV animation (Pro)
|
||||
- Bar: more stacking modes, percent stacking, waterfall modes, rounded bar caps (Free), hover effects (Free), texture UV animation (Pro)
|
||||
- Scatter: more mapping dimensions (size/color), density expressions (aggregation/gridding)
|
||||
- Pie: more layout/aggregation strategies, label strategies, interactions
|
||||
|
||||
### 1.2 New chart types (may add new `SerieType`)
|
||||
|
||||
- Goal: support more common standalone chart categories in AssetStore.
|
||||
- Candidate directions (examples):
|
||||
- Gauge
|
||||
- Funnel
|
||||
- BoxPlot
|
||||
- Candlestick (OHLC)
|
||||
- Treemap / Sunburst (hierarchical visualization)
|
||||
- Sankey / Graph (more complex structural charts; later)
|
||||
|
||||
### 1.3 3D charts (3D Charts)
|
||||
|
||||
- Goal: provide a 3D chart capability set (possibly a separate rendering pipeline).
|
||||
- Candidate directions (examples):
|
||||
- 3D Bar / 3D Column
|
||||
- 3D Scatter
|
||||
- 3D Surface (higher complexity; later)
|
||||
|
||||
---
|
||||
|
||||
## 2. Multi-axis & coordinate systems
|
||||
|
||||
- Goal: enhance multi-axis scenarios while keeping semantics clear.
|
||||
- Directions:
|
||||
- more axis combinations (dual Y axes, top/bottom X, mixed left/right Y)
|
||||
- clearer axis binding strategy (which axis a Serie binds to, which axis tooltip/label formats with)
|
||||
- constraints and hints for switching/mixing coordinate systems (avoid confusing configs)
|
||||
|
||||
---
|
||||
|
||||
## 3. Font & text system
|
||||
|
||||
- Goal: unify text rendering look and configurable options, reducing UI Toolkit cross-platform differences.
|
||||
- Directions:
|
||||
- more complete text styles (font, size, weight, color, outline/shadow, etc.)
|
||||
- text layout strategies (wrap, truncate, ellipsis, alignment, anchors)
|
||||
- enhanced number formatting (thousands separator, units, percent, scientific notation, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 4. Time axis & log axis
|
||||
|
||||
- Goal: improve expression for time series and wide-range values.
|
||||
- Directions:
|
||||
- time axis: ticks, formatting, interval strategies (day/week/month/year)
|
||||
- log axis: log10/log2 ticks and labels
|
||||
- integration with data injection (how to feed time data, handle missing points)
|
||||
|
||||
---
|
||||
|
||||
## 5. Theme / palette system
|
||||
|
||||
- Goal: abstract "colors/fonts/default styles" from individual Profiles into reusable themes.
|
||||
- Directions:
|
||||
- Theme assets (Palette + fonts + default styles)
|
||||
- override strategy between Profile and Theme (theme defaults vs Profile overrides)
|
||||
- theme preview, switching, theme library
|
||||
|
||||
---
|
||||
|
||||
## 6. Direct networking / data binding
|
||||
|
||||
- Goal: reduce integration cost from network API to chart.
|
||||
- Directions:
|
||||
- standard input protocol based on `ChartFeed`
|
||||
- optional API Envelope support (e.g. `{code,message,data}`)
|
||||
- samples: HTTP fetch -> parse -> Apply
|
||||
- caching, throttling, error hints, fallback strategies
|
||||
|
||||
---
|
||||
|
||||
## 7. Automated tests & QA
|
||||
|
||||
- Goal: reduce iteration risk and make refactors safer.
|
||||
- Directions:
|
||||
- data migration tests (serialization compatibility)
|
||||
- rendering regression tests (screenshot diff/pixel tolerance, or key mesh assertions)
|
||||
- interaction tests (tooltip/hit test stability)
|
||||
- performance benchmarks (large data refresh, GC, frame time)
|
||||
|
||||
---
|
||||
|
||||
## 8. Editor workflow & tooling
|
||||
|
||||
- Goal: make configuration, preview, injection, and reuse smoother.
|
||||
- Directions:
|
||||
- LibraryWindow: templates/copy/import-export/batch operations
|
||||
- JSON Injection: stronger protocol compatibility, better error localization, better example generation
|
||||
- clearer manual and sample project
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 84f6d1c5ac835fb409a6d70824b41c75
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/en/05_01-UpdatePlan.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,8 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 3b13c9d015526e9458cba8f2b92e7818
|
||||
folderAsset: yes
|
||||
DefaultImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
@@ -0,0 +1,73 @@
|
||||
# 快速导览
|
||||
|
||||
本手册面向通过 **`EasyChartLibraryWindow`** 在 Unity 编辑器里配置图表（`ChartProfile` 资产）的工作流。
|
||||
|
||||
- 菜单入口：`EasyChart/Library Editor`
|
||||
- 手册查看器：`EasyChart/Manual`
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
### A. 上手与工作流
|
||||
|
||||
- [快速导览](./00_00-Index.md)
|
||||
- [快速上手：2 分钟做出第一张图](./00_01-QuickStart.md)
|
||||
- [UIToolKit工作流（推荐）](./00_02-WorkflowAndLibrary.md)
|
||||
- [UGUI工作流](./00_03-UGUIWorkflow.md)
|
||||
- [运行时数据注入（UIToolKit）](./00_04-RuntimeDataInjectionUIToolKit.md)
|
||||
- [运行时数据注入（UGUI）](./00_05-RuntimeDataInjectionUGUI.md)
|
||||
|
||||
### B. 编辑器与面板
|
||||
|
||||
- [编辑器工作流与面板说明](./01_01-EditorWorkflow.md)
|
||||
- [Library 面板（资源树）](./01_02-LibraryPanel.md)
|
||||
- [JSON Injection 面板](./01_03-JsonInjectionPanel.md)
|
||||
- [Preview 面板](./02_04-PreviewPanel.md)
|
||||
- [Inspector 面板](./02_05-InspectorPanel.md)
|
||||
- [Series 面板](./02_06-SeriesPanel.md)
|
||||
|
||||
### C. Series详细配置（用户目的导向）
|
||||
|
||||
- [折线图（Line）](./03_01-LineChart.md)
|
||||
- [柱状图（Bar）](./03_02-BarChart.md)
|
||||
- [散点图（Scatter）](./03_03-ScatterChart.md)
|
||||
- [热力图（Heatmap）](./03_04-HeatmapChart.md)
|
||||
- [雷达图（Radar）](./03_05-RadarChart.md)
|
||||
- [饼图（Pie）](./03_06-PieChart.md)
|
||||
- [圆环图（RingChart）](./03_07-RingChart.md)
|
||||
|
||||
### D. 配置项参考（按字段分类，查字典）
|
||||
|
||||
- [常用配方（Common Recipes）](./04_08-CommonRecipes.md)
|
||||
- [FAQ（常见问题与最快排错路线）](./04_09-FAQ.md)
|
||||
|
||||
### E. 更新与规划
|
||||
|
||||
- [更新计划（Roadmap / Update Plan）](./05_01-UpdatePlan.md)
|
||||
|
||||
---
|
||||
|
||||
## 约定与术语
|
||||
|
||||
- **ChartProfile**：图表配置资产（可复用，可在编辑器预览）。
|
||||
- **Series / Serie**：数据序列（例如折线的一条线、柱状图的一组柱）。
|
||||
- **SeriesData**：序列中的数据点集合。
|
||||
- **Axis**：坐标轴配置（`AxisType=Category/Value`）。
|
||||
- **Category**：类目轴（使用 `labels` 列表）。
|
||||
- **Value**：数值轴（连续数值范围）。
|
||||
|
||||
---
|
||||
|
||||
## 推荐文件组织
|
||||
|
||||
建议在项目中为图表配置建立一个统一目录：
|
||||
|
||||
- `Assets/EasyChart/Library/Custom/`：你自己的 `ChartProfile` 资产
|
||||
- `Assets/EasyChart/Docs/Manual/`：本手册章节（Markdown）
|
||||
|
||||
---
|
||||
|
||||
## 手册版本
|
||||
|
||||
- 本手册将随 EasyChart 的字段与编辑器功能迭代同步更新。
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 53aa31f9abd8cc148a6ad3cfc73b7b84
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/00_00-Index.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,93 @@
|
||||
# 快速上手：2 分钟做出第一张图
|
||||
|
||||
本章目标：按 EasyChart 推荐的最快路径跑通“**编辑 → 导出 → 在 UI 中使用**”的闭环。
|
||||
|
||||
---
|
||||
|
||||
## 打开编辑器窗口
|
||||
|
||||
在 Unity 菜单栏选择：
|
||||
|
||||
- `EasyChart/Library Editor`
|
||||
|
||||
你会看到一个类似“资源库/配置面板/预览区”的窗口（后续章节会解释每个区域）。
|
||||
|
||||
---
|
||||
|
||||
## 克隆一个 Library（推荐）
|
||||
|
||||
如果你想快速开始并保持风格一致，建议：
|
||||
|
||||
- 先在窗口顶部工具栏选择一个已有 Library（例如内置 Demo 库）
|
||||
- 点击工具栏的 **Clone**，克隆出你的个人库（例如 `MyLibrary`）
|
||||
|
||||
这样你后续所有修改都发生在自己的库里，避免污染原始示例。
|
||||
|
||||
---
|
||||
|
||||
## 克隆一个 ChartProfile（推荐）
|
||||
|
||||
在资源树里找到一个接近你目标效果的图表（`ChartProfile`），右键：
|
||||
|
||||
- `Clone`
|
||||
|
||||
克隆后，你会得到一个新的 Profile（用于做“同款变体”）。选中它，右侧 Inspector 会显示你可以直接修改的所有配置。
|
||||
|
||||
---
|
||||
|
||||
## 修改配置并保存
|
||||
|
||||
最少改动建议：
|
||||
|
||||
- `coordinateSystem`：确保与你要的 Series 匹配（例如 Line/Bar/Scatter 用 `Cartesian2D`）
|
||||
- `series`：确认 `type` 正确，并填充 `seriesData`
|
||||
- `axes`：最少保证 X/Y 轴类型与数据含义匹配
|
||||
|
||||
完成修改后，点击窗口顶部工具栏的保存按钮（如果你的版本有），或等待 Unity 自动保存资产。
|
||||
|
||||
---
|
||||
|
||||
## 导出 UXML（用于 UI Builder 复用）
|
||||
|
||||
推荐做法是把 Profile 导出为可复用的 `.uxml`：
|
||||
|
||||
- 在资源树里右键你的 Profile
|
||||
- 选择 `Export to UXML`
|
||||
|
||||
导出的 UXML 会进入：
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/`（Mirror/Backup 相关操作也会在这个根目录下管理导出物）
|
||||
|
||||
---
|
||||
|
||||
## 在 QuickStart 场景里用 UIDocument + UI Builder 使用
|
||||
|
||||
打开示例场景：
|
||||
|
||||
- `Assets/EasyChart/Demo/Scenes/EasyChart_QuickStart.unity`
|
||||
|
||||
然后在 Project 中找到：
|
||||
|
||||
- `Assets/EasyChart/Demo/UIToolKit/NewUXMLTemplate.uxml`
|
||||
|
||||
双击它打开（或在 UI Builder 中打开）。接下来：
|
||||
|
||||
- 从 Project 里把你刚导出的图表 `.uxml` 拖入到 `NewUXMLTemplate.uxml` 的层级中
|
||||
- 保存 UXML
|
||||
- 确认场景里的 `UIDocument` 引用了你编辑后的 `NewUXMLTemplate.uxml`
|
||||
|
||||
运行场景，你会看到图表渲染在 UI Toolkit 页面中。
|
||||
|
||||
---
|
||||
|
||||
## 备选：导出为 UGUI 预制体并使用
|
||||
|
||||
如果你希望用 UGUI（Canvas/RectTransform）工作流，也可以在 Library Editor 中把选中的 Profile 导出为 UGUI 预制体并直接放进场景 UI（具体入口与细节取决于你当前版本提供的菜单项）。
|
||||
|
||||
---
|
||||
|
||||
## 下一步你应该看什么
|
||||
|
||||
- 你要系统理解 UI Toolkit 推荐工作流：`00-WorkflowAndLibrary.md`
|
||||
- 你要用 UGUI（Canvas/RectTransform）把图表用起来：`33-UGUIWorkflow.md`
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 7a3e06221e4a0974ebd24b9f268e3d0c
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/00_01-QuickStart.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,429 @@
|
||||
# UIToolKit工作流（推荐）
|
||||
|
||||
本章目标：先把 EasyChart 推荐的整体实现思路讲清楚（以 UI Toolkit 为主）：
|
||||
|
||||
1. 在编辑器中用 **`EasyChartLibraryWindow`** 编辑 `ChartProfile`
|
||||
2. 将 `ChartProfile` **导出为 `.uxml`**，作为你的“图表库”资源
|
||||
3. 在 UI Toolkit 中用 **UI Builder** / UXML 组合页面，实现快速搭建 UI
|
||||
|
||||
本章专注于 **UI Toolkit（推荐）**。如果你需要 UGUI（Canvas/RectTransform）工作流，请看：
|
||||
|
||||
- `33-UGUIWorkflow.md`
|
||||
|
||||
|
||||
## 0. 为什么推荐 UI Toolkit 工作流
|
||||
|
||||
核心原因：把“图表配置源（ChartProfile）”和“UI 落地物（UXML）”分层管理。
|
||||
|
||||
- `ChartProfile`：负责图表“长什么样/用什么轴/有哪些 Series/数据如何解释”，适合在编辑器中集中维护。
|
||||
- 导出的 `.uxml`：负责把图表以 UI Toolkit 组件形式落地到页面中，适合复用/组合/版本控制。
|
||||
|
||||
你最终得到的是：
|
||||
|
||||
- 配置可复用（多个页面引用同一套图表风格）
|
||||
- 页面可组装（UI Builder 拖拽组合，不需要每次从零搭 UI）
|
||||
- 团队协作更清晰（Profile 作为“源”，UXML 作为“产物/组件库”）
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么要导出 UXML
|
||||
|
||||
在项目里，`ChartProfile` 负责描述“图表长什么样、用什么轴、有什么 Series、数据点怎么解释”。
|
||||
|
||||
当你导出 `.uxml` 后，你得到的是一个可在 UI Toolkit 中复用的 UI 资源：
|
||||
|
||||
- 可以被 UI Builder 直接拖拽使用
|
||||
- 可以被多个页面复用（同一套图表样式）
|
||||
- 可以被版本控制与资产管理（你的“图表库”）
|
||||
|
||||
---
|
||||
|
||||
## 2. 推荐工作流（从配置到页面）
|
||||
|
||||
### Step 1：克隆出你的工作库与图表（推荐）
|
||||
|
||||
- 在 Unity 菜单栏打开：`EasyChart/Library Editor`
|
||||
|
||||
推荐流程：
|
||||
|
||||
- **Clone Library**：先克隆一个你自己的 Library（避免直接改内置示例库）
|
||||
- **Clone ChartProfile**：在你的库里右键某个接近目标效果的 Profile，选择 `Clone` 生成变体
|
||||
- 在右侧 Inspector 修改：
|
||||
- `coordinateSystem`
|
||||
- `series`
|
||||
- `axes`
|
||||
|
||||
> 建议：把你自己的 Profile 统一放在 `Assets/EasyChart/Library/Custom/`（或团队约定目录）。
|
||||
|
||||
### Step 2：导出 UXML（生成库资源）
|
||||
|
||||
你可以在 Library Editor 里执行导出：
|
||||
|
||||
- 对某个 Profile：`Export to UXML`
|
||||
- 对某个文件夹：
|
||||
- `Export Folder to UXML (Mirror)`
|
||||
- `Export Folder to UXML (Backup)`
|
||||
- 全量：
|
||||
- `Export All UXML (Mirror)`
|
||||
- `Export All UXML (Backup)`
|
||||
|
||||
导出根目录：
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/`
|
||||
|
||||
多 Library 时通常结构为：
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/<LibraryName>/...`
|
||||
|
||||
其中 `_Backups` 子目录用于存放备份导出（以及一些导出过程附带的 JSON 备份文件）：
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/<LibraryName>/_Backups/...`
|
||||
|
||||
导出的 UXML 核心结构类似：
|
||||
|
||||
- 一个 `<ec:ChartElement profile-name="..." />`
|
||||
- `profile-name` 对应某个 ChartProfile 的 key（通常是资产文件名）
|
||||
- 同时会写入图表的 width/height 样式
|
||||
|
||||
> 重点：你应该把导出的 `.uxml` 当作“可复用图表组件”，而不是每次手写 UI。
|
||||
|
||||
### Mirror vs Backup（你应该怎么选）
|
||||
|
||||
- **Mirror**：
|
||||
- 用于“把 Profile 当前状态镜像到 UXML”
|
||||
- 通常会覆盖同名导出物，并可能清理不再存在的旧文件（保持镜像一致）
|
||||
- **Backup**：
|
||||
- 用于“按时间/标签做一次备份导出”
|
||||
- 不建议作为页面直接引用的主路径（更适合作为历史快照/回滚）
|
||||
|
||||
### Step 3：在 UI Builder 里组装页面
|
||||
|
||||
在 UI Builder 中：
|
||||
|
||||
- 打开你的页面 UXML
|
||||
- 从 Project 里拖入导出的图表 `.uxml`
|
||||
- 将它与其他 UI（Label、Button、ListView 等）组合成完整页面
|
||||
|
||||
如果你要最快验证导出链路，可以直接使用示例场景与模板：
|
||||
|
||||
- 场景：`Assets/EasyChart/Demo/Scenes/EasyChart_QuickStart.unity`
|
||||
- 模板：`Assets/EasyChart/Demo/UIToolKit/NewUXMLTemplate.uxml`
|
||||
|
||||
把导出的图表 `.uxml` 拖入 `NewUXMLTemplate.uxml`，然后确认场景中的 `UIDocument` 引用了该模板。
|
||||
|
||||
#### 在 UI Builder 中的具体操作（建议按这个顺序）
|
||||
|
||||
1. 打开 UI Builder（或直接双击你的页面 `.uxml`）。
|
||||
2. 在 Project 中找到你导出的图表 `.uxml`（通常位于 `Assets/EasyChart/LibraryUxml/<LibraryName>/...`）。
|
||||
3. 将该 `.uxml` 拖入页面的 Hierarchy（建议放进一个容器 `VisualElement` 内）。
|
||||
4. 保存页面 UXML。
|
||||
5. 回到场景，确认 `UIDocument` 引用的是你刚保存的页面 `.uxml`。
|
||||
|
||||
#### 导出的图表 UXML 内部是什么
|
||||
|
||||
导出的 `.uxml` 通常包含一个 `EasyChart.ChartElement`，并带有属性：
|
||||
|
||||
- `profile-name`：通常对应 `ChartProfile` 的资产文件名（key）
|
||||
- `profile-guid`：更稳定的资产定位方式
|
||||
|
||||
因此：
|
||||
|
||||
- 如果你只是修改了 Profile，页面不会自动变化：需要重新导出（Mirror）让 UXML 更新。
|
||||
- 如果你改了 Profile 的资产文件名，导出的 `profile-name` 也会随之变化（建议保持命名稳定）。
|
||||
|
||||
### Step 4：运行时加载/替换数据（按你的业务决定）
|
||||
|
||||
`ChartProfile`/UXML 负责“样式与结构”，而数据来源通常来自你的业务逻辑。
|
||||
|
||||
- 静态展示：直接在 Profile 的 `seriesData` 中填写
|
||||
- 动态展示：运行时写入/替换 `seriesData`（并保持 `SeriesData.id` 稳定性）
|
||||
|
||||
---
|
||||
|
||||
## 3. 图表库的目录建议
|
||||
|
||||
建议把“配置源”和“导出物”分开：
|
||||
|
||||
- `Assets/EasyChart/Library/Custom/`：你维护的 `ChartProfile`
|
||||
- `Assets/EasyChart/LibraryUxml/`：导出的 UXML（镜像/备份都会落在这个根目录下）
|
||||
|
||||
当你使用多 Library 时，导出物通常会按库名分子目录：
|
||||
|
||||
- `Assets/EasyChart/LibraryUxml/<LibraryName>/...`
|
||||
|
||||
建议约定：
|
||||
|
||||
- **Profile 只在 `Assets/EasyChart/Library/...` 下维护**（作为配置源）
|
||||
- **页面只引用 Mirror 的导出物**（作为组件库）
|
||||
- Backup 永远只当“历史快照”
|
||||
|
||||
> 这样做的好处是：
|
||||
> - 配置源可读、可编辑
|
||||
> - 导出物可复用、可组合、可直接用于 UI Builder
|
||||
|
||||
---
|
||||
|
||||
## 4. 常见问题与排错
|
||||
|
||||
- **UI Builder 里找不到导出的图表 UXML**
|
||||
- 优先检查 `Assets/EasyChart/LibraryUxml/` 下是否已生成
|
||||
- 如果你使用了多 Library，检查是否在 `Assets/EasyChart/LibraryUxml/<LibraryName>/` 下
|
||||
- Mirror/Backup 的导出物可能位于 `_Backups`，不建议页面引用 `_Backups` 里的文件
|
||||
|
||||
- **页面里引用了 UXML 但运行时不显示**
|
||||
- 确认场景里的 `UIDocument` 引用了你编辑的页面 `.uxml`
|
||||
- 回到 Library Editor 的 Preview 看该 Profile 是否能正常显示（先排除 Profile 配置问题）
|
||||
|
||||
- **修改了 Profile 但页面没变化**
|
||||
- Profile 是“源”，页面引用的是导出的 UXML
|
||||
- 修改 Profile 后请重新执行导出（Mirror），再回到页面刷新/保存
|
||||
|
||||
- **UI Builder 里看得到组件，但运行时仍然不显示**
|
||||
- 优先确认：场景里的 `UIDocument` 是否真的引用了该页面（而不是另一个旧页面）
|
||||
- 再确认：Profile 在 Library Editor 的 Preview 是否能正常显示（先排除配置问题）
|
||||
|
||||
---
|
||||
|
||||
## 5. 下一步你应该看什么
|
||||
|
||||
- 你想快速跑通一张图：`01-QuickStart.md`
|
||||
- 你要用 UGUI（Canvas/RectTransform）把图表用起来：`33-UGUIWorkflow.md`
|
||||
|
||||
---
|
||||
|
||||
## 6. 编辑器工作流与面板速查（Library Editor）
|
||||
|
||||
本节把原先分散在多个章节中的“编辑器工作流与面板说明”合并到一起，作为你在 `EasyChart/Library Editor` 中操作时的速查。
|
||||
|
||||
### 6.1 你在编辑的是什么？（ChartProfile）
|
||||
|
||||
在 Library Editor 里被选中的图表，本质上是一个 `ChartProfile` 资产。
|
||||
|
||||
- 它是可复用配置：同一个 Profile 可以被多个场景/Prefab 引用。
|
||||
- 它是可预览配置：在编辑器里修改后可以立即看到预览变化。
|
||||
|
||||
### 6.2 Library Editor 的核心区域
|
||||
|
||||
你可以把窗口理解为四块：
|
||||
|
||||
- 左侧：Library（资源树）
|
||||
- 中部：Preview（预览区）
|
||||
- 右侧：Inspector（配置）
|
||||
- 右侧：Series（系列与数据）
|
||||
|
||||
此外左侧通常还有 JSON Injection（JSON 注入面板）。
|
||||
|
||||
### 6.3 Library 面板（资源树）
|
||||
|
||||
功能概览：
|
||||
|
||||
- 以树状结构展示图表库目录下的文件夹与 `ChartProfile`（`.asset`）。
|
||||
- 选中某个 `ChartProfile` 后，会驱动 Inspector/Series/Preview 的绑定与刷新。
|
||||
- 支持创建/重命名/删除/拖拽移动与排序。
|
||||
|
||||
选择逻辑：
|
||||
|
||||
- 选中的是文件夹：右侧 Inspector/Series 清空（无 Profile 可编辑）。
|
||||
- 选中的是 ChartProfile：右侧面板绑定到该 Profile。
|
||||
|
||||
常用操作（标题栏与右键菜单，具体以版本为准）：
|
||||
|
||||
- Folder：New Folder / New Chart / Export Folder to UXML（Mirror/Backup）/ Rename / Delete
|
||||
- ChartProfile：Export to UXML / Clone / Rename / Delete
|
||||
|
||||
### 6.4 Preview 面板（预览区）
|
||||
|
||||
Preview 的作用是把当前选中的 `ChartProfile` 直接渲染出来，方便你在编辑配置时即时验证效果。
|
||||
|
||||
常见问题：
|
||||
|
||||
- 预览为空：确认是否至少 1 条 `Serie`，且该 serie 的 `seriesData` 不为空。
|
||||
- 数据有但显示怪：确认坐标系与 SeriesType 匹配，轴范围是否把数据排除在外。
|
||||
|
||||
### 6.5 Inspector 面板（配置面板）
|
||||
|
||||
Inspector 的定位是以“配置视角”编辑 Profile 的序列化字段（坐标系、轴、网格、交互、图例等），并驱动 Preview 更新。
|
||||
|
||||
提示：
|
||||
|
||||
- 如果你发现某些字段修改后没效果，先确认页面引用的是你导出的 UXML，而不是直接引用 Profile。
|
||||
|
||||
### 6.6 Series 面板（系列与数据）
|
||||
|
||||
Series 面板以“图表结构”的方式编辑 `ChartProfile.series`：
|
||||
|
||||
- 添加/删除/排序系列
|
||||
- 为每条 serie 选择 `type` 并编辑 `settings`
|
||||
- 编辑 `seriesData`（数据点）
|
||||
|
||||
### 6.7 JSON Injection 面板（JSON 注入）
|
||||
|
||||
定位：把当前 Profile 的信息表达为可复制的 JSON，并支持解析 JSON 回写到当前 Profile。
|
||||
|
||||
推荐工作流：
|
||||
|
||||
1. 从当前 Profile 生成示例 JSON
|
||||
2. Copy 到外部编辑器做批量修改
|
||||
3. 粘贴回来并 ApplyToChart
|
||||
|
||||
---
|
||||
|
||||
## 7. 轴与范围（Axis & Range）
|
||||
|
||||
### 7.1 AxisType：Category vs Value
|
||||
|
||||
- Category（类目轴）：用 `labels` 定义离散类目（A/B/C 或 周一/周二/周三）。
|
||||
- Value（数值轴）：连续数值范围（0~100，-3~3，0~1e6）。
|
||||
|
||||
#### 7.1.1 什么时候用 Category
|
||||
|
||||
- X 轴是“文本标签序列”
|
||||
- 你希望数据点落在 `labels[i]` 上
|
||||
- 典型：柱状图（每类一组柱）、折线图（按类目对齐）
|
||||
|
||||
Category 的关键点：
|
||||
|
||||
- `labels[0]` 对应类目索引 `0`
|
||||
- `labels[1]` 对应类目索引 `1`
|
||||
|
||||
#### 7.1.2 什么时候用 Value
|
||||
|
||||
- X 或 Y 轴是连续数值（例如时间戳、金额、温度）
|
||||
- 你希望轴可以按数值缩放/平移
|
||||
|
||||
Value 的关键点：
|
||||
|
||||
- 轴范围通常由自动范围计算得到（如果开启 auto range）
|
||||
- 你可以只锁定一端（例如固定最小值为 0，最大值自动）
|
||||
|
||||
### 7.2 Category 轴：labels 与 LabelPlacement
|
||||
|
||||
`labels` 决定类目个数与标签文本。
|
||||
|
||||
`LabelPlacement` 影响对齐方式：
|
||||
|
||||
- `Tick`：标签对齐刻度点，更适合 Line/Scatter。
|
||||
- `CellCenter`：标签对齐格子中心，更适合 Bar/Heatmap。
|
||||
|
||||
常见现象：
|
||||
|
||||
- 柱子落在两个标签之间：优先把 `LabelPlacement` 调成 `CellCenter`。
|
||||
|
||||
### 7.3 Value 轴：autoRangeMin / autoRangeMax
|
||||
|
||||
如果你看到范围“锁死”导致数据不显示，先把范围回退到全自动：
|
||||
|
||||
- 打开 `autoRangeMin/autoRangeMax`
|
||||
|
||||
确认可见后，再逐步加入业务约束（例如柱状图纵轴从 0 起）。
|
||||
|
||||
#### 7.3.1 常见模板：Y 轴从 0 开始
|
||||
|
||||
- `axisType = Value`
|
||||
- 固定 `minValue = 0`
|
||||
- `autoRangeMax = true`
|
||||
|
||||
#### 7.3.2 常见模板：只锁定 Max（例如百分比）
|
||||
|
||||
- 固定 `maxValue = 100`
|
||||
- `autoRangeMin = true`
|
||||
|
||||
### 7.4 rounding / unit / labelFormat
|
||||
|
||||
- rounding：让范围吸附到更“整”的单位。
|
||||
- unit：显示单位压缩（个/万/百万）。
|
||||
- labelFormat：控制数字格式（N0/N2/F1/百分比等）。
|
||||
|
||||
#### 7.4.1 单位显示（showUnit / unitText）
|
||||
|
||||
当数值很大（例如 10,000 以上）时，常见做法是让轴末端显示单位（如“万”“k”“M”）。
|
||||
|
||||
#### 7.4.2 快速排错
|
||||
|
||||
- 标签对不齐 / 柱子夹在标签中间：优先检查 Category 轴的 `LabelPlacement`
|
||||
- 轴范围很怪（特别大/特别小）：检查是否锁死 min/max；检查 rounding/unit
|
||||
- 刻度小数太多：优先设置 `labelFormat`
|
||||
|
||||
---
|
||||
|
||||
## 8. Series 与数据（Serie / SeriesData）
|
||||
|
||||
### 8.1 Serie（一条序列）
|
||||
|
||||
在 `ChartProfile.series` 中每个元素是一个 `Serie`：
|
||||
|
||||
- `name`
|
||||
- `type`
|
||||
- `visible`
|
||||
- `settings`
|
||||
- `labelSettings`
|
||||
- `seriesData`
|
||||
|
||||
补充：`settings` 通常是多态对象（`SerializeReference`）。切换 `type` 时，会尝试保留每种类型上一次的 settings（编辑体验更好）。
|
||||
|
||||
### 8.2 SeriesData（一个数据点）
|
||||
|
||||
`SeriesData` 常见字段：
|
||||
|
||||
- `id`：稳定标识（tooltip/hover/隐藏状态）。
|
||||
- `x`：X 坐标或 Category 索引。
|
||||
- `value`：主要数值。
|
||||
- `y`：第二维坐标（散点/热力图等）。
|
||||
- `z`：第三维（sizeMapping 等）。
|
||||
- `name`：点名称（Radar/Pie/Ring 等可能用到）。
|
||||
- `useColor` + `color`：点级颜色覆盖。
|
||||
|
||||
如果启用了交互，建议保证 `SeriesData.id` 稳定，避免每次刷新数据都生成一套新的 id。
|
||||
|
||||
### 8.3 SerieType 与坐标系的匹配
|
||||
|
||||
- Cartesian2D：Line/Bar/Scatter/Heatmap
|
||||
- Polar2D：Radar
|
||||
|
||||
不建议在同一个 ChartProfile（非 Pie）里混用 Polar 与 Cartesian 系列；如果你真的混用，要特别小心 axes/grid 语义是否一致。
|
||||
|
||||
### 8.4 常用数据写法（按类型）
|
||||
|
||||
#### 8.4.1 Line
|
||||
|
||||
- 常见：Category X + Value Y
|
||||
- 数据点：`x=类目索引`，`value=数值`
|
||||
- 连续：Value X + Value Y
|
||||
- 数据点：`x=横轴数值`，`value=纵轴数值`
|
||||
|
||||
#### 8.4.2 Bar
|
||||
|
||||
- Category X + Value Y
|
||||
- 每个柱子一个点：`x=类目索引`，`value=柱高`
|
||||
- 并列：多条 Bar serie 共享同一套 Category X
|
||||
- 堆叠：`stacked=true` 且 `stackGroup` 相同的系列会堆叠
|
||||
|
||||
#### 8.4.3 Scatter
|
||||
|
||||
- 常用：X=Value，Y=Value
|
||||
- 数据点推荐显式写 `x/y`
|
||||
|
||||
#### 8.4.4 Heatmap
|
||||
|
||||
- 三元组：`x=列索引`，`y=行索引`，`value=强度`
|
||||
|
||||
#### 8.4.5 Radar
|
||||
|
||||
- 常见理解：`x=维度索引`，`value=该维度数值`，`name=维度名称`
|
||||
|
||||
### 8.5 数据常见坑（按现象排查）
|
||||
|
||||
- Category 图表 X 轴是 Category，但数据点 x 不是 0/1/2...
|
||||
- 现象：点/柱子不在标签上
|
||||
- 处理：确保 `x=类目索引`，或者把 X 改成 Value
|
||||
|
||||
- 出现 NaN/Infinity
|
||||
- 现象：整张图不渲染、范围爆炸
|
||||
- 处理：在数据源侧过滤异常值
|
||||
|
||||
- 看不到图（但 seriesData 不为空）
|
||||
- 检查：坐标系是否匹配（Cartesian vs Polar）
|
||||
- 检查：AxisType 是否匹配数据含义
|
||||
|
||||
- 交互/tooltip 指向错乱
|
||||
- 检查：`SeriesData.id` 是否稳定（不要每次刷新都随机生成一套新的点）
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 09c273b938da2fb42869b05022661833
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/00_02-WorkflowAndLibrary.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,129 @@
|
||||
# UGUI工作流
|
||||
|
||||
本章目标：用 UGUI（Canvas/RectTransform）把 EasyChart 图表用起来，并理解两种渲染模式的选择：
|
||||
|
||||
- `ScreenSpaceOverlay`：画质最好（不使用 RenderTexture），但通常只在 Game 视图可见
|
||||
- `WorldSpace`：Scene/Game 都可见（使用 RenderTexture），适合 3D 世界空间 UI
|
||||
|
||||
---
|
||||
|
||||
## 1. 推荐方案：UGUIChartBridge
|
||||
|
||||
推荐使用 `UGUIChartBridge` 组件。
|
||||
|
||||
它的定位是：
|
||||
|
||||
- 仍然使用 **UI Toolkit 的 `ChartElement`** 作为图表渲染核心
|
||||
- 通过桥接把图表“贴合”到某个 UGUI `RectTransform` 上
|
||||
|
||||
因此它兼顾：
|
||||
|
||||
- 图表能力与 UI Toolkit 渲染
|
||||
- UGUI 场景/Prefab 的搭建与布局习惯
|
||||
|
||||
---
|
||||
|
||||
## 2. 通用前置条件
|
||||
|
||||
无论你选哪种模式，都建议先准备：
|
||||
|
||||
- 一个要显示的 `ChartProfile`（建议从 `EasyChart/Library Editor` 克隆后修改得到）
|
||||
- 一个 `PanelSettings` 资产，并在 `UGUIChartBridge` 的 `Panel Settings Asset` 中指定
|
||||
|
||||
> 备注：`Panel Settings Asset` 对字体渲染与整体稳定性更友好。
|
||||
|
||||
---
|
||||
|
||||
## 3. Screen Space Overlay（推荐用于 HUD/面板）
|
||||
|
||||
### 适用场景
|
||||
|
||||
- HUD、UI 面板、弹窗
|
||||
- 追求画质与清晰度
|
||||
|
||||
### 特点
|
||||
|
||||
- 不使用 RenderTexture
|
||||
- 通常只在 Game 视图可见
|
||||
|
||||
### 搭建步骤（概览）
|
||||
|
||||
1. 创建 `Canvas`
|
||||
2. 在 Canvas 下创建一个带 `RectTransform` 的节点（`Image` 或空物体均可）
|
||||
3. 添加 `UGUIChartBridge`
|
||||
4. 配置：
|
||||
- `Profile`
|
||||
- `Panel Settings Asset`
|
||||
- `Render Mode = ScreenSpaceOverlay`
|
||||
- `Sort Order`（用于层级覆盖；仅 Screen Space Overlay 模式生效）
|
||||
|
||||
关键点：
|
||||
|
||||
- 该模式会把图表渲染在一个运行时创建/复用的 `UIDocument` 里。
|
||||
- 如果被其他 UI 盖住，优先调大 `Sort Order`。
|
||||
|
||||
---
|
||||
|
||||
## 4. World Space（推荐用于 3D 世界空间面板）
|
||||
|
||||
### 适用场景
|
||||
|
||||
- 3D 世界里的看板/屏幕/面板
|
||||
- 希望 Scene 视图也能看到渲染结果
|
||||
|
||||
### 特点
|
||||
|
||||
- 使用 RenderTexture
|
||||
- Scene 与 Game 视图通常都可见
|
||||
- 画质可能略受 RenderTexture 分辨率影响
|
||||
|
||||
### 搭建步骤（概览）
|
||||
|
||||
1. 创建 `Canvas`
|
||||
2. 设置 `Render Mode = World Space`
|
||||
3. 在 Canvas 下创建一个带 `RectTransform` 的节点（建议 `RawImage`）
|
||||
4. 添加 `UGUIChartBridge`
|
||||
5. 配置：
|
||||
- `Profile`
|
||||
- `Panel Settings Asset`
|
||||
- `Render Mode = WorldSpace`
|
||||
|
||||
关键点：
|
||||
|
||||
- World Space 模式会创建并维护一个 `RenderTexture`，并通过 `RawImage` 显示。
|
||||
- 清晰度与 `RenderTexture` 分辨率强相关：分辨率通常来自目标 `RectTransform` 的宽高。
|
||||
- 如果图表模糊，请优先把目标 `RectTransform` 设大一些（例如 600x400+）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 选型建议（快速结论）
|
||||
|
||||
- 优先选 **ScreenSpaceOverlay**：
|
||||
- 你做的是传统 UI（HUD/面板）
|
||||
- 你最在意清晰度
|
||||
|
||||
- 优先选 **WorldSpace**：
|
||||
- 你的图表要出现在 3D 世界里
|
||||
- 你希望 Scene 视图也能看到
|
||||
|
||||
---
|
||||
|
||||
## 6. 常见问题与排错
|
||||
|
||||
- **运行时不显示**
|
||||
- 确认目标物体的 `RectTransform` 尺寸不是 0
|
||||
- 确认 `Profile` 已赋值，且该 Profile 在 Library Editor 的 Preview 中能正常显示
|
||||
- 如果字体显示异常，优先检查 `Panel Settings Asset` 是否为空
|
||||
|
||||
- **World Space 模式图表模糊**
|
||||
- 提升目标 `RectTransform` 尺寸（会提高 RenderTexture 分辨率）
|
||||
- 避免运行时频繁剧烈缩放（会触发 RenderTexture 调整）
|
||||
|
||||
---
|
||||
|
||||
## 7. 备选：导出 UGUI Prefab
|
||||
|
||||
如果你的版本提供 `Export UGUI Prefab`：
|
||||
|
||||
- 你也可以将 Profile 导出为 UGUI 预制体并直接在 Canvas 下使用
|
||||
- 但对交互/兼容性的覆盖范围取决于导出器版本
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 717828663095c664db6b23f3ab9cf0c2
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/00_03-UGUIWorkflow.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,182 @@
|
||||
# 运行时数据注入（UIToolKit）
|
||||
|
||||
本章介绍：在 UI Toolkit 工作流下，如何在运行时给 `ChartElement` 注入数据。
|
||||
|
||||
对应脚本：`EasyChartDataSource`
|
||||
|
||||
---
|
||||
|
||||
## 1. 这套方案适合什么场景？
|
||||
|
||||
- 你的图表是 UI Toolkit 体系（`UIDocument` + UXML + `ChartElement`）
|
||||
- 你希望提供一套“业务侧更容易调用”的注入 API（labels / values / x-y / pie / ring）
|
||||
- 或者你希望直接拿一段 JSON 注入（`ChartFeed`）
|
||||
|
||||
---
|
||||
|
||||
## 2. 快速上手（最推荐的流程）
|
||||
|
||||
1. 在场景里准备 `UIDocument`，并确保 UXML 里有 `ChartElement`。
|
||||
2. 在挂着 `UIDocument` 的 GameObject 上添加组件：`EasyChartDataSource`。
|
||||
3. 在 Inspector 里填写：
|
||||
- `uiDocument`
|
||||
- `chartElementName`（默认 `main-chart`，对应 UXML 中 `ChartElement` 的 `name`）
|
||||
- `profile`（可选，但强烈建议填：让样式/Series 类型来自你在编辑器配置好的 `ChartProfile`）
|
||||
4. 在运行时用代码调用：
|
||||
- `SetCategoryLabels(...)`
|
||||
- `SetSeriesValues(...)` / `SetSeriesXY(...)`
|
||||
- 或 `ApplyJson(...)`
|
||||
|
||||
组件内部会：
|
||||
|
||||
- 从 `UIDocument.rootVisualElement` 里找到目标 `ChartElement`
|
||||
- 必要时用 `profile` 初始化图表 Data
|
||||
- 修改 `ChartElement.Data` 并调用 `RefreshData()`
|
||||
|
||||
---
|
||||
|
||||
## 3. Inspector 字段说明
|
||||
|
||||
`EasyChartDataSource` 的核心配置字段：
|
||||
|
||||
- `uiDocument`
|
||||
- 指向当前 UI 的 `UIDocument`。
|
||||
- 如果不填，脚本会尝试 `GetComponent<UIDocument>()`。
|
||||
|
||||
- `chartElementName`
|
||||
- 目标 `ChartElement` 的 `name`（UXML/USS 的那个 name）。默认值为 `main-chart`。
|
||||
- 如果你希望用 JSON 中的 `chartId/chartName` 自动定位，也可以让 `ChartElement` 的 `name` 与之保持一致（见第 5 节）。
|
||||
|
||||
- `profile`
|
||||
- 可选。
|
||||
- 如果赋值，组件会将 `ChartElement.Profile = profile`，用于初始化/保持样式、Series 结构等。
|
||||
|
||||
- `playAnimationOnRefresh`
|
||||
- 每次注入后调用 `RefreshData(..., playAnimation: playAnimationOnRefresh)`。
|
||||
|
||||
- `allowCreateSeriesFromFeed`
|
||||
- 当你用 JSON（`ApplyJson`）注入时，如果 feed 中的 series 无法匹配到现有 Serie：
|
||||
- `false`（默认）：不创建新 Serie，只更新匹配到的部分。
|
||||
- `true`：允许根据 feed 创建新的 Serie（可能触发重建 renderers）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 常用注入 API（不写 JSON）
|
||||
|
||||
### 4.1 设置类目轴标签
|
||||
|
||||
`SetCategoryLabels(labels, axisId = AxisId.XBottom)`
|
||||
|
||||
- 会把该轴设为 Category，并覆盖 `labels`。
|
||||
|
||||
### 4.2 单序列 y 值（自动 x=0..n-1）
|
||||
|
||||
`SetSeriesValues("Sales", values)`
|
||||
|
||||
- 默认会找到/创建一条 Serie（默认类型为 Line，不强制改类型）。
|
||||
- 写入 `SeriesData.value`，并把 `SeriesData.x` 设为索引。
|
||||
|
||||
### 4.3 XY 点
|
||||
|
||||
`SetSeriesXY("Scatter", x, y)`
|
||||
|
||||
- 把 `x[]` 写入 `SeriesData.x`，把 `y[]` 写入 `SeriesData.value`。
|
||||
|
||||
### 4.4 Pie / Ring 注入
|
||||
|
||||
- `SetPie(serieName, names, values)`
|
||||
- 强制该 Serie 为 `Pie` 类型。
|
||||
- 使用 `SeriesData.name` 作为切片名，`SeriesData.value` 为数值。
|
||||
|
||||
- `SetRing(serieName, names, percents)`
|
||||
- 强制该 Serie 为 `RingChart` 类型。
|
||||
- 使用 `SeriesData.name` 作为环名，`SeriesData.value` 为进度值。
|
||||
|
||||
---
|
||||
|
||||
## 5. JSON 注入（ChartFeed）
|
||||
|
||||
你可以用：`ApplyJson(json)`
|
||||
|
||||
该方法会把 JSON 解析为 `ChartFeed` 并应用到 `ChartElement.Data`。
|
||||
|
||||
### 5.1 `ChartFeed` 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"chartId": "optional",
|
||||
"chartName": "optional",
|
||||
"axes": [
|
||||
{
|
||||
"axisId": "XBottom",
|
||||
"labels": ["Mon", "Tue", "Wed"]
|
||||
}
|
||||
],
|
||||
"series": [
|
||||
{
|
||||
"serieId": "optional",
|
||||
"name": "optional",
|
||||
"type": "Line",
|
||||
"datas": [
|
||||
{ "x": 0, "value": 12 },
|
||||
{ "x": 1, "value": 18 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
对应字段见运行时代码 `Scripts/Runtime/Feed/ChartFeed.cs`。
|
||||
|
||||
### 5.2 ChartElement 的定位规则（`chartId` / `chartName`）
|
||||
|
||||
`ApplyJson` 内部会尝试：
|
||||
|
||||
- 如果 feed 提供了 `chartId`：优先 `rootVisualElement.Q<ChartElement>(chartId)`
|
||||
- 其次如果提供了 `chartName`：尝试 `Q<ChartElement>(chartName)`
|
||||
- 都找不到才退回到 `chartElementName`（默认 `main-chart`）
|
||||
|
||||
因此：
|
||||
|
||||
- 如果你只有一个图表，保持默认值也没问题。
|
||||
- 如果你一个 UI 里有多个 `ChartElement`，建议让每个图表的 `name` 与 feed 的 `chartId` 或 `chartName` 对齐。
|
||||
|
||||
### 5.3 series 匹配与类型覆盖
|
||||
|
||||
`ApplyJson` 会先检查 JSON 内是否出现过 `"type":`，若出现则认为你希望允许类型覆盖（`allowTypeOverride=true`）。
|
||||
|
||||
Serie 匹配规则：
|
||||
|
||||
- 如果 `serieId` 非空：按 `Serie.id` 匹配
|
||||
- 否则如果 `name` 非空：按 `Serie.name` 匹配
|
||||
- 否则（索引模式）：按 feed 的序号匹配（第 i 条对第 i 条）
|
||||
|
||||
当无法匹配到 Serie 时：
|
||||
|
||||
- `allowCreateSeriesFromFeed=false`（默认）：该条 feed 会被跳过（不创建）。
|
||||
- `allowCreateSeriesFromFeed=true`：会创建新的 Serie，并使用 feed 的 `type/name/serieId`。
|
||||
|
||||
对已匹配到的 Serie：
|
||||
|
||||
- 仅当 `allowTypeOverride=true` 且不是索引模式时，才会允许覆盖 `id/name/type`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 常见问题与排错
|
||||
|
||||
- **不显示 / TryGetChart 失败**
|
||||
- 确认 `uiDocument` 赋值正确
|
||||
- 确认 UXML 中 `ChartElement` 的 `name` 与 `chartElementName` 一致
|
||||
|
||||
- **JSON 解析失败**
|
||||
- `EasyChartDataSource` 解析 JSON 时：
|
||||
- 会优先尝试 Newtonsoft（若项目里存在 `Newtonsoft.Json`）
|
||||
- 否则使用 Unity `JsonUtility`，并把 `type/axisId` 的字符串写法转换为枚举整数再解析
|
||||
- 建议先用一份已知能解析的 JSON（例如从编辑器 JSON 面板生成）再改。
|
||||
|
||||
- **注入后 Series 对不上 / 更新错了线**
|
||||
- 优先使用 `serieId` 做稳定匹配。
|
||||
- 如果只用 `name`，且同名 Serie 存在多个，脚本会使用第一个并给 warning。
|
||||
|
||||
- **JSON 想新增 Serie 但没新增**
|
||||
- 把 `allowCreateSeriesFromFeed` 打开。
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 6f3c0195d0b34d6a9c18cf8c8b45f91d
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/00_04-RuntimeDataInjectionUIToolKit.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,155 @@
|
||||
# 运行时数据注入（UGUI）
|
||||
|
||||
对应脚本：`UGUIRuntimeJsonInjection`、`UGUIRuntimeJsonInjectionEditor`
|
||||
|
||||
本章介绍：在 UGUI 工作流（`UGUIChartBridge`）下，如何通过 JSON 在运行时把数据注入到图表中。
|
||||
|
||||
---
|
||||
|
||||
## 1. 这套方案适合什么场景？
|
||||
|
||||
- 你有一份来自服务器/业务层的 JSON（或你希望在运行时快速手工编辑 JSON）
|
||||
- 你希望像编辑器里 `JSON Injection` 面板一样，直接“生成示例 → 修改 → 应用”
|
||||
- 你已经通过 `ChartProfile` 把样式、轴、Series 类型等结构配置好了
|
||||
|
||||
这套注入逻辑的定位是：**更新数据为主**，结构变更（比如新增 Series、强行覆盖 Series 类型）不是它的主要目标。
|
||||
|
||||
---
|
||||
|
||||
## 2. 快速上手（最推荐的流程）
|
||||
|
||||
1. 在场景中搭好 `UGUIChartBridge`（并确保 `Profile` 已赋值）。
|
||||
2. 在同一个 GameObject 上添加组件：`UGUIRuntimeJsonInjection`。
|
||||
3. 点击 **Generate Example JSON** 生成一份与你当前 Profile 匹配的示例 JSON。
|
||||
4. 在 `JSON Content` 文本框里修改数据。
|
||||
5. 点击 **Apply JSON to Chart**。
|
||||
|
||||
你会看到组件内部：
|
||||
|
||||
- 解析 JSON → 转成 `ChartFeed`
|
||||
- 将 `ChartFeed` 应用到 `UGUIChartBridge.Profile`
|
||||
- 调用 `_bridge.Refresh()` 刷新图表
|
||||
|
||||
---
|
||||
|
||||
## 3. 组件与 Inspector 字段说明
|
||||
|
||||
`UGUIRuntimeJsonInjection` 必须和 `UGUIChartBridge` 在同一个物体上（脚本有 `[RequireComponent(typeof(UGUIChartBridge))]`）。
|
||||
|
||||
### 3.1 JSON Generation Settings
|
||||
|
||||
- **Example Mode（`ChartJsonExampleMode`）**
|
||||
- 控制“生成示例 JSON”时的格式。
|
||||
- 一般建议先用 `Standard` 或 `Standard_Axis`（更直观）。
|
||||
|
||||
- **Data Mode（`ChartJsonDatasMode`）**
|
||||
- 控制 `datas` 的数据表达方式。
|
||||
- `Standard`：`datas` 为对象数组（例如 `{ "x": 0, "value": 12 }`）。
|
||||
- `Values`：`datas` 为纯数值数组（更短）。
|
||||
- 备注：该格式需要走 `ChartJsonUtils` 的“灵活解析器”（基于 Newtonsoft 的反射解析）。如果你的项目里没有 Newtonsoft（`Newtonsoft.Json` / `Unity.Newtonsoft.Json`），可能会解析失败。
|
||||
- 因此 **推荐默认使用 `Standard`**，除非你确认项目已引入 Newtonsoft。
|
||||
|
||||
- **API Envelope（`UseApiEnvelope`）**
|
||||
- 生成示例 JSON 时，是否包一层接口返回壳：
|
||||
- `{ "code": 200, "message": "success", "data": { ...真正的ChartFeed... } }`
|
||||
- 应用时也会尝试自动从壳里提取 `data`。
|
||||
|
||||
- **Auto Generate（`AutoGenerateJson`）**
|
||||
- 当你切换 `Example Mode / Data Mode / API Envelope` 时，自动重新生成示例 JSON。
|
||||
|
||||
### 3.2 JSON Content
|
||||
|
||||
- **JSON Content（`JsonContent`）**
|
||||
- 你要注入的 JSON 字符串。
|
||||
- 如果为空，点击 Apply 时会直接警告并返回。
|
||||
|
||||
---
|
||||
|
||||
## 4. JSON 格式（ChartFeed）
|
||||
|
||||
底层的数据模型是 `ChartFeed`：
|
||||
|
||||
```json
|
||||
{
|
||||
"chartId": "optional",
|
||||
"chartName": "optional",
|
||||
"axes": [
|
||||
{
|
||||
"axisId": "XBottom",
|
||||
"labels": ["Mon", "Tue", "Wed"]
|
||||
}
|
||||
],
|
||||
"series": [
|
||||
{
|
||||
"serieId": "optional",
|
||||
"name": "optional",
|
||||
"type": "Line",
|
||||
"datas": [
|
||||
{ "x": 0, "value": 12 },
|
||||
{ "x": 1, "value": 18 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
字段对应代码：
|
||||
|
||||
- `chartId` / `chartName`
|
||||
- 在 `UGUIRuntimeJsonInjection` 的注入路径里 **不会覆盖** Profile 的 `chartId/chartName`（它调用 `ChartJsonUtils.ApplyFeedToProfile(profile, feed)`，内部 `allowMetaOverwrite=false`）。
|
||||
- 但这两个字段可以用来帮助别的注入器（例如 `EasyChartDataSource`）在 UI 树里“按名字/ID 寻找 ChartElement”。
|
||||
|
||||
- `axes[]`
|
||||
- `axisId` 为 `AxisId` 枚举（如 `XBottom`、`XTop`、`YLeft`、`YRight` 等）。
|
||||
- `labels` 存在时会把该轴视为 Category，并直接覆盖 labels。
|
||||
|
||||
- `series[]`
|
||||
- **匹配优先级**：
|
||||
- 如果给了 `serieId`：按 `Serie.id` 精确匹配
|
||||
- 否则如果给了 `name`：按 `Serie.name` 匹配
|
||||
- 否则（`serieId` 与 `name` 都为空）：按索引匹配（第 0 个 feed 对应 Profile 第 0 个 serie）
|
||||
- `type`
|
||||
- 主要用于生成示例 JSON。
|
||||
- 在当前注入路径中：
|
||||
- 对已存在且能匹配到的 Serie：**不会强制改类型**（因为这里不允许覆盖 meta）。
|
||||
- 对“索引模式 + 超出 Profile 数量”而新建出来的 Serie：会使用 feed 里的 `type` 作为新 Serie 的类型。
|
||||
- `datas[]` 对应每个点：
|
||||
- `x/y/z/value` 数值
|
||||
- `id/name`（可选）
|
||||
- `useColor/color`（可选）
|
||||
|
||||
---
|
||||
|
||||
## 5. 应用时发生了什么？（注入流程）
|
||||
|
||||
点击 **Apply JSON to Chart** 时：
|
||||
|
||||
1. 若 JSON 是 API 壳（含 `data` 字段），会先尝试把 `data` 里的对象抽出来。
|
||||
2. 调用 `ChartJsonUtils.TryDeserializeFeed(json, out feed)` 反序列化为 `ChartFeed`。
|
||||
- 会优先尝试 Newtonsoft（如果项目里有），否则回退到 Unity `JsonUtility`。
|
||||
- `type: "Line"` / `axisId: "XBottom"` 这类字符串，也会在回退路径中被规范化为枚举值再解析。
|
||||
3. 调用 `ChartJsonUtils.ApplyFeedToProfile(_bridge.Profile, feed)` 把 feed 写回 Profile。
|
||||
4. 调用 `_bridge.Refresh()` 触发重绘。
|
||||
|
||||
---
|
||||
|
||||
## 6. 常见问题与排错
|
||||
|
||||
- **点击 Apply 没反应 / 控制台有 warning：No UGUIChartBridge or ChartProfile found**
|
||||
- 确认对象上有 `UGUIChartBridge`
|
||||
- 确认 `UGUIChartBridge.Profile` 已赋值
|
||||
|
||||
- **报错：Failed to parse JSON**
|
||||
- 先用 Generate 生成一份能解析的 JSON，再在它的基础上改。
|
||||
- 如果你的接口返回有外层包裹，优先勾选 `API Envelope`，或确保 JSON 的 `data` 字段内才是 `ChartFeed`。
|
||||
|
||||
- **JSON 生效了但数据没变 / 只变了一部分**
|
||||
- 检查 `series` 的匹配方式（`serieId` / `name` / 索引模式）。
|
||||
- 如果你使用的是 `serieId/name` 匹配：确保 Profile 里确实存在对应的 Serie（该注入路径在这种模式下不会自动创建新 Serie）。
|
||||
- 如果你使用的是“索引模式”（`serieId` 与 `name` 都为空）：
|
||||
- 当 feed 的 `series[]` 数量 **超过** Profile 的 Series 数量时，会自动补创建新的 Serie。
|
||||
- 如果你不希望自动创建，请给每条 serie 明确填 `name` 或 `serieId`。
|
||||
|
||||
- **在编辑器 PlayMode 注入后，Profile 资产被改脏了**
|
||||
- 注入的本质是“把 feed 应用到 `ChartProfile` 上”。如果你把资产直接拖到桥接上，运行时改动可能会让该资产处于 dirty 状态。
|
||||
- 如果你不希望影响资产，建议在运行时对 Profile 做一份实例化拷贝再注入。
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 9cfd9f2b2e0d4dc5b3d38d1a4c4ad7a7
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/00_05-RuntimeDataInjectionUGUI.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,168 @@
|
||||
# 编辑器工作流与面板说明
|
||||
|
||||
本章目标：让你清楚在 `EasyChart/Library Editor` 里“**哪里改什么**”，以及常见编辑流程（创建、克隆、预览、导出）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 你在编辑的是什么？（ChartProfile）
|
||||
|
||||
在 Library Editor 里被选中的图表，本质上是一个 `ChartProfile` 资产。
|
||||
|
||||
- 它是 **可复用配置**：同一个 Profile 可以被多个场景/Prefab 引用。
|
||||
- 它是 **可预览配置**：在编辑器里修改后可以立即看到预览变化。
|
||||
|
||||
建议：将你自己的 Profile 放到 `Assets/EasyChart/Library/Custom/`（或你团队约定目录）。
|
||||
|
||||
---
|
||||
|
||||
## 2. Library Editor 的三个核心区域
|
||||
|
||||
虽然 UI 细节可能随版本略有变化，但整体可以按下面理解：
|
||||
|
||||
### 2.1 左侧：资源树（Library Tree）
|
||||
|
||||
这里展示的是图表资产（`ChartProfile`）所在的文件夹结构。
|
||||
|
||||
常用操作：
|
||||
|
||||
- 在文件夹上右键：
|
||||
- `New Folder...`：新建子目录
|
||||
- `New Chart...`：创建新的 `ChartProfile`
|
||||
- 在图表上右键：
|
||||
- `Clone`：复制一个新的 Profile（用于做变体）
|
||||
- `Export to UXML`：导出（若你的工作流需要把配置同步/落盘到 UXML）
|
||||
- `Ping`：在 Project 面板定位该资产
|
||||
- `Rename...` / `Delete`
|
||||
|
||||
> 建议：用 `Clone` 来做“同款不同配色/不同数据规模”的图表变体，避免从零配置。
|
||||
|
||||
### 2.2 右侧：Inspector（配置面板）
|
||||
|
||||
这里是你主要编辑的地方。
|
||||
|
||||
通常会包含：
|
||||
|
||||
- **基础设置**：
|
||||
- `coordinateSystem`
|
||||
- `padding`（如果有）
|
||||
- `animationDuration`（如果有）
|
||||
- **Series 列表**：每个 Serie 代表一条线/一组柱/一个散点序列等
|
||||
- **Axes（坐标轴）**：
|
||||
- 选择使用哪个 `XAxisId/YAxisId`
|
||||
- 对应 `AxisConfig` 的显示、label、range、ticks 等
|
||||
- **Legend / Tooltip / Grid**：若你的版本已暴露这些设置
|
||||
|
||||
> 经验：先把 `coordinateSystem`、`Series`、`Axes` 配好，其他属于“锦上添花”。
|
||||
|
||||
### 2.3 预览区（Preview）
|
||||
|
||||
用于检查：
|
||||
|
||||
- 是否有数据
|
||||
- 轴范围是否正确
|
||||
- 标签是否拥挤/偏移
|
||||
- Tooltip / Legend 的交互（如果启用）
|
||||
|
||||
预览出现异常时优先排查顺序：
|
||||
|
||||
1. `coordinateSystem` 是否正确
|
||||
2. `series` 是否至少有 1 条且有数据点
|
||||
3. Axis 的 `axisType` 与数据 `x/y` 的含义是否匹配
|
||||
4. Value 轴是否被手动锁死范围（`autoRangeMin/autoRangeMax`）
|
||||
|
||||
### 2.4 JSON Injection（JSON 注入面板）
|
||||
|
||||
在左侧面板下方有一个 **JSON Injection** 区域，用于：
|
||||
|
||||
- 快速生成当前选中 `ChartProfile` 的“注入 JSON 示例”
|
||||
- 将你粘贴/编辑的 JSON 应用回当前选中 Profile（`ApplyToChart`）
|
||||
|
||||
常用控件：
|
||||
|
||||
- **API Envelope**：是否使用 `{ code, message, data }` 外层包裹。
|
||||
- 打开时：生成 JSON 会包一层；解析时也可以识别并自动取 `data`。
|
||||
- **Feed Mode**：示例 JSON 的“结构层级/字段完整度”（用于兼容不同注入协议）。
|
||||
- **Datas Format**：`datas` 字段内部数据点格式（例如更紧凑的数组，或更易读的对象）。
|
||||
- **ApplyToChart**：将当前文本框中的 JSON 解析并写回到当前选中的 `ChartProfile`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐的编辑流程（从 0 到可复用）
|
||||
|
||||
### Step 1：创建或选择一个 ChartProfile
|
||||
|
||||
- 新建：在目标文件夹右键 `New Chart...`
|
||||
- 已有：在左侧树点击选择
|
||||
|
||||
如果你希望使用“先克隆再修改”的方式（更推荐）：
|
||||
|
||||
- 先在窗口顶部工具栏 **Clone** 一个你自己的 Library
|
||||
- 然后在你自己的库里右键 Profile -> `Clone` 生成变体
|
||||
|
||||
### Step 2：确定坐标系
|
||||
|
||||
- `Cartesian2D`：Line/Bar/Scatter/Heatmap
|
||||
- `Polar2D`：Radar
|
||||
|
||||
> 建议：坐标系先定下来，再选 SeriesType，避免后续切换带来风格/轴设置混淆。
|
||||
|
||||
### Step 3：配置 Series
|
||||
|
||||
- 添加 Series
|
||||
- 设置 `type`
|
||||
- 填充 `seriesData`
|
||||
|
||||
建议：先用少量数据点（3~8 个）把效果跑通，再扩展数据量。
|
||||
|
||||
### Step 4：配置 Axes
|
||||
|
||||
最常见组合：
|
||||
|
||||
- X：Category
|
||||
- `labels` 填文本
|
||||
- Y：Value
|
||||
- 开启自动范围（默认）
|
||||
|
||||
当你希望更专业的轴显示：
|
||||
|
||||
- 使用 `labelFormat`（例如 `F1`、`N0` 等）
|
||||
- 使用 `autoRangeMin/autoRangeMax` 只锁定一端范围
|
||||
- 如果是 Value 轴需要单位：
|
||||
- `showUnit=true`
|
||||
- `unitText="个"/"万"`
|
||||
- `unitLabelStyle` 调字体/颜色/位置
|
||||
|
||||
### Step 5：克隆出变体（推荐）
|
||||
|
||||
当你需要同款图表做多个版本（配色、字号、轴显示略不同）：
|
||||
|
||||
- 右键图表 -> `Clone`
|
||||
- 修改差异项
|
||||
|
||||
这样可以保证风格一致，也更便于版本管理。
|
||||
|
||||
当你想把图表用于 UI：
|
||||
|
||||
- UI Toolkit：导出为 UXML，然后在 UI Builder 中组装页面（可参考示例场景 `Assets/EasyChart/Demo/Scenes/EasyChart_QuickStart.unity` 与模板 `Assets/EasyChart/Demo/UIToolKit/NewUXMLTemplate.uxml`）
|
||||
- UGUI：可导出为 UGUI Prefab 并在 Canvas/RectTransform 工作流中使用
|
||||
|
||||
---
|
||||
|
||||
## 4. 常见坑（快速定位）
|
||||
|
||||
- **看不到任何东西**
|
||||
- `seriesData` 是否为空
|
||||
- `AxisType` 是否和数据含义匹配（Category 轴配了 labels 吗）
|
||||
|
||||
- **Value 轴显示很怪（范围太大/太小）**
|
||||
- 检查 `autoRangeMin/autoRangeMax`
|
||||
- 检查 rounding/unit 是否把范围吸附到不合适的单位上
|
||||
|
||||
- **柱状图与标签不对齐**
|
||||
- 关注 `LabelPlacement`（Tick vs CellCenter）
|
||||
|
||||
---
|
||||
|
||||
## 下一章
|
||||
|
||||
- `00-WorkflowAndLibrary.md`：轴类型、标签放置、自动范围、取整、单位显示等内容已合并到第 7 节
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 92f5070109cc2bb4985fc1864050983f
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/01_01-EditorWorkflow.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,162 @@
|
||||
# Library 面板（资源树）
|
||||
|
||||
本章说明 `Unity Easy Chart/Library Editor` 窗口左侧的 **Library** 面板：用于管理你的图表资产（`ChartProfile`）与文件夹结构，并决定右侧各面板正在编辑的是哪个 Profile。
|
||||
|
||||
---
|
||||
|
||||
## 功能概览
|
||||
|
||||
- **展示结构**：以树状结构展示“图表库根目录”下的文件夹与 `ChartProfile`（`.asset`）。
|
||||
- **选择驱动编辑**：点击某个 `ChartProfile` 后，会驱动：
|
||||
- Inspector 面板绑定到该 Profile
|
||||
- Series 面板绑定到该 Profile 的 `series`
|
||||
- Preview 预览刷新
|
||||
- JSON Injection 生成示例 JSON（并可 Apply 回写到该 Profile）
|
||||
- **管理资产**：提供创建、重命名、删除、拖拽移动、展开/收起等操作。
|
||||
|
||||
---
|
||||
|
||||
## 界面结构说明
|
||||
|
||||
Library 面板的顶部标题栏从左到右通常包含：
|
||||
|
||||
- **Library**：标题。
|
||||
- **(当前库名称)**：括号内显示当前选中的库/根目录名称（用于区分你可能配置的多个库）。
|
||||
- **Menu（菜单按钮）**：常用操作入口（和右键菜单类似，但更集中）。
|
||||
- **Help（帮助按钮）**：打开本章节。
|
||||
|
||||
窗口顶部全局工具栏（Window Toolbar）中，Library 下拉框右侧包含：
|
||||
|
||||
- **+**：新增一个 Library。
|
||||
- **-**：删除当前 Library。
|
||||
- **Clone（克隆当前 Library）**：把当前 Library 复制为一个新 Library（详见下文）。
|
||||
|
||||
标题栏下面是：
|
||||
|
||||
- **资源树（TreeView）**：
|
||||
- 文件夹
|
||||
- `ChartProfile` 资产（图表配置文件）
|
||||
|
||||
---
|
||||
|
||||
## 选择逻辑（非常重要）
|
||||
|
||||
- **选中的是文件夹**：
|
||||
- 右侧 Inspector/Series 会清空（因为没有具体 Profile 可以编辑）。
|
||||
- JSON Injection 会切换为“无选中 Profile”的示例或保持当前示例（具体以实现为准）。
|
||||
- **选中的是 ChartProfile**：
|
||||
- Inspector/Series 立即绑定到该 Profile 的序列化数据。
|
||||
- 任何字段变化会触发 Preview 延迟刷新（`delayCall`）。
|
||||
|
||||
建议：如果你发现右侧面板没有内容，先确认左侧是否选中了一个 `ChartProfile`。
|
||||
|
||||
---
|
||||
|
||||
## 常用操作（标题栏 Menu）
|
||||
|
||||
点击标题栏右侧 **Menu**（小菜单图标）会弹出操作菜单，常见项包括：
|
||||
|
||||
- **New Chart**：在“目标文件夹”下创建新的 `ChartProfile`。
|
||||
- **New Folder**：在“目标文件夹”下创建新文件夹。
|
||||
- **Refresh**：重新扫描并重建树（当你在 Project 视图中手动移动/复制文件后很有用）。
|
||||
- **Expand All**：展开所有文件夹。
|
||||
- **Collapse All**：收起所有文件夹。
|
||||
- **Rename / Delete**：对“当前选中项”执行重命名/删除。
|
||||
- 如果当前选中的是库根目录，通常会被禁用。
|
||||
- **Export UGUI Prefab**（当选中的是 Profile 时可用）：把选中 Profile 导出为 UGUI Prefab（用于运行时展示）。
|
||||
|
||||
### 目标文件夹是如何决定的
|
||||
|
||||
Menu 中的 **New Chart / New Folder** 会把资源创建在“目标文件夹”下：
|
||||
|
||||
- 如果你当前选中的是 **文件夹**：目标就是该文件夹。
|
||||
- 如果你当前选中的是 **ChartProfile**：目标通常是该 Profile 所在的文件夹。
|
||||
- 如果没有选中或不明确：目标通常回退到库根目录。
|
||||
|
||||
---
|
||||
|
||||
## Clone Library（克隆当前 Library）
|
||||
|
||||
当你需要把一整套图表库（包含 Profile 与 UXML）复制成一个新的库（用于分支/版本/主题变体等）时，可以使用窗口顶部工具栏里的 **Clone**。
|
||||
|
||||
### 入口与操作
|
||||
|
||||
- 点击 Library 下拉框右侧的 **Clone** 图标。
|
||||
- 输入新库名称并确认。
|
||||
|
||||
### 克隆内容
|
||||
|
||||
- `Assets/EasyChart/Library/<当前库>` 会被复制到 `Assets/EasyChart/Library/<新库>`。
|
||||
- `Assets/EasyChart/LibraryUxml/<当前库>` 会被复制到 `Assets/EasyChart/LibraryUxml/<新库>`（如果源库存在对应 UXML 目录）。
|
||||
|
||||
### 限制与命名规则
|
||||
|
||||
- `<Root>` 库不允许克隆。
|
||||
- 新名称会做基础清理（移除非法文件名字符），空白名称会被忽略。
|
||||
- 如果目标库已存在（同名文件夹已存在），会提示并取消。
|
||||
|
||||
### 克隆后的行为
|
||||
|
||||
- 会自动切换当前选中的 Library 为新库。
|
||||
- 会刷新 Library 下拉列表与左侧资源树，并触发右侧面板/预览的刷新。
|
||||
|
||||
---
|
||||
|
||||
## 常用操作（右键菜单）
|
||||
|
||||
你也可以在树上的条目上 **右键**：
|
||||
|
||||
### 右键文件夹
|
||||
|
||||
- **New Folder...**：在该文件夹下创建子文件夹。
|
||||
- **New Chart...**：在该文件夹下创建新的 `ChartProfile`。
|
||||
- **Export Folder to UXML (Mirror/Backup)**：导出该文件夹下的内容到 UXML（用于备份/分发/版本化）。
|
||||
- **Rename...**：重命名文件夹。
|
||||
- **Delete**：删除文件夹（请谨慎，属于破坏性操作）。
|
||||
|
||||
### 右键 ChartProfile
|
||||
|
||||
- **Export to UXML**：导出当前 Profile 的 UXML。
|
||||
- **Clone**：克隆一个新的 Profile（用于快速派生相似图表）。
|
||||
- **Rename...**：重命名资产（同时会尝试同步更新 `profile.name` / `profile.chartName`）。
|
||||
- **Ping**：在 Project 视图中定位该资产。
|
||||
- **Delete**：删除资产。
|
||||
|
||||
---
|
||||
|
||||
## 拖拽移动与排序
|
||||
|
||||
Library 树支持拖拽移动文件夹或 `ChartProfile`：
|
||||
|
||||
- **拖拽 ChartProfile 到文件夹**：会触发 `AssetDatabase.MoveAsset`，把 `.asset` 移动到目标文件夹。
|
||||
- **拖拽文件夹到文件夹**：会把整个文件夹移动到目标文件夹下。
|
||||
|
||||
注意：
|
||||
|
||||
- 如果目标无效（例如拖到自身/子目录），会拒绝（鼠标提示为 Rejected）。
|
||||
- 移动后会自动刷新树。
|
||||
|
||||
---
|
||||
|
||||
## 重命名（双击与内联编辑）
|
||||
|
||||
在树上 **双击** 条目会进入内联重命名流程（等价于执行 Rename）。
|
||||
|
||||
实现上会对名字做基础清理（移除非法文件名字符）。如果你输入空白或与原名相同，会取消重命名。
|
||||
|
||||
---
|
||||
|
||||
## 常见问题与排错
|
||||
|
||||
- **右侧面板为空**：
|
||||
- 先确认左侧是否选中了 `ChartProfile`（而不是文件夹）。
|
||||
- **改了名字但 chartName 没更新**：
|
||||
- ChartProfile 可能有额外同步逻辑；建议在 Inspector 里确认 `Chart Name` 字段是否一致。
|
||||
- **拖拽失败**：
|
||||
- 常见原因：拖到了自身、拖到子目录、或目标路径已存在同名资源。
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- 点击标题栏最右侧 **Help** 图标可回到本章节。
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 1f3a7a0f7bcd4c9bbf0f6e8a3f5c1d2a
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/01_02-LibraryPanel.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,138 @@
|
||||
# JSON Injection 面板
|
||||
|
||||
本章说明 `Unity Easy Chart/Library Editor` 窗口左侧底部的 **JSON Injection** 面板。
|
||||
|
||||
它的定位是：用一段可读/可复制的 JSON 来表达当前 `ChartProfile` 的配置（或外部导入的配置），并支持 **ApplyToChart** 将 JSON 解析后回写到选中的 Profile。
|
||||
|
||||
---
|
||||
|
||||
## 面板位置与作用
|
||||
|
||||
- **位置**：Library 面板（资源树）下方。
|
||||
- **主要用途**：
|
||||
- **导出**：把当前选中 `ChartProfile` 转成示例 JSON（Feed）
|
||||
- **编辑**：在文本框里手动修改 JSON
|
||||
- **导入/应用**：点击 **ApplyToChart**，把 JSON 解析并应用到当前选中的 `ChartProfile`
|
||||
|
||||
适用场景：
|
||||
|
||||
- **调试**：快速定位“某个字段是否生效”。
|
||||
- **批量修改**：复制 JSON 到外部编辑器（支持多光标/查找替换），再粘贴回来 Apply。
|
||||
- **与外部系统对接**：例如你的工具链/脚本生成 Feed，再在编辑器里 Apply。
|
||||
|
||||
---
|
||||
|
||||
## 控件说明（标题栏）
|
||||
|
||||
标题栏从左到右一般包含：
|
||||
|
||||
- **Min/Max**（按钮文字会变化）
|
||||
- 用于切换面板高度。
|
||||
- `Min`：收起为较小高度（更偏“辅助工具”）。
|
||||
- `Max`：展开为较大高度（更适合长 JSON）。
|
||||
|
||||
- **ApplyToChart**（图标按钮）
|
||||
- 把当前文本框里的 JSON 尝试解析为 Feed，并应用到选中的 `ChartProfile`。
|
||||
- 成功后会：
|
||||
- 标记资产为 Dirty 并 `SaveAssets()`
|
||||
- 刷新 Series 列表
|
||||
- 刷新 Preview
|
||||
|
||||
- **Help**（图标按钮）
|
||||
- 打开本章节。
|
||||
|
||||
---
|
||||
|
||||
## 控件说明（按钮行）
|
||||
|
||||
标题栏下方还有一行按钮（可能会自动换行）：
|
||||
|
||||
- **API Envelope**（图标开关）
|
||||
- 控制示例 JSON 是否包裹为“API 返回格式”。
|
||||
- 你需要把 Feed 直接交给某个 HTTP API/服务时，这个选项会更方便。
|
||||
- 切换后会重新生成示例，并覆盖文本框（详见“覆盖规则”）。
|
||||
|
||||
- **Feed Mode**（下拉框）
|
||||
- 用于控制“示例 JSON 输出包含哪些层级/字段”。
|
||||
- 选项来自内部枚举（常见有）：
|
||||
- `Lite`
|
||||
- `Standard / ID`
|
||||
- `Standard / Default`
|
||||
- `Standard / With Axes`
|
||||
- `Full`
|
||||
- 一般建议：
|
||||
- **快速看结构**：用 `Lite`
|
||||
- **需要稳定引用**：用 `Standard / ID`
|
||||
- **需要包含轴配置**：用 `Standard / With Axes`
|
||||
- **需要完整复制/迁移**：用 `Full`
|
||||
|
||||
- **Datas Format**（下拉框）
|
||||
- 控制 `seriesData`（数据点）字段的输出格式。
|
||||
- 常见选项：
|
||||
- `Values`：更精简，偏“只关心数值”。
|
||||
- `Standard`：默认格式，适合一般编辑与 Apply。
|
||||
- `Full`：更完整（可能包含更多字段/结构），适合迁移/还原。
|
||||
|
||||
- **Copy**（图标按钮）
|
||||
- 复制当前文本框内容到剪贴板。
|
||||
|
||||
---
|
||||
|
||||
## 文本框与“覆盖规则”（非常重要）
|
||||
|
||||
JSON 文本框是可编辑的，但为了避免你手写的内容被自动覆盖，面板内部有一个“脏标记”逻辑：
|
||||
|
||||
- **只要你手动改过文本框内容**，就会认为“用户已修改”（dirty）。
|
||||
- 当处于 dirty 状态时：
|
||||
- 编辑器不会自动用示例 JSON 覆盖你的内容。
|
||||
- 但当你切换以下选项时，会**强制覆盖**（同时清除 dirty）：
|
||||
- `API Envelope`
|
||||
- `Feed Mode`
|
||||
- `Datas Format`
|
||||
- 或在切换选中 Profile 时（会重置为该 Profile 的示例）
|
||||
|
||||
建议：
|
||||
|
||||
- 如果你要做大幅改动：
|
||||
- 先 Copy 到外部编辑器改
|
||||
- 改完再粘贴回来 Apply
|
||||
|
||||
---
|
||||
|
||||
## ApplyToChart 的行为与注意事项
|
||||
|
||||
- **ApplyToChart 会修改当前选中的 `ChartProfile` 资产**。
|
||||
- 如果 JSON 解析失败，会在 Console 输出错误：
|
||||
- `ApplyToChart failed: invalid JSON or unsupported format.`
|
||||
- `Full` 模式下会允许覆盖更多“Meta/结构”信息（例如某些标识/配置），因此更强大也更危险。
|
||||
|
||||
建议：
|
||||
|
||||
- 在 Apply 前确保：
|
||||
- 左侧已选中正确的 `ChartProfile`
|
||||
- JSON 格式正确（括号/逗号）
|
||||
- 你理解当前 Feed Mode 会覆盖哪些内容
|
||||
|
||||
---
|
||||
|
||||
## 推荐工作流
|
||||
|
||||
### 1) 从当前 Profile 导出并微调
|
||||
|
||||
- 选中一个 `ChartProfile`
|
||||
- 选择合适的 `Feed Mode` / `Datas Format`
|
||||
- Copy 到外部编辑器微调
|
||||
- 粘贴回来
|
||||
- ApplyToChart
|
||||
|
||||
### 2) 从外部导入配置
|
||||
|
||||
- 把外部 JSON 粘贴到文本框
|
||||
- ApplyToChart
|
||||
- 去 Inspector / Series 进一步精调
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- 点击标题栏最右侧 **Help** 图标可回到本章节。
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 4c9b2d1e8f0a4a7d9c3e5b1f6a2d7c8e
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/01_03-JsonInjectionPanel.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,78 @@
|
||||
# Preview 面板
|
||||
|
||||
本章说明 `Unity Easy Chart/Library Editor` 中间区域顶部的 **Preview** 面板。
|
||||
|
||||
Preview 的作用是：把当前选中的 `ChartProfile` 直接渲染出来，让你在编辑配置时能即时看到结果。
|
||||
|
||||
---
|
||||
|
||||
## Preview 会在什么时候刷新
|
||||
|
||||
Preview 刷新是“延迟刷新”（避免你连续拖动/输入时频繁重绘）：
|
||||
|
||||
- 当你在 **Inspector** 或 **Series** 面板修改任何绑定字段时，会触发一次 `ScheduleUpdatePreview()`。
|
||||
- 当你在 **JSON Injection** 面板点击 **ApplyToChart** 后，会触发刷新。
|
||||
- 当你在左侧 **Library** 树切换到另一个 `ChartProfile` 时，会刷新到新 Profile。
|
||||
|
||||
实现上会把刷新放到 `EditorApplication.delayCall`，因此你可能会感觉到“改完后稍后才更新”——这是预期行为。
|
||||
|
||||
---
|
||||
|
||||
## Preview 显示什么
|
||||
|
||||
- Preview 使用一个运行时的图表组件（例如 `ChartElement`）进行绘制。
|
||||
- Preview 会直接读取当前选中 `ChartProfile` 的数据并渲染。
|
||||
|
||||
你可以把 Preview 理解为：
|
||||
|
||||
- **你编辑的就是它渲染的**
|
||||
- **你看到的就是运行时的效果**（大多数情况下）
|
||||
|
||||
---
|
||||
|
||||
## 常见问题与排错
|
||||
|
||||
### 1) 预览为空
|
||||
|
||||
优先排查：
|
||||
|
||||
- 是否选中了一个 `ChartProfile`
|
||||
- 是否至少存在一条 `Serie`
|
||||
- `seriesData` 是否为空（没有数据点）
|
||||
|
||||
### 2) 数据有但显示很怪 / 看不到
|
||||
|
||||
常见原因：
|
||||
|
||||
- **坐标系与 SeriesType 不匹配**：例如 Profile 是 `Polar2D`，但 Series 选择了非 Radar 的类型。
|
||||
- **轴范围/数据范围不匹配**：例如数值全都落在轴范围之外。
|
||||
- **分类轴可见数量（VisibleCount）太小**：导致只显示一小段。
|
||||
|
||||
### 3) Console 报错 “Preview refresh failed”
|
||||
|
||||
当刷新过程中出现异常，会在 Console 输出：
|
||||
|
||||
- `[EasyChartLibraryWindow] Preview refresh failed: ...`
|
||||
|
||||
这通常意味着：
|
||||
|
||||
- 某个配置组合不合法
|
||||
- 或某个字段值超出预期（例如 null / NaN）
|
||||
|
||||
建议处理：
|
||||
|
||||
- 先回退最近一次改动
|
||||
- 再逐步改回去定位哪一个字段触发异常
|
||||
|
||||
---
|
||||
|
||||
## 提示
|
||||
|
||||
- Preview 只负责“呈现结果”，结构性问题通常需要回到 **Inspector/Series/JSON Injection** 去修。
|
||||
- 如果你在短时间内修改了很多字段，Preview 可能在最后一次改动后才统一刷新（这是为了性能）。
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- 点击标题栏最右侧 **Help** 图标可回到本章节。
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: b8e1c4d2a6f3490b9c7d1e2f3a4b5c6d
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/02_04-PreviewPanel.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,201 @@
|
||||
# Inspector 面板
|
||||
|
||||
本章说明 `Unity Easy Chart/Library Editor` 中间区域底部的 **Inspector** 面板。
|
||||
|
||||
Inspector 的定位是：以“配置视角”直接编辑当前选中 `ChartProfile` 的序列化字段（坐标系、轴、网格、交互、图例等），并驱动 Preview 实时更新。
|
||||
|
||||
---
|
||||
|
||||
## 面板结构概览
|
||||
|
||||
当你在左侧 Library 树选中一个 `ChartProfile` 后，Inspector 会构建一组折叠面板（Foldout），通常包括：
|
||||
|
||||
- **Chart Settings**：图表基础设置（例如背景、名称等）
|
||||
- **Coordinate System**：坐标系选择与相关项
|
||||
- **Axis Settings**：轴配置（X/Y 或 Angle/Radius）
|
||||
- **Grid Settings**：网格相关配置
|
||||
- **Hover Settings**：悬停/提示相关配置
|
||||
- **Legend Settings**：图例配置
|
||||
|
||||
提示：
|
||||
|
||||
- 如果你选中的是文件夹而不是 `ChartProfile`，Inspector 会清空（这是正常的）。
|
||||
|
||||
---
|
||||
|
||||
## Chart Settings（常用）
|
||||
|
||||
### Chart Name
|
||||
|
||||
Inspector 里有 `Chart Name` 文本框（来自 `ChartProfile.chartName`）。它不只是显示名，还会参与资产重命名流程：
|
||||
|
||||
- 当你在该字段输入新名字并 **失去焦点** 或按 **Enter**：
|
||||
- 编辑器会尝试把 `.asset` 文件重命名为该名字
|
||||
- 同时尽量保持 `profile.name` 与 `profile.chartName` 同步
|
||||
|
||||
注意：
|
||||
|
||||
- 名字会被做文件名清理（非法字符会被移除/替换）。
|
||||
- 如果重命名失败（例如同名冲突），会弹出 Error，并回退字段。
|
||||
|
||||
### Background
|
||||
|
||||
`Background` 通常是一个子折叠块，包含背景颜色/透明度等字段（具体以版本为准）。
|
||||
|
||||
---
|
||||
|
||||
## Coordinate System（坐标系）
|
||||
|
||||
这里会显示 `coordinateSystem` 选择项。
|
||||
|
||||
坐标系会影响：
|
||||
|
||||
- Series 可选的类型/语义（例如 Polar2D 常见是 Radar；Pie 类属于特殊布局）
|
||||
- Axis Settings 中显示的是 Cartesian（X/Y）还是 Polar（Angle/Radius）配置
|
||||
|
||||
建议：
|
||||
|
||||
- 在开始配置前先确定坐标系，避免后续大规模调整。
|
||||
|
||||
---
|
||||
|
||||
## Axis Settings（轴配置）
|
||||
|
||||
### 轴选择（X Axis / Y Axis）
|
||||
|
||||
在 Cartesian 模式下，顶部会提供 X/Y 轴的选择下拉：
|
||||
|
||||
- **X Axis**：例如 `XBottom` / `XTop`
|
||||
- **Y Axis**：例如 `YLeft` / `YRight`
|
||||
|
||||
选择改变时会：
|
||||
|
||||
- 确保轴列表里存在对应 AxisId 的元素（必要时自动创建）
|
||||
- 刷新下面的 Axis 字段 UI
|
||||
- 触发 Preview 刷新
|
||||
|
||||
### 单个 Axis 的常见字段
|
||||
|
||||
每个 Axis 配置通常包含：
|
||||
|
||||
- `axisType`：Category / Value 等
|
||||
- `visible`：是否显示
|
||||
- `color` / `width`：轴线样式
|
||||
|
||||
#### LabelTexts（分类轴标签）
|
||||
|
||||
Inspector 会提供一个 `LabelTexts`（内部字段名 `labels`）用于配置分类标签。
|
||||
|
||||
#### Range（范围）
|
||||
|
||||
常见有：
|
||||
|
||||
- `minValue` / `maxValue`
|
||||
- `autoRangeMin` / `autoRangeMax`（开关）
|
||||
- `autoRangeRounding`（自动范围的取整策略）
|
||||
- `autoRangeUnit`（某些取整策略下会出现）
|
||||
|
||||
#### Ticks / VisibleCount
|
||||
|
||||
如果轴支持自动刻度：
|
||||
|
||||
- `autoTicks` 开启时会显示 `splitCount`。
|
||||
- 对 **Category Axis** 来说，这个字段会显示为 **VisibleCount**（表示可见分类数量）。
|
||||
|
||||
#### Category Auto Scroll（分类轴自动滚动）
|
||||
|
||||
如果轴支持分类滚动，常见字段包括：
|
||||
|
||||
- `categoryAutoScroll`：是否自动滚动（跑马灯效果）。
|
||||
- `categorySmoothScroll`：是否平滑滚动。
|
||||
- `categoryScrollInterval`：滚动间隔。
|
||||
- `categoryScrollStep`：每次滚动步长。
|
||||
|
||||
#### Unit（单位显示）
|
||||
|
||||
常见字段：
|
||||
|
||||
- `showUnit`：是否显示单位。
|
||||
- `unitText`：单位文本（例如 `ms`/`%`/`MB`）。
|
||||
- `unitLabelStyle`：单位文本样式。
|
||||
|
||||
---
|
||||
|
||||
## Polar Axis（极坐标轴）
|
||||
|
||||
当 `coordinateSystem = Polar2D` 时，Axis Settings 会显示 `polarAxes`：
|
||||
|
||||
- **Angle Axis**（angleAxis）
|
||||
- **Radius Axis**（radiusAxis）
|
||||
|
||||
常见字段含义与 Cartesian 类似：
|
||||
|
||||
- `labels`：角度/维度标签（Radar 的维度名称通常来自这里）。
|
||||
- `visible/color/width`：轴线样式。
|
||||
- `showLabels/fontSize/labelColor/labelPosition/labelOffset`：标签显示控制。
|
||||
- `autoRangeMin/autoRangeMax/minValue/maxValue`：半径轴范围。
|
||||
- `autoTicks/splitCount`：刻度数量。
|
||||
|
||||
---
|
||||
|
||||
## Grid Settings（字段说明，仅 Cartesian2D）
|
||||
|
||||
Grid Settings 在 Cartesian2D 下可见，核心字段来自 `cartesianGrid`：
|
||||
|
||||
- **xGridColor / xGridLineWidth**：X 方向网格线颜色与线宽。
|
||||
- **yGridColor / yGridLineWidth**：Y 方向网格线颜色与线宽。
|
||||
|
||||
如果需要虚线：
|
||||
|
||||
- `xGridDashed` / `yGridDashed`：是否虚线。
|
||||
- `xGridDashLength` / `yGridDashLength`：虚线实线段长度。
|
||||
- `xGridDashGap` / `yGridDashGap`：虚线间隔。
|
||||
- `xGridDashOffset` / `yGridDashOffset`：虚线偏移。
|
||||
|
||||
---
|
||||
|
||||
## Hover Settings（字段说明，仅 Cartesian2D）
|
||||
|
||||
Hover Settings 在 Cartesian2D 下可见，核心字段来自 `hover`：
|
||||
|
||||
- **cursorLineColor**：悬停光标线颜色。
|
||||
- **cursorLineWidth**：线宽。
|
||||
- **cursorLineDashed**：是否虚线。
|
||||
- **cursorLineDashLength / cursorLineDashGap / cursorLineDashOffset**：虚线参数。
|
||||
|
||||
---
|
||||
|
||||
## Legend Settings（字段说明）
|
||||
|
||||
Legend Settings 来自 `legendSettings`（某些情况下会被自动隐藏，见下文）。
|
||||
|
||||
- **enabled**：是否显示图例。
|
||||
- **position**：图例位置（Top/Bottom/Left/Right）。
|
||||
- **fontSize / color**：文字大小与颜色。
|
||||
- **backgroundColor**：图例背景色。
|
||||
- **itemSpacing**：图例项间距。
|
||||
- **offset**：相对边缘的偏移。
|
||||
- 当 offset 为默认值时，会随着 position 自动给一个常用偏移（例如 Bottom 默认 `y=-30`）。
|
||||
|
||||
---
|
||||
|
||||
## Legend Settings（可能会自动隐藏）
|
||||
|
||||
当图表是“纯 Pie 系列”（只有 Pie/Ring/Pie3D，没有非 Pie 系列）时，Legend Settings 可能会被自动隐藏。
|
||||
|
||||
这是为了避免在某些布局下显示无意义或冲突的图例配置。
|
||||
|
||||
---
|
||||
|
||||
## 编辑建议与排错
|
||||
|
||||
- **改动较多时**：建议配合顶部工具栏的 `Save` 保存资产。
|
||||
- **修改了关键结构**（例如坐标系、轴类型、Series Type）：
|
||||
- 改完观察 Preview 是否正确刷新
|
||||
- 如出现不一致，尝试切换一下选中 Profile 触发重建
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- 点击标题栏最右侧 **Help** 图标可回到本章节。
|
||||
@@ -0,0 +1,14 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 9d7c3b2a1e0f4c8baf6d5e4c3b2a1f0e
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
AssetOrigin:
|
||||
serializedVersion: 1
|
||||
productId: 359794
|
||||
packageName: Easy Chart Lite
|
||||
packageVersion: 1.0
|
||||
assetPath: Assets/EasyChart/Docs/Manual/zh/02_05-InspectorPanel.md
|
||||
uploadId: 857482
|
||||
@@ -0,0 +1,166 @@
|
||||
# Series 面板（数据与系列）
|
||||
|
||||
本章说明 `Unity Easy Chart/Library Editor` 右侧的 **Series** 面板。
|
||||
|
||||
Series 面板以“图表结构”的方式编辑 `ChartProfile.series`：你可以添加/删除/排序系列，设置每条 Serie 的类型与参数，并直接编辑 `seriesData`（数据点）。
|
||||
|
||||
---
|
||||
|
||||
## 面板结构概览
|
||||
|
||||
当你选中一个 `ChartProfile` 后，Series 面板会显示：
|
||||
|
||||
- 一组 Serie 卡片（每个卡片对应 `series[i]`）
|
||||
- 最底部的 **+ Add Series** 按钮
|
||||
|
||||
每个 Serie 卡片通常由三部分组成：
|
||||
|
||||
- **Header（标题行）**：折叠按钮 + 标题
|
||||
- **Body（主体）**：Name / Id / Type / Settings / Data
|
||||
- **Footer（右下角控制）**：↑ ↓ X
|
||||
|
||||
---
|
||||
|
||||
## Header：折叠/展开
|
||||
|
||||
- Header 左侧有一个小按钮：
|
||||
- `▼` 表示已展开
|
||||
- `▶` 表示已折叠
|
||||
- 折叠状态会被记住（按 Profile + index 存储），用于减少长配置的视觉负担。
|
||||
|
||||
---
|
||||
|
||||
## Name 与 Serie Id
|
||||
|
||||
### Name
|
||||
|
||||
- `Name` 字段用于显示与编辑该 Serie 的名称。
|
||||
- 当你修改 Name 时，卡片标题会同步更新，并触发 Preview 刷新。
|
||||
|
||||
### Serie Id（只读）
|
||||
|
||||
如果该 Serie 支持 `id` 字段，面板会显示：
|
||||
|
||||
- **Serie Id**（只读文本框）
|
||||
- **Copy**（按钮）复制 id 到剪贴板
|
||||
|
||||
这个 id 常用于：
|
||||
|
||||
- 交互/高亮/外部系统引用某条 serie
|
||||
- 保持引用稳定（尤其是你会重排/增删 series 时）
|
||||
|
||||
---
|
||||
|
||||
## Type（系列类型）与兼容性提示
|
||||
|
||||
### Type 下拉框
|
||||
|
||||
- `Type` 用于选择 SerieType（Line/Bar/Scatter/Pie/Radar…）。
|
||||
- 下拉框会基于注册表提供可选类型；如果当前类型不在列表里，会临时插入以保证可见。
|
||||
|
||||
### 兼容性警告
|
||||
|
||||
当 SeriesType 与 Profile 的 `coordinateSystem` 不兼容时，Series 面板会显示一段警告文字：
|
||||
|
||||
- 仍然允许渲染（不会强制阻止）
|
||||
- 但会提示坐标轴/网格语义可能不一致
|
||||
|
||||
典型例子：
|
||||
|
||||
- Profile 是 `Polar2D`，但 SeriesType 选择了 Line/Bar（不推荐）
|
||||
|
||||
### Pro-only 类型限制
|
||||
|
||||
某些类型在 Free 版本不可用（例如 RingChart / HorizontalBar / Heatmap / Pie3D 等）。
|
||||
|
||||
- 当你尝试选择这些类型时，如果未安装 Pro：
|
||||
- 会显示提示文本
|
||||
- 并自动把下拉框回退到原来的类型（不会修改资产）
|
||||
|
||||
---
|
||||
|
||||
## Settings（系列参数）
|
||||
|
||||
Series 面板会为每条 serie 显示一组 Settings 配置：
|
||||
|
||||
- 根折叠块名称会随类型变化（例如 `LineSettings` / `BarSettings` / `PieSettings` …）。
|
||||
- 某些类型会有更细分的子折叠（例如 Ring 的 layout/valueMapping 等）。
|
||||
|
||||
提示：
|
||||
|
||||
- 切换 Type 可能会触发“Settings 实例替换”（managedReference 结构变化）。
|
||||
- 发生替换时会延迟一帧重建 UI，以避免序列化句柄失效。
|
||||
|
||||
---
|
||||
|
||||
## Data：seriesData（数据点）
|
||||
|
||||
Series 面板里会直接展示 `seriesData` 数组（Unity 的默认数组编辑器）。
|
||||
|
||||
- 默认会强制展开（便于编辑）。
|
||||
- 当你增删/修改数据点时，会触发 Preview 刷新。
|
||||
|
||||
建议：
|
||||
|
||||
- 数据点较多时，可以配合 JSON Injection 面板进行批量编辑。
|
||||
|
||||
---
|
||||
|
||||
## Footer：排序与删除（渲染顺序）
|
||||
|
||||
每个 serie 卡片右下角有三个按钮：
|
||||
|
||||
- **↑**：把当前 serie 上移一位（`MoveArrayElement(index, index-1)`）
|
||||
- **↓**：把当前 serie 下移一位（`MoveArrayElement(index, index+1)`）
|
||||
- **X**：删除当前 serie（`DeleteArrayElementAtIndex(index)`）
|
||||
|
||||
渲染顺序提示：
|
||||
|
||||
- 通常 **后面的 serie 会绘制在更上层**。
|
||||
- 因此你可以用 ↑↓ 来控制遮挡关系（例如点/线盖住柱子）。
|
||||
|
||||
---
|
||||
|
||||
## + Add Series（新增系列）
|
||||
|
||||
点击底部 **+ Add Series**：
|
||||
|
||||
- 会在 `series` 数组末尾插入一个新元素。
|
||||
- 注意：如果当前已经存在至少一条 serie，Unity 的 `InsertArrayElementAtIndex(arraySize)` 会 **复制最后一个元素**（包括 type/settings）。
|
||||
- 如果这是第一条 serie，会根据坐标系设置默认类型：
|
||||
- Polar2D：默认 Radar
|
||||
- 其他：默认 Line
|
||||
|
||||
新增后通常会：
|
||||
|
||||
- 自动填入名称（如 `Serie N`）
|
||||
- 触发 `EnsureRuntimeData()`
|
||||
- 刷新 Series 列表与 Preview
|
||||
|
||||
---
|
||||
|
||||
## 推荐工作流
|
||||
|
||||
### 1) 从零创建一张基础图
|
||||
|
||||
- + Add Series
|
||||
- Type 选择 Line 或 Bar
|
||||
- 在 seriesData 里加入几个点
|
||||
- 去 Inspector 调整轴范围/可见数量
|
||||
|
||||
### 2) 调整遮挡关系
|
||||
|
||||
- 用 ↑↓ 调整 series 顺序
|
||||
- 观察 Preview 中的层级变化
|
||||
|
||||
### 3) 大量数据/批量修改
|
||||
|
||||
- 在 JSON Injection 中切换 `Datas Format`
|
||||
- Copy 到外部编辑器批量生成/替换数据
|
||||
- 粘贴回来 ApplyToChart
|
||||
|
||||
---
|
||||
|
||||
## Help
|
||||
|
||||
- 点击标题栏最右侧 **Help** 图标可回到本章节。
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user