Dygraphs 中的注释 Annotations

携手创作，共同成长！这是我参与「掘金日新计划 · 8 月更文挑战」的第11天，点击查看活动详情

Dygraphs 让我们在图表上添加单独的注释（标记）。这些注释（标记）可以是简单的文字或者一个 icon，在图表上面展示出来，可以添加一个长的描述信息，当我们将鼠标在其上方悬停，长描述就会出现。

案例：道琼斯工业平均指数

添加注释

下面有两个方法，用来添加，移除和修改注释。

方法	描述
setAnnotations(array)	设置当前要展示的注释列表。这会覆盖现有注释并重绘 `dygraph`
annotations()	返回当前展示注释的数组

调用 dygraph.setAnnotations(dygraph.annotations()) 是无操作的：仅仅是刷新了图表。

假设我们有一个简单的图表，并想添加注释。如下：

Annotations 就是 Javascript 字典。series x 字段是必须的：它们表明注释应该依附在哪个点上。如果指定 shortText，shortText 将出现在注释 "flag" 上。如果不指定 shortText，我们可以指定 icon 替代，来显示小图。text 参数是指定鼠标悬停的文字。如果你高亮注释，并且将鼠标停留在该注释，text 字段的文字将出现。

修改注释

移除或者修改存在的注释，我们可以调用 annotations() 方法去获取注释的数组。更改这个数组，然后将其放回 setAnnotations(array) 参数中。比如，下面代码展示的是删除第二个注释，并且更改了第一个注释的 series 字段：

var annotations = g.annotations();
annotations.splice(1,1);  // 移除第二个注释
annotations[0].series = "Series 2";
g.setAnnotations(annotations);  // 重绘
复制代码

注释和数据源

当你将 URL 作为数据源传递给 dygraphs 时，它必须在绘制图表前发出数据请求。这就意味着在我们调用 new Dygraph 后，图表数据上不可用，因此对 g.setAnnotations 的调用将失败。解决这个问题的最好方法就是使用 ready() 方法：

g = new Dygraph(div, "path/to/data.csv");
g.ready(function() {
  // 当 data.csv 返回数据调用，并绘制图表
  g.setAnnotations([
    …
  ]);
});
复制代码

注释属性参考

这些属性可以在单个注释中设置在字典集里面。

属性	描述
series	必须，表明注释点是属于哪条线
x	必须，指定点的 `x` 轴的值
shortText	显示在注释的标记中的文本
text	注释的长文本描述，当鼠标悬停在注释上展示
icon	可以替代 `shortText` 来展示图标。如果你指定 `icon`，比必须指定 `width` 和 `height` 属性
width	注释标记或图标的宽度（单位 `px`）
height	注释标记或图标的高度（单位 `px`）
cssClass	`CSS` 类用来修饰注释
tickHeight	将点连接到标志或者图标的刻度线高度（单位 `px`）
tickWidth	将点连接到标志或者图标的刻度线宽度（单位 `px`）
tickColor	将点连接到标志或者图标的刻度线颜色
attachAtBottom	布尔值，如果是 `true`，将注释点依附在 `x` 轴，而不是依附在实际的点
clickHandler	见下介绍
mouseOverHandler	见下介绍
mouseOutHandler	见下介绍
dblClickHandler	见下介绍

注释事件处理程序

Dygraphs 允许我们将事件处理程序附加到我们的注释中。这些可以全局指定（对于所有注释）或基于每个注释：

每个注释	全局指定
clickHandler	annotationClickHandler
mouseOverHandler	annotationMouseOverHandler
mouseOutHandler	annotationMouseOutHandler
dblClickHandler	annotationDblClickHandler

上面这些事件程序传递相同的参数：

g.updateOptions( {
  annotationClickHandler: function(annotation, point, dygraph, event) {
    // 获取/修改 annotation.series, annotation.x, ...
  }
}); 
复制代码

annotation：注释的相关信息
point：注释点的相关信息
dygraph：我们新建的 Dygraph 对象信息
event：注释点的事件信息

英文版请看 annotations

往期精彩推荐

如果读者觉得文章还可以，不防一键三连：关注➕点赞➕收藏