tmui-cli 2.0.0 → 2.0.2

package/data/tmui4x/31./345/216/237/347/224/237/345/233/276/350/241/250/03/345/233/276/350/241/250/347/261/273/345/236/213/11./345/234/260/345/233/276.md

@@ -0,0 +1,91 @@
+# 地图 Map
+
+基于 GeoJSON `Feature` 数据渲染区域地图，支持填充/描边两种模式、区域选中、高亮与标签。
+
+## 效果
+
+<ViewMobile url="/pages/chart/map" />
+
+## 数据格式
+
+`data` 需要传入 GeoJSON 的 `features` 数组（每一项为 `Feature`）。
+
+- 区域名称读取：`feature.properties.name`
+- 标签位置读取：优先 `feature.properties.centroid`，其次 `feature.properties.center`
+- `label.formatter` 中的 `{value}` 读取：`feature.properties.value`
+
+## 加载 GeoJSON
+
+```typescript
+const geoFeatures = ref<UTSJSONObject[]>([] as UTSJSONObject[])
+
+uni.request({
+  url: 'https://geo.datav.aliyun.com/areas_v3/bound/420100_full.json',
+  method: 'GET',
+  success: (res) => {
+    if (res.statusCode != 200) return
+    let body = res.data as any | null
+    if (typeof body == 'string') body = JSON.parseObject(body as string)
+    if (body == null) return
+    const obj = body as UTSJSONObject
+    const features = obj.get('features')
+    if (features == null) return
+    const arr = features as UTSJSONObject[]
+    for (let i = 0; i < arr.length; i++) {
+      const props = arr[i].get('properties') as UTSJSONObject
+      if (props != null) props.set('value', Math.round(Math.random() * 9000 + 1000))
+    }
+    geoFeatures.value = arr
+  }
+})
+```
+
+## 基本用法
+
+```typescript
+{
+  data: geoFeatures,
+  series: [{
+    type: 'map',
+    mapMode: 'fill',
+    mapActiveColor: '#3b82f6',
+    mapStrokeColor: '#cbd5e1',
+    mapStrokeWidth: 1,
+    label: { show: true, fontSize: 8, color: '#6b7280', formatter: '{name}\n{value}亿' }
+  }],
+  padding: { left: 8, right: 8, top: 8, bottom: 8 },
+  legend: { show: false }
+}
+```
+
+## 填充与描边模式
+
+```typescript
+series: [{
+  type: 'map',
+  mapMode: 'stroke' // 'fill'(默认) | 'stroke'
+}]
+```
+
+## 交互事件
+
+点击地图区域会触发图表的 `click` 事件，`event.title` 为区域名称（`properties.name`）。
+
+## 系列配置项
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| type | string | - | 固定 `'map'` |
+| mapMode | string | `'fill'` | 地图模式：`'fill'` 填充 / `'stroke'` 线轮廓 |
+| mapFillColor | string | 自动 | 区域填充色（fill 模式） |
+| mapStrokeColor | string | 自动 | 区域描边色 |
+| mapActiveColor | string | 自动 | 选中区域填充/描边色 |
+| mapStrokeWidth | number | 自动 | 描边宽度 |
+| label | ChartLabelOptions | - | 区域标签配置（show/fontSize/color/formatter） |
+
+## 标签格式化
+
+`label.formatter` 支持占位：
+
+- `{name}`：区域名称（`properties.name`）
+- `{value}`：区域数值（`properties.value`）

package/data/tmui4x/31./345/216/237/347/224/237/345/233/276/350/241/250/03/345/233/276/350/241/250/347/261/273/345/236/213/12./344/273/252/350/241/250/347/233/230/345/233/276.md

