Chart/api/zoom.ts

  1. /**
  2.  * Copyright (c) 2017 ~ present NAVER Corp.
  3.  * billboard.js project is licensed under the MIT license
  4.  */
  5. import {zoomIdentity as d3ZoomIdentity, zoomTransform as d3ZoomTransform} from "d3-zoom";
  6. import type {TDomainRange} from "../../ChartInternal/data/IData";
  7. import {extend, getMinMax, isDefined, isObject, parseDate} from "../../module/util";
  9. /**
  10.  * Zoom by giving x domain range.
  11.  * - **ℹ️ NOTE:**
  12.  *  - For `wheel` type zoom, the minimum zoom range will be set as the given domain range. To get the initial state, [.unzoom()](#unzoom) should be called.
  13.  *  - To be used [zoom.enabled](Options.html#.zoom) option should be set as `truthy`.
  14.  *  - When x axis type is `category`, domain range should be specified as index numbers.
  15.  *  - Due to the limitations of floating point precision, domain value may not be exact returning approximately values.
  16.  * @function zoom
  17.  * @instance
  18.  * @memberof Chart
  19.  * @param {Array} domainValue If domain range is given, the chart will be zoomed to the given domain. If no argument is given, the current zoomed domain will be returned.
  20.  * @returns {Array} domain value in array
  21.  * @example
  22.  *  // Zoom to specified domain range
  23.  *  chart.zoom([10, 20]);
  24.  *
  25.  *  // For timeseries x axis, the domain value can be string, but the format should match with the 'data.xFormat' option.
  26.  *  chart.zoom(["2021-02-03", "2021-02-08"]);
  27.  *
  28.  *  // For category x axis, the domain value should be index number.
  29.  *  chart.zoom([0, 3]);
  30.  *
  31.  *  // Get the current zoomed domain range
  32.  *  // Domain value may not be exact returning approximately values.
  33.  *  chart.zoom();
  34.  */
  35. // NOTE: declared funciton assigning to variable to prevent duplicated method generation in JSDoc.
  36. const zoom = function<T = TDomainRange>(domainValue?: T): T | undefined {
  37. 	const $$ = this.internal;
  38. 	const {axis, config, org, scale, state} = $$;
  39. 	const isCategorized = axis.isCategorized();
  40. 	let domain;
  42. 	if (config.zoom_enabled) {
  43. 		domain = domainValue;
  45. 		if (Array.isArray(domain)) {
  46. 			if (axis.isTimeSeries()) {
  47. 				domain = domain.map(x => parseDate.bind($$)(x));
  48. 			}
  50. 			const isWithinRange = $$.withinRange(
  51. 				domain,
  52. 				$$.getZoomDomain("zoom", true),
  53. 				$$.getZoomDomain("zoom")
  54. 			);
  56. 			if (isWithinRange) {
  57. 				state.domain = domain;
  59. 				domain = $$.getZoomDomainValue(domain);
  61. 				// hide any possible tooltip show before the zoom
  62. 				$$.api.tooltip.hide();
  64. 				if (config.subchart_show) {
  65. 					const x = scale.zoom || scale.x;
  67. 					$$.brush.getSelection().call($$.brush.move, domain.map(x));
  68. 					// resultDomain = domain;
  69. 				} else {
  70. 					// in case of 'config.zoom_rescale=true', use org.xScale
  71. 					const x = isCategorized ? scale.x.orgScale() : (org.xScale || scale.x);
  73. 					$$.updateCurrentZoomTransform(x, domain);
  74. 				}
  76. 				$$.setZoomResetButton();
  77. 			}
  78. 		} else {
  79. 			domain = $$.zoom.getDomain();
  80. 		}
  81. 	}
  83. 	return state.domain ?? domain;
  84. };
  86. extend(zoom, {
  87. 	/**
  88. 	 * Enable and disable zooming.
  89. 	 * @function zoom․enable
  90. 	 * @instance
  91. 	 * @memberof Chart
  92. 	 * @param {string|boolean} enabled Possible string values are "wheel" or "drag". If enabled is true, "wheel" will be used. If false is given, zooming will be disabled.<br>When set to false, the current zooming status will be reset.
  93. 	 * @example
  94. 	 *  // Enable zooming using the mouse wheel
  95. 	 *  chart.zoom.enable(true);
  96. 	 *  // Or
  97. 	 *  chart.zoom.enable("wheel");
  98. 	 *
  99. 	 *  // Enable zooming by dragging
  100. 	 *  chart.zoom.enable("drag");
  101. 	 *
  102. 	 *  // Disable zooming
  103. 	 *  chart.zoom.enable(false);
  104. 	 */
  105. 	enable(enabled: boolean | "wheel" | "drag" | any): void {
  106. 		const $$ = this.internal;
  107. 		const {config} = $$;
  109. 		if (/^(drag|wheel)$/.test(enabled)) {
  110. 			config.zoom_type = enabled;
  111. 		}
  113. 		config.zoom_enabled = !!enabled;
  115. 		if (!$$.zoom) {
  116. 			$$.initZoom();
  117. 			$$.bindZoomEvent();
  118. 		} else if (enabled === false) {
  119. 			$$.bindZoomEvent(false);
  120. 		}
  122. 		$$.updateAndRedraw();
  123. 	},
  125. 	/**
  126. 	 * Set or get x Axis maximum zoom range value
  127. 	 * @function zoom․max
  128. 	 * @instance
  129. 	 * @memberof Chart
  130. 	 * @param {number} [max] maximum value to set for zoom
  131. 	 * @returns {number} zoom max value
  132. 	 * @example
  133. 	 *  // Set maximum range value
  134. 	 *  chart.zoom.max(20);
  135. 	 */
  136. 	max(max?: number): number {
  137. 		const $$ = this.internal;
  138. 		const {config, org: {xDomain}} = $$;
  140. 		if (max === 0 || max) {
  141. 			config.zoom_x_max = getMinMax("max", [xDomain[1], max]);
  142. 		}
  144. 		return config.zoom_x_max;
  145. 	},
  147. 	/**
  148. 	 * Set or get x Axis minimum zoom range value
  149. 	 * @function zoom․min
  150. 	 * @instance
  151. 	 * @memberof Chart
  152. 	 * @param {number} [min] minimum value to set for zoom
  153. 	 * @returns {number} zoom min value
  154. 	 * @example
  155. 	 *  // Set minimum range value
  156. 	 *  chart.zoom.min(-1);
  157. 	 */
  158. 	min(min?: number): number {
  159. 		const $$ = this.internal;
  160. 		const {config, org: {xDomain}} = $$;
  162. 		if (min === 0 || min) {
  163. 			config.zoom_x_min = getMinMax("min", [xDomain[0], min]);
  164. 		}
  166. 		return config.zoom_x_min;
  167. 	},
  169. 	/**
  170. 	 * Set zoom range
  171. 	 * @function zoom․range
  172. 	 * @instance
  173. 	 * @memberof Chart
  174. 	 * @param {object} [range] zoom range
  175. 	 * @returns {object} zoom range value
  176. 	 * {
  177. 	 *   min: 0,
  178. 	 *   max: 100
  179. 	 * }
  180. 	 * @example
  181. 	 *  chart.zoom.range({
  182. 	 *      min: 10,
  183. 	 *      max: 100
  184. 	 *  });
  185. 	 */
  186. 	range(range): {min: (number | undefined)[], max: (number | undefined)[]} {
  187. 		const zoom = this.zoom;
  189. 		if (isObject(range)) {
  190. 			const {min, max} = range;
  192. 			isDefined(min) && zoom.min(min);
  193. 			isDefined(max) && zoom.max(max);
  194. 		}
  196. 		return {
  197. 			min: zoom.min(),
  198. 			max: zoom.max()
  199. 		};
  200. 	}
  201. });
  203. export default {
  204. 	zoom,
  206. 	/**
  207. 	 * Unzoom zoomed area
  208. 	 * - **NOTE:** Calling .unzoom() will not trigger zoom events.
  209. 	 * @function unzoom
  210. 	 * @instance
  211. 	 * @memberof Chart
  212. 	 * @example
  213. 	 *  chart.unzoom();
  214. 	 */
  215. 	unzoom(): void {
  216. 		const $$ = this.internal;
  217. 		const {config, $el: {eventRect, zoomResetBtn}, scale: {zoom}, state} = $$;
  219. 		if (zoom) {
  220. 			config.subchart_show ?
  221. 				$$.brush.getSelection().call($$.brush.move, null) :
  222. 				$$.zoom.updateTransformScale(d3ZoomIdentity);
  224. 			$$.updateZoom(true);
  225. 			zoomResetBtn?.style("display", "none");
  227. 			// reset transform
  228. 			if (d3ZoomTransform(eventRect.node()) !== d3ZoomIdentity) {
  229. 				$$.zoom.transform(eventRect, d3ZoomIdentity);
  230. 			}
  232. 			state.domain = undefined;
  233. 		}
  234. 	}
  235. };