config/Options/shape/gauge.ts

  1. /**
  2. * Copyright (c) 2017 ~ present NAVER Corp.
  3. * billboard.js project is licensed under the MIT license
  4. */
  5. /**
  6. * gauge config options
  7. */
  8. export default {
  9. /**
  10. * Set gauge options
  11. * @name gauge
  12. * @memberof Options
  13. * @type {object}
  14. * @property {object} gauge Gauge object
  15. * @property {boolean} [gauge.background=""] Set background color. (The `.bb-chart-arcs-background` element)
  16. * @property {boolean} [gauge.fullCircle=false] Show full circle as donut. When set to 'true', the max label will not be showed due to start and end points are same location.
  17. * @property {boolean} [gauge.label.show=true] Show or hide label on gauge.
  18. * @property {Function} [gauge.label.extents] Set customized min/max label text.
  19. * @property {Function} [gauge.label.format] Set formatter for the label on gauge. Label text can be multilined with `\n` character.<br>
  20. * Will pass following arguments to the given function:
  21. * - value {number}: absolute value
  22. * - ratio {number}: value's ratio
  23. * - id {string}: data's id value
  24. * @property {number|Function} [gauge.label.ratio=undefined] Set ratio of labels position.
  25. * @property {number} [gauge.label.threshold=0] Set threshold ratio to show/hide labels.
  26. * @property {boolean} [gauge.expand=true] Enable or disable expanding gauge.
  27. * @property {number} [gauge.expand.rate=0.98] Set expand rate.
  28. * @property {number} [gauge.expand.duration=50] Set the expand transition time in milliseconds.
  29. * @property {boolean} [gauge.enforceMinMax=false] Enforce to given min/max value.
  30. * - **Note:** Only works for single data series.
  31. * - When `gauge.min=50` and given value is `30`, gauge will render as empty value.
  32. * - When `gauge.max=100` and given value is `120`, gauge will render till 100, not surpassing max value.
  33. * @property {number} [gauge.min=0] Set min value of the gauge.
  34. * @property {number} [gauge.max=100] Set max value of the gauge.
  35. * @property {number} [gauge.startingAngle=-1 * Math.PI / 2] Set starting angle where data draws.
  36. *
  37. * **Limitations:**
  38. * - when `gauge.fullCircle=false`:
  39. * - -1 * Math.PI / 2 <= startingAngle <= Math.PI / 2
  40. * - `startingAngle <= -1 * Math.PI / 2` defaults to `-1 * Math.PI / 2`
  41. * - `startingAngle >= Math.PI / 2` defaults to `Math.PI / 2`
  42. * - when `gauge.fullCircle=true`:
  43. * - -1 * Math.PI < startingAngle < Math.PI
  44. * - `startingAngle < -1 * Math.PI` defaults to `Math.PI`
  45. * - `startingAngle > Math.PI` defaults to `Math.PI`
  46. * @property {number} [gauge.arcLength=100] Set the length of the arc to be drawn in percent from -100 to 100.<br>
  47. * Negative value will draw the arc **counterclockwise**. Need to be used in conjunction with `gauge.fullCircle=true`.
  48. *
  49. * **Limitations:**
  50. * - -100 <= arcLength (in percent) <= 100
  51. * - 'arcLength < -100' defaults to -100
  52. * - 'arcLength > 100' defaults to 100
  53. * @property {string} [gauge.title=""] Set title of gauge chart. Use `\n` character for line break.
  54. * - **NOTE:**
  55. * - When `arc.needle.show=true` is set, special template `{=NEEDLE_VALUE}` can be used inside the title text to show current needle value.
  56. * @property {string} [gauge.units] Set units of the gauge.
  57. * @property {number} [gauge.width] Set width of gauge chart.
  58. * @property {string} [gauge.type="single"] Set type of gauge to be displayed.<br><br>
  59. * **Available Values:**
  60. * - single
  61. * - multi
  62. * @property {number} [gauge.arcs.minWidth=5] Set minimal width of gauge arcs until the innerRadius disappears.
  63. * @see [Demo: enforceMinMax, min/max](https://naver.github.io/billboard.js/demo/#GaugeChartOptions.GaugeMinMax)
  64. * @see [Demo: archLength](https://naver.github.io/billboard.js/demo/#GaugeChartOptions.GaugeArcLength)
  65. * @see [Demo: startingAngle](https://naver.github.io/billboard.js/demo/#GaugeChartOptions.GaugeStartingAngle)
  66. * @see [Demo: labelRatio](https://naver.github.io/billboard.js/demo/#GaugeChartOptions.GaugeLabelRatio)
  67. * @example
  68. * gauge: {
  69. * background: "#eee", // will set 'fill' css prop for '.bb-chart-arcs-background' classed element.
  70. * fullCircle: false,
  71. * label: {
  72. * show: false,
  73. * format: function(value, ratio, id) {
  74. * return value;
  75. *
  76. * // to multiline, return with '\n' character
  77. * // return value +"%\nLine1\n2Line2";
  78. * },
  79. *
  80. * extents: function(value, isMax) {
  81. * return (isMax ? "Max:" : "Min:") + value;
  82. * },
  83. *
  84. * // 0.1(10%) ratio value means, the minimum ratio to show text label relative to the total value.
  85. * // if data value is below than 0.1, text label will be hidden.
  86. * threshold: 0.1,
  87. *
  88. * // set ratio callback. Should return ratio value
  89. * ratio: function(d, radius, h) {
  90. * ...
  91. * return ratio;
  92. * },
  93. * // or set ratio number
  94. * ratio: 0.5
  95. * },
  96. *
  97. * // disable expand transition for interaction
  98. * expand: false,
  99. *
  100. * expand: {
  101. * // set duration of expand transition to 500ms.
  102. * duration: 500,
  103. *
  104. * // set expand area rate
  105. * rate: 1
  106. * },
  107. *
  108. * // enforce min/max value.
  109. * // when given value < min, will render as empty value.
  110. * // when value > max, will render to given max value not surpassing it.
  111. * enforceMinMax: true,
  112. *
  113. * min: -100,
  114. * max: 200,
  115. * type: "single" // or 'multi'
  116. * title: "Title Text",
  117. *
  118. * // when 'arc.needle.show=true' is set, can show current needle value.
  119. * title: "Needle value:\n{=NEEDLE_VALUE}",
  120. *
  121. * units: "%",
  122. * width: 10,
  123. * startingAngle: -1 * Math.PI / 2,
  124. * arcLength: 100,
  125. * arcs: {
  126. * minWidth: 5
  127. * }
  128. * }
  129. */
  130. gauge_background: "",
  131. gauge_fullCircle: false,
  132. gauge_label_show: true,
  133. gauge_label_extents: <(() => string) | undefined>undefined,
  134. gauge_label_format: <(() => string) | undefined>undefined,
  135. gauge_label_ratio: <(() => number) | undefined>undefined,
  136. gauge_label_threshold: 0,
  137. gauge_enforceMinMax: false,
  138. gauge_min: 0,
  139. gauge_max: 100,
  140. gauge_type: "single",
  141. gauge_startingAngle: -1 * Math.PI / 2,
  142. gauge_arcLength: 100,
  143. gauge_title: "",
  144. gauge_units: <string | undefined>undefined,
  145. gauge_width: <number | undefined>undefined,
  146. gauge_arcs_minWidth: 5,
  147. gauge_expand: <boolean | {duration: number}>{},
  148. gauge_expand_rate: 0.98,
  149. gauge_expand_duration: 50
  150. };