F2 文本标注 TextGuide 完整指南：用法、对齐、偏移与源码原理

数据可视化前端【免费下载链接】F2An elegant, interactive and flexible charting library for mobile.项目地址https://gitcode.com/gh_mirrors/f2/F2点击查看免费下载文本标注TextGuide是 F2 图表库中用于在图表上直接绘制文字注释的组件。本文将以 F2 内置的 TextGuide 为核心从基础用法、Props 与 TypeScript 类型定义出发逐一讲解records定位、style对象/函数两种形态、textAlign与textBaseline对齐机制、offsetX/offsetY偏移与动画配置并结合仓库源码Text.tsx、withGuide.tsx与测试用例说明其底层工作原理。读完本文你将能在折线图、柱状图、饼图等任意图表上精确、灵活地叠加文本标注。TextGuide 是什么在 F2 的组件体系中Guide标注是一类特殊的图表叠加组件用于在图上标识额外的标记注解。除 TextGuide 外F2 还内置了 PointGuide点标注、TagGuide标签标注、ImageGuide图片标注、RectGuide矩形标注、LineGuide辅助线标注等详见 guide.zh.md。TextGuide 与其他 Guide 组件一样是经过withGuide高阶组件包装后得到的类组件见 index.tsx。它负责把用户传入的records数据项或比例值解析为画布坐标并在该位置渲染一段文本因此非常适合做数据标签如柱顶数值、极值标记如最大值/最小值说明、阈值提示如 50% 位置线等场景。快速上手TextGuide 的用法与普通 F2 组件一致直接嵌套在Chart内部通过records指定标注位置、content指定文本内容。下面这段代码在每个柱子的位置标注对应的数值import { Canvas, Chart, Interval, TextGuide } 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 / {data.map((item) ( TextGuide records{[item]} content{${item.sold}} style{{ fill: #000, fontSize: 24px, textAlign: center, textBaseline: bottom }} / ))} /Chart /Canvasrecords接受一个数组数组中的每个数据项都会被解析为一个坐标点当传入[item]时TextGuide 会在该数据项对应的几何位置如柱子的顶部、折线图的数据点处渲染文本。content既可以是字符串也可以是数字渲染时统一转为字符串。Props 与 TypeScript 类型定义TextGuide 的完整类型定义如下对应 Text.tsx 中的TextGuideProps它继承自GuidePropsinterface TextGuideProps { /** 标注位置的数据项或比例值 */ records: RecordItem[]; /** 文本内容 */ content: string | number; /** x 轴偏移量支持数字或带单位的字符串如 10px*/ offsetX?: number | string; /** y 轴偏移量支持数字或带单位的字符串如 10px*/ offsetY?: number | string; /** 文本样式支持对象或函数形式函数接收 points 和 chart 参数*/ style?: PartialTextStyleProps | ((points: Point[], chart: Chart) PartialTextStyleProps); /** 动画配置详见 [动画文档](https://link.gitcode.com/i/6dbfdcbac31ea118b992d46e44f7de8d) */ animation?: AnimationProps | ((points: Point[], chart: Chart) AnimationProps); }各 Props 的作用与默认值汇总如下属性类型默认值说明recordsArrayRecordItem-标注位置的数据项或比例值支持特殊值见下方说明contentstring \| number-文本内容offsetXnumber \| string0x 轴偏移量offsetYnumber \| string0y 轴偏移量styleTextStyleProps \| Function-文本样式支持对象或函数形式animationAnimationProps \| Function-动画配置详见 动画文档此外由于 TextGuide 继承自GuideProps它还支持onClick点击事件回调、precise精确标注开关等能力这些会在下文结合源码展开。records 特殊值用语义字符串定位records的值可以使用特殊字符串来表示位置无需手动计算具体数值值含义对应位置min最小值0max最大值1median中位值0.550%50% 位置0.5100%100% 位置1.0示例// 在每个 x 轴位置标注 y 轴最小值 {data.map((item) ( TextGuide records{[{ genre: item.genre, sold: min }]} contentMin / ))} // 标注 y 轴 50% 位置 {data.map((item) ( TextGuide records{[{ genre: item.genre, sold: 50% }]} content50% / ))}特殊值是如何被解析的这些特殊字符串的解析逻辑位于withGuide的parseReplaceStr方法见 withGuide.tsxmin→0、max→1、median→0.5由内部的replaceMap直接映射以%结尾且前缀为合法数字的字符串如50%会去掉%后除以 100得到0.5其余普通值则交给对应scale.scale(value)完成归一化。归一化得到的{ x, y }再经过coord.convertPoint转换为画布上的实际像素坐标最终成为文本的基准点。也就是说records中的特殊值既可以出现在y字段如sold: min也可以出现在x字段如genre: min机制完全对称。style 属性对象形式与函数形式style支持两种形式对象形式静态样式所有标注共用一套样式。style{{ fill: #000, fontSize: 24px, textAlign: center }}函数形式动态样式根据位置或数据计算样式。函数会接收points坐标数组和chart图表实例两个参数style{(points) ({ fill: points[0].y 100 ? #f00 : #00f })}从 withGuide.tsx 的render实现可以看到函数形式的调用时机是style(points, chart)withGuide先完成坐标转换得到points再把它们连同chart实例一并传给样式函数。因此你既可以根据某个数据点的像素坐标points[0].y做判断也可以结合chart实例读取原始数据做更复杂的条件渲染。位置与对齐textAlign和textBaseline是控制文本相对于标注基准点points[0]对齐位置的关键属性textAlign- 控制文本相对于基准点 X 坐标的对齐方式textBaseline- 控制文本相对于基准点 Y 坐标的对齐方式例如textAlign: centertextBaseline: bottom表示文本中心线与基准点 X 坐标齐平、文本底线与基准点 Y 坐标齐平即文本位于基准点上方。文本对齐textAligntextAlign控制文本的哪条垂直参考线左边缘、中心线、右边缘与基准点 X 坐标对齐值说明start文本起始位置与基准点 X 坐标齐平默认从左到右时等于 leftcenter文本中心线与基准点 X 坐标齐平end文本结束位置与基准点 X 坐标齐平从左到右时等于 rightleft文本左边缘与基准点 X 坐标齐平right文本右边缘与基准点 X 坐标齐平文本基线对齐textBaselinetextBaseline控制文本的哪条水平参考线顶线、中线、底线、字母基线与基准点 Y 坐标对齐值说明top文本顶线与基准点 Y 坐标齐平middle文本中线与基准点 Y 坐标齐平默认bottom文本底线与基准点 Y 坐标齐平alphabetic字母基线与基准点 Y 坐标齐平hanging悬挂基线与基准点 Y 坐标齐平典型组合示例// 文本位于数据点上方底部紧贴 TextGuide records{[item]} content{item.sold} style{{ textAlign: center, textBaseline: bottom }} / // 文本中心与数据点重合 TextGuide records{[item]} content{item.sold} style{{ textAlign: center, textBaseline: middle }} / // 文本位于数据点下方顶部紧贴 TextGuide records{[item]} content{item.sold} style{{ textAlign: center, textBaseline: top }} /支持的完整样式属性清单见 Shape 属性文档。偏移量 offsetX / offsetY当文本需要与数据点错开一定距离时例如避免与柱状图形重叠可使用offsetX与offsetY进行平移。二者既支持纯数字逻辑像素也支持带单位的字符串如10pxTextGuide records{[item]} content{item.sold} offsetX{10} offsetY-10px style{{ textAlign: center, textBaseline: bottom }} /在 Text.tsx 的实现中偏移量会先经过context.px2hd(offsetX)/context.px2hd(offsetY)转换为当前设备像素比下的物理像素再与基准点坐标相加posX x offsetXNum、posY y offsetYNum。这意味着即使在高清屏如 2x、3x DPR上标注的偏移量也能保持一致观感。此外当points[0]不存在或其x、y为NaN时组件会直接返回null不渲染避免非法坐标导致的绘制异常。实战示例折线图数据点标注在折线图中records{[item]}的基准点points[0]就是折线图上该数据点的位置Canvas context{context} Chart data{data} Line xgenre ysold / {data.map((item) ( TextGuide records{[item]} content{item.sold} style{{ fill: #000, fontSize: 24px, textAlign: center, textBaseline: bottom, }} / ))} /Chart /Canvas仓库的 guide.test.tsx 中就有类似用例在Line图上为每个数据点叠加TextGuide并通过offsetY-40px、offsetX-30px让文本与数据点错开同时挂载onClick回调监听点击事件。使用特殊值标注Canvas context{context} Chart data{data} Interval xgenre ysold / {data.map((item) ( TextGuide records{[{ genre: item.genre, sold: min }]} content最小值 style{{ fill: red, fontSize: 20px, textAlign: center }} / ))} /Chart /Canvas使用偏移量TextGuide records{[item]} content{item.sold} offsetX{10} offsetY-10px style{{ textAlign: center, textBaseline: bottom }} /style 函数形式函数接收points坐标数组和chart图表实例参数TextGuide records{[item]} content{item.sold} style{(points, chart) ({ fill: item.sold 200 ? red : black, fontSize: item.sold 200 ? 28px : 20px, textAlign: center, })} /多标注组合使用多个map分别生成多个标注可以同时叠加不同语义的文本例如同时标注每个柱子的最小值和最大值Canvas context{context} Chart data{data} Interval xgenre ysold / {data.map((item) ( TextGuide records{[{ genre: item.genre, sold: min }]} contentMin style{{ fill: green, textAlign: center }} / ))} {data.map((item) ( TextGuide records{[{ genre: item.genre, sold: max }]} contentMax style{{ fill: red, textAlign: center }} / ))} /Chart /Canvas使用动画TextGuide records{[item]} content{item.sold} animation{{ appear: { duration: 600, easing: ease-in, property: [opacity], start: { opacity: 0 }, end: { opacity: 1 }, } }} /更多动画配置详见 动画文档。需要说明的是即使你不传animationText.tsx 内部也会通过deepMix合并一个默认的update动画easing: linear、duration: 450、property: [x, y]保证图表数据变化时标注能够平滑跟随基准点移动你传入的animation配置会与这个默认值深度合并因此可以只覆盖需要调整的字段。同时animation也支持函数形式withGuide会在渲染时调用animation(points, chart)动态生成动画配置。深入原理withGuide 的标注定位流程TextGuide 之所以能同时支持“按数据定位”“按特殊值定位”和“精确标注”关键在于它并不是直接渲染而是由withGuide高阶组件统一完成坐标解析。其核心流程见 withGuide.tsx如下解析每条 recordparsePoint(record)取出chart.getXScales()[0]与chart.getYScales()[0]只取第一个 x/y 比例尺分别对 record 的对应字段调用parseReplaceStr得到归一化坐标{ x, y }再交给coord.convertPoint转成画布坐标分类字段处理如果比例尺是分类scale.isCategory_numberic方法会先用scale.translate把分类字段值转换为序号确保定位准确渲染视图组件将转换后的points、主题theme、coord以及处理后的style/animation传入TextGuideView由视图组件最终绘制text图形节点事件与显隐withGuide用group包裹视图统一转发onClick事件同时支持visible属性为false时整组标注不渲染。precise 精确标注模式在adjust.type dodge分组柱状图等场景下普通定位方式可能只能落到分组的中心位置。此时可以给 TextGuide 加上precise属性withGuide会走一条专门的路径调用adjust.adjust.getPositionInfo结合颜色比例尺getColorScales()[0]与dodge的 margin 信息计算出该数据项在分组内的精确位置。仓库的 preciseGuide.test.tsx 就验证了在带dodge调整的Interval图上使用precise为每个柱子精确标注数值的效果。主题与默认样式TextGuide 的样式默认值来自context.theme.guide即 theme.ts 中的guide主题配置在 Text.tsx 中通过deepMix({ ...theme.text }, props)将主题默认值与传入 props 合并用户传入的style、offsetX等会覆盖主题默认值未指定的字段则回退到主题默认。这也意味着你可以在项目级主题中统一调整所有文本标注的默认颜色、字号与偏移。总结TextGuide 是 F2 中进行图表文本标注的主力组件通过records含min/max/median/百分比等特殊值确定位置通过style的对象或函数形式控制外观通过textAlign/textBaseline精确控制文本与基准点的对齐关系通过offsetX/offsetY微调偏移再配合animation、onClick、precise等能力可以覆盖从简单数据标签到复杂条件标注的绝大多数场景。理解其底层的withGuide解析流程与TextGuideView渲染实现将帮助你在实际项目中更高效地排查定位问题、定制标注行为。赞分享数据可视化前端【免费下载链接】F2An elegant, interactive and flexible charting library for mobile.项目地址https://gitcode.com/gh_mirrors/f2/F2点击查看免费下载相关推荐F2 TagGuide 标签标注组件完全指南用法、方向控制与精确定位原理F2 TagGuide 标签标注组件完全指南用法、方向控制与精确定位原理 TagGuide 是 F2 图表库中用于在数据点上绘制带箭头的标签标注Tag数据可视化前端CKEditor 5 文本对齐功能Text Alignment完全指南配置、源码原理与实战CKEditor 5 文本对齐功能Text Alignment完全指南配置、源码原理与实战 CKEditor 5 的文本对齐Text Alignment前端富文本UI组件ng-zorro-antd 表单标签文本对齐nzLabelAlign从 Demo 到源码的完整指南ng zorro antd 表单标签文本对齐nzLabelAlign从 Demo 到源码的完整指南 表单标签的对齐方式直接决定数据录入界面的视觉秩序标签UI组件前端上一篇Rusted PackFile Manager终极指南从环境配置到高级模组开发的完整避坑方案下一篇Honey Select 2游戏体验升级全攻略从普通玩家到高手的蜕变之旅创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考