拼ui 一些业务逻辑x实现
This commit is contained in:
@@ -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`
|
||||
Reference in New Issue
Block a user