d3-annotation API完全参考：掌握注释配置的终极指南

d3-annotation API完全参考：掌握注释配置的终极指南

【免费下载链接】d3-annotationUse d3-annotation with built-in annotation types, or extend it to make custom annotations. It is made for d3-v4 in SVG.项目地址: https://gitcode.com/gh_mirrors/d3/d3-annotation

d3-annotation是一个基于d3-v4的SVG注释工具库，提供了丰富的内置注释类型和灵活的自定义扩展能力，帮助开发者为数据可视化添加专业注释。本指南将全面解析其API配置选项，助你轻松实现各类注释效果。

快速入门：安装与基础配置

安装方式

d3-annotation支持多种安装方式，可根据项目需求选择：

• 直接引入：下载未压缩版或压缩版后通过<script>标签引入
• CDN：使用cdnjs提供的CDN链接
• NPM：通过包管理器安装

  npm i d3-svg-annotation -S

基础使用示例

创建注释的核心步骤包括初始化注释对象、配置属性和绑定到SVG元素：

const annotations = d3.annotation() .annotations([ { x: 100, y: 200, // 主体位置 dx: 50, dy: -30, // 注释偏移 note: { title: "重要数据点", label: "此处数据异常增长" } } ]); d3.select("svg") .append("g") .call(annotations);

图1：d3-annotation提供的四种基础注释类型，包括标签、带箭头连接器、曲线连接器和圆形标注

核心API详解

注释数据结构

每个注释对象包含以下核心属性：

• id：注释唯一标识，用于筛选和解析
• x,y：主体位置坐标（像素）
• dx, dy：注释偏移量（像素）
• nx, ny：注释绝对位置（像素，非偏移）
• type：注释类型（如d3.annotationLabel）
• disable：禁用部分（数组，可选值：'connector'|'subject'|'note'）
• color：注释颜色（v2.0+支持）

图2：注释配置的JSON结构示意图

主要配置方法

annotations([objects])

设置或获取注释数组。每个对象包含注释的完整配置：

annotation.annotations([ { id: "annotation-1", x: 150, y: 300, note: { title: "销售峰值", label: "2023年Q4达到年度最高", wrap: 150, // 文本换行宽度 padding: 10 // 内边距 }, connector: { type: "curve", // 曲线连接器 end: "arrow" // 箭头结尾 } } ]);

accessors({x: function, y: function})

设置数据访问器函数，将注释数据映射到坐标：

// 时间序列数据示例 const parseTime = d3.timeParse("%d-%b-%y"); annotation.accessors({ x: d => xScale(parseTime(d.date)), y: d => yScale(d.value) });

对应地，accessorsInverse()方法提供反向映射，将坐标转换回原始数据。

editMode(boolean)

启用编辑模式，为注释添加可拖动的控制点：

// 切换编辑模式 annotation.editMode(true); // 需调用update应用更改 annotation.update();

编辑模式下可通过.handle选择器自定义控制点样式。

type(d3annotationType)

设置默认注释类型，内置类型包括：

• d3.annotationLabel：基础标签注释
• d3.annotationCalloutCircle：圆形标注
• d3.annotationCalloutRect：矩形标注
• d3.annotationXYThreshold：阈值标注

图3：d3-annotation的类结构层次，展示了注释的组成部分和CSS类命名

高级配置选项

注释内容定制

note对象支持丰富的文本配置：

note: { title: "标题文本", label: "详细说明文本", align: "left", // 对齐方式 orientation: "top", // 方向 lineType: "vertical", // 行类型 wrap: 120, // 文本换行宽度 wrapSplitter: /\n/, // 换行分隔符（v2.1.0+） bgPadding: {top: 5, bottom: 5, left: 10, right: 10} // 背景内边距（v2.3.0+） }

连接器样式配置

connector对象控制连接线样式：

connector: { type: "elbow", // 类型：line|elbow|curve end: "dot", // 结尾样式：none|dot|arrow endScale: 1.5 // 结尾缩放比例（v2.1.0+） }

事件处理

通过on()方法绑定事件处理器：

annotation.on("subjectclick", (event, d) => { console.log("点击了主体:", d); }) .on("dragend", (event, d) => { console.log("拖动结束:", d.x, d.y); });

支持的事件包括：subjectover、subjectout、subjectclick、connectorover、connectorout、connectorclick、noteover、noteout、noteclick、dragend、dragstart。

响应式与动态更新

d3-annotation提供了多种更新方法以适应动态数据变化：

• update()：重绘所有注释，反映配置更改
• updateText()：仅更新文本内容和换行设置
• updatedAccessors()：使用更新后的访问器函数重绘注释

图4：响应式注释在不同尺寸下的自动调整效果，支持拖动调整位置

自定义扩展

d3-annotation的架构设计支持创建自定义注释类型。通过继承基础类并实现绘图方法：

// 自定义注释类型示例 class CustomAnnotation extends d3.annotationLabel { static className = "custom-annotation"; drawSubject(context) { // 自定义主体绘制逻辑 return context.svg.append("path") .attr("d", d3.symbol().type(d3.symbolStar)) .attr("transform", `translate(${context.annotation.x},${context.annotation.y})`); } }

核心绘制方法包括：

• drawNote(context)：绘制注释框
• drawNoteContent(context)：绘制注释内容
• drawConnector(context)：绘制连接线
• drawSubject(context)：绘制主体标记

更多扩展细节可参考源码实现。

实用工具方法

• json()：在控制台输出当前注释配置并复制到剪贴板
• collection()：获取注释集合实例
• textWrap()：设置全局文本换行宽度
• notePadding()：设置全局注释内边距
• disable()：禁用指定注释部分

总结

d3-annotation提供了一套完整的API，从基础注释到高级自定义，满足各类数据可视化注释需求。通过灵活配置注释对象、连接器和主体样式，结合响应式更新和事件处理，可以创建交互丰富的注释系统。无论是简单的标签标注还是复杂的自定义注释类型，d3-annotation都能帮助开发者轻松实现专业的数据可视化注释效果。

【免费下载链接】d3-annotationUse d3-annotation with built-in annotation types, or extend it to make custom annotations. It is made for d3-v4 in SVG.项目地址: https://gitcode.com/gh_mirrors/d3/d3-annotation