Chart/api/axis.ts

  1. /**
  2.  * Copyright (c) 2017 ~ present NAVER Corp.
  3.  * billboard.js project is licensed under the MIT license
  4.  */
  5. import {isDefined, isNumber, isObjectType, isValue} from "../../module/util";
  7. type AxisOption = {x?: number | false, y?: number | false, y2?: number | false} | number | false;
  9. type RangeAxisOption = {min?: AxisOption, max?: AxisOption};
  11. /**
  12.  * Set the min/max value
  13.  * @param {Chart} $$ Chart instance
  14.  * @param {string} type Set type 'min' or 'max'
  15.  * @param {object} value Value to be set
  16.  * @private
  17.  */
  18. function setMinMax($$, type: "min" | "max", value: AxisOption): void {
  19. 	const {config} = $$;
  20. 	const helper = (key, value) => {
  21. 		const v = isNumber(value) ? value : (
  22. 			value === false ? undefined : null
  23. 		);
  25. 		if (v !== null) {
  26. 			config[`axis_${key}_${type}`] = v;
  27. 		}
  28. 	};
  30. 	if (isDefined(value)) {
  31. 		if (isObjectType(value)) {
  32. 			Object.keys(value).forEach(key => {
  33. 				helper(key, value[key]);
  34. 			});
  35. 		} else if (isNumber(value) || value === false) {
  36. 			// shorthand values affects only y and y2.
  37. 			["y", "y2"].forEach(key => {
  38. 				helper(key, value);
  39. 			});
  40. 		}
  42. 		$$.redraw({
  43. 			withUpdateOrgXDomain: true,
  44. 			withUpdateXDomain: true
  45. 		});
  46. 	}
  47. }
  49. /**
  50.  * Get the min/max value
  51.  * @param {Chart} $$ Chart instance
  52.  * @param {string} type Set type 'min' or 'max'
  53.  * @returns {{x, y, y2}}
  54.  * @private
  55.  */
  56. function getMinMax($$, type: "min" | "max"): {x: number, y: number, y2: number} {
  57. 	const {config} = $$;
  59. 	return {
  60. 		x: config[`axis_x_${type}`],
  61. 		y: config[`axis_y_${type}`],
  62. 		y2: config[`axis_y2_${type}`]
  63. 	};
  64. }
  66. /**
  67.  * Define axis
  68.  * @ignore
  69.  */
  70. const axis = {
  71. 	/**
  72. 	 * Get and set axis labels.
  73. 	 * - **NOTE:** Only applicable for chart types which has x and y axes.
  74. 	 * @function axis․labels
  75. 	 * @instance
  76. 	 * @memberof Chart
  77. 	 * @param {object} labels specified axis' label to be updated.
  78. 	 * @param {string} [labels.x] x Axis string
  79. 	 * @param {string} [labels.y] y Axis string
  80. 	 * @param {string} [labels.y2] y2 Axis string
  81. 	 * @returns {object|undefined} axis labels text object
  82. 	 * @example
  83. 	 * // Update axis' label
  84. 	 * chart.axis.labels({
  85. 	 *   x: "New X Axis Label",
  86. 	 *   y: "New Y Axis Label",
  87. 	 *   y2: "New Y2 Axis Label"
  88. 	 * });
  89. 	 *
  90. 	 * chart.axis.labels();
  91. 	 * // --> {
  92. 	 * //  x: "New X Axis Label",
  93. 	 * //  y: "New Y Axis Label",
  94. 	 * //  y2: "New Y2 Axis Label"
  95. 	 * // }
  96. 	 */
  97. 	labels: function<T>(labels?: {x?: string, y?: string, y2?: string}): T | undefined {
  98. 		const $$ = this.internal;
  99. 		let labelText;
  101. 		if (labels) {
  102. 			Object.keys(labels).forEach(axisId => {
  103. 				$$.axis.setLabelText(axisId, labels[axisId]);
  104. 			});
  106. 			$$.axis.updateLabels();
  107. 		}
  109. 		["x", "y", "y2"].forEach(v => {
  110. 			const text = $$.axis.getLabelText(v);
  112. 			if (text) {
  113. 				!labelText && (labelText = {});
  114. 				labelText[v] = text;
  115. 			}
  116. 		});
  118. 		return <T>labelText;
  119. 	},
  121. 	/**
  122. 	 * Get and set axis min value.
  123. 	 * - **NOTE:** Only applicable for chart types which has x and y axes.
  124. 	 * @function axis․min
  125. 	 * @instance
  126. 	 * @memberof Chart
  127. 	 * @param {object} min If min is given, specified axis' min value will be updated.<br>
  128. 	 *   If no argument is given, the min values set on generating option for each axis will be returned.
  129. 	 *   If not set any min values on generation, it will return `undefined`.<br>
  130. 	 *   To unset specific axis max, set `false` to each of them.
  131. 	 * @returns {object|undefined}
  132. 	 * @example
  133. 	 * // Update axis' min
  134. 	 * chart.axis.min({
  135. 	 *   x: -10,
  136. 	 *   y: 1000,
  137. 	 *   y2: 100
  138. 	 * });
  139. 	 *
  140. 	 * // To unset specific axis min, set false to each of them.
  141. 	 * chart.axis.min({
  142. 	 *   x: false,
  143. 	 *   y: false,
  144. 	 *   y2: false
  145. 	 * });
  146. 	 *
  147. 	 * // shorthand (only affects y and y2 axis)
  148. 	 * chart.axis.min(-50);
  149. 	 * chart.axis.min(false);
  150. 	 */
  151. 	min: function(min?: AxisOption): object | void {
  152. 		const $$ = this.internal;
  154. 		return isValue(min) || min === false ?
  155. 			setMinMax($$, "min", min as AxisOption) :
  156. 			getMinMax($$, "min");
  157. 	},
  159. 	/**
  160. 	 * Get and set axis max value.
  161. 	 * - **NOTE:** Only applicable for chart types which has x and y axes.
  162. 	 * @function axis․max
  163. 	 * @instance
  164. 	 * @memberof Chart
  165. 	 * @param {object} max If max is given, specified axis' max value will be updated.<br>
  166. 	 *   If no argument is given, the max values set on generating option for each axis will be returned.
  167. 	 *   If not set any max values on generation, it will return `undefined`.<br>
  168. 	 *   To unset specific axis max, set `false` to each of them.
  169. 	 * @returns {object|undefined}
  170. 	 * @example
  171. 	 * // Update axis' label
  172. 	 * chart.axis.max({
  173. 	 *    x: 100,
  174. 	 *    y: 1000,
  175. 	 *    y2: 10000
  176. 	 * });
  177. 	 *
  178. 	 * // To unset specific axis max, set false to each of them.
  179. 	 * chart.axis.max({
  180. 	 *   x: false,
  181. 	 *   y: false,
  182. 	 *   y2: false
  183. 	 * });
  184. 	 *
  185. 	 * // shorthand (only affects y and y2 axis)
  186. 	 * chart.axis.max(10);
  187. 	 * chart.axis.max(false);
  188. 	 */
  189. 	max: function(max?: AxisOption): object | void {
  190. 		const $$ = this.internal;
  192. 		return isValue(max) || max === false ?
  193. 			setMinMax($$, "max", max as AxisOption) :
  194. 			getMinMax($$, "max");
  195. 	},
  197. 	/**
  198. 	 * Get and set axis min and max value.
  199. 	 * - **NOTE:** Only applicable for chart types which has x and y axes.
  200. 	 * @function axis․range
  201. 	 * @instance
  202. 	 * @memberof Chart
  203. 	 * @param {object} range If range is given, specified axis' min and max value will be updated.
  204. 	 *   If no argument is given, the current min and max values for each axis will be returned.<br>
  205. 	 *   To unset specific axis max, set `false` to each of them.
  206. 	 * @returns {object|undefined}
  207. 	 * @example
  208. 	 * // Update axis' label
  209. 	 * chart.axis.range({
  210. 	 *   min: {
  211. 	 *     x: -10,
  212. 	 *     y: -1000,
  213. 	 *     y2: -10000
  214. 	 *   },
  215. 	 *   max: {
  216. 	 *     x: 100,
  217. 	 *     y: 1000,
  218. 	 *     y2: 10000
  219. 	 *   },
  220. 	 * });
  221. 	 *
  222. 	 * // To unset specific axis max, set false to each of them.
  223. 	 * chart.axis.range({
  224. 	 *   min: {
  225. 	 *     x: false,
  226. 	 *     y: false,
  227. 	 *     y2: false
  228. 	 *   },
  229. 	 *   max: {
  230. 	 *     x: false,
  231. 	 *     y: false,
  232. 	 *     y2: false
  233. 	 *   },
  234. 	 * });
  235. 	 *
  236. 	 * // shorthand (only affects y and y2 axis)
  237. 	 * chart.axis.range({ min: -50, max: 1000 });
  238. 	 * chart.axis.range({ min: false, max: false });
  239. 	 */
  240. 	range: function(range: RangeAxisOption): object | void {
  241. 		const {axis} = this;
  243. 		if (arguments.length) {
  244. 			const {min, max} = range;
  246. 			isDefined(max) && axis.max(max);
  247. 			isDefined(min) && axis.min(min);
  248. 		} else {
  249. 			return {
  250. 				max: axis.max(),
  251. 				min: axis.min()
  252. 			};
  253. 		}
  255. 		return undefined;
  256. 	}
  257. };
  259. export default {axis};