数据可视化前端【免费下载链接】F2An elegant, interactive and flexible charting library for mobile.项目地址https://gitcode.com/gh_mirrors/f2/F2点击查看免费下载导读PointGuide 是 F2 移动端图表库内置的标注Guide组件之一用于在图表画布上以圆形标记的形式标注数据点例如标注折线图上的最大值、最小值、中位值或特定百分比位置。本文将以 point-guide.zh.md 为核心结合仓库源码与测试用例系统讲解 PointGuide 的用法、全部 Props、records 特殊值语义、style 对象/函数两种形态、动画配置以及面向分组柱状图的 precise 精确定位能力帮助你在实际项目中快速、准确地为图表添加数据标注。PointGuide 在 F2 中的定位与组件结构在 F2 的组件体系中PointGuide 属于 guide 组件族与 TextGuide、LineGuide、ArcGuide、RectGuide、ImageGuide、TagGuide、LottieGuide、PolylineGuide 并列统一由withGuide高阶组件包装对应视图而成。相关注册与导出位于 packages/f2/src/components/guide/index.tsx其中const PointGuide withGuide(PointGuideView);withGuidepackages/f2/src/components/guide/withGuide.tsx负责所有 Guide 组件的通用逻辑解析records为画布坐标、处理precise精确定位、执行style/animation函数形态的求值以及统一处理visible与onClick。而PointGuideViewpackages/f2/src/components/guide/views/Point.tsx则专司把解析后的坐标渲染为一个圆点circle图形并把主题默认样式与传入style深合并。这种通用逻辑 视图渲染的分层结构意味着所有 Guide 在records解析规则、特殊值语义、precise 定位上的行为是一致的本文讲解的 PointGuide 知识同样适用于其他 Guide 组件。快速上手最小可用示例PointGuide 的典型用法是把图表数据逐条映射为标注在Chart内、与图形组件如Line并列声明PointGuide通过records指定标注位置通过style指定圆点外观。import { Canvas, Chart, Line, PointGuide } from antv/f2; const data [ { genre: Sports, sold: 275 }, { genre: Strategy, sold: 115 }, { genre: Action, sold: 120 }, { genre: Shooter, sold: 350 }, { genre: Other, sold: 150 }, ]; Canvas context{context} Chart data{data} Line xgenre ysold / {data.map((item) ( PointGuide records{[item]} offsetX{0} offsetY{0} style{{ fill: #f00 }} / ))} /Chart /Canvas要点说明records接收一个数组数组中的每个元素是一条数据记录RecordItem Recordstring, string | number组件会把它翻译为画布坐标后取第一个点渲染圆点。所以想标几个点就放几条记录。Line xgenre ysold声明了 x、y 字段映射PointGuide 会复用图表的 x/y 度量Scale来做坐标换算。圆点的默认外观由主题控制详见下文默认样式值。TypeScript 类型定义与全部 PropsPointGuide 的完整类型定义摘自 point-guide.zh.mdinterface PointGuideProps { /** 标注位置的数据项或比例值 */ records: RecordItem[]; /** x 轴偏移量支持数字或带单位的字符串如 10px*/ offsetX?: number | string; /** y 轴偏移量支持数字或带单位的字符串如 10px*/ offsetY?: number | string; /** 圆形样式支持对象或函数形式 */ style?: PartialCircleStyleProps | ((points: Point[], chart: Chart) PartialCircleStyleProps); /** 动画配置详见 [动画文档](https://link.gitcode.com/i/6b1d3ce1a38bbcb0b4b9ec286e2e3e7a) */ animation?: AnimationProps | ((points: Point[], chart: Chart) AnimationProps); /** 点击事件回调 */ onClick?: (ev: Event) void; /** 是否显示默认 true */ visible?: boolean; /** 是否精确定位用于分组柱状图中精确定位到每个子柱子 */ precise?: boolean; } /** 画布坐标点 */ interface Point { x: number; y: number; } /** 数据记录 */ type RecordItem Recordstring, string | number;全部 Props 一览属性类型默认值说明recordsArrayRecordItem-标注位置的数据项或比例值支持特殊值见下文offsetXnumber \| string0x 轴偏移量offsetYnumber \| string0y 轴偏移量styleCircleStyleProps \| Function见下方圆形样式支持对象或函数形式animationAnimationProps \| Function-动画配置详见 动画文档onClick(ev: Event) void-点击事件回调visiblebooleantrue是否显示标注preciseboolean-是否精确定位用于分组柱状图中精确定位到每个子柱子默认样式值PointGuide 圆点的默认样式定义在 F2 主题的guide.point节点中见 packages/f2/src/theme.ts{ fill: #fff, r: 3, lineWidth: 2, stroke: #1890ff, }即白色填充、半径为 3、描边宽度 2、主题蓝#1890ff描边。由于视图在渲染时使用deepMix({ ...theme.point }, props)深合并因此你传入的style会覆盖这些默认值中的对应字段未声明的字段继续沿用主题默认。此外主题中guide.point还带有offsetX: 0、offsetY: 0这与文档表格中 offset 的默认值一致。records 特殊值无需手算坐标的定位语法records中的字段值不仅可以是真实数据还可以使用特殊字符串来表达比例位置组件会将其归一化为 01 的比例值再经度量换算无需你手动计算具体数值。完整取值表如下值含义对应位置min最小值0max最大值1median中位值0.50%0% 位置0.050%50% 位置0.5100%100% 位置1.0注意这里的min/max/median是比例意义上的最小值/最大值即坐标轴的起点 0 与终点 1对应到连续型 y 轴上等价于数据的最小值/最大值刻度0%、50%、100%则是坐标轴的 0%、50%、100% 位置。两者指向同一组位置。特殊值的底层解析逻辑从源码看这一语义由withGuide中的parseReplaceStr实现packages/f2/src/components/guide/withGuide.tsx先查内置映射表min → 0、max → 1、median → 0.5命中则直接返回比例值若值是形如xx%的字符串以%结尾且前缀是数字则rateValue / 100得到比例值例如50%→ 0.5否则走正常路径scale.scale(value)用对应度量把真实数据值换算成归一化比例。换算出的比例值会与另一维度的值一同交给coord.convertPoint({ x, y })转为最终画布坐标。因此特殊值既可以用于 y 轴如sold: min也可以用于 x 轴如genre: min标注坐标轴最左端。示例标注每个 x 位置的 y 最小值{data.map((item) ( PointGuide records{[{ genre: item.genre, sold: min }]} style{{ stroke: #262626 }} / ))}style 属性的两种形态style支持对象形式与函数形式两种写法对应静态样式与动态样式两种诉求。对象形式静态样式style{{ fill: #f00, stroke: #000, lineWidth: 2 }}适用于样式与数据、位置无关的场景。可配置的样式字段是CircleStyleProps即圆形图形属性cx、cy由组件自动计算其余如fill、stroke、lineWidth、r、opacity、shadow等均可完整属性见 Shape 属性文档。函数形式动态样式style{(points, chart) ({ fill: points[0].y 0.5 ? #f00 : #00f })}函数接收两个参数points:Point[]- 转换后的画布坐标点数组每个元素形如{ x: number; y: number }取自records解析结果chart:Chart- 图表实例可获取图表布局信息如chart.layout、坐标、度量等。从源码看packages/f2/src/components/guide/withGuide.tsxwithGuide在渲染阶段会检测style是否为函数若是则先以style(points, chart)求值得到最终的样式对象再传入视图函数形态的animation同理。这意味着你可以在函数内基于任意一个标注点的画布坐标、甚至整个图表的状态来动态决定圆点的大小、颜色等外观。实战按相对高度动态着色Canvas context{context} Chart data{data} Line xgenre ysold / {data.map((item) ( PointGuide records{[item]} style{(points, chart) { const y points[0].y; const { top, bottom } chart.layout; const normalizedY (y - bottom) / (top - bottom); return { fill: normalizedY 0.7 ? red : gray, r: normalizedY 0.7 ? 6 : 4, }; }} / ))} /Chart /Canvas这里利用chart.layout的top/bottom把点的画布 y 坐标归一化到 01再据此区分高点红色、半径 6与普通点灰色、半径 4非常适合做阈值告警式标注。用法示例集以下示例覆盖 PointGuide 最常见的几种实战形态可直接复制到项目中按需组合。使用特殊值标注min 与 max 同屏展示Canvas context{context} Chart data{data} Line xgenre ysold / {data.map((item) ( PointGuide records{[{ genre: item.genre, sold: min }]} style{{ stroke: #262626 }} / ))} {data.map((item) ( PointGuide records{[{ genre: item.genre, sold: max }]} style{{ stroke: #82DC95 }} / ))} /Chart /Canvas标注百分比位置Canvas context{context} Chart data{data} Line xgenre ysold / {data.map((item) ( PointGuide records{[{ genre: item.genre, sold: 100% }]} style{{ stroke: blue }} / ))} {data.map((item) ( PointGuide records{[{ genre: item.genre, sold: 50% }]} style{{ stroke: red }} / ))} /Chart /Canvas多标注组合min / median / max 三线同绘使用多个map分别生成多组标注可用于在一条折线上同时标出每个 x 位置的最低、居中与最高参考点Canvas context{context} Chart data{data} Line xgenre ysold / {data.map((item) ( PointGuide records{[{ genre: item.genre, sold: min }]} style{{ stroke: #262626 }} / ))} {data.map((item) ( PointGuide records{[{ genre: item.genre, sold: median }]} style{{ stroke: #FF6797 }} / ))} {data.map((item) ( PointGuide records{[{ genre: item.genre, sold: max }]} style{{ stroke: #82DC95 }} / ))} /Chart /Canvas使用动画animation同样支持对象与函数两种形态函数接收(points, chart)并返回动画配置。下面的示例让标注点以 450ms 的 appear 动画淡入Canvas context{context} Chart data{data} Line xgenre ysold / {data.map((item) ( PointGuide records{[item]} style{{ fill: red, r: 6 }} animation{{ appear: { duration: 450, } }} / ))} /Chart /Canvas更多动画阶段的配置appear/update/leave等详见 动画文档。深入原理records 如何变成画布坐标要真正用好 PointGuide理解坐标换算链路很有价值。从源码看整个流程集中在withGuide的parsePointpackages/f2/src/components/guide/withGuide.tsx中取度量从chart.getXScales()[0]与chart.getYScales()[0]分别取 x、y 轴的主度量逐字段换算对records中的每条记录x 字段与 y 字段各自经过parseReplaceStr普通值走scale.scale特殊值走映射/百分比换算得到 01 归一化比例坐标转换把{ x, y }比例值交给coord.convertPoint得到画布像素坐标渲染PointGuideView取points[0]作为圆心叠加offsetX/offsetY偏移后绘制circle。关于偏移与单位PointGuideView在渲染前用context.px2hd(offsetX)、context.px2hd(offsetY)处理偏移量packages/f2/src/components/guide/views/Point.tsx因此offsetX/offsetY既支持纯数字也支持带单位的字符串如10px最终按当前环境的像素比换算。另外视图对isNaN(x) || isNaN(y)的坐标直接返回空节点避免在坐标无效时绘制脏图形。precise 精确定位分组柱状图场景默认情况下Guide 的 x 定位落在该 x 字段对应刻度上。但在**分组柱状图dodge 调整**中同一 x 刻度下存在多个按颜色分组的子柱子普通定位无法落到具体的某一根柱子上。此时需要precise属性。parsePoint中precise的分支逻辑packages/f2/src/components/guide/withGuide.tsx当precise adjust?.type dodge时额外取出颜色度量chart.getColorScales()[0]调用adjust.adjust.getPositionInfo结合分类字段与颜色字段算出该数据项在 dodge 调整后的精确位置再经coord.convertPoint定位该逻辑对 TextGuide 等所有 Guide 生效示例中以 TextGuide 演示PointGuide 的precise语义相同。仓库测试 packages/f2/test/components/guide/preciseGuide.test.tsx 提供了完整的分组柱状图验证用例数据含name分组字段、月份x 字段、月均降雨量y 字段配合adjust{{ type: dodge, marginRatio: 0.05 }}的分组柱状图逐条records{[item]}加precise即可让每条标注精确钉在对应的子柱子上。Canvas context{context} Chart data{data} Axis field月份 / Axis field月均降雨量 / Interval x月份 y月均降雨量 color{{ field: name }} adjust{{ type: dodge, marginRatio: 0.05 }} / {data.map((item) ( PointGuide records{[item]} precise style{{ r: 6 }} / ))} /Chart /Canvas使用precise的注意事项它仅在分组dodge调整下有意义非 dodge 场景下该分支不会生效走常规定位records中需要包含颜色字段分组字段的值否则无法定位到具体子柱子若对定位精度有疑问可参考测试中 TextGuide 的逐数据项标注写法通过比对快照验证效果。交互与其他能力点击事件onClick{(ev) ...}接收事件对象。从withGuide的渲染结构看点击事件挂在包裹标注的group节点上packages/f2/src/components/guide/withGuide.tsx可在图表事件体系内实现标注的点击反馈。显隐控制visible默认为true设为false时整个标注组不渲染if (!visible) return;可用于按条件展示标注。主题覆盖除传入style外也可通过全局主题覆盖guide.point来统一调整所有 PointGuide 的默认外观主题文件见 packages/f2/src/theme.ts。相关阅读Guide 组件总览与注册 packages/f2/src/components/guide/index.tsxGuide 通用逻辑records 解析 / precise / 函数式 style 与 animation packages/f2/src/components/guide/withGuide.tsxPointGuide 视图渲染 packages/f2/src/components/guide/views/Point.tsx主题默认样式 packages/f2/src/theme.ts测试用例 type.test.tsx、preciseGuide.test.tsx其他标注类型文档 TextGuide、LineGuide、RectGuide、ImageGuide赞分享数据可视化前端【免费下载链接】F2An elegant, interactive and flexible charting library for mobile.项目地址https://gitcode.com/gh_mirrors/f2/F2点击查看免费下载相关推荐F2 ImageGuide 图片标注组件完全指南定位、样式、事件与动画实战F2 ImageGuide 图片标注组件完全指南定位、样式、事件与动画实战 在移动端图表中除了图形本身常常需要在关键数据点如最高值、最低值或特定记录上数据可视化前端TypeScript SDK 故障排查完全指南从 stdio 污染到协议时代协商失败的逐条解法TypeScript SDK 故障排查完全指南从 stdio 污染到协议时代协商失败的逐条解法 本篇指南面向使用 Model Context Protocol数据可视化前端昇腾CANN PTO浮点取模指令 TFMOD Tile Operation Diagram ! TFMOD tile operation https://raw.gitcode.com/ca数据可视化前端上一篇CAMEL 多智能体框架快速上手三步让两个 AI 角色自动协作完成任务下一篇如何高效使用开源网盘直链解析工具智能下载解决方案完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考