logo

F2

  • 教程
  • 组件API
  • 图表示例
  • 所有产品antv logo arrow
  • 5.10.0
  • 顶层 API - F2
  • 组件 - Component
  • 画布 - Canvas
  • 时间轴 - Timeline
  • 图表 - Chart
    • 图表 - Chart
    • 几何标记 - Geometry
    • 线 - Line
    • 区间 - Interval
    • 点 - Point
    • 面积 - Area
    • K 线图 - Candlestick
    • 坐标轴 - Axis
    • 图例 - Legend
    • 提示 - tooltip
    • 饼图标签 - PieLabel
    • 标注 - Guide
      • 标签标注 - TagGuide
      • 点标注 - PointGuide
      • 辅助线标注 - LineGuide
      • 矩形标注 - RectGuide
      • 图片标注 - ImageGuide
      • 文本标注 - TextGuide
      • 标注 - Guide
    • 滚动条 - ScrollBar
    • 放大镜 - Magnifier
  • 仪表盘 - Gauge
  • 旭日图 - Sunburst
  • 矩形树图 - Treemap

标签标注 - TagGuide

上一篇
饼图标签 - PieLabel
下一篇
点标注 - PointGuide

资源

Ant Design
Galacea Effects
Umi-React 应用开发框架
Dumi-组件/文档研发工具
ahooks-React Hooks 库
WeaveFox-前端智能研发

社区

体验科技专栏
seeconfSEE Conf-蚂蚁体验科技大会
weavefoxWeaveFox-智能研发技术社区

帮助

GitHub
StackOverflow

more products更多产品

Ant DesignAnt Design-企业级 UI 设计语言
yuque语雀-知识创作与分享工具
EggEgg-企业级 Node 开发框架
kitchenKitchen-Sketch 工具集
GalaceanGalacean-互动图形解决方案
weavefoxWeaveFox-前端智能研发
© Copyright 2026 Ant Group Co., Ltd..备案号:京ICP备15032932号-38

Loading...

Usage 用法

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 x="genre" y="sold" />
<TagGuide
records={[{ genre: 'Sports', sold: 350 }]}
content="最高销量"
direct="tr"
background={{ fill: '#fff' }}
textStyle={{ fill: '#000' }}
/>
</Chart>
</Canvas>

TypeScript 类型定义

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?: Partial<RectStyleProps>;
/** 文本样式,支持 text 组件属性 */
textStyle?: Partial<TextStyleProps>;
/** 是否精确定位(用于分组柱状图),详见下方说明 */
precise?: boolean;
/** 是否显示标注 */
visible?: boolean;
/** 点击事件回调 */
onClick?: (ev: Event) => void;
/** 动画配置,详见 [动画文档](/tutorial/animation) */
animation?: AnimationProps | ((points: Point[], chart: Chart) => AnimationProps);
}

Props

属性类型默认值说明
recordsArray<RecordItem>-标注位置的数据项或比例值,支持特殊值(见下方说明)
contentstring-文本内容
offsetXnumber | string0x 轴偏移量
offsetYnumber | string0y 轴偏移量
direct'tl' | 'tc' | 'tr' | 'cl' | 'cr' | 'bl' | 'bc' | 'br''tl'箭头方向(见下方说明)
sidestring | number'8px'箭头的边长
autoAdjustbooleantrue是否自动调整标签方向,避免超出画布
backgroundRectStyleProps-背景容器样式,支持 rect 组件属性(见下方说明)
textStyleTextStyleProps-文本样式,支持 text 组件属性
precisebooleanfalse是否精确定位,用于分组柱状图中精确定位到每个子柱子(见下方说明)
visiblebooleantrue是否显示标注
onClickFunction-点击事件回调
animationAnimationProps | Function-动画配置,详见 动画文档

records 特殊值

records 的值可以使用特殊字符串来表示位置,无需计算具体数值:

值含义对应位置
'min'最小值0
'max'最大值1
'median'中位值0.5
'50%'50% 位置0.5
'100%'100% 位置1.0

direct 方向说明

direct 属性控制标签相对于标注点的方向:

