Skip to content

Latest commit

 

History

History
199 lines (166 loc) · 13.5 KB

line.md

File metadata and controls

199 lines (166 loc) · 13.5 KB
Raw

Line Annotations

Line annotations are used to draw lines on the chart area. This can be useful for highlighting information such as a threshold.

/* <block:options:0> */
const options = {
  plugins: {
    autocolors: false,
    annotation: {
      annotations: {
        line1: {
          type: 'line',
          yMin: 60,
          yMax: 60,
          borderColor: 'rgb(255, 99, 132)',
          borderWidth: 2,
        }
      }
    }
  }
};
/* </block:options> */

/* <block:config:1> */
const config = {
  type: 'line',
  data: {
    labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
    datasets: [{
      label: 'My First Dataset',
      data: [65, 59, 80, 81, 56, 55, 40],
      fill: false,
      borderColor: 'rgb(75, 192, 192)',
      tension: 0.1
    }]
  },
  options
};
/* </block:config> */

module.exports = {
  config
};

Configuration

The following options are available for line annotations. All of these options can be .

Name Type Scriptable Default
adjustScaleRange boolean Yes true
arrowHeads {start: object, end:object} Yes
borderColor Color Yes options.color
borderDash number[] Yes []
borderDashOffset number Yes 0
borderShadowColor Color Yes 'transparent'
borderWidth number Yes 2
display boolean Yes true
drawTime string Yes 'afterDatasetsDraw'
endValue number Yes undefined
label object Yes
scaleID string Yes undefined
shadowBlur number Yes 0
shadowOffsetX number Yes 0
shadowOffsetY number Yes 0
value number Yes undefined
xMax number | string Yes undefined
xMin number | string Yes undefined
xScaleID string Yes 'x'
yMax number | string Yes undefined
yMin number | string Yes undefined
yScaleID string Yes 'y'

General

If one of the axes does not match an axis in the chart and the line behaviors are the following, depending how the line should be drawn:

  1. if scaleId is not resolved, the line will take the entire chart dimension, starting top-left vertex to bottom-right vertex of the chart
  2. if xScaleId is not resolved, the line will take the entire chart width
  3. if yScaleId is not resolved, the line will take the entire chart height

The 2 coordinates, start, end, are optional. If not specified, the line is expanded out to the edges in the respective direction. The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the line is expanded out to the edges in the respective direction.

Name Description
adjustScaleRange Should the scale range be adjusted if this annotation is out of range.
display Whether or not this annotation is visible.
drawTime See drawTime.

Positioning

The line can be positioned in two different ways. If scaleID is set, then value and endValue must also be set to indicate the endpoints of the line. The line will be perpendicular to the axis identified by scaleID.

If scaleID is unset, then xScaleID and yScaleID are used to draw a line from (xMin, yMin) to (xMax, yMax).

Name Description
endValue End two of the line when a single scale is specified.
scaleID ID of the scale in single scale mode. If unset, xScaleID and yScaleID are used.
value End one of the line when a single scale is specified.
xMax X coordinate of end two of the line in units along the x axis.
xMin X coordinate of end one of the line in units along the x axis.
xScaleID ID of the X scale to bind onto, default is 'x'.
yMax Y coordinate of end two of the line in units along the y axis.
yMin Y coordinate of end one of the line in units along the y axis.
yScaleID ID of the Y scale to bind onto, default is 'y'.

Styling

Name Description
borderColor Stroke color.
borderDash Length and spacing of dashes. See MDN.
borderDashOffset Offset for line dashes. See MDN.
borderShadowColor The color of shadow. See MDN.
borderWidth Stroke width.
shadowBlur The amount of blur applied to shadow. See MDN.
shadowOffsetX The distance that shadow will be offset horizontally. See MDN.
shadowOffsetY The distance that shadow will be offset vertically. See MDN.

Label

Namespace: options.annotations[annotationID].label, it defines options for the line annotation label.

All of these options can be Scriptable

