config/Options/shape/bar.ts

  1. /**
  2.  * Copyright (c) 2017 ~ present NAVER Corp.
  3.  * billboard.js project is licensed under the MIT license
  4.  */
  5. /**
  6.  * bar config options
  7.  */
  8. export default {
  9. 	/**
  10. 	 * Set bar options
  11. 	 * @name bar
  12. 	 * @memberof Options
  13. 	 * @type {object}
  14. 	 * @property {object} bar Bar object
  15. 	 * @property {boolean} [bar.front=false] Set 'bar' to be positioned over(on the top) other shapes elements.
  16. 	 * @property {number} [bar.indices.removeNull=false] Remove nullish data on bar indices positions.
  17. 	 * @property {number} [bar.label.threshold=0] Set threshold ratio to show/hide labels.
  18. 	 * @property {boolean|object} [bar.linearGradient=false] Set the linear gradient on bar.<br><br>
  19. 	 * Or customize by giving below object value:
  20. 	 *  - x {Array}: `x1`, `x2` value (default: `[0, 0]`)
  21. 	 *  - y {Array}: `y1`, `y2` value (default: `[0, 1]`)
  22. 	 *  - stops {Array}: Each item should be having `[offset, stop-color, stop-opacity]` values.
  23. 	 *    - (default: `[[0, $DATA_COLOR, 1], [1, $DATA_COLOR, 0]]`)
  24. 	 * @property {boolean} [bar.overlap=false] Bars will be rendered at same position, which will be overlapped each other. (for non-grouped bars only)
  25. 	 * @property {number} [bar.padding=0] The padding pixel value between each bar.
  26. 	 * @property {number} [bar.radius] Set the radius of bar edge in pixel.
  27. 	 * @property {number} [bar.radius.ratio] Set the radius ratio of bar edge in relative the bar's width.
  28. 	 * @property {number} [bar.sensitivity=2] The senstivity offset value for interaction boundary.
  29. 	 * @property {number|Function|object} [bar.width] Change the width of bar chart.
  30. 	 * @property {number} [bar.width.ratio=0.6] Change the width of bar chart by ratio.
  31. 	 * - **NOTE:** Criteria for ratio.
  32. 	 *   - When x ticks count is same with the data count, the baseline for ratio is the minimum interval value of x ticks.
  33. 	 * 	   - ex. when timeseries x values are: [2024-01-01, 2024-02-01, 2024-03-01], the minimum interval will be `2024-02-01 ~ 2024-03-01`
  34. 	 *     - if the minimum interval is 30px, then ratio=1 means 30px.
  35. 	 *   - When x ticks count is lower than the data count, the baseline will be calculated as `chart width / data count`.
  36. 	 * 	   - ex. when chart width is 500, data count is 5, then ratio=1 means 100px.
  37. 	 * @property {number} [bar.width.max] The maximum width value for ratio.
  38. 	 * @property {number} [bar.width.dataname] Change the width of bar for indicated dataset only.
  39. 	 * @property {number} [bar.width.dataname.ratio=0.6] Change the width of bar chart by ratio.
  40. 	 *  - **NOTE:**
  41. 	 *   - Works only for non-stacked bar
  42. 	 * @property {number} [bar.width.dataname.max] The maximum width value for ratio.
  43. 	 * @property {boolean} [bar.zerobased=true] Set if min or max value will be 0 on bar chart.
  44. 	 * @see [Demo: bar front](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarFront)
  45. 	 * @see [Demo: bar indices](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarIndices)
  46. 	 * @see [Demo: bar overlap](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarOverlap)
  47. 	 * @see [Demo: bar padding](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarPadding)
  48. 	 * @see [Demo: bar radius](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarRadius)
  49. 	 * @see [Demo: bar width](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarWidth)
  50. 	 * @see [Demo: bar width variant](https://naver.github.io/billboard.js/demo/#BarChartOptions.BarWidthVariant)
  51. 	 * @example
  52. 	 *  bar: {
  53. 	 *      // make bar shape to be positioned over the other shape elements
  54. 	 *      front: true,
  55. 	 *
  56. 	 *      // remove nullish data on bar indices postions
  57. 	 *      indices: {
  58. 	 *          removeNull: true
  59. 	 *      },
  60. 	 *
  61. 	 *      // will generate follwing linearGradient:
  62. 	 *      // for more info: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient
  63. 	 *      // <linearGradient x1="0" x2="0" y1="0" y2="1">
  64. 	 *      //    <stop offset="0" stop-color="$DATA_COLOR" stop-opacity="1"></stop>
  65. 	 *      //    <stop offset="1" stop-color="$DATA_COLOR" stop-opacity="0"></stop>
  66. 	 *      // </linearGradient>
  67. 	 *      linearGradient: true,
  68. 	 *
  69. 	 *      // Or customized gradient
  70. 	 *      linearGradient: {
  71. 	 *      	x: [0, 0],  // x1, x2 attributes
  72. 	 *      	y: [0, 0],  // y1, y2 attributes
  73. 	 *      	stops: [
  74. 	 *      	  // offset, stop-color, stop-opacity
  75. 	 *      	  [0, "#7cb5ec", 1],
  76. 	 *
  77. 	 *      	  // setting 'null' for stop-color, will set its original data color
  78. 	 *      	  [0.5, null, 0],
  79. 	 *
  80. 	 *      	  // setting 'function' for stop-color, will pass data id as argument.
  81. 	 *      	  // It should return color string or null value
  82. 	 *      	  [1, function(id) { return id === "data1" ? "red" : "blue"; }, 0],
  83. 	 *      	]
  84. 	 *      },
  85. 	 *
  86. 	 *      // remove nullish da
  87. 	 *      overlap: true,
  88. 	 *
  89. 	 *      padding: 1,
  90. 	 *
  91. 	 *      // bar radius
  92. 	 *      radius: 10,
  93. 	 *      // or
  94. 	 *      radius: {
  95. 	 *          ratio: 0.5
  96. 	 *      }
  97. 	 *
  98. 	 *      label: {
  99. 	 *          // 0.1(10%) ratio value means, the minimum ratio to show text label relative to the y Axis domain range value.
  100. 	 *          // if data value is below than 0.1, text label will be hidden.
  101. 	 *          threshold: 0.1,
  102. 	 *      },
  103. 	 *
  104. 	 *      // will not have offset between each bar elements for interaction
  105. 	 *      sensitivity: 0,
  106. 	 *
  107. 	 *      width: 10,
  108. 	 *
  109. 	 *      // or specify width callback. The callback will receive width, targetsNum, maxDataCount as arguments.
  110. 	 *      // - width: chart area width
  111. 	 *      // - targetsNum: number of targets
  112. 	 *      // - maxDataCount: maximum data count among targets
  113. 	 *      width: function(width, targetsNum, maxDataCount) {
  114. 	 *            return width / (targetsNum * maxDataCount);
  115. 	 *      }
  116. 	 *
  117. 	 *      // or specify ratio & max
  118. 	 *      width: {
  119. 	 *          ratio: 0.2,
  120. 	 *          max: 20
  121. 	 *      },
  122. 	 *
  123. 	 *      // or specify width per dataset
  124. 	 *      width: {
  125. 	 *          data1: 20,
  126. 	 *          data2: {
  127. 	 *              ratio: 0.2,
  128. 	 *              max: 20
  129. 	 *          }
  130. 	 *      },
  131. 	 *
  132. 	 *      zerobased: false
  133. 	 *  }
  134. 	 */
  135. 	bar_front: false,
  136. 	bar_indices_removeNull: false,
  137. 	bar_label_threshold: 0,
  138. 	bar_linearGradient: <boolean | {
  139. 		x?: [number, number],
  140. 		y?: [number, number],
  141. 		stops?: [number, string | null | Function, number]
  142. 	}>false,
  143. 	bar_overlap: false,
  144. 	bar_padding: 0,
  145. 	bar_radius: <number | {ratio: number} | undefined>undefined,
  146. 	bar_radius_ratio: <number | undefined>undefined,
  147. 	bar_sensitivity: 2,
  148. 	bar_width: <number | ((width: number, targetsNum: number, maxDataCount: number) => number) | {
  149. 		ratio?: number,
  150. 		max?: number
  151. 	} | undefined>undefined,
  152. 	bar_width_ratio: 0.6,
  153. 	bar_width_max: undefined,
  154. 	bar_zerobased: true
  155. };