Guide

Last updated 2 months ago

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.

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

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
}

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

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

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

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.

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

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();