config/Options/shape/arc.ts

  1. /**
  2. * Copyright (c) 2017 ~ present NAVER Corp.
  3. * billboard.js project is licensed under the MIT license
  4. */
  5. /**
  6. * arc config options
  7. */
  8. export default {
  9. /**
  10. * Set arc options
  11. * @name arc
  12. * @memberof Options
  13. * @type {object}
  14. * @property {object} arc Arc object
  15. * @property {number|Function} [arc.cornerRadius=0] Set corner radius of Arc(donut/gauge/pie/polar) shape.
  16. * - **NOTE:**
  17. * - Corner radius can't surpass the `(outerRadius - innerRadius) /2` of indicated shape.
  18. * @property {number} [arc.cornerRadius.ratio=0] Set ratio relative of outer radius.
  19. * @property {object} [arc.needle] Set needle options.
  20. * @property {boolean} [arc.needle.show=false] Show or hide needle.
  21. * @property {string} [arc.needle.color] Set needle filled color.
  22. * @property {Function} [arc.needle.path] Set custom needle path function.
  23. * - **NOTE:**
  24. * - The path should be starting from 0,0 (which is center) to top center coordinate.
  25. * - The function will receive, `length`{number} parameter which indicating the needle length in pixel relative to radius.
  26. * @property {number} [arc.needle.value] Set needle value.
  27. * - **NOTE:**
  28. * - For single gauge chart, needle will point the data value by default, otherwise will point 0(zero).
  29. * @property {number} [arc.needle.length=100] Set needle length in percentages relative to radius.
  30. * @property {object} [arc.needle.top] Set needle top options.
  31. * @property {number} [arc.needle.top.rx=0] Set needle top [rx radius value](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve).
  32. * @property {number} [arc.needle.top.ry=0] Set needle top [ry radius value](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve).
  33. * @property {number} [arc.needle.top.width=0] Set needle top width in pixel.
  34. * @property {object} [arc.needle.bottom] Set needle bottom options.
  35. * @property {number} [arc.needle.bottom.rx=1] Set needle bottom [rx radius value](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve).
  36. * @property {number} [arc.needle.bottom.ry=1] Set needle bottom [ry radius value](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve).
  37. * @property {number} [arc.needle.bottom.width=15] Set needle bottom width in pixel.
  38. * @property {number} [arc.needle.bottom.len=0] Set needle bottom length in pixel. Setting this value, will make bottom larger starting from center.
  39. * @property {object} [arc.rangeText] Set rangeText options.
  40. * @property {Array} [arc.rangeText.values] Set range text values to be shown around Arc.
  41. * - When `unit: 'absolute'`: Given values are treated as absolute values.
  42. * - When `unit: '%'`: Given values are treated as percentages.
  43. * @property {string} [arc.rangeText.unit="absolute"] Specify the range text unit.
  44. * - "absolute": Show absolute value
  45. * - "%": Show percentage value
  46. * @property {boolean} [arc.rangeText.fiexed=false] Set if range text shown will be fixed w/o data toggle update. Only available for gauge chart.
  47. * @property {Function} [arc.rangeText.format] Set format function for the range text.
  48. * @property {number} [arc.rangeText.position] Set position function or object for the range text.
  49. * @see [Demo: Donut corner radius](https://naver.github.io/billboard.js/demo/#DonutChartOptions.DonutCornerRadius)
  50. * @see [Demo: Donut corner radius](https://naver.github.io/billboard.js/demo/#PieChartOptions.CornerRadius)
  51. * @see [Demo: Donut needle](https://naver.github.io/billboard.js/demo/#DonutChartOptions.DonutNeedle)
  52. * @see [Demo: Donut RangeText](https://naver.github.io/billboard.js/demo/#DonutChartOptions.DonutRangeText)
  53. * @see [Demo: Gauge corner radius](https://naver.github.io/billboard.js/demo/#GaugeChartOptions.GaugeCornerRadius)
  54. * @see [Demo: Gauge needle](https://naver.github.io/billboard.js/demo/#GaugeChartOptions.GaugeNeedle)
  55. * @see [Demo: Gauge RangeText](https://naver.github.io/billboard.js/demo/#GaugeChartOptions.GaugeRangeText)
  56. * @example
  57. * arc: {
  58. * cornerRadius: 12,
  59. *
  60. * // can customize corner radius for each data with function callback
  61. * //
  62. * // The function will receive:
  63. * // - id {string}: Data id
  64. * // - value {number}: Data value
  65. * // - outerRadius {number}: Outer radius value
  66. * cornerRadius: function(id, value, outerRadius) {
  67. * return (id === "data1" && value > 10) ?
  68. * 50 : outerRadius * 1.2;
  69. * },
  70. *
  71. * // set ratio relative of outer radius
  72. * cornerRadius: {
  73. * ratio: 0.5
  74. * },
  75. *
  76. * needle: {
  77. * show: true,
  78. * color: "red", // any valid CSS color
  79. * path: function(length) {
  80. * const len = length - 20;
  81. *
  82. * // will return upper arrow shape path
  83. * // Note: The path should begun from '0,0' coordinate to top center.
  84. * const path = `M 0 -${len + 20}
  85. * L -12 -${len}
  86. * L -5 -${len}
  87. * L -5 0
  88. * A 1 1 0 0 0 5 0
  89. * L 5 -${len}
  90. * L 12 -${len} Z`;
  91. *
  92. * return path;
  93. * },
  94. * value: 40, // will make needle to point value 40.
  95. * length: 80, // needle length in percentages relative to radius.
  96. *
  97. * top: {
  98. * // rx and ry are the two radii of the ellipse;
  99. * // https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve
  100. * rx: 1,
  101. * ry: 1,
  102. * width: 5
  103. * },
  104. * bottom: {
  105. * // rx and ry are the two radii of the ellipse;
  106. * // https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve
  107. * rx: 1,
  108. * ry: 1,
  109. * width: 10
  110. * len: 10
  111. * }
  112. * },
  113. *
  114. * rangeText: {
  115. * values: [15, 30, 50, 75, 95],
  116. * unit: "%",
  117. * fixed: false, // only available for gauge chart
  118. * format: function(v) {
  119. * return v === 15 ? "Fifteen" : v;
  120. * },
  121. *
  122. * position: function(v) {
  123. * return v === 15 ? {x: 20, y: 10} : null; // can return one props value also.
  124. * },
  125. * position: {x: 10, y: 15},
  126. * position: {x: 10}
  127. * }
  128. * }
  129. */
  130. arc_cornerRadius: <number | ((id: string, value: number) => number)>0,
  131. arc_cornerRadius_ratio: 0,
  132. arc_needle_show: false,
  133. arc_needle_color: <string | undefined>undefined,
  134. arc_needle_value: <number | undefined>undefined,
  135. arc_needle_path: undefined,
  136. arc_needle_length: 100,
  137. arc_needle_top_rx: 0,
  138. arc_needle_top_ry: 0,
  139. arc_needle_top_width: 0,
  140. arc_needle_bottom_rx: 1,
  141. arc_needle_bottom_ry: 1,
  142. arc_needle_bottom_width: 15,
  143. arc_needle_bottom_len: 0,
  144. arc_rangeText_values: <number[] | undefined>undefined,
  145. arc_rangeText_unit: <"absolute" | "%">"absolute",
  146. arc_rangeText_fixed: false,
  147. arc_rangeText_format: <((v: number) => number) | undefined>undefined,
  148. arc_rangeText_position: <
  149. | ((v: number) => {x?: number, y?: number})
  150. | {x?: number, y?: number}
  151. | undefined
  152. >undefined
  153. };