Chart/api/regions.ts

  1. /**
  2.  * Copyright (c) 2017 ~ present NAVER Corp.
  3.  * billboard.js project is licensed under the MIT license
  4.  */
  5. import {$REGION} from "../../config/classes";
  6. import {extend, getOption, isTabVisible} from "../../module/util";
  8. type RegionsParam = {axis?: "add" | "update", class?: string, start?: number, end?: number}[];
  10. /**
  11.  * Region add/update function
  12.  * @param {Array} regions Regions will be replaced with this argument. The format of this argument is the same as regions.
  13.  * @param {boolean} isAdd If true, add new regions, otherwise update regions
  14.  * @returns {Array} regions
  15.  * @private
  16.  */
  17. function regionsFn(regions: RegionsParam, isAdd = false): RegionsParam {
  18. 	const $$ = this.internal;
  19. 	const {config} = $$;
  20. 	const withTransition = config.transition_duration && isTabVisible();
  22. 	if (!regions) {
  23. 		return config.regions;
  24. 	}
  26. 	config.regions = isAdd ? config.regions.concat(regions) : regions;
  28. 	$$.updateRegion();
  29. 	$$.redrawRegion(withTransition);
  31. 	return isAdd ? config.regions : regions;
  32. }
  34. /**
  35.  * Update regions.
  36.  * @function regions
  37.  * @instance
  38.  * @memberof Chart
  39.  * @param {Array} regions Regions will be replaced with this argument. The format of this argument is the same as [regions](./Options.html#.regions) option.
  40.  * @returns {Array} regions
  41.  * @example
  42.  * // Show 2 regions
  43.  * chart.regions([
  44.  *    {axis: "x", start: 5, class: "regionX"},
  45.  *    {
  46.  *      axis: "y", end: 50, class: "regionY",
  47.  *      label: {
  48.  *      	text: "Region Text",
  49.  *      	x: 5,  // position relative of the initial x coordinate
  50.  *      	y: 5,  // position relative of the initial y coordinate
  51.  *      	color: "red",  // color string
  52.  *      	rotated: true  // make text to show in vertical or horizontal
  53.  *      }
  54.  *    }
  55.  * ]);
  56.  */
  57. const regions = function(regions: RegionsParam): RegionsParam {
  58. 	return regionsFn.bind(this)(regions);
  59. };
  61. extend(regions, {
  62. 	/**
  63. 	 * Add new region.<br><br>
  64. 	 * This API adds new region instead of replacing like regions.
  65. 	 * @function regions․add
  66. 	 * @instance
  67. 	 * @memberof Chart
  68. 	 * @param {Array|object} regions New region will be added. The format of this argument is the same as [regions](./Options.html#.regions) and it's possible to give an Object if only one region will be added.
  69. 	 * @returns {Array} regions
  70. 	 * @example
  71. 	 * // Add a new region
  72. 	 * chart.regions.add(
  73. 	 *    {
  74. 	 *      axis: "x", start: 5, class: "regionX",
  75. 	 *      label: {
  76. 	 *      	text: "Region Text",
  77. 	 *      	color: "red"  // color string
  78. 	 *      }
  79. 	 *    }
  80. 	 * );
  81. 	 *
  82. 	 * // Add new regions
  83. 	 * chart.regions.add([
  84. 	 *    {axis: "x", start: 5, class: "regionX"},
  85. 	 *    {
  86. 	 *      axis: "y", end: 50, class: "regionY",
  87. 	 *      label: {
  88. 	 *      	text: "Region Text",
  89. 	 *      	x: 5,  // position relative of the initial x coordinate
  90. 	 *      	y: 5,  // position relative of the initial y coordinate
  91. 	 *      	color: "red",  // color string
  92. 	 *      	rotated: true  // make text to show in vertical or horizontal
  93. 	 *      }
  94. 	 *    }
  95. 	 * ]);
  96. 	 */
  97. 	add: function(regions: RegionsParam): RegionsParam {
  98. 		return regionsFn.bind(this)(regions, true);
  99. 	},
  101. 	/**
  102. 	 * Remove regions.<br><br>
  103. 	 * This API removes regions.
  104. 	 * @function regions․remove
  105. 	 * @instance
  106. 	 * @memberof Chart
  107. 	 * @param {object} optionsValue This argument should include classes. If classes is given, the regions that have one of the specified classes will be removed. If args is not given, all of regions will be removed.
  108. 	 * @returns {Array} regions Removed regions
  109. 	 * @example
  110. 	 * // regions that have 'region-A' or 'region-B' will be removed.
  111. 	 * chart.regions.remove({
  112. 	 *   classes: [
  113. 	 *     "region-A", "region-B"
  114. 	 *   ]
  115. 	 * });
  116. 	 *
  117. 	 * // all of regions will be removed.
  118. 	 * chart.regions.remove();
  119. 	 */
  120. 	remove: function(optionsValue: RegionsParam): RegionsParam {
  121. 		const $$ = this.internal;
  122. 		const {config, $T} = $$;
  124. 		const options = optionsValue || {};
  125. 		const classes = getOption(options, "classes", [$REGION.region]);
  126. 		let regions = $$.$el.main.select(`.${$REGION.regions}`)
  127. 			.selectAll(classes.map(c => `.${c}`));
  129. 		$T(regions)
  130. 			.style("opacity", "0")
  131. 			.remove();
  133. 		regions = config.regions;
  135. 		if (Object.keys(options).length) {
  136. 			regions = regions.filter(region => {
  137. 				let found = false;
  139. 				if (!region.class) {
  140. 					return true;
  141. 				}
  143. 				region.class.split(" ").forEach(c => {
  144. 					if (classes.indexOf(c) >= 0) {
  145. 						found = true;
  146. 					}
  147. 				});
  149. 				return !found;
  150. 			});
  152. 			config.regions = regions;
  153. 		} else {
  154. 			config.regions = [];
  155. 		}
  157. 		return regions;
  158. 	}
  159. });
  161. export default {regions};