Chart/api/grid.ts

  1. /**
  2. * Copyright (c) 2017 ~ present NAVER Corp.
  3. * billboard.js project is licensed under the MIT license
  4. */
  5. import {extend, isTabVisible} from "../../module/util";
  6. type GridsParam = {value?: number, class?: string, text?: string}[];
  7. /**
  8. * Update grid lines.
  9. * @param {Array} grids grid lines to update
  10. * @param {string} axisId axis' id: "x" or "y"
  11. * @returns {Array}
  12. * @private
  13. */
  14. function grid(grids: GridsParam, axisId: "x" | "y"): GridsParam {
  15. const $$ = this.internal;
  16. const {config} = $$;
  17. const withTransition = config.transition_duration && isTabVisible();
  18. const gridPropLines = `grid_${axisId}_lines`;
  19. if (!grids) {
  20. return config[gridPropLines];
  21. }
  22. config[gridPropLines] = grids;
  23. $$.updateGrid();
  24. $$.redrawGrid(withTransition);
  25. return config[gridPropLines];
  26. }
  27. /**
  28. * Add grid lines.
  29. * @param {Array|object} grids grid lines to add
  30. * @param {string} axisId axis' id: "x" or "y"
  31. * @returns {Array}
  32. * @private
  33. */
  34. function add(grids: GridsParam, axisId: "x" | "y"): GridsParam {
  35. const gridPropLines = `grid_${axisId}_lines`;
  36. return grid.bind(this)(
  37. this.internal.config[gridPropLines].concat(grids || []),
  38. axisId
  39. );
  40. }
  41. /**
  42. * Remove grid lines.
  43. * @param {object} grids grid lines to remove
  44. * @param {boolean} isXAxis weather is x axis or not
  45. * @private
  46. */
  47. function remove(grids: GridsParam | undefined, isXAxis: boolean): void {
  48. this.internal.removeGridLines(grids, isXAxis);
  49. }
  50. /**
  51. * Update x grid lines.
  52. * @function xgrids
  53. * @instance
  54. * @memberof Chart
  55. * @param {Array} grids X grid lines will be replaced with this argument. The format of this argument is the same as grid.x.lines.
  56. * @returns {Array}
  57. * @example
  58. * // Show 2 x grid lines
  59. * chart.xgrids([
  60. * {value: 1, text: "Label 1"},
  61. * {value: 4, text: "Label 4"}
  62. * ]);
  63. * // --> Returns: [{value: 1, text: "Label 1"}, {value: 4, text: "Label 4"}]
  64. */
  65. const xgrids = function(grids: GridsParam): GridsParam {
  66. return grid.bind(this)(grids, "x");
  67. };
  68. extend(xgrids, {
  69. /**
  70. * Add x grid lines.<br>
  71. * This API adds new x grid lines instead of replacing like xgrids.
  72. * @function xgrids․add
  73. * @instance
  74. * @memberof Chart
  75. * @param {Array|object} grids New x grid lines will be added. The format of this argument is the same as grid.x.lines and it's possible to give an Object if only one line will be added.
  76. * @returns {Array}
  77. * @example
  78. * // Add a new x grid line
  79. * chart.xgrids.add(
  80. * {value: 4, text: "Label 4"}
  81. * );
  82. *
  83. * // Add new x grid lines
  84. * chart.xgrids.add([
  85. * {value: 2, text: "Label 2"},
  86. * {value: 4, text: "Label 4"}
  87. * ]);
  88. */
  89. add(grids: GridsParam): GridsParam {
  90. return add.bind(this)(grids, "x");
  91. },
  92. /**
  93. * Remove x grid lines.<br>
  94. * This API removes x grid lines.
  95. * @function xgrids․remove
  96. * @instance
  97. * @memberof Chart
  98. * @param {object} grids This argument should include value or class. If value is given, the x grid lines that have specified x value will be removed. If class is given, the x grid lines that have specified class will be removed. If args is not given, all of x grid lines will be removed.
  99. * @param {number} [grids.value] target value
  100. * @param {string} [grids.class] target class
  101. * @returns {void}
  102. * @example
  103. * // x grid line on x = 2 will be removed
  104. * chart.xgrids.remove({value: 2});
  105. *
  106. * // x grid lines that have 'grid-A' will be removed
  107. * chart.xgrids.remove({
  108. * class: "grid-A"
  109. * });
  110. *
  111. * // all of x grid lines will be removed
  112. * chart.xgrids.remove();
  113. */
  114. remove(grids?: GridsParam): void { // TODO: multiple
  115. return remove.bind(this)(grids, true);
  116. }
  117. });
  118. /**
  119. * Update y grid lines.
  120. * @function ygrids
  121. * @instance
  122. * @memberof Chart
  123. * @param {Array} grids Y grid lines will be replaced with this argument. The format of this argument is the same as grid.y.lines.
  124. * @returns {object}
  125. * @example
  126. * // Show 2 y grid lines
  127. * chart.ygrids([
  128. * {value: 100, text: "Label 1"},
  129. * {value: 400, text: "Label 4"}
  130. * ]);
  131. * // --> Returns: [{value: 100, text: "Label 1"}, {value: 400, text: "Label 4"}]
  132. */
  133. const ygrids = function(grids: GridsParam): GridsParam {
  134. return grid.bind(this)(grids, "y");
  135. };
  136. extend(ygrids, {
  137. /**
  138. * Add y grid lines.<br>
  139. * This API adds new y grid lines instead of replacing like ygrids.
  140. * @function ygrids․add
  141. * @instance
  142. * @memberof Chart
  143. * @param {Array|object} grids New y grid lines will be added. The format of this argument is the same as grid.y.lines and it's possible to give an Object if only one line will be added.
  144. * @returns {object}
  145. * @example
  146. * // Add a new x grid line
  147. * chart.ygrids.add(
  148. * {value: 400, text: "Label 4"}
  149. * );
  150. *
  151. * // Add new x grid lines
  152. * chart.ygrids.add([
  153. * {value: 200, text: "Label 2"},
  154. * {value: 400, text: "Label 4"}
  155. * ]);
  156. */
  157. add(grids: GridsParam): GridsParam {
  158. return add.bind(this)(grids, "y");
  159. },
  160. /**
  161. * Remove y grid lines.<br>
  162. * This API removes x grid lines.
  163. * @function ygrids․remove
  164. * @instance
  165. * @memberof Chart
  166. * @param {object} grids This argument should include value or class. If value is given, the y grid lines that have specified y value will be removed. If class is given, the y grid lines that have specified class will be removed. If args is not given, all of y grid lines will be removed.
  167. * @param {number} [grids.value] target value
  168. * @param {string} [grids.class] target class
  169. * @returns {void}
  170. * @example
  171. * // y grid line on y = 200 will be removed
  172. * chart.ygrids.remove({value: 200});
  173. *
  174. * // y grid lines that have 'grid-A' will be removed
  175. * chart.ygrids.remove({
  176. * class: "grid-A"
  177. * });
  178. *
  179. * // all of y grid lines will be removed
  180. * chart.ygrids.remove();
  181. */
  182. remove(grids?: GridsParam): void { // TODO: multiple
  183. return remove.bind(this)(grids, false);
  184. }
  185. });
  186. export default {xgrids, ygrids};