值含义图示
tltop-left,标签在左上方↖
tctop-center,标签在上方居中↑
trtop-right,标签在右上方↗
clcenter-left,标签在左侧居中←
crcenter-right,标签在右侧居中→
blbottom-left,标签在左下方↙
bcbottom-center,标签在下方居中↓
brbottom-right,标签在右下方↘

background 属性

background 用于设置标签背景容器的样式,支持 rect 组件属性:

background={{
fill: '#fff',
stroke: '#1677FF',
strokeWidth: 2,
radius: '8px',
padding: ['8px', '12px'],
}}

支持的属性见 Rect 属性文档。

precise 精确定位模式

在分组柱状图中使用 precise 属性,可以让标注精确定位到每个子柱子的中心位置,而不是分组位置:

<Canvas context={context}>
<Chart data={data}>
<Interval x="月份" y="销量" color="城市" adjust={{ type: 'dodge' }} />
{data.map((item) => (
<TagGuide
records={[item]}
precise
content={`${item.销量}`}
direct="tc"
/>
))}
</Chart>
</Canvas>

适用场景:当使用 adjust="dodge" 分组调整时,设置 precise={true} 可确保标注准确对应每个子柱子。

默认样式

{
container: {
fill: '#1677FF',
radius: '4px',
padding: ['4px', '8px'],
},
text: {
fontSize: '22px',
fill: '#fff',
},
arrow: {
fill: '#1677FF',
},
}

用法示例

基础用法

<Canvas context={context}>
<Chart data={data}>
<Interval x="genre" y="sold" />
<TagGuide
records={[{ genre: 'Shooter', sold: 350 }]}
content="最高销量"
direct="tr"
/>
</Chart>
</Canvas>;

自定义样式

<TagGuide
records={[{ genre: 'Shooter', sold: 350 }]}
content="最高销量"
direct="tl"
background={{
fill: '#fff',
stroke: '#1677FF',
strokeWidth: 2,
radius: '8px',
padding: ['8px', '12px'],
}}
textStyle={{
fill: '#1677FF',
fontSize: '24px',
fontWeight: 'bold',
}}
/>

不同方向标注

{/* 右上方向 */}
<TagGuide records={[item]} content="右上" direct="tr" />
{/* 下方居中 */}
<TagGuide records={[item]} content="下方" direct="bc" />
{/* 左侧居中 */}
<TagGuide records={[item]} content="左侧" direct="cl" />

使用特殊值

{/* 标注最大值 */}
<TagGuide
records={[{ genre: 'Sports', sold: 'max' }]}
content="最大值"
direct="tc"
background={{ fill: 'green' }}
/>

禁用自动调整

<TagGuide
records={[item]}
content="固定方向"
direct="tl"
autoAdjust={false}
/>

自定义箭头大小

<TagGuide
records={[item]}
content="大箭头"
direct="tr"
side="12px"
/>

多标签组合

使用多个 map 分别生成多个标签:

<Canvas context={context}>
<Chart data={data}>
<Interval x="genre" y="sold" />
{data.map((item) => (
<TagGuide
records={[{ genre: item.genre, sold: 'max' }]}
content="Max"
direct="tc"
background={{ fill: 'red' }}
/>
))}
{data.map((item) => (
<TagGuide
records={[{ genre: item.genre, sold: 'min' }]}
content="Min"
direct="bc"
background={{ fill: 'green' }}
/>
))}
</Chart>
</Canvas>;

配合 offset 使用

<TagGuide
records={[item]}
content="偏移标签"
direct="tr"
offsetX={20}
offsetY={-30}
/>

使用动画

<TagGuide
records={[item]}
content="标签"
direct="tr"
animation={{
appear: {
duration: 450,
easing: 'linear',
}
}}
/>

更多动画配置详见 动画文档。

分组柱状图精确定位

在分组柱状图中使用 precise 属性,让标注精确定位到每个子柱子:

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="月均温度" color="name" 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),负数标签向下(bc)
  • background 函数让标签背景色与对应柱子颜色一致

点击事件

<TagGuide
records={[item]}
content="点击我"
direct="tr"
onClick={(e) => {
console.log('标签被点击', e);
}}
/>

根据条件控制显示

通过 visible 属性动态控制标签显示:

{data.map((item) => (
<TagGuide
records={[item]}
content={item.sold}
direct="tc"
visible={item.sold > 200}
/>
))}