拼ui 一些业务逻辑x实现

2026-03-19 06:15:09 +08:00
parent f5c6f143c0
commit 49e45ac464
1118 changed files with 246518 additions and 5368 deletions
@@ -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)