| commit | author | age | ||
| 83c3f6 | 1 | # Time Cartesian Axis |
| SP | 2 | |
| 3 | The time scale is used to display times and dates. When building its ticks, it will automatically calculate the most comfortable unit base on the size of the scale. | |
| 4 | ||
| 5 | ## Data Sets | |
| 6 | ||
| 7 | ### Input Data | |
| 8 | ||
| 9 | The x-axis data points may additionally be specified via the `t` or `x` attribute when using the time scale. | |
| 10 | ||
| 11 | data: [{ | |
| 12 | x: new Date(), | |
| 13 | y: 1 | |
| 14 | }, { | |
| 15 | t: new Date(), | |
| 16 | y: 10 | |
| 17 | }] | |
| 18 | ||
| 19 | ||
| 20 | ### Date Formats | |
| 21 | ||
| 22 | When providing data for the time scale, Chart.js supports all of the formats that Moment.js accepts. See [Moment.js docs](http://momentjs.com/docs/#/parsing/) for details. | |
| 23 | ||
| 24 | ## Configuration Options | |
| 25 | ||
| 26 | The following options are provided by the time scale. You may also set options provided by the [common tick configuration](README.md#tick-configuration). | |
| 27 | ||
| 28 | | Name | Type | Default | Description | |
| 29 | | -----| ---- | --------| ----------- | |
| 30 | | `distribution` | `String` | `linear` | How data is plotted. [more...](#scale-distribution) | |
| 31 | | `bounds` | `String` | `data` | Determines the scale bounds. [more...](#scale-bounds) | |
| 32 | | `ticks.source` | `String` | `auto` | How ticks are generated. [more...](#ticks-source) | |
| 33 | | `time.displayFormats` | `Object` | | Sets how different time units are displayed. [more...](#display-formats) | |
| 34 | | `time.isoWeekday` | `Boolean` | `false` | If true and the unit is set to 'week', then the first day of the week will be Monday. Otherwise, it will be Sunday. | |
| 35 | | `time.max` | [Time](#date-formats) | | If defined, this will override the data maximum | |
| 36 | | `time.min` | [Time](#date-formats) | | If defined, this will override the data minimum | |
| 37 | | `time.parser` | `String/Function` | | Custom parser for dates. [more...](#parser) | |
| 38 | | `time.round` | `String` | `false` | If defined, dates will be rounded to the start of this unit. See [Time Units](#time-units) below for the allowed units. | |
| 39 | | `time.tooltipFormat` | `String` | | The moment js format string to use for the tooltip. | |
| 40 | | `time.unit` | `String` | `false` | If defined, will force the unit to be a certain type. See [Time Units](#time-units) section below for details. | |
| 41 | | `time.stepSize` | `Number` | `1` | The number of units between grid lines. | |
| 42 | | `time.minUnit` | `String` | `'millisecond'` | The minimum display format to be used for a time unit. | |
| 43 | ||
| 44 | ### Time Units | |
| 45 | ||
| 46 | The following time measurements are supported. The names can be passed as strings to the `time.unit` config option to force a certain unit. | |
| 47 | ||
| 48 | * millisecond | |
| 49 | * second | |
| 50 | * minute | |
| 51 | * hour | |
| 52 | * day | |
| 53 | * week | |
| 54 | * month | |
| 55 | * quarter | |
| 56 | * year | |
| 57 | ||
| 58 | For example, to create a chart with a time scale that always displayed units per month, the following config could be used. | |
| 59 | ||
| 60 | ```javascript | |
| 61 | var chart = new Chart(ctx, { | |
| 62 | type: 'line', | |
| 63 | data: data, | |
| 64 | options: { | |
| 65 | scales: { | |
| 66 | xAxes: [{ | |
| 67 | type: 'time', | |
| 68 | time: { | |
| 69 | unit: 'month' | |
| 70 | } | |
| 71 | }] | |
| 72 | } | |
| 73 | } | |
| 74 | }) | |
| 75 | ``` | |
| 76 | ||
| 77 | ### Display Formats | |
| 78 | The following display formats are used to configure how different time units are formed into strings for the axis tick marks. See [moment.js](http://momentjs.com/docs/#/displaying/format/) for the allowable format strings. | |
| 79 | ||
| 80 | Name | Default | Example | |
| 81 | --- | --- | --- | |
| 82 | millisecond | 'h:mm:ss.SSS a' | 11:20:01.123 AM | |
| 83 | second | 'h:mm:ss a' | 11:20:01 AM | |
| 84 | minute | 'h:mm a' | 11:20 AM | |
| 85 | hour | 'hA' | 11AM | |
| 86 | day | 'MMM D' | Sep 4 | |
| 87 | week | 'll' | Sep 4 2015 | |
| 88 | month | 'MMM YYYY' | Sep 2015 | |
| 89 | quarter | '[Q]Q - YYYY' | Q3 - 2015 | |
| 90 | year | 'YYYY' | 2015 | |
| 91 | ||
| 92 | For example, to set the display format for the 'quarter' unit to show the month and year, the following config would be passed to the chart constructor. | |
| 93 | ||
| 94 | ```javascript | |
| 95 | var chart = new Chart(ctx, { | |
| 96 | type: 'line', | |
| 97 | data: data, | |
| 98 | options: { | |
| 99 | scales: { | |
| 100 | xAxes: [{ | |
| 101 | type: 'time', | |
| 102 | time: { | |
| 103 | displayFormats: { | |
| 104 | quarter: 'MMM YYYY' | |
| 105 | } | |
| 106 | } | |
| 107 | }] | |
| 108 | } | |
| 109 | } | |
| 110 | }) | |
| 111 | ``` | |
| 112 | ||
| 113 | ### Scale Distribution | |
| 114 | ||
| 115 | The `distribution` property controls the data distribution along the scale: | |
| 116 | ||
| 117 | * `'linear'`: data are spread according to their time (distances can vary) | |
| 118 | * `'series'`: data are spread at the same distance from each other | |
| 119 | ||
| 120 | ```javascript | |
| 121 | var chart = new Chart(ctx, { | |
| 122 | type: 'line', | |
| 123 | data: data, | |
| 124 | options: { | |
| 125 | scales: { | |
| 126 | xAxes: [{ | |
| 127 | type: 'time', | |
| 128 | distribution: 'series' | |
| 129 | }] | |
| 130 | } | |
| 131 | } | |
| 132 | }) | |
| 133 | ``` | |
| 134 | ||
| 135 | ### Scale Bounds | |
| 136 | ||
| 137 | The `bounds` property controls the scale boundary strategy (bypassed by min/max time options) | |
| 138 | ||
| 139 | * `'data'`: make sure data are fully visible, labels outside are removed | |
| 140 | * `'ticks'`: make sure ticks are fully visible, data outside are truncated | |
| 141 | ||
| 142 | ### Ticks Source | |
| 143 | ||
| 144 | The `ticks.source` property controls the ticks generation | |
| 145 | ||
| 146 | * `'auto'`: generates "optimal" ticks based on scale size and time options. | |
| 147 | * `'data'`: generates ticks from data (including labels from data `{t|x|y}` objects) | |
| 148 | * `'labels'`: generates ticks from user given `data.labels` values ONLY | |
| 149 | ||
| 150 | ### Parser | |
| 151 | If this property is defined as a string, it is interpreted as a custom format to be used by moment to parse the date. | |
| 152 | ||
| 153 | If this is a function, it must return a moment.js object given the appropriate data value. | |
