Guide

Line	Text	Rect	Point	Tag	RegionFilter	Arc	Html
​​​​	​​​​	​​​​	​​​​	​​​​	​​​​	​​​​	​​​​

Guide component is used for annotations of chart. In F2, annotations are driven by data. Being driven by data means that the aesthetics of an annotation object are linked to variables in a dataset in a similar manner to that for a graphic. A text annotation, for example, might be positioned according to a value of a variable, or its color might be determined by a variable value, or its content might be determined by statistical parameters.

We provide 8 types of guide components, we will introduce them and their usage below.

How to Register Guide Plugin

F2 has modular structure provides best tree-shaking results and package size optimization.

If you just import F2 from '@antv/f2', then it has included 6 types Guide by default, they are Arc, Html, Line, Rect, Tag and Text. But if you want a better package size optimization, you can register manually:

• If you want to use all types of guide, you can:

const F2 = require('@antv/f2/lib/core');

// Step 1: require guide components
require('@antv/f2/lib/component/guide'); // require all guide components

// Step 2: require guide plugin
const Guide = require('@antv/f2/lib/plugin/guide');

// Step 3：register Guide plugin
F2.Chart.plugins.register(Guide); // Global registeration here, for all chart instances.

// Or just for current chart instance
const chart = new F2.Chart({
  id: 'canvas',
  plugins: Guide
});

• or you just want to use several types, you can:

const F2 = require('@antv/f2/lib/core');

// All guide types are listed below, and you can choose one according to your needs.
// Guide.Arc
require('@antv/f2/lib/component/guide/arc');

// Guide.Html
require('@antv/f2/lib/component/guide/html');

// Guide.Text
require('@antv/f2/lib/component/guide/text');

// Guide.Rect
require('@antv/f2/lib/component/guide/rect');

// Guide.Line
require('@antv/f2/lib/component/guide/line');

// Guide.Point
require('@antv/f2/lib/component/guide/point');

// Guide.Tag
require('@antv/f2/lib/component/guide/tag');

// Guide.RegionFilter
require('@antv/f2/lib/component/guide/region-filter');

// Step 2: require guide plugin
const Guide = require('@antv/f2/lib/plugin/guide');

// Step 3：register Guide plugin
F2.Chart.plugins.register(Guide); // Global registeration here, for all chart instances.

// Or just for current chart instance
const chart = new F2.Chart({
  id: 'canvas',
  plugins: Guide
});

Line

Example Usage

chart.guide().line({
  start: [ 'Feb.', 100 ],
  end: [ 'Aug.', 300 ],
  style: {
    lineWidth: 2,
    stroke: 'red'
  }
});

Properties

The global options for the chart guide line is defined in F2.Global.guide.line.

Name	Type	Default	Description
top	Boolean	true	Wether draw the guide line to the top layer of the canvas, defaults to true.
start	Array/Function		Starting position of the guide line. Detail usage see here.
end	Array/Function		Ending point of guide line, use the same way as start.
style	Object		Style for guide line, see Canvas(todo) for more details.

Demo: https://antv.alipay.com/zh-cn/f2/3.x/demo/component/guide-line.html

Text

Example Usage

chart.guide().text({
  position: ['2018-05-19', 'max'],
  content: 'weekend',
  style: {
    textAlign: 'start',
    textBaseline: 'top',
    fill: '#fa541c'
  },
  offsetX: -8
});

Properties

The global options for the chart guide text is defined in F2.Global.guide.text.

Name	Type	Default	Description
top	Boolean	true	Wether draw the guide text to the top layer of the canvas, defaults to true
position	Array/Function		Position of the guide text, see detail usage here.
content	String		text content
style	Object		text style
offsetX	Number	0	offset of guide text in x-axis
offsetY	Number	0	offset of guide text in y-axis

Demo: https://antv.alipay.com/zh-cn/f2/3.x/demo/guide/text.html

Tag

Example Usage

chart.guide().tag({
  position: [6, 2800],
  content: '最高点',
  offsetY: -5,
  direct: 'tl'
});

Properties

The global options for the chart guide tag is defined in F2.Global.guide.tag.

Name	Type	Default	Description
top	Boolean	true	Wether draw the guide tag to the top layer of the canvas, defaults to true
position	Array/Function		Position of the guide tag, see detail usage here.
content	String		tag content, if you want a text wrapping, just write '\n' in the text, such as 'maximum \n200'.
direct	String	'tl'	direction of tag, if autoAdjust is true,when the tag is outside the chart [plot](todo) area, the direct will be automatically corrected and guaranteed to be in the plot area.
autoAdjust	Boolean	true	If value is true, when the tag is outside the chart plot area, the direct will be automatically corrected and guaranteed to be in the plot area.
side	Number	4	The length of tag arrow.
style	Object		text style
offsetX	Number	0	offset of guide tag in x-axis
offsetY	Number	0	offset of guide tag in y-axis
background	Object		The background style of guide tag. See below.
textStyle	Object		style for tag's label.
withPoint	Boolean	true	wether to draw a point at the dataset.
pointStyle	Object		If the withPoint is true, configure the style for the point shape.

direct

backgroud configuration

  background: {
    padding: 20, //  padding of the tag, just use as css padding
    radius: 5, // the box-radius of tag
    fill: '#1890FF', // the background color of tag
  }

Demo: https://antv.alipay.com/zh-cn/f2/3.x/demo/component/guide-tag.html