@@ -0,0 +1,89 @@
+# 仪表盘图 Gauge
+
+以百分比进度展示的仪表盘，支持渐变进度弧、指针、刻度、中心文字与格式化数值。
+
+## 效果
+
+<ViewMobile url="/pages/chart/gauge" />
+
+## 基本用法
+
+仪表盘不依赖 `data`，主要通过 `series[0].percent` 指定进度（0~1）。
+
+```typescript
+{
+  data: [] as UTSJSONObject[],
+  series: [{
+    type: 'gauge',
+    percent: 0.72,
+    pieCenterText: 'SCORE',
+    gaugeTickCount: 10
+  }]
+}
+```
+
+## 渐变进度弧
+
+```typescript
+series: [{
+  type: 'gauge',
+  percent: 0.72,
+  gaugePointerColor: '#33f6a2',
+  gaugeProgressColor: '#3b82f6',
+  gradient: ['#33f6a2', '#3696f6']
+}]
+```
+
+## 半圆仪表盘
+
+```typescript
+series: [{
+  type: 'gauge',
+  percent: 0.65,
+  gaugeStartAngle: -180,
+  gaugeEndAngle: 0,
+  gaugePointerColor: '#ef4444',
+  gaugeProgressColor: '#ef4444',
+  gaugeTickCount: 10
+}]
+```
+
+## 中心数值与格式化
+
+`label` 仅控制中心的数值显示，不影响刻度与 `pieCenterText / pieCenterSubText`。
+
+```typescript
+series: [{
+  type: 'gauge',
+  percent: 0.65,
+  pieCenterText: '健康度',
+  pieCenterSubText: '一般',
+  label: {
+    show: true,
+    formatter: '温度：{value}'
+  }
+}]
+```
+
+`label.formatter` 占位：
+
+- `{name}`：`pieCenterText`
+- `{value}`：0~100 的整数
+- `{percent}`：带一位小数的百分比字符串（如 `65.0%`）
+
+## 系列配置项
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| type | string | - | 固定 `'gauge'` |
+| percent | number | 0.5 | 进度 0~1 |
+| gaugeStartAngle | number | -210 | 起始角度（度） |
+| gaugeEndAngle | number | 30 | 结束角度（度） |
+| gaugeTickCount | number | 10 | 主刻度数量 |
+| gaugePointerColor | string | 自动 | 指针颜色 |
+| gaugeTrackColor | string | 自动 | 轨道颜色 |
+| gaugeProgressColor | string | 自动 | 进度弧颜色（与 gradient 二选一，gradient 优先） |
+| gradient | string[] | - | 进度弧渐变色数组（支持首项 `'to right'`/`'to bottom'` 指定方向） |
+| pieCenterText | string | '' | 中心主文字 |
+| pieCenterSubText | string | '' | 中心副标题 |
+| label | ChartLabelOptions | - | 中心数值标签配置（show/color/fontSize/formatter） |

package/data/tmui4x/31./345/216/237/347/224/237/345/233/276/350/241/250/04/344/272/244/344/272/222/344/270/216/351/253/230/344/272/256/01./351/253/230/344/272/256/346/240/267/345/274/217/351/205/215/347/275/256.md

@@ -0,0 +1,47 @@
+# 高亮样式配置
+
+通过 `activeStyle` 统一配置所有图表的选中高亮效果。所有属性可选，不设置时使用默认值（已适配暗色模式）。
+
+## 配置方式
+
+```typescript
+{
+  activeStyle: {
+    pointColor: '#ffffff',                // 选中点填充色
+    pointBorderWidth: 2.5,                // 选中点描边宽度
+    pointScale: 3,                        // 选中点半径增量(px)
+    backdrop: 'rgba(0,0,0,0.04)',         // 选中列背景遮罩色
+    borderColor: '#1f2937',               // 选中元素描边色（堆叠柱/树图等）
+    borderWidth: 1.5,                     // 选中元素描边宽度
+    pieScale: 6,                          // 饼图选中放大半径(px)
+    crosshairWidth: 1,                    // 十字线宽度
+    crosshairColor: 'rgba(0,0,0,0.15)'   // 十字线颜色
+  }
+}
+```
+
+## 各图表的高亮效果
+
+| 图表类型 | 高亮表现 |
+|---------|---------|
+| 折线/面积 | 选中点放大 + 变色 + 描边 + 背景遮罩 |
+| 柱图 | 背景遮罩 |
+| K线 | 背景遮罩 |
+| 漏斗 | 横向背景遮罩 |
+| 饼/环图 | 扇区向外放大 |
+| 散点 | 选中点放大 + 描边 |
+| 雷达 | 选中顶点放大 + 变色 |
+| 矩形树图 | 选中块描边 + 其余淡化 |
+
+## 暗色模式自动适配
+
+不配置 `activeStyle` 时，默认值会根据暗色模式自动切换：
+
+| 属性 | 亮色默认 | 暗色默认 |
+|------|---------|---------|
+| pointColor | `#ffffff` | `#1e293b` |
+| backdrop | `rgba(0,0,0,0.04)` | `rgba(255,255,255,0.08)` |
+| borderColor | `#1f2937` | `#94a3b8` |
+| crosshairColor | `rgba(0,0,0,0.15)` | `rgba(255,255,255,0.25)` |
+
+环形图/饼图的中心文字颜色也会自动适配暗色。

package/data/tmui4x/31./345/216/237/347/224/237/345/233/276/350/241/250/05/351/253/230/347/272/247/345/212/237/350/203/275/01./346/225/260/346/215/256/347/274/251/346/224/276/344/270/216/345/271/263/347/247/273.md

