# Guide | Line | Text | Rect | Point | Tag | RegionFilter | Arc | Html | | :----------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ​​![](https://cdn.nlark.com/yuque/0/2018/png/98090/1533349223352-4c1df992-fbe1-4c8c-9d6f-73ed99ef2df7.png)​​ | ​​![](https://cdn.nlark.com/yuque/0/2018/png/98090/1533349238531-321b1246-2453-46a2-bccc-64f6e4dcf65f.png)​​ | ​​![](https://cdn.nlark.com/yuque/0/2018/png/98090/1533349260616-82d0a341-2e1b-4b8e-8b46-ed0bb604c3b8.png)​​ | ​​![](https://cdn.nlark.com/yuque/0/2018/png/98090/1533349370834-d9c41109-9613-4c5e-a862-f3a1f9ebf95c.png)​​ | ​​![](https://cdn.nlark.com/yuque/0/2018/png/98090/1533349392502-fe41adeb-3d44-4db2-8539-06a65dd39521.png)​​ | ​​![](https://cdn.nlark.com/yuque/0/2018/png/98090/1533349418575-50080410-b295-4cb7-b42c-e488b3a8ba9f.png)​​ | ​​![](https://firebasestorage.googleapis.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LHpLji2HmId7esWiRt3%2Fuploads%2F35Fz8mHagKlLnAfuchiH%2Ffile.png?alt=media)​​ | ​​![](https://firebasestorage.googleapis.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LHpLji2HmId7esWiRt3%2Fuploads%2FVzxp5stSr19hIl3sT7kS%2Ffile.png?alt=media)​​ | 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: ```javascript 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: ```javascript 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 ```javascript 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](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `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: ### Text #### Example Usage ```javascript 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](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `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: ### Tag #### Example Usage ```javascript 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](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `content` | String | | tag content, if you want a text wrapping, just write '\n' in the text, such as 'maximum \n200'. | | `direct` | String | 'tl' | [direction](https://antv.gitbook.io/f2/api/guide#direct) 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](https://antv.gitbook.io/f2/~/edit/drafts/-LP3rGQNp1gYGlOMY4Cr/api/chart#appendpadding) 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](https://antv.gitbook.io/f2/api/guide#backgroud-configuration). | | `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` ![](https://2543643007-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LHpLji2HmId7esWiRt3%2F-LJS4sidvKnAi07rKtst%2F-LJS5-05YP6xqK5Ih8Re%2Fimage.png?alt=media\&token=55509582-956e-416d-ad12-350c342078a2) #### `backgroud` configuration ```javascript 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 } ``` ![](https://2543643007-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LHpLji2HmId7esWiRt3%2F-LJRnj93P6--NQPIGQ_t%2F-LJRsPOUQt_cNcCMCmuT%2Fimage.png?alt=media\&token=b310dcdf-d075-414d-8945-c6c04ee828ad) #### Demo: ### Rect #### Example Usage ```javascript 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](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `end` | Array/Function | | Ending position of the guide tag, see detail usage [here](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `style` | Object | | rect box style | #### Demo: ### Point #### Example Usage ```javascript 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](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `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: ### Arc **Works in polar coordinate.** #### Example Usage ```javascript 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](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `end` | Array/Function | | ending position of the guide arc, see detail usage [here](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `style` | Object | | arc style | #### Demo: ### RegionFilter #### Example Usage ```javascript 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](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `end` | Array/Function | | ending position of the guide regionFilter, see detail usage [here](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `color` | String | | the filled color for the filtered region. | | `style` | Object | | additional style settings for the shape in the filter region. | #### Demo: ### Html #### Example Usage ```javascript chart.guide().html({ position: ['Samsung', 21.2], html: '
21.2%
', 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](https://antv.gitbook.io/f2/api/guide#start-end-position-usage). | | `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: #### `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') ```javascript // 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](https://antv.alipay.com/zh-cn/f2/3.x/demo/other/multiple-y.html). ```javascript 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()` ```javascript 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 ```javascript chart.guide().clear(); ```