Rect

Example Usage

chart.guide().rect({
  start: ['2018-05-19', 'max'],
  end: ['2018-05-20', 'min'],
  style: {
    fillOpacity: 0.1,
    fill: '#fa541c',
    lineWidth: 1,
    stroke: '#ccc'
  }
});

Properties

The global options for the chart guide rect is defined in F2.Global.guide.rect.

Name	Type	Default	Description
top	Boolean	false	Wether draw the guide rect to the top layer of the canvas, defaults to false.
start	Array/Function		Starting position of the guide tag, see detail usage here.
end	Array/Function		Ending position of the guide tag, see detail usage here.
style	Object		rect box style

Demo: https://antv.alipay.com/zh-cn/f2/3.x/demo/component/guide-rect.html

Point

Example Usage

chart.guide().point({
  position: ['2018-05-19', 'max'],
  style: {
    fill: '#1890FF',
    r: 3,
    lineWidth: 1,
    stroke: '#fff'
  },
  offsetX: 5，
  offsetY: 5
});

Properties

The global options for the chart guide point is defined in F2.Global.guide.point.

Name	Type	Default	Description
top	Boolean	true	Wether draw the guide point to the top layer of the canvas, defaults to true
position	Array/Function		Position of the guide point, see detail usage here.
style	Object		point style
offsetX	Number	0	offset of guide point in x-axis
offsetY	Number	0	offset of guide point in y-axis

Demo: https://antv.alipay.com/zh-cn/f2/3.x/demo/component/guide-point.html

Arc

Works in polar coordinate.

Example Usage

chart.guide().arc({
  start: [0, 0],
  end: [1, 99.98],
  top: false,
  style: {
    lineWidth: 15,
    stroke: '#ccc'
  }
}); // draw a cricle

Properties

The global options for the chart guide arc is defined in F2.Global.guide.arc.

Name	Type	Default	Description
top	Boolean	true	Wether draw the guide arc to the top layer of the canvas, defaults to true
start	Array/Function		starting position of the guide arc, see detail usage here.
end	Array/Function		ending position of the guide arc, see detail usage here.
style	Object		arc style

Demo: https://antv.alipay.com/zh-cn/f2/3.x/demo/component/guide-arc.html

RegionFilter

Example Usage

chart.guide().regionFilter({
  start: ['min', 95],
  end: ['max', 'max'],
  color: '#FF4D4F'
});

Properties

The global options for the chart guide regionFilter is defined in F2.Global.guide.regionFilter.

Name	Type	Default	Description
start	Array/Function		starting position of the guide regionFilter, see detail usage here.
end	Array/Function		ending position of the guide regionFilter, see detail usage here.
color	String		the filled color for the filtered region.
style	Object		additional style settings for the shape in the filter region.

Demo: https://antv.alipay.com/zh-cn/f2/3.x/demo/component/guide-regionFilter.html

Html

Example Usage

chart.guide().html({
  position: ['Samsung', 21.2],
  html: '<div style="background: #1890ff;font-size: 10px;color: #fff;padding: 2px;text-align: center;border-radius: 2px;">21.2%</div>',
  alignX: 'center',
  alignY: 'bottom',
  offsetY: -8
});

Properties

The global options for the chart guide html is defined in F2.Global.guide.html.

Name	Type	Default	Description
position	Array/Function		position of the guide html, see detail usage here.
html	String		html code that needs to be displayed
alignX	String	'center'	alignment of html in horizontal direction, can be set to: 'left', 'center', 'right', defaults to 'center'
alignY	String	'middle'	alignment of html in vertical direction, can be set to: 'top', 'middle', 'bottom', defaults to 'middle'
offsetX	Number	0	offset of the guide html in x-axis
offsetY	Number	0	offset of the guide html in y-axis

Demo: https://antv.alipay.com/zh-cn/f2/3.x/demo/component/guide-html.html

start , end , position usage

The values of the three parameters passed in can be following type:

• Array，the value in the array can be the data in dataset, or can be percentage, or keyword(they are 'max', 'min', 'median')

// this is the dataset of chart
const data = [
  { name: 'a', value: 300 },
  { name: 'b', value: 250 },
  { name: 'c', value: 180 }
];

chart.guide().line({
  start: [ 'a', 300 ],
  end: [ 'c', 180 ]  
});

chart.guide().text({
  position: [ '50%', 'max' ],
  content: 'Hi'
});

• Function: Callback can used to dynamically locate the position. It is often used in the scenario where position of the guide element changes according to the change of the data. Detail demo and code here.

chart.guide().line({
   /**
   * @param  {Scale} xScale scale of x-axis
   * @param {Array} yScales scale array of y-axis
   * @return {Array} return value must be an array
   */
  start(xScale, yScales) {
    return []; // position information
  },
  /**
   * ending point of guide line
   * @param  {Scale} xScale scale of x-axis
   * @param {Array} yScales scale array of y-axis
   * @return {Array} return value must be an array
   */
  end(xScale, yScales) {
    return []; // position information
  }
});

Repaint a guide component

guide.repaint()

const guide = chart.guide().text({
  position: [ 'min', 'median' ],
  content: '12345'
});

chart.render();

// update guide configuration
guide.position = [ '50%', '50%' ];
guide.content = 12;
guide.repaint();

How to clear guides

chart.guide().clear();