拼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,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`