diff --git a/site/docs/api/chart/gauge.zh.md b/site/docs/api/chart/gauge.zh.md deleted file mode 100644 index 6b1216c87..000000000 --- a/site/docs/api/chart/gauge.zh.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: Gauge 仪表盘 -type: 组件 -order: 5 ---- - -# Gauge 仪表盘 - -仪表盘组件用于显示进度或完成度的可视化组件，常用于展示关键绩效指标（KPI）。 - -## 何时使用 - -- 需要显示单个指标的完成进度 -- 展示目标值与实际值的对比 -- 显示百分比或比例数据 -- 仪表盘样式的数据展示 - -## 代码演示 - -### 基础仪表盘 - - - -### 带颜色区间的仪表盘 - - - -### 自定义文本的仪表盘 - - - -## API - -### Gauge - -| 属性名 | 类型 | 默认值 | 描述 | -| ---------- | ------------------------ | ------------------ | ---------------- | -| percent | number | 0 | 进度值，范围 0-1 | -| startAngle | number | Math.PI | 起始角度（弧度） | -| endAngle | number | Math.PI \* 2 | 结束角度（弧度） | -| center | { x: number, y: number } | { x: 150, y: 150 } | 仪表盘中心点坐标 | -| r | number \| string | 100 | 仪表盘半径 | -| r0 | number \| string | 0 | 内圆半径 | -| tickCount | number | 5 | 刻度数量 | -| tickOffset | number \| string | -20px | 刻度偏移量 | -| tickLength | number \| string | 10px | 刻度长度 | - -## 使用示例 - -### 基础使用 - -```jsx -import { jsx, Canvas, Gauge } from '@antv/f2'; - -const context = document.getElementById('container').getContext('2d'); - -const { props } = ( - - - -); - -const chart = new Canvas(props); -chart.render(); -``` - -### 带颜色区间的仪表盘 - -```jsx -import { jsx, Canvas, Gauge } from '@antv/f2'; - -const context = document.getElementById('container').getContext('2d'); - -const actualValue = 85; -const targetValue = 100; -const percent = actualValue / targetValue; - -// 根据值获取颜色 -const getColor = (value) => { - if (value < 60) return '#ff4d4f'; // 红色 - if (value < 80) return '#faad14'; // 黄色 - return '#52c41a'; // 绿色 -}; - -const { props } = ( - - - - - {/* 添加文本显示 */} - - - - - -); - -const chart = new Canvas(props); -chart.render(); -``` - -### 自定义样式 - -```jsx -import { jsx, Canvas, Gauge } from '@antv/f2'; - -const context = document.getElementById('container').getContext('2d'); - -const { props } = ( - - - -); - -const chart = new Canvas(props); -chart.render(); -``` - -## 常见问题 - -### 如何设置颜色区间？ - -Gauge 组件本身不直接支持颜色区间设置，但你可以通过以下方式实现： - -1. 使用自定义渲染覆盖默认颜色 -2. 在文本或标签中显示对应的颜色状态 -3. 使用多个 Gauge 组件叠加实现 - -### 如何显示百分比？ - -可以通过添加文本组件来显示百分比： - -```jsx - -``` - -### 如何调整仪表盘大小？ - -通过调整`r`属性来改变仪表盘半径，同时需要相应调整`center`坐标： - -```jsx - -``` - -## 相关组件 - -- [Progress](/api/chart/progress) - 进度条组件 -- [Ring](/api/chart/ring) - 环形图组件 diff --git a/site/docs/api/chart/legend.zh.md b/site/docs/api/chart/legend.zh.md index 122bf586a..4e757236e 100644 --- a/site/docs/api/chart/legend.zh.md +++ b/site/docs/api/chart/legend.zh.md @@ -30,6 +30,10 @@ const data = [ ## Props +### layoutMode: 'uniform' | 'adaptive' + +可选值为：`'uniform' | 'adaptive'` , 默认为 `'uniform'` + ### position: string 可选值为：`'top' | 'right' | 'bottom' | 'left'`, 默认为 `'top'` diff --git a/site/docs/api/chart/magnifier.zh.md b/site/docs/api/chart/magnifier.zh.md new file mode 100644 index 000000000..085590628 --- /dev/null +++ b/site/docs/api/chart/magnifier.zh.md @@ -0,0 +1,168 @@ +--- +title: 放大镜 - Magnifier +type: 组件 +order: 11 +--- + +放大镜组件用于在图表上提供局部放大功能，帮助用户更清晰地查看数据细节。 + +## 何时使用 + +- 数据点过于密集，需要查看局部细节 +- 需要放大特定区域进行详细分析 + +## Usage + +```jsx +import { jsx, Canvas, Chart, Line, Magnifier } from '@antv/f2'; + +const context = document.getElementById('container').getContext('2d'); +const data = [ + { date: '2024-01-01', value: 10 }, + { date: '2024-01-02', value: 15 }, + { date: '2024-01-03', value: 8 }, + { date: '2024-01-04', value: 25 }, + { date: '2024-01-05', value: 30 }, + { date: '2024-01-06', value: 28 }, + { date: '2024-01-07', value: 35 }, +]; + +const { props } = ( + + + + + + +); + +const chart = new Canvas(props); +chart.render(); +``` + +## Props + +部分属性可参考 scale 图表度量，度量详细介绍可见：[度量](/tutorial/scale.zh.md) + +### show: boolean + +是否显示放大镜，默认为 `false` + +### x: number + +放大镜中心点的 x 坐标，默认为 `0` + +### y: number + +放大镜中心点的 y 坐标，默认为 `0` + +### width: number + +放大镜的宽度，默认为 `100` + +### height: number + +放大镜的高度，默认为 `80` + +### scale: number + +放大倍数，默认为 `2` + +### radius: number + +放大镜圆角半径，默认为 `10` + +### borderWidth: number + +边框宽度，默认为 `1` + +### borderColor: string + +边框颜色，默认为 `#e8e8e8` + +### backgroundColor: string + +背景颜色，默认为 `rgba(255, 255, 255, 0.9)` + +### shadowBlur: number + +阴影模糊程度，默认为 `10` + +### shadowColor: string + +阴影颜色，默认为 `rgba(0, 0, 0, 0.3)` + +### visible: boolean + +是否显示，默认为 `true` + +### field: string + +数据字段名 + +## 方法 + +可通过获取 ref 调用 + +### show(x: number, y: number) + +在指定坐标显示放大镜 + +### hide() + +隐藏放大镜 + +### updatePosition(x: number, y: number) + +更新放大镜位置 + +### updateScale(scale: number) + +更新放大倍数 + +## 使用场景示例 + +### 基础使用 + +```jsx + +``` + +### 自定义样式 + +```jsx + +``` + +### 动态控制 + +```jsx +const [showMagnifier, setShowMagnifier] = useState(false); +const [position, setPosition] = useState({ x: 0, y: 0 }); + +// 在图表点击时显示放大镜 +const handleChartClick = (ev) => { + setPosition({ x: ev.x, y: ev.y }); + setShowMagnifier(true); +}; + +; +``` + +## 常见问题 + +### 1. 放大镜不显示 + +- 检查 `show` 属性是否为 `true` +- 确认 `x` 和 `y` 坐标是否在图表范围内 +- 检查 `visible` 属性是否为 `true` diff --git a/site/docs/api/chart/pieLabel.zh.md b/site/docs/api/chart/pieLabel.zh.md new file mode 100644 index 000000000..f1703257c --- /dev/null +++ b/site/docs/api/chart/pieLabel.zh.md @@ -0,0 +1,260 @@ +--- +title: 饼图标签 - PieLabel +type: 组件 +order: 9 +--- + +饼图标签组件用于在饼图上显示数据标签，支持两种布局方式：默认布局和蜘蛛网布局，提供灵活的标签定位和样式自定义功能。 + +## 何时使用 + +- 需要在饼图上显示详细的数据标签 +- 数据标签需要避免重叠，提供清晰的视觉引导 + +## 使用方式 + +```jsx +import { jsx, Canvas, Chart, Pie, PieLabel } from '@antv/f2'; + +const context = document.getElementById('container').getContext('2d'); +const data = [ + { name: '餐饮', value: 20 }, + { name: '交通', value: 15 }, + { name: '购物', value: 25 }, + { name: '娱乐', value: 30 }, + { name: '其他', value: 10 }, +]; + +const { props } = ( + + + + ({ text: data.name })} + label2={(data) => ({ + text: data.value + '%', + fontWeight: 500, + })} + /> + + +); + +const chart = new Canvas(props); +chart.render(); +``` + +## 属性 + +### type: 'default' | 'spider' + +标签布局类型，默认为 `'default'` + +- **default**: 默认布局，使用曲线连接线，标签分布在左右两侧 +- **spider**: 蜘蛛网布局，使用直线连接线，标签呈放射状分布，推荐该布局 + +### anchorOffset: string | number + +锚点的偏移量，即标签线与饼图扇形的连接点距离，默认为 `'10px'` + +### inflectionOffset: string | number + +拐点的偏移量，即标签线的拐点距离，默认为 `'30px'` + +### sidePadding: string | number + +文本距离画布四边的距离，默认为 `'15px'` + +### label1: function + +第一行标签配置，接收数据项作为参数，返回标签配置对象 + +```jsx +label1={(data) => ({ + text: data.name, + fill: '#808080', + fontSize: 12, + textAlign: 'start' +})} +``` + +### label2: function + +第二行标签配置，接收数据项作为参数，返回标签配置对象 + +```jsx +label2={(data) => ({ + text: '￥' + data.value.toLocaleString(), + fill: '#000000', + fontSize: 14, + fontWeight: 500, + textAlign: 'start' +})} +``` + +### records: any[] + +指定要显示的数据记录，用于自定义显示特定数据项的标签 + +```jsx +records={[ + { name: '餐饮', value: 20 }, + { name: '交通', value: 15 } +]} +``` + +### triggerOn: 'click' | 'press' + +触发的事件类型，默认为 `'click'` + +### onClick: function + +标签点击事件回调函数，接收事件对象作为参数 + +```jsx +onClick={(data) => { + console.log('点击了标签:', data); +}} +``` + +### adjustRatio: number + +调整高度的阈值比例，默认为 `1` + +## 标签配置属性 + +标签配置对象支持以下属性： + +| 属性名 | 类型 | 描述 | +| ------------ | ----------------------------- | ---------------- | +| text | string | 标签文本内容 | +| fill | string | 文本颜色 | +| fontSize | number | 字体大小 | +| fontWeight | number \| string | 字体粗细 | +| textAlign | 'start' \| 'center' \| 'end' | 文本对齐方式 | +| textBaseline | 'top' \| 'middle' \| 'bottom' | 文本基线对齐方式 | + +## 布局类型示例 + +### 默认布局 + +```jsx + ({ text: data.name })} + label2={(data) => ({ text: data.value + '%' })} +/> +``` + +### 蜘蛛网布局 + +蜘蛛网布局适用于数据较多或需要更紧凑布局的场景： + +```jsx + ({ + text: data.name, + fill: '#666', + })} + label2={(data) => ({ + text: '￥' + data.value.toLocaleString(), + fill: '#000', + fontWeight: 500, + })} +/> +``` + +## 使用场景示例 + +### 基础使用 + +```jsx + + + ({ text: data.name })} label2={(data) => ({ text: data.value })} /> + +``` + +### 自定义样式 + +```jsx + + + ({ + text: data.name, + fill: '#1890ff', + fontSize: 14, + fontWeight: 500, + })} + label2={(data) => ({ + text: data.value + ' (' + ((data.value / total) * 100).toFixed(1) + '%)', + fill: '#666', + fontSize: 12, + })} + /> + +``` + +### 交互式标签 + +```jsx +const [selected, setSelected] = useState(null); + + + + ({ + text: data.name, + fill: selected === data.name ? '#1890ff' : '#666', + })} + label2={(data) => ({ + text: data.value, + fill: selected === data.name ? '#1890ff' : '#000', + fontWeight: selected === data.name ? 600 : 400, + })} + onClick={(data) => setSelected(data.name)} + /> +; +``` + +### 自定义显示记录 + +```jsx + + + d.value > 10)} // 只显示值大于10的标签 + label1={(data) => ({ text: data.name })} + label2={(data) => ({ text: data.value + '%' })} + /> + +``` + +## 常见问题 + +### 1. 标签显示不全或重叠 + +- 调整 `sidePadding` 属性增加边距 +- 使用 `type="spider"` 蜘蛛网布局获得更好的空间利用 +- 减少显示的标签数量，使用 `records` 属性筛选重要数据 + +### 2. 标签位置不理想 + +- 调整 `anchorOffset` 和 `inflectionOffset` 改变连接线长度 +- 检查数据是否有异常值导致标签位置计算错误 +- 确保饼图有足够的空间显示标签 + +### 3. 点击事件不响应 + +- 确认 `triggerOn` 属性设置正确（'click' 或 'press'） +- 检查是否有其他元素遮挡了标签 +- 验证 `onClick` 回调函数是否正确绑定 diff --git a/site/docs/api/gauge.zh.md b/site/docs/api/gauge.zh.md new file mode 100644 index 000000000..2750d02d5 --- /dev/null +++ b/site/docs/api/gauge.zh.md @@ -0,0 +1,87 @@ +--- +title: 仪表盘 - Gauge +type: 组件 +order: 5 +--- + +仪表盘组件用于显示进度或完成度的可视化组件，常用于展示关键绩效指标（KPI）。 + +## 何时使用 + +- 需要显示单个指标的完成进度 +- 展示目标值与实际值的对比 +- 显示百分比或比例数据 +- 仪表盘样式的数据展示 + +## Usage + +```jsx +import { jsx, Canvas, Gauge } from '@antv/f2'; + +const context = document.getElementById('container').getContext('2d'); + +const { props } = ( + + + +); + +const chart = new Canvas(props); +chart.render(); +``` + +## Props + +部分属性可参考 scale 图表度量，度量详细介绍可见：[度量](/tutorial/scale.zh.md) + +### percent: number + +进度值，范围 0-1，默认为 `0` + +### startAngle: number + +起始角度（弧度），默认为 `Math.PI` + +### endAngle: number + +结束角度（弧度），默认为 `Math.PI * 2` + +### center: { x: number, y: number } + +仪表盘中心点坐标，默认为 `{ x: 150, y: 150 }` + +### r: number | string + +仪表盘半径，默认为 `100` + +### r0: number | string + +内圆半径，默认为 `0` + +### tickCount: number + +刻度数量，默认为 `5` + +### tickOffset: number | string + +刻度偏移量，默认为 `-20px` + +### tickLength: number | string + +刻度长度，默认为 `10px` + +### visible: boolean + +是否显示，默认为 `true` + +### field: string + +数据字段名 + +## 常见问题 diff --git a/site/docs/api/chart/sunburst.md b/site/docs/api/sunburst.md similarity index 100% rename from site/docs/api/chart/sunburst.md rename to site/docs/api/sunburst.md diff --git a/site/docs/api/chart/treemap.md b/site/docs/api/treemap.md similarity index 100% rename from site/docs/api/chart/treemap.md rename to site/docs/api/treemap.md