|
| 1 | +# Doughnut Label Annotations |
| 2 | + |
| 3 | +Doughnut label annotations are used to add contents (text, image, canvas) in the middle area of the doughnut charts. |
| 4 | + |
| 5 | +```js chart-editor |
| 6 | +/* <block:options:0> */ |
| 7 | +const options = { |
| 8 | + plugins: { |
| 9 | + annotation: { |
| 10 | + annotations: { |
| 11 | + dLabel: { |
| 12 | + type: 'doughnutLabel', |
| 13 | + content: ({chart}) => ['Total', |
| 14 | + chart.getDatasetMeta(0).total, |
| 15 | + 'last 7 months' |
| 16 | + ], |
| 17 | + font: [{size: 60}, {size: 50}, {size: 30}], |
| 18 | + color: ['black', 'red', 'grey'] |
| 19 | + } |
| 20 | + } |
| 21 | + } |
| 22 | + } |
| 23 | +}; |
| 24 | +/* </block:options> */ |
| 25 | + |
| 26 | +/* <block:config:1> */ |
| 27 | +const config = { |
| 28 | + type: 'doughnut', |
| 29 | + data: { |
| 30 | + labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'], |
| 31 | + datasets: [{ |
| 32 | + label: 'Amount', |
| 33 | + data: [65, 59, 80, 81, 56, 55, 40] |
| 34 | + }] |
| 35 | + }, |
| 36 | + options |
| 37 | +}; |
| 38 | +/* </block:config> */ |
| 39 | + |
| 40 | +module.exports = { |
| 41 | + config |
| 42 | +}; |
| 43 | +``` |
| 44 | + |
| 45 | +## Configuration |
| 46 | + |
| 47 | +### Options |
| 48 | + |
| 49 | +The following options are available for label annotations. |
| 50 | + |
| 51 | +| Name | Type | [Scriptable](../options.md#scriptable-options) | Default |
| 52 | +| ---- | ---- | :----: | ---- |
| 53 | +| [`autoHide`](#general) | `boolean` | Yes | `true` |
| 54 | +| [`autoFit`](#general) | `boolean` | Yes | `true` |
| 55 | +| [`backgroundColor`](#styling) | [`Color`](../options.md#color) | Yes | `'transparent'` |
| 56 | +| [`backgroundShadowColor`](#styling) | [`Color`](../options.md#color) | Yes | `'transparent'` |
| 57 | +| [`borderColor`](#styling) | [`Color`](../options.md#color) | Yes | `'transparent'` |
| 58 | +| [`borderDash`](#styling) | `number[]` | Yes | `[]` |
| 59 | +| [`borderDashOffset`](#styling) | `number` | Yes | `0` |
| 60 | +| [`borderShadowColor`](#styling) | [`Color`](../options.md#color) | Yes | `'transparent'` |
| 61 | +| [`display`](#general) | `boolean` | Yes | `true` |
| 62 | +| [`drawTime`](#general) | `string` | Yes | `'afterDatasetsDraw'` |
| 63 | +| [`borderJoinStyle`](#styling) | `string` | Yes | `'miter'` |
| 64 | +| [`borderWidth`](#styling) | `number`| Yes | `0` |
| 65 | +| [`color`](#styling) | [`Color`\|`Color[]`](../options.md#color) | Yes | `'black'` |
| 66 | +| [`content`](#general) | `string`\|`string[]`\|[`Image`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image)\|[`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) | Yes | `null` |
| 67 | +| [`font`](#styling) | [`Font`\|`Font[]`](../options.md#font) | Yes | `{}` |
| 68 | +| [`height`](#general) | `number`\|`string` | Yes | `undefined` |
| 69 | +| [`hitTolerance`](#general) | `number` | Yes | `0` |
| 70 | +| [`id`](#general) | `string` | No | `undefined` |
| 71 | +| [`init`](../configuration.html#common) | `boolean` | [See initial animation](../configuration.html#initial-animation) | `undefined` |
| 72 | +| [`opacity`](#styling) | `number` | Yes | `undefined` |
| 73 | +| [`position`](#position) | `string`\|`{x: string, y: string}` | Yes | `'center'` |
| 74 | +| [`rotation`](#general) | `number`| Yes | `0` |
| 75 | +| [`shadowBlur`](#styling) | `number` | Yes | `0` |
| 76 | +| [`shadowOffsetX`](#styling) | `number` | Yes | `0` |
| 77 | +| [`shadowOffsetY`](#styling) | `number` | Yes | `0` |
| 78 | +| [`spacing`](#general) | `number`| Yes | `1` |
| 79 | +| [`textAlign`](#general) | `string` | Yes | `'center'` |
| 80 | +| [`textStrokeColor`](#styling) | [`Color`](../options.md#color) | Yes | `undefined` |
| 81 | +| [`textStrokeWidth`](#styling) | `number` | Yes | `0` |
| 82 | +| [`width`](#general) | `number`\|`string` | Yes | `undefined` |
| 83 | +| [`xAdjust`](#general) | `number` | Yes | `0` |
| 84 | +| [`yAdjust`](#general) | `number` | Yes | `0` |
| 85 | + |
| 86 | +### General |
| 87 | + |
| 88 | +The content will be rendered in the center of the chart. |
| 89 | + |
| 90 | +| Name | Description |
| 91 | +| ---- | ---- |
| 92 | +| `autoFit` | If `true`, the label will be automatically fit inside the chart if its dimension is bigger than the available space. |
| 93 | +| `autoHide` | If `true`, the label will be automatically hidden if the dataset or its data items will be all hidden. |
| 94 | +| `content` | The content to show in the annotation. |
| 95 | +| `display` | Whether or not this annotation is visible. |
| 96 | +| `drawTime` | See [drawTime](../options.md#draw-time). |
| 97 | +| `height` | 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. |
| 98 | +| `hitTolerance` | Amount of pixels to interact with annotations within some distance of the mouse point. |
| 99 | +| `id` | Identifies a unique id for the annotation and it will be stored in the element context. When the annotations are defined by an object, the id is automatically set using the key used to store the annotations in the object. When the annotations are configured by an array, the id, passed by this option in the annotation, will be used. |
| 100 | +| `rotation` | Rotation of the label in degrees. |
| 101 | +| `spacing` | The space in pixels between the inner radius of the chart and the background of the label. |
| 102 | +| `textAlign` | Text alignment of label content when there's more than one line. Possible options are: `'left'`, `'start'`, `'center'`, `'end'`, `'right'`. |
| 103 | +| `width` | 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. |
| 104 | +| `xAdjust` | Adjustment of label relative to computed position. Negative values move the label left, positive right. |
| 105 | +| `yAdjust` | Adjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down. |
| 106 | + |
| 107 | +### Styling |
| 108 | + |
| 109 | +| Name | Description |
| 110 | +| ---- | ---- |
| 111 | +| `backgroundColor` | Fill color. |
| 112 | +| `backgroundShadowColor` | The color of shadow. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). |
| 113 | +| `borderColor` | Stroke color. |
| 114 | +| `borderDash` | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). |
| 115 | +| `borderDashOffset` | Offset for border line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). |
| 116 | +| `borderJoinStyle` | Border line join style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). |
| 117 | +| `borderShadowColor` | The color of the border shadow. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). |
| 118 | +| `borderWidth` | Stroke width (in pixels). |
| 119 | +| `color` | Text color. When the label to draw has multiple lines, you can use different color for each row of the label. This is enabled configuring an array of colors. When the lines are more than the configured colors, the last configuration of this option is used for all remaining lines. |
| 120 | +| `font` | Text font. When the label to draw has multiple lines, you can use different font for each row of the label. This is enabled configuring an array of fonts. When the lines are more than the configured fonts, the last configuration of this option is used for all remaining lines. |
| 121 | +| `opacity` | Overrides the opacity of the image or canvas element. Could be set a number in the range 0.0 to 1.0, inclusive. If undefined, uses the opacity of the image or canvas element. It is used only when the content is an image or canvas element. |
| 122 | +| `shadowBlur` | The amount of blur applied to shadow of the box where the label is located. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur). |
| 123 | +| `shadowOffsetX` | The distance that shadow, of the box where the label is located, will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX). |
| 124 | +| `shadowOffsetY` | The distance that shadow, of the box where the label is located, will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY). |
| 125 | +| `textStrokeColor` | The color of the stroke around the text. |
| 126 | +| `textStrokeWidth` | Stroke width around the text. |
| 127 | + |
| 128 | +### Position |
| 129 | + |
| 130 | +A position can be set in 2 different values types: |
| 131 | + |
| 132 | +1. `'start'`, `'center'`, `'end'` which are defining where the label will be located |
| 133 | +2. a `string`, in percentage format `'number%'`, is representing the percentage on the size where the label will be located |
| 134 | + |
| 135 | +If this value is a string (possible options are `'start'`, `'center'`, `'end'` or a string in percentage format), it is applied to vertical and horizontal position in the box. |
| 136 | + |
| 137 | +If this value is an object, the `x` property defines the horizontal alignment in the label, with respect to the center point of the chart. Similarly, the `y` property defines the vertical alignment in the label, with respect to the center point of the chart. Possible options for both properties are `'start'`, `'center'`, `'end'`, a string in percentage format. Omitted property have value of the default, `'center'`. |
| 138 | + |
| 139 | +#### borderRadius |
| 140 | + |
| 141 | +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. |
| 142 | + |
| 143 | +## Element |
| 144 | + |
| 145 | +The following diagram is showing the element properties about a `'doughnutLabel'` annotation: |
| 146 | + |
| 147 | + |
0 commit comments