@@ -0,0 +1,93 @@
+# 数据缩放与平移
+
+适用于笛卡尔坐标系图表（折线、柱图、面积、K线），用于浏览大数据量。
+
+## 效果
+
+<ViewMobile url="/pages/chart/zoom" />
+
+## 配置
+
+```typescript
+{
+  dataZoom: {
+    enabled: true,    // 是否启用，默认 true
+    start: 0,         // 初始视口起点 0~1，默认 0
+    end: 1,           // 初始视口终点 0~1，默认 1
+    minSpan: 0.1      // 最小视口宽度 0~1
+  }
+}
+```
+
+## 平移操作
+
+在图表上左右滑动即可平移视口，查看不同区间的数据。
+
+## 大数据量示例
+
+一次传入上万条数据，通过 `start`/`end` 控制初始显示区间：
+
+```typescript
+{
+  data: generateBigData(10000),  // 10000 条数据
+  series: [{ type: 'line', xField: 'date', yField: 'value' }],
+  dataZoom: {
+    start: 0.9,   // 初始只显示最后 10%
+    end: 1
+  }
+}
+```
+
+## 边缘加载事件 reachEdge
+
+当用户滑到数据头部或尾部附近（约 50px 范围内）时触发 `reachEdge` 事件，用于动态加载更多数据。
+
+```html
+<x-chart :options="opts" @reachEdge="onEdge" />
+```
+
+```typescript
+import { ChartEdgeEvent } from '@/uni_modules/tmx-ui/core/canvas/chart/types.uts'
+
+const onEdge = (e: ChartEdgeEvent) => {
+  if (e.direction == 'end') {
+    // 滑到尾部，加载更多新数据
+    loadMoreData('after')
+  } else if (e.direction == 'start') {
+    // 滑到头部，加载更多历史数据
+    loadMoreData('before')
+  }
+}
+```
+
+**ChartEdgeEvent 类型**：
+
+```typescript
+import { ChartEdgeEvent } from '@/uni_modules/tmx-ui/core/canvas/chart/types.uts'
+
+// type ChartEdgeEvent = {
+//   direction: string,  // 'start' 滑到头部 | 'end' 滑到尾部
+//   start: number,      // 当前视口起点 0~1
+//   end: number,        // 当前视口终点 0~1
+//   total: number       // 当前总数据条数
+// }
+```
+
+到达边缘后只触发一次，离开边缘区域再滑回来才会再次触发，避免重复加载。
+
+## 性能优化
+
+组件内置了以下优化，无需手动处理：
+
+- **LTTB 降采样**：可见点数超过画布像素宽度时自动降采样，视觉无损
+- **密集跳过**：相邻点距离 < 3px 时跳过点和命中区域的创建
+- **平移节流**：滑动时每帧最多重绘一次
+- **O(n) 去重**：标签域构建使用 Map 替代 includes
+
+## 纯展示模式
+
+如果图表只用于展示不需要交互，设置 `preventScroll` 为 false 允许页面滚动：
+
+```html
+<x-chart :options="opts" :preventScroll="false" />
+```

package/data/tmui4x/31./345/216/237/347/224/237/345/233/276/350/241/250/05/351/253/230/347/272/247/345/212/237/350/203/275/02./345/212/250/346/200/201/346/233/264/346/226/260/344/270/216/345/212/250/347/224/273.md

@@ -0,0 +1,58 @@
+# 动态更新与动画
+
+## 入场动画
+
+图表首次渲染和数据变更时自动播放入场动画（约 500ms）：
+
+- **柱图**：从底部向上生长
+- **饼/环图**：扇区从起始角展开
+- **进度环**：弧线从起始角展开
+- **其他**：淡入
+
+## 通过 props 更新
+
+直接修改绑定的 `options` 对象，会触发入场动画重新播放：
+
+```html
+<x-chart :options="chartOptions" />
+```
+
+```typescript
+// 切换数据
+chartOptions = { data: newData, series: [...] }
+```
+
+## 通过 ref 方法更新
+
+```html
+<x-chart ref="chartRef" :options="opts" />
+```
+
+```typescript
+const chartRef = ref()
+
+// 更新配置（触发入场动画）
+chartRef.value.setOptions({
+  data: newData,
+  series: [{ type: 'bar', xField: 'x', yField: 'y' }]
+})
+
+// 仅重绘（不触发动画）
+chartRef.value.redraw()
+```
+
+## 混合图表
+
+同一图表中可以混合多种系列类型：
+
+```typescript
+{
+  data: [...],
+  series: [
+    { type: 'bar', xField: 'month', yField: 'sales' },
+    { type: 'line', xField: 'month', yField: 'profit', color: '#ef4444' }
+  ]
+}
+```
+
+柱图和折线会共享同一坐标轴，自动合并 Y 轴范围。