F2 TagGuide 标签标注组件完全指南：用法、方向控制与精确定位原理

数据可视化前端【免费下载链接】F2An elegant, interactive and flexible charting library for mobile.项目地址https://gitcode.com/gh_mirrors/f2/F2点击查看免费下载TagGuide 是 F2 图表库中用于在数据点上绘制带箭头的标签标注Tag的 Guide 组件常用于标注柱状图/折线图中的最高销量、最大值、关键数据点等。本文基于 F2 仓库中的官方文档 tag-guide.zh.md 与对应源码完整讲解 TagGuide 的全部 Props 配置、8 个箭头方向、特殊值定位、分组柱状图精确定位等能力并深入到 withGuide.tsx 与 Tag.tsx 的源码剖析其坐标解析、自动避让算法与箭头绘制原理。读完本文你将能在自己的 F2 移动端图表中熟练使用 TagGuide 完成各类数据标注场景。一、TagGuide 是什么TagGuide 是 F2 提供的九种 Guide 组件之一其余包括 TextGuide、LineGuide、RectGuide、ImageGuide、ArcGuide、PointGuide、LottieGuide、PolylineGuide。在 index.tsx 中TagGuide 由withGuide(TagGuideView)高阶组件包装生成const TagGuide withGuide(TagGuideView);它的典型形态是一个带圆角背景的文本标签 一个指向标注点的三角形箭头。与普通 TextGuide 的区别在于TagGuide 自带气泡/标签容器和箭头视觉上更像移动端图表中的 Tooltip 标记或排行榜角标适合标注最高销量最大值等单一重点信息。其核心 API 为一个 JSX 组件可直接放在Chart内使用import { Canvas, Chart, Interval, TagGuide } 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} Interval xgenre ysold / TagGuide records{[{ genre: Sports, sold: 350 }]} content最高销量 directtr background{{ fill: #fff }} textStyle{{ fill: #000 }} / /Chart /Canvas从源码结构看records描述标注指向哪个数据点content描述标签里显示什么文字direct决定箭头和标签相对数据点的方位三者构成 TagGuide 的最基本用法。二、Props 全解析TagGuide 的 TypeScript 类型定义见文档与 Tag.tsx 中的TagGuideProps如下interface TagGuideProps { /** 标注位置的数据项或比例值 */ records: RecordItem[]; /** 文本内容 */ content?: string; /** x 轴偏移量支持数字或带单位的字符串如 10px*/ offsetX?: number | string; /** y 轴偏移量支持数字或带单位的字符串如 10px*/ offsetY?: number | string; /** 箭头方向 */ direct?: tl | tc | tr | cl | cr | bl | bc | br; /** 箭头的边长 */ side?: string | number; /** 是否自动调整方向避免超出画布 */ autoAdjust?: boolean; /** 背景容器样式支持 rect 组件属性 */ background?: PartialRectStyleProps; /** 文本样式支持 text 组件属性 */ textStyle?: PartialTextStyleProps; /** 是否精确定位用于分组柱状图详见下方说明 */ precise?: boolean; /** 是否显示标注 */ visible?: boolean; /** 点击事件回调 */ onClick?: (ev: Event) void; /** 动画配置详见 [动画文档](https://link.gitcode.com/i/ff8a4d601e10d051ab03c9bc10f1bb39) */ animation?: AnimationProps | ((points: Point[], chart: Chart) AnimationProps); }各属性含义与默认值汇总如下属性类型默认值说明recordsArrayRecordItem-标注位置的数据项或比例值支持特殊值见下文contentstring-文本内容offsetXnumber \| string0x 轴偏移量支持数字或带单位字符串如10pxoffsetYnumber \| string0y 轴偏移量同上directtl \| tc \| tr \| cl \| cr \| bl \| bc \| brtl箭头方向见下文方向表sidestring \| number8px箭头的边长autoAdjustbooleantrue是否自动调整标签方向避免超出画布backgroundRectStyleProps-背景容器样式支持 rect 组件属性textStyleTextStyleProps-文本样式支持 text 组件属性precisebooleanfalse是否精确定位用于分组柱状图中精确定位到每个子柱子visiblebooleantrue是否显示标注onClickFunction-点击事件回调animationAnimationProps \| Function-动画配置详见 动画文档上述默认值offsetX: 0、offsetY: 0、direct: tl、side: 8px、autoAdjust: true与 Tag.tsx 中的defaultProps完全一致const defaultProps: OmitTagGuideProps, records { offsetX: 0, offsetY: 0, points: [], direct: tl, side: 8px, autoAdjust: true, };注意side的默认值为8px是一个带单位的字符串渲染时所有带单位的值都会经过context.px2hd换算为物理像素源码中const cfg { ...defaultProps, ...props }后统一执行px2hd(cfg)。三、records 特殊值无需计算坐标即可定位records是标注位置的核心值可以是具体数据项也可以是特殊字符串。在 withGuide.tsx 的parseReplaceStr方法中实现了特殊值的解析值含义对应位置min最小值0max最大值1median中位值0.550%50% 位置0.5100%100% 位置1.0对应的解析逻辑分为三层关键字映射min → 0、max → 1、median → 0.5通过replaceMap直接返回归一化比例值百分比解析形如xx%的字符串会被解析为Number(value.slice(0, -1)) / 100即50% → 0.5、100% → 1.0兜底逻辑以上都不是时调用scale.scale(value)走正常的数据字段换算。因此records{[{ genre: Sports, sold: max }]}无需关心sold的具体最大值是多少F2 会自动把标签指向该字段比例位置为 1.0即最大值处的点。四、direct8 个方向的箭头控制direct属性控制标签相对于标注点的方向两个字符分别代表垂直方位 水平方位第一个字符t/b/c表示上/下/居中第二个字符l/r/c表示左/右/居中。8 个取值如下值含义图示tltop-left标签在左上方↖tctop-center标签在上方居中↑trtop-right标签在右上方↗clcenter-left标签在左侧居中←crcenter-right标签在右侧居中→blbottom-left标签在左下方↙bcbottom-center标签在下方居中↓brbottom-right标签在右下方↘在 Tag.tsx 的_getArrowPoints中每个方向都对应一组箭头polygon的三个顶点坐标例如tc上方居中箭头顶点为[{x: guideWidth/2, y: guideHeight side}, {x: guideWidth/2 - side, y: guideHeight - 1}, {x: guideWidth/2 side, y: guideHeight - 1}]同时标签位置整体向上偏移guideHeight sidebc下方居中箭头向下posY posY sidecr右侧居中箭头向右posX sideposY - guideHeight / 2。结合测试用例 type.test.tsx一个图表中同时使用全部 8 个方向是被明确支持的场景TagGuide records{[{ genre: Sports, sold: 5 }]} directtc contenttag / TagGuide records{[{ genre: Strategy, sold: 10 }]} directtl contenttag / TagGuide records{[{ genre: Action, sold: 20 }]} directtr contenttag / TagGuide records{[{ genre: Shooter, sold: 20 }]} directcl contenttag / TagGuide records{[{ genre: Other, sold: 40 }]} directcr contenttag / TagGuide records{[{ genre: Action, sold: 20 }]} directbl contenttag / TagGuide records{[{ genre: Sports, sold: 5 }]} directbc contenttag / TagGuide records{[{ genre: Strategy, sold: 10 }]} directbr contenttag /五、background 与 textStyle自定义标签外观background设置标签背景容器的样式即一个 rect 组件textStyle设置内部文本样式text 组件。示例background{{ fill: #fff, stroke: #1677FF, strokeWidth: 2, radius: 8px, padding: [8px, 12px], }}支持的属性见 Rect 属性文档。从源码 Tag.tsx 看Label子组件渲染结构为rect内嵌text背景样式通过展开运算符与默认样式合并rect style{{ display: flex, fill: defaultStyle.container.fill, padding: defaultStyle.container.padding, radius: defaultStyle.container.radius, ...background, }} text style{{ text: content, fontSize: defaultStyle.text.fontSize, fill: defaultStyle.text.fill, ...textStyle, }} / /rect两点实现细节值得注意用户传入的background/textStyle覆盖默认值未传入的字段保持默认无需完整重写样式箭头颜色跟随背景色源码中箭头 polygon 的fill为background?.fill || defaultStyle.arrow.fillTag.tsx即只要设置了background.fill箭头会自动取同色保证标签 箭头视觉一体。此外background也支持函数形式函数签名接收points解析后的坐标点数组返回样式对象可用于按数据项动态着色见下文分组柱状图示例。六、precise 精确定位模式在分组柱状图adjust{{ type: dodge }}中默认情况下 Guide 组件定位到的是分组所在的位置即整组柱子的 X 中心而不是某个子柱子的中心。precise{true}可以让标注精确定位到每个子柱子的中心。其底层实现位于 withGuide.tsx 的parsePoint方法if (precise adjust?.type dodge) { const xScale chart.getXScales()[0]; const typeScale chart.getColorScales()[0]; const numericRecord this._numberic(record); adjust.adjust.getPositionInfo(numericRecord, xScale.field, record[typeScale.field]); const x xScale.scale(numericRecord[xScale.field]); const y yScale.scale(numericRecord[yScale.field]); return coord.convertPoint({ x, y }); }可以看到precise模式依赖三个条件precise为true、当前adjust.type为dodge、图表存在颜色分组字段。此时通过adjust.getPositionInfo()拿到该子柱子在该分组内的真实位置信息后再做坐标换算。适用场景当使用adjustdodge分组调整时设置precise{true}可确保标注准确对应每个子柱子。官方测试用例 preciseGuide.test.tsx 使用三城市、两月份的降雨量分组柱状图验证了该能力。一个完整的分组柱状图 逐柱标注 动态样式示例来自文档import { Canvas, Chart, Interval, TagGuide, Axis } from antv/f2; const data [ { name: London, 月份: Jan., 月均温度: 5.2 }, { name: London, 月份: Feb., 月均温度: 6.8 }, { name: Beijing, 月份: Jan., 月均温度: -3.9 }, { name: Beijing, 月份: Feb., 月均温度: 2.1 }, ]; Canvas context{context} Chart data{data} Axis field月份 / Axis field月均温度 min{-10} / Interval x月份 y月均温度 colorname adjust{{ type: dodge, marginRatio: 0.05 }} / {data.map((item) ( TagGuide records{[item]} precise content{${item[月均温度]}°C} direct{item[月均温度] 0 ? tc : bc} background{(points) { const colorMap { London: #1677FF, Beijing: #22C678 }; return { fill: colorMap[item.name] }; }} textStyle{{ fontSize: 20px, fill: #fff }} / ))} /Chart /Canvas说明min{-10}Y 轴底部预留空间避免负数标签遮挡 X 轴刻度direct根据数值正负动态调整正数标签向上tc负数标签向下bcbackground函数让标签背景色与对应柱子颜色一致。七、默认样式与主题TagGuide 的默认样式文档原文定义在 Tag.tsx 的defaultStyle中{ container: { fill: #1677FF, radius: 4px, padding: [4px, 8px], }, text: { fontSize: 22px, fill: #fff, }, arrow: { fill: #1677FF, }, }即默认标签为品牌蓝#1677FF圆角矩形、白色 22px 文字、同色箭头。这些默认值可以在不传background/textStyle时直接生效构成开箱即用的效果。八、实战用法示例大全以下示例均来自官方文档可组合使用以满足各类标注场景。1. 基础用法Canvas context{context} Chart data{data} Interval xgenre ysold / TagGuide records{[{ genre: Shooter, sold: 350 }]} content最高销量 directtr / /Chart /Canvas;2. 自定义样式白底蓝边标签TagGuide records{[{ genre: Shooter, sold: 350 }]} content最高销量 directtl background{{ fill: #fff, stroke: #1677FF, strokeWidth: 2, radius: 8px, padding: [8px, 12px], }} textStyle{{ fill: #1677FF, fontSize: 24px, fontWeight: bold, }} /3. 不同方向标注{/* 右上方向 */} TagGuide records{[item]} content右上 directtr / {/* 下方居中 */} TagGuide records{[item]} content下方 directbc / {/* 左侧居中 */} TagGuide records{[item]} content左侧 directcl /4. 使用特殊值{/* 标注最大值 */} TagGuide records{[{ genre: Sports, sold: max }]} content最大值 directtc background{{ fill: green }} /5. 禁用自动调整TagGuide records{[item]} content固定方向 directtl autoAdjust{false} /6. 自定义箭头大小TagGuide records{[item]} content大箭头 directtr side12px /7. 多标签组合用 map 批量生成使用多个map分别生成多组标签Canvas context{context} Chart data{data} Interval xgenre ysold / {data.map((item) ( TagGuide records{[{ genre: item.genre, sold: max }]} contentMax directtc background{{ fill: red }} / ))} {data.map((item) ( TagGuide records{[{ genre: item.genre, sold: min }]} contentMin directbc background{{ fill: green }} / ))} /Chart /Canvas;8. 配合 offset 使用offsetX/offsetY支持数字或带单位字符串可在定位基础上再做像素级微调TagGuide records{[item]} content偏移标签 directtr offsetX{20} offsetY{-30} /测试中同样可以看到offsetX0px、offsetY-24px这类带单位写法见 guide.test.tsx。9. 使用动画TagGuide records{[item]} content标签 directtr animation{{ appear: { duration: 450, easing: linear, } }} /更多动画配置详见 动画文档。animation也支持函数形式(points: Point[], chart: Chart) AnimationProps可以在 withGuide.tsx 中看到其动态求值逻辑isFunction(animation) ? animation(points, chart) : animation。10. 分组柱状图精确定位完整版见上文precise 精确定位模式一节的完整示例包含min{-10}预留空间、正负方向自适应、函数式背景着色三个要点。11. 点击事件TagGuide records{[item]} content点击我 directtr onClick{(e) { console.log(标签被点击, e); }} /事件挂载在 withGuide.tsx 返回的group容器上onClick onClick(ev)。12. 根据条件控制显示通过visible属性动态控制标签显示例如只给销量大于 200 的柱子打标{data.map((item) ( TagGuide records{[item]} content{item.sold} directtc visible{item.sold 200} / ))}实现上visible false时 withGuide.tsx 直接返回空组件完全不渲染。九、源码级原理从 records 到箭头的完整链路结合 withGuide.tsx 与 Tag.tsxTagGuide 的渲染链路可以概括为五个阶段坐标解析withGuide.convertPoints → parsePoint将records中的每个数据项解析为画布坐标点。普通模式下走parseReplaceStr支持 min/max/median/百分比precise dodge模式下走adjust.getPositionInfo获取子柱位置。可见性与事件处理withGuide.rendervisible false直接返回空group上挂载onClick。样式/动画求值style与animation若为函数则以(points, chart)调用求值withGuide.tsx第 128-129 行。布局测量Tag.render先渲染一次Labelrect text通过computeLayout得到标签的guideWidth/guideHeight供定位与箭头计算使用。方向决策与箭头绘制autoAdjust为true时调用_getDirect对 8 个方向逐一做越界翻转判断随后_getArrowPoints按最终方向计算箭头三角形三个顶点最终以group rect text polygon的层级渲染。autoAdjust 的自动避让算法Tag.tsx值得展开说明它利用传入的canvasWidth/canvasHeight由 withGuide 从 context 的宽高传入对垂直与水平两个维度分别检查垂直方向direct首字符为t且y - side - guideHeight 0顶部空间不足时翻转为b为b且y side guideHeight canvasHeight时翻转为t水平方向l方向空间不足翻转为rr空间不足翻转为l居中c方向则检查guideWidth / 2 x是否越界来左右翻转。这就是autoAdjust默认true能让标签始终保持在画布内的实现原理当业务上要求方向严格固定时设置autoAdjust{false}即可。十、测试验证与稳定性仓库为 TagGuide 提供了专门的快照测试位于 packages/f2/test/components/guide/type.test.tsx覆盖 TagGuide 基础渲染、8 个方向同时渲染TagGuide不同方向、以及通过canvas.update动态更新content后的重绘TagGuide updatepreciseGuide.test.tsx覆盖分组柱状图下precise精确定位以及 Guide 被多次 render 时的稳定性通过MockTagGuide故意多次调用super.render()验证。这些测试以toMatchImageSnapshot断言渲染结果从侧面验证了 TagGuide 在方向、更新、精确定位等场景下的行为是可预期且稳定的。在文档给出的基础上你还可以参照 guide.test.tsx 了解 offset 与其他 Guide 组件的组合用法。结语TagGuide 是 F2 中实现重点数据标注最直观的组件records定义目标点支持 min/max/median/百分比特殊值direct控制 8 个方向side控制箭头大小background/textStyle控制外观precise解决分组柱状图的逐柱子定位autoAdjust保证标签不出画布visible/onClick/animation则让标注具备交互与动效。配合本文梳理的源码链路withGuide 坐标解析 → 布局测量 → 方向决策 → 箭头绘制你既可以快速上手也能在遇到复杂标注需求如分组图、动态样式、负值标签时准确判断该用哪个属性、改哪层实现。赞分享数据可视化前端【免费下载链接】F2An elegant, interactive and flexible charting library for mobile.项目地址https://gitcode.com/gh_mirrors/f2/F2点击查看免费下载相关推荐F2 标注组件Guide完全指南从内置标注到自定义标注F2 标注组件Guide完全指南从内置标注到自定义标注 标注Guide组件是 F2 移动端图表库中用于在图表上叠加文本、点、线、矩形、图像、标签、阶梯数据可视化前端Svelte {html} 标签完全指南向组件注入原始 HTML 的原理、限制与安全实践Svelte {html} 标签完全指南向组件注入原始 HTML 的原理、限制与安全实践 在 Svelte 中普通插值 {content} 会自动对字符串前端Web框架编译器F2 ImageGuide 图片标注组件完全指南定位、样式、事件与动画实战F2 ImageGuide 图片标注组件完全指南定位、样式、事件与动画实战 在移动端图表中除了图形本身常常需要在关键数据点如最高值、最低值或特定记录上数据可视化前端上一篇plannotator 仓库 Renovate GitHub Actions PR 审查技能实战指南供应链完整性与 CI/CD 兼容性验证下一篇vscode-edge-devtools 安全配置保护你的调试会话与数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考