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