Name Type Default Notes
backgroundColor Color 'rgba(0,0,0,0.8)' Background color of the label container.
backgroundShadowColor Color 'transparent' The color of shadow of the box where the label is located. See MDN.
borderCapStyle string 'butt' Cap style of the border line. See MDN.
borderColor Color black The border line color.
borderDash number[] [] Length and spacing of dashes. See MDN.
borderDashOffset number 0 Offset for border line dashes. See MDN.
borderJoinStyle string 'miter' Border line joint style. See MDN.
borderRadius number | object 6 Radius of label box corners in pixels.
borderShadowColor Color 'transparent' The color of border shadow of the box where the label is located. See MDN.
borderWidth number 0 The border line width (in pixels).
color Color '#fff' Text color.
content string|string[]|Image|HTMLCanvasElement null The content to show in the label.
drawTime string options.drawTime See drawTime. Defaults to the line annotation draw time if unset.
enabled boolean false Whether or not the label is shown.
font Font { weight: 'bold' } Label font.
height number|string undefined Overrides the height of the image or canvas element. Could be set in pixel by a number, or in percentage of current height of image or canvas element by a string. If undefined, uses the height of the image or canvas element. It is used only when the content is an image or canvas element.
padding Padding 6 The padding to add around the text label.
position string 'center' Anchor position of label on line. Possible options are: 'start', 'center', 'end'. It can be set by a string in percentage format 'number%' which are representing the percentage on the width of the line where the label will be located.
rotation number|'auto' 0 Rotation of label, in degrees, or 'auto' to use the degrees of the line.
shadowBlur number 0 The amount of blur applied to shadow of the box where the label is located. See MDN.
shadowOffsetX number 0 The distance that shadow, of the box where the label is located, will be offset horizontally. See MDN.
shadowOffsetY number 0 The distance that shadow, of the box where the label is located, will be offset vertically. See MDN.
textAlign string 'center' Text alignment of label content when there's more than one line. Possible options are: 'start', 'center', 'end'.
width number|string undefined Overrides the width of the image or canvas element. Could be set in pixel by a number, or in percentage of current width of image or canvas element by a string. If undefined, uses the width of the image or canvas element. It is used only when the content is an image or canvas element.
xAdjust number 0 Adjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right.
xPadding number 6 Padding of label to add left/right. This is deprecated. Use padding.
yAdjust number 0 Adjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down.
yPadding number 6 Padding of label to add top/bottom. This is deprecated. Use padding.

borderRadius

If this value is a number, it is applied to all corners of the rectangle (topLeft, topRight, bottomLeft, bottomRight). If this value is an object, the topLeft property defines the top-left corners border radius. Similarly, the topRight, bottomLeft, and bottomRight properties can also be specified. Omitted corners have radius of 0.

Arrow heads

Namespace: options.annotations[annotationID].arrowHeads, it defines options for the line annotation arrow heads.

All of these options can be Scriptable

Name Type Notes
end object To configure the arrow head at the end of the line.
start object To configure the arrow head at the start of the line.

Arrow head configuration

Enabling it, you can add arrow heads at start and/or end of a line. It uses the borderWidth of the line options to configure the line width of the arrow head.

The following options are available for can be specified per (start and/or end) arrow head, or at the top level (arrowHeads) which apply to all arrow heads.

All of these options can be Scriptable

Name Type Default Notes
backgroundColor Color lineAnnotation.borderColor Background color of the arrow head.
backgroundShadowColor Color 'transparent' The color of shadow of the arrow head. See MDN.
borderColor Color lineAnnotation.borderColor The border arrow head color.
borderDash number[] lineAnnotation.borderDash Length and spacing of dashes. See MDN.
borderDashOffset number lineAnnotation.borderDashOffset Offset for border arrow head dashes. See MDN.
borderShadowColor Color lineAnnotation.borderShadowColor The color of border shadow of the arrow head. See MDN.
borderWidth number lineAnnotation.borderWidth The border line width (in pixels).
enabled boolean false Whether or not the arrow head is shown.
fill boolean false Whether or not the arrow head is filled.
length number 12 The length of the arrow head in pixels.
shadowBlur number lineAnnotation.shadowBlur The amount of blur applied to shadow of the arrow head. See MDN.
shadowOffsetX number lineAnnotation.shadowOffsetX The distance that shadow, of the arrow head, will be offset horizontally. See MDN.
shadowOffsetY number lineAnnotation.shadowOffsetY The distance that shadow, of the arrow head, will be offset vertically. See MDN.
width number 6 The width of the arrow head in pixels.