| {"$schema":"http://echarts.baidu.com/doc/json-schem","option":{"type":"Object","properties":{"Get Started with ECharts in 5 minutes":{"type":["*"],"description":"<h2 id=\"installing-echarts\">Installing ECharts</h2>\n<p>First, install ECharts using one of the following methods:</p>\n<ul>\n<li><p>The <a href=\"https://ecomfe.github.io/echarts-doc/public/en/download.html\" target=\"_blank\">official download page</a>, has different builds for most common use cases. If you would like to include all packages, you can download <a href=\"http://echarts.baidu.com/dist/echarts.min.js\" target=\"_blank\">the full minified version</a>.</p>\n</li>\n<li><p>From the latest <a href=\"https://github.com/ecomfe/echarts\" target=\"_blank\">GitHub</a> release, you can find the latest version of echarts in <code>dist</code> directory of the unzipped files.</p>\n</li>\n<li><p>Using npm: <code>npm install echarts --save</code>. <a href=\"https://ecomfe.github.io/echarts-doc/public/en/tutorial.html#Use%20ECharts%20with%20webpack\" target=\"_blank\">Using ECharts with webpack</a></p>\n</li>\n<li><p>Using the <a href=\"http://echarts.baidu.com/builder.html\" target=\"_blank\">online build tool</a> (Currently available in Chinese only).</p>\n</li>\n</ul>\n<h2 id=\"including-echarts\">Including ECharts</h2>\n<p>ECharts 3 no longer requires using AMD to load packages, and the AMD loader is no longer included in ECharts. Instead, ECharts should be included using a traditional <code><script></code> tag:</p>\n<pre><code class=\"lang-html\"><!DOCTYPE html>\n<html>\n<head>\n <meta charset="utf-8">\n <!-- including ECharts file -->\n <script src="echarts.min.js"></script>\n</head>\n</html>\n</code></pre>\n<h2 id=\"draw-a-simple-chart\">Draw a simple chart</h2>\n<p>Before drawing charts, we need to prepare a DOM container with width and height for ECharts.</p>\n<pre><code><body>\n <!-- preparing a DOM with width and height for ECharts -->\n <div id="main" style="width:600px; height:400px;"></div>\n</body>\n</code></pre><p>Then we can initialize an ECharts instance using <a href=\"api.html#echarts.init\" target=\"_blank\">echarts.init</a>, and create a simple bar chart with <a href=\"api.html#echartsInstance.setOption\" target=\"_blank\">setOption</a>. Below is the complete code.</p>\n<pre><code class=\"lang-html\"><!DOCTYPE html>\n<html>\n<head>\n <meta charset="utf-8">\n <title>ECharts</title>\n <!-- including ECharts file -->\n <script src="echarts.js"></script>\n</head>\n<body>\n <!-- prepare a DOM container with width and height -->\n <div id="main" style="width: 600px;height:400px;"></div>\n <script type="text/javascript">\n // based on prepared DOM, initialize echarts instance\n var myChart = echarts.init(document.getElementById('main'));\n\n // specify chart configuration item and data\n var option = {\n title: {\n text: 'ECharts entry example'\n },\n tooltip: {},\n legend: {\n data:['Sales']\n },\n xAxis: {\n data: ["shirt","cardign","chiffon shirt","pants","heels","socks"]\n },\n yAxis: {},\n series: [{\n name: 'Sales',\n type: 'bar',\n data: [5, 20, 36, 10, 10, 20]\n }]\n };\n\n // use configuration item and data specified to show chart\n myChart.setOption(option);\n </script>\n</body>\n</html>\n</code></pre>\n<p>You've made your first chart!</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/getting-started&reset=1&edit=1\" width=\"600\" height=\"300\" ></iframe>\n\n\n<p>For more examples, go to the <a href=\"https://www.echartsjs.com/examples/en/editor.html?c=doc-example/getting-started\" target=\"_blank\">ECharts Gallery</a></p>\n"},"Create Custom Build of ECharts":{"type":["*"],"description":"<p>In most cases, ECharts builds can be downloaded from the <a href=\"https://ecomfe.github.io/echarts-doc/public/en/download.html\" target=\"_blank\">download page</a> or from the <code>echarts/dist</code> directory in our <a href=\"https://github.com/ecomfe/echarts/releases\" target=\"_blank\">GitHub project</a>, where\nthese pre-builds are provided:</p>\n<ul>\n<li>Complete verion: <code>echarts/dist/echarts.js</code>, including all charts and components (see <code>echarts/echarts.all.js</code> for detail), but has maximum file size.</li>\n<li>Common version: <code>echarts/dist/echarts.common.js</code>, including common charts and components (see <code>echarts/echarts.common.js</code> for detail), moderate file size.</li>\n<li>Simple version: <code>echarts/dist/echarts.simple.js</code>, including a smaller subset of the most common charts and components (see <code>echarts/echarts.simple.js</code> for detail), small file size.</li>\n</ul>\n<p>If it is important for your use case to reduce the size of your ECharts dependency, you can customize your ECharts build by using one of these approaches:</p>\n<ul>\n<li><a href=\"http://echarts.baidu.com/builder.html\" target=\"_blank\">Online custom build tool</a> is relatively convenient (Currently available in Chinese only)</li>\n<li>The script <code>echarts/build/build.js</code> found in the project is flexible for module selecting, and supports multi-language builds</li>\n<li>Build ECharts and your project directly by using tools such as <a href=\"https://rollupjs.org/\" target=\"_blank\">rollup</a>, <a href=\"https://webpack.github.io/\" target=\"_blank\">webpack</a>, <a href=\"http://browserify.org/\" target=\"_blank\">browserify</a></li>\n</ul>\n<p>Below are some examples to illustrate the latter two approaches.</p>\n<h2 id=\"prepare-create-our-project-and-install-echarts\">Prepare: create our project and install echarts</h2>\n<p>Create a sample project using the command line</p>\n<pre><code class=\"lang-shell\">mkdir myProject\ncd myProject\n</code></pre>\n<p>Then in the <code>myProject</code> directory, initialize <a href=\"https://www.npmjs.com/\" target=\"_blank\">npm</a> environment and install echarts (assume that <a href=\"https://www.npmjs.com/\" target=\"_blank\">npm</a> has been installed):</p>\n<pre><code class=\"lang-shell\">npm init\nnpm install echarts --save\n</code></pre>\n<p>The installed echarts is in the <code>myProject/node_modules</code> directory, which can be used in our project directly. For example:</p>\n<p>Use ES Module:</p>\n<pre><code class=\"lang-js\">import * as echarts from 'echarts';\n</code></pre>\n<p>Use CommonJS:</p>\n<pre><code class=\"lang-js\">var echarts = require('echarts')\n</code></pre>\n<p>Next, we just describe our examples in ES Module way.</p>\n<h2 id=\"create-custom-build-by-echarts-build-build-js-\">Create custom build by <code>echarts/build/build.js</code></h2>\n<p>In this example, for minimizing file size, we will build a echarts bundle with only pie chart included, and create a web page to show it.</p>\n<p>echarts has provided a script <code>echarts/build/build.js</code> as a build tool (<a href=\"https://nodejs.org\" target=\"_blank\">Node.js</a> is required to execute it). Now we can use the command below in the <code>myProject</code> directory to check its help info:</p>\n<pre><code class=\"lang-shell\">node node_modules/echarts/build/build.js --help\n</code></pre>\n<p>These options can be used in this example:</p>\n<ul>\n<li><code>-i</code>: Entry file of the echarts code. Can be an absolute path or a relative path relative to the current working directory.</li>\n<li><code>-o</code>: The bundle file path. Can be an absolute path or a relative path relative to the current working directory.</li>\n<li><code>--min</code>: Whether to compress file (not by default), and remove the code that is for printing error and warning info.</li>\n<li><code>--lang <language shortcut or file path></code>: Whether to use the specified language (Chinese by default). For example: <code>--lang en</code> means using English, <code>--lang my/langXX.js</code> means using <code><cwd>/my/langXX.js</code> to substitute <code>echarts/lib/lang.js</code> while buiding.</li>\n<li><code>--sourcemap</code>: Whether to output source map, which is useful in debug.</li>\n<li><code>--format</code>: The format of output. Can be <code>'umb'</code>(default), <code>'amd'</code>, <code>'iife'</code>, <code>'cjs'</code>, <code>'es'</code>.</li>\n</ul>\n<p>Now we want to create a echarts bundle that only supports pie chart, we should firstly create an entry file (say <code>myProject/echarts.custom.js</code>) to import modules we need:</p>\n<pre><code class=\"lang-js\">// Import the main module of echarts and export them.\nexport * from 'echarts/src/echarts';\n// Import pie chart.\nimport 'echarts/src/chart/pie';\n// In this case, modules in either `echarts/src` or `echarts/lib`\n// can be imported (but should not be mixed). See\n// "Use `echarts/lib/**` or `echarts/src/**`" below.\n</code></pre>\n<p>Then we can use command below in <code>myProject</code> directory to build the bundle:</p>\n<pre><code class=\"lang-shell\">node node_modules/echarts/build/build.js --min -i echarts.custom.js -o lib/echarts.custom.min.js --lang en\n</code></pre>\n<p>Now the bundle <code>myProject/lib/echarts.custom.min.js</code> has been created. Then we can create a web page (say <code>myProject/pie.html</code>) to test it:</p>\n<pre><code class=\"lang-html\"><!DOCTYPE html>\n<html>\n<head>\n <meta charset="utf-8">\n <title>myProject</title>\n <!-- import the bundle `lib/echarts.custom.js`. -->\n <script src="lib/echarts.custom.js"></script>\n</head>\n<body>\n <div id="main" style="width: 600px;height:400px;"></div>\n <script>\n // Create a pie chart:\n echarts.init(document.getElementById('main')).setOption({\n series: {\n type: 'pie',\n data: [\n {name: 'A', value: 1212},\n {name: 'B', value: 2323},\n {name: 'C', value: 1919}\n ]\n }\n });\n </script>\n</body>\n</html>\n</code></pre>\n<p>Open <code>myProject/pie.html</code> in a browser, we can see the pie chart:</p>\n<p><img width=\"300\" height=\"auto\" src=\"documents/asset/img/custom-build-pie.png\"></p>\n<h2 id=\"modules-that-are-permitted-to-be-imported\">Modules that are permitted to be imported</h2>\n<p>All of the permitted modules are declared in <a href=\"https://github.com/ecomfe/echarts/blob/master/echarts.all.js\" target=\"_blank\"><code>myProject/node_module/echarts/echarts.all.js</code></a> and <a href=\"https://github.com/ecomfe/echarts/blob/master/src/export.js\" target=\"_blank\"><code>myProject/node_module/echarts/src/export.js</code></a>. Other modules in the source code of echarts and zrender <strong>SHOULD NOT BE IMPORTED</strong>, because they are inner modules, whose interfaces and functionalities may be modified in the subsequent upgrades of echarts.</p>\n<h2 id=\"use-echarts-lib-or-echarts-src-\">Use <code>echarts/lib/**</code> or <code>echarts/src/**</code>?</h2>\n<ul>\n<li>If intending to import part of echarts modules in your project and build yourself, only <code>echarts/lib/**</code> can be used, <code>echarts/src/**</code> should not be used.</li>\n<li>If using <code>echarts/build/build.js</code> to make a bundle, either <code>echarts/lib/**</code> or <code>echarts/src/**</code> can be used (should not be mixed), where <code>echarts/src/**</code> brings smaller bundle size a little.</li>\n</ul>\n<blockquote>\n<p>Reason: currently, <code>echarts/src/**</code> is the source code that using ES Module, and they are transpiled to CommonJS code and placed in <code>echarts/lib/**</code>. (This transformation is for backward compatible with old version of NodeJS and webpack that do not support ES Module.)\nHistorically, echarts extensions and user projects have been using the package path <code>echarts/lib/**</code>. So it should not be changed, otherwise, mixed using both <code>echarts/src/**</code> and <code>echarts/lib/**</code> will generate two echarts namespace and bring some problems. But it is not an issue when using <code>echarts/build/build.js</code> to create a bundle, where ES modules in <code>echarts/src/**</code> can be analyzed statically for smaller bundle size.</p>\n</blockquote>\n<h2 id=\"build-echarts-and-our-project-directly-by-rollup\">Build echarts and our project directly by rollup</h2>\n<p>Now we have known that how to create custom build by <code>echarts/build/build.js</code>. Alternatively, we can bundle echarts and our project directly by the tool like <a href=\"https://rollupjs.org/\" target=\"_blank\">rollup</a>, <a href=\"https://webpack.github.io/\" target=\"_blank\">webpack</a> or <a href=\"http://browserify.org/\" target=\"_blank\">browserify</a>. In some project, this approach is required. Next we only go with <a href=\"https://rollupjs.org/\" target=\"_blank\">rollup</a>, because <a href=\"https://webpack.github.io/\" target=\"_blank\">webpack</a> and <a href=\"http://browserify.org/\" target=\"_blank\">browserify</a> are in the similar way.</p>\n<p>Firstly install <a href=\"https://rollupjs.org/\" target=\"_blank\">rollup</a> in <code>myProject</code> directory:</p>\n<pre><code class=\"lang-shell\">npm install rollup --save-dev\nnpm install rollup-plugin-node-resolve --save-dev\nnpm install rollup-plugin-uglify --save-dev\n</code></pre>\n<p>Then we create a project JS file <code>myProject/line.js</code> for line chart rendering:</p>\n<pre><code class=\"lang-js\">// Import the main module of echarts.\nimport * as echarts from 'echarts/lib/echarts';\n// Import line chart.\nimport 'echarts/lib/chart/line';\n// Import components of tooltip, title and toolbox.\nimport 'echarts/lib/component/tooltip';\nimport 'echarts/lib/component/title';\nimport 'echarts/lib/component/toolbox';\n\n// Render line chart and components.\necharts.init(document.getElementById('main')).setOption({\n title: {text: 'Line Chart'},\n tooltip: {},\n toolbox: {\n feature: {\n dataView: {},\n saveAsImage: {\n pixelRatio: 2\n },\n restore: {}\n }\n },\n xAxis: {},\n yAxis: {},\n series: [{\n type: 'line',\n smooth: true,\n data: [[12, 5], [24, 20], [36, 36], [48, 10], [60, 10], [72, 20]]\n }]\n});\n</code></pre>\n<p>The created module <code>myProject/line.js</code> can not work directly in the browsers that do not support ES Module. So we need to build them. Before we run <a href=\"https://rollupjs.org/\" target=\"_blank\">rollup</a>, a config file <code>myProject/rollup.config.js</code> should be created:</p>\n<pre><code class=\"lang-js\">// Responsible for looking for modules in `node_module` directory. For example,\n// if there is code `import 'echarts/lib/chart/line';`, the module file\n// `node_module/echarts/lib/chart/line.js` can be find by this plugin.\nimport nodeResolve from 'rollup-plugin-node-resolve';\n// Responsible for compress code.\nimport uglify from 'rollup-plugin-uglify';\n// Support multi-language.\nimport ecLangPlugin from 'echarts/build/rollup-plugin-ec-lang';\n\nexport default {\n name: 'myProject',\n // The entry file.\n input: './line.js',\n plugins: [\n nodeResolve(),\n ecLangPlugin({lang: 'en'}), // Use english\n // Remove the snippet in `__DEV__`, which mainly prints error log.\n uglify()\n ],\n output: {\n // Output file in the format of 'umd'.\n format: 'umd',\n // Output source map.\n sourcemap: true,\n // The path of the output bundle.\n file: 'lib/line.min.js'\n }\n};\n</code></pre>\n<p>Then execute the following command in <code>myProject</code> directory to start the build:</p>\n<pre><code class=\"lang-shell\">./node_modules/.bin/rollup -c\n</code></pre>\n<blockquote>\n<p><code>-c</code> indicate <code>rollup</code> to use <code>myProject/rollup.config.js</code> as the config file.</p>\n</blockquote>\n<p>The created bundle <code>myProject/lib/line.min.js</code> includes project code and part of echarts code that we requried. Now we create a web page <code>myProject/line.html</code> to test it:</p>\n<pre><code class=\"lang-html\"><!DOCTYPE html>\n<html>\n<head>\n <meta charset="utf-8">\n <title>myProject</title>\n</head>\n<body>\n <div id="main" style="width: 600px;height:400px;"></div>\n <!-- Import the created bundle: -->\n <script src="lib/line.min.js"></script>\n</body>\n</html>\n</code></pre>\n<p>Open <code>myProject/line.html</code> in a browser, we will get:</p>\n<p><img width=\"500\" height=\"auto\" src=\"documents/asset/img/custom-build-line.png\"></p>\n<h2 id=\"multi-language\">Multi-language</h2>\n<p>In the example above, we can notice that the label of the <code>toolbox</code> component is in English. Essentially any text can be customized by <code>echarts option</code>, but if we want to show label in a certain language by default, we have to specify the language while building the code.</p>\n<p>For example:</p>\n<pre><code class=\"lang-shell\">node node_modules/echarts/build/build.js --min -i echarts.custom.js -o lib/echarts.custom.min.js --lang en\n</code></pre>\n<p>It means that the pre-defined English text is used. Moreover, can be <code>--lang fi</code>.</p>\n<pre><code class=\"lang-shell\">node node_modules/echarts/build/build.js --min -i echarts.custom.js -o lib/echarts.custom.min.js --lang my/langXX.js\n</code></pre>\n<p>It means that <code>myProject/my/langXX.js</code> is used to substitute <code>myProject/node_modules/echarts/lib/lang.js</code> while performing build. So we can customize text in our language in <code>myProject/my/langXX.js</code>. Notice, <code>-o</code> or <code>--output</code> must be specified in the approach.</p>\n<p>Besides, the same lang parameter can be pass to <code>echarts/build/rollup-plugin-ec-lang</code>.</p>\n"},"Use ECharts with webpack":{"type":["*"],"description":"<p><a href=\"https://webpack.github.io/\" target=\"_blank\">Webpack</a> is a popular module packaging tool, which can be used easily to import and packaging ECharts. Here we assume you already have certain understanding about webpack and used it in your project.</p>\n<h2 id=\"use-npm-to-install-echarts\">Use npm to install ECharts</h2>\n<p>Before <code>3.1.1</code> version, ECharts package on npm was maintained by third-party. Since <code>3.1.1</code>, ECharts and zrender on npm are maintained officially by <a href=\"https://github.com/ecomfe/\" target=\"_blank\">EFE</a> team.</p>\n<p>You can use the following command to install ECharts with npm.</p>\n<pre><code class=\"lang-shell\">npm install echarts --save\n</code></pre>\n<h2 id=\"include-echarts\">Include ECharts</h2>\n<p>ECharts and zrender installed by npm will be placed under <code>node_modules</code>. You can obtain echarts directly in project with <code>require('echarts')</code>.</p>\n<pre><code class=\"lang-js\">var echarts = require('echarts');\n\n// initialize echarts instance with prepared DOM\nvar myChart = echarts.init(document.getElementById('main'));\n// draw chart\nmyChart.setOption({\n title: {\n text: 'ECharts entry example'\n },\n tooltip: {},\n xAxis: {\n data: ['shirt', 'cardign', 'chiffon shirt', 'pants', 'heels', 'socks']\n },\n yAxis: {},\n series: [{\n name: 'sales',\n type: 'bar',\n data: [5, 20, 36, 10, 10, 20]\n }]\n});\n</code></pre>\n<h2 id=\"include-echarts-charts-and-components-on-demand\">Include ECharts charts and components on demand</h2>\n<p>By default, <code>require('echarts')</code> returns the whole ECharts package including all charts and components, so the package size is a bit large. If you have a strict demand of package size, you may include packages on demand.</p>\n<p>For example, the code above only uses bar chart, tooltip and title component, so you only need to include these modules, effectively making the package size from more than 400 KB to about 170 KB.</p>\n<pre><code class=\"lang-js\">// include ECharts main module\nvar echarts = require('echarts/lib/echarts');\n// include bar chart\nrequire('echarts/lib/chart/bar');\n// include tooltip and title component\nrequire('echarts/lib/component/tooltip');\nrequire('echarts/lib/component/title');\n\n// initialize echarts instance with prepared DOM\nvar myChart = echarts.init(document.getElementById('main'));\n// draw chart\nmyChart.setOption({\n title: {\n text: 'ECharts introductory example'\n },\n tooltip: {},\n xAxis: {\n data: ['shirt', 'cardign', 'chiffon shirt', 'pants', 'heels', 'socks']\n },\n yAxis: {},\n series: [{\n name: 'sales',\n type: 'bar',\n data: [5, 20, 36, 10, 10, 20]\n }]\n});\n</code></pre>\n<p>Available modules see <a href=\"https://github.com/ecomfe/echarts/blob/master/index.js\" target=\"_blank\">https://github.com/ecomfe/echarts/blob/master/index.js</a></p>\n<p>The same goes for another popular packaging tools <a href=\"http://browserify.org/\" target=\"_blank\">browserify</a>, which will not be introduced again here. Using <a href=\"https://rollupjs.org/\" target=\"_blank\">rollup</a> to make a custom build of echarts is introduced in <a href=\"http://echarts.baidu.com/tutorial.html#Create%20Custom%20Build%20of%20ECharts\" target=\"_blank\">Create Custom Build of ECharts</a></p>\n"},"Customized Chart Styles":{"type":["*"],"description":"<p>ECharts provides a rich amount of configurable items, which can be set in global, series, and data three different levels. Next, let's see an example of how to use ECharts to implement the following Nightingale rose chart:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-styling-step5&edit=1&reset=1\" width=\"500\" height=\"400\" ></iframe>\n\n\n<h2 id=\"drawing-nightingale-rose-chart\">Drawing Nightingale Rose Chart</h2>\n<p><a href=\"#Get%20Started%20with%20ECharts%20in%205%20minutes\">Getting started tutorial</a> introduced how to make a simple bar chart. This time, we are going to make a pie chart. Pie charts use arc length of fans to represent ratio of a certain series in total share. It's data format is simpler than bar chart, because it only contains one dimension without category. Besides, since it's not in rectangular system, it doesn't need <code>xAxis</code>，<code>yAxis</code> either.</p>\n<pre><code class=\"lang-js\">myChart.setOption({\n series : [\n {\n name: 'Reference Page',\n type: 'pie',\n radius: '55%',\n data:[\n {value:400, name:'Searching Engine'},\n {value:335, name:'Direct'},\n {value:310, name:'Email'},\n {value:274, name:'Alliance Advertisement'},\n {value:235, name:'Video Advertisement'}\n ]\n }\n ]\n})\n</code></pre>\n<p>With the above code, we can create a simple pie chart:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-styling-step0&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>Here, the value of <code>data</code> is not a single value, as that of the example in get started. Instead, it's an object containing <code>name</code> and <code>value</code>. Data in ECharts can always be a single value, or a configurable object with name, style and label. You may refer to <a href=\"option.html#series-pie.data\" target=\"_blank\">data</a> for more information.</p>\n<p><a href=\"option.html#series-pie\" target=\"_blank\">Pie charts</a> of EChart can be made into Nightingale rose charts with <a href=\"option.html#series-pie.roseType\" target=\"_blank\">roseType</a> field.</p>\n<pre><code class=\"lang-js\">roseType: 'angle'\n</code></pre>\n<p>Nightingale rose charts use radius to represent data value.</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-styling-step1&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<h2 id=\"configuring-shadow\">Configuring Shadow</h2>\n<p>Commonly used styles of ECharts, like shadow, opacity, color, border-color, border-width, and etc., are set by <a href=\"#series-pie.itemStyle\">itemStyle</a> in series.</p>\n<pre><code class=\"lang-js\">itemStyle: {\n // shadow size\n shadowBlur: 200,\n // horizontal offset of shadow\n shadowOffsetX: 0,\n // vertical offset of shadow\n shadowOffsetY: 0,\n // shadow color\n shadowColor: 'rgba(0, 0, 0, 0.5)'\n}\n</code></pre>\n<p>The effect after added shadow is:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-styling-step2&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>Each <code>itemStyle</code> has <code>emphasis</code> as the highlighted style when mouse hovered. The last example shows the effect of adding shadow by default. But in most situations, we may probably need to add shadow to emphasis when mouse is hovered.</p>\n<pre><code class=\"lang-js\">itemStyle: {\n emphasis: {\n shadowBlur: 200,\n shadowColor: 'rgba(0, 0, 0, 0.5)'\n }\n}\n</code></pre>\n<h2 id=\"dark-background-and-light-text\">Dark Background and Light Text</h2>\n<p>Now, we need to change the whole theme as that shown in the example at the beginning of this tutorial. This can be achieved by changing background color and text color.</p>\n<p>Background is a global configurable object, so we can set it directly with <a href=\"option.html#backgroundColor\" target=\"_blank\">backgroundColor</a> of option.</p>\n<pre><code class=\"lang-js\">setOption({\n backgroundColor: '#2c343c'\n})\n</code></pre>\n<p>Text style can also be set globally in <a href=\"option.html#textStyle\" target=\"_blank\">textStyle</a>.</p>\n<pre><code class=\"lang-js\">setOption({\n textStyle: {\n color: 'rgba(255, 255, 255, 0.3)'\n }\n})\n</code></pre>\n<p>On the other hand, we can also set them in <a href=\"option.html#series-pie.label.textStyle\" target=\"_blank\">label.textStyle</a> of each series.</p>\n<pre><code class=\"lang-js\">label: {\n textStyle: {\n color: 'rgba(255, 255, 255, 0.3)'\n }\n}\n</code></pre>\n<p>We also need to set line color of pie chart to be lighter.</p>\n<pre><code class=\"lang-js\">labelLine: {\n lineStyle: {\n color: 'rgba(255, 255, 255, 0.3)'\n }\n}\n</code></pre>\n<p>Thus, we can get the following effect.</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-styling-step3&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>Similar to <code>itemStyle</code>, <code>label</code> and <code>labelLine</code> also have <code>emphasis</code> children.</p>\n<h2 id=\"setting-fan-colors\">Setting Fan Colors</h2>\n<p>Fan colors can be set in <code>itemStyle</code>:</p>\n<pre><code class=\"lang-js\">itemStyle: {\n // 设置扇形的颜色\n color: '#c23531',\n shadowBlur: 200,\n shadowColor: 'rgba(0, 0, 0, 0.5)'\n}\n</code></pre>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-styling-step4&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>This is quite similar to our expect effect, except that fan colors should be made darker within shadow area, so as to make a sense of layering and space with blocked light.</p>\n<p>Each fan's color can be set under <code>data</code>:</p>\n<pre><code class=\"lang-js\">data: [{\n value:400,\n name:'搜索引擎',\n itemStyle: {\n color: '#c23531'\n }\n}, ...]\n</code></pre>\n<p>But since we only need the variation of color in this example, there's a simpler way to map data value to lightness through <a href=\"#option.html#visualMap\">visualMap</a>.</p>\n<pre><code class=\"lang-js\">visualMap: {\n // hide visualMap component; use lightness mapping only\n show: false,\n // mapping with min value at 80\n min: 80,\n // mapping with max value at 600\n max: 600,\n inRange: {\n // mapping lightness from 0 to 1\n colorLightness: [0, 1]\n }\n}\n</code></pre>\n<p>The final effect is:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-styling-step5&edit=1&reset=1\" width=\"500\" height=\"400\" ></iframe>\n\n\n\n\n"},"Overview of Style Customization":{"type":["*"],"description":"<p>This article provides an overview of the different approaches about style customization. For example, how to config the color, size, shadow of the graphic elements and labels.</p>\n<blockquote>\n<p>The term "style" may not follow the convention of data visualization, but we use it in this article because it is popular and easy to understand.</p>\n</blockquote>\n<p>These approaches below will be introduced. The functionalities of them might be overlapped, but they are suitable for different scenarios.</p>\n<ul>\n<li>Theme</li>\n<li>Pallette</li>\n<li>Customize style explicitly (itemStyle, lineStyle, areaStyle, label, ...)</li>\n<li>Visual encoding (visualMap component)</li>\n</ul>\n<p>Other article about styling can be check in <a href=\"#Customized%20Chart%20Styles\">Customized Chart Styles</a> and <a href=\"#Visual%20Map%20of%20Data\">Visual Map of Data</a>.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Theme</strong></p>\n<p>Setting a theme is the simplest way to change the color style. For example, in <a href=\"https://ecomfe.github.io/echarts-examples/public/index.html\" target=\"_blank\">Examples page</a>, "Theme" can be selected, and view the result directly.</p>\n<p>Since ECharts4, besides the original default theme, ECharts provide another two built-in themes, named '<code>'light'</code> and <code>'dark'</code>. They can be used as follows:</p>\n<pre><code class=\"lang-js\">var chart = echarts.init(dom, 'light');\n</code></pre>\n<p>或者</p>\n<pre><code class=\"lang-js\">var chart = echarts.init(dom, 'dark');\n</code></pre>\n<p>Other themes are not included in ECharts package by default, and need to load them ourselves if we want to use them. Themes can be visited and downloaded in <a href=\"http://echarts.baidu.com/theme-builder/\" target=\"_blank\">Theme Builder</a>. Theme can also be created or edited in it. The downloaded theme can be used as follows:</p>\n<p>If a theme is downloaded as a JSON file, we should register it by ourselves, for example:</p>\n<pre><code class=\"lang-js\">var xhr = new XMLHttpRequest();\n// Assume the theme name is "vintage".\nxhr.open('GET', 'xxx/xxx/vintage.json', true);\nxhr.onload = function () {\n var themeJSON = this.response;\n echarts.registerTheme('vintage', JSON.parse(themeJSON))\n var chart = echarts.init(dom, 'vintage');\n // ...\n});\nxhr.send();\n</code></pre>\n<p>If a them is downloaded as a JS file, it will auto register itself:</p>\n<pre><code class=\"lang-js\">// Import the `vintage.js` file in HTML, then:\nvar chart = echarts.init(dom, 'vintage');\n// ...\n</code></pre>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Palette</strong></p>\n<p>Pallettes can be given in option. They provide a group of colors, which will be auto picked by series and data. We can give a global palette, or exclusive pallette for certain series.</p>\n<pre><code class=\"lang-js\">option = {\n // Global palette:\n color: ['#c23531','#2f4554', '#61a0a8', '#d48265', '#91c7ae','#749f83', '#ca8622', '#bda29a','#6e7074', '#546570', '#c4ccd3'],\n\n series: [{\n type: 'bar',\n // A palette only work for the series:\n color: ['#dd6b66','#759aa0','#e69d87','#8dc1a9','#ea7e53','#eedd78','#73a373','#73b9bc','#7289ab', '#91ca8c','#f49f42'],\n ...\n }, {\n type: 'pie',\n // A palette only work for the series:\n color: ['#37A2DA', '#32C5E9', '#67E0E3', '#9FE6B8', '#FFDB5C','#ff9f7f', '#fb7293', '#E062AE', '#E690D1', '#e7bcf3', '#9d96f5', '#8378EA', '#96BFFF'],\n ...\n }]\n}\n</code></pre>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Customize style explicitly (itemStyle, lineStyle, areaStyle, label, ...)</strong></p>\n<p>It is a common way to set style explicitly. Throughout ECharts <a href=\"option.html\" target=\"_blank\">option</a>, style related options can be set in various place, including <a href=\"option.html#series.itemStyle\" target=\"_blank\">itemStyle</a>, <a href=\"option.html#series-line.lineStyle\" target=\"_blank\">lineStyle</a>, <a href=\"option.html#series-line.areaStyle\" target=\"_blank\">areaStyle</a>, <a href=\"option.html#series.label\" target=\"_blank\">label</a>, etc.</p>\n<p>Generally speaking, all of the built-in components and series follow the naming convention like <code>itemStyle</code>, <code>lineStyle</code>, <code>areaStyle</code>, <code>label</code> etc., although they may occur in different place according to different series or components.</p>\n<p>There is another article for style setting, <a href=\"#Customized%20Chart%20Styles\">Customized Chart Styles</a>.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Style of emphasis state</strong></p>\n<p>When mouse hovering a graphic elements, usually the emphasis style will be displayed. By default, the emphasis style is auto generated by the normal style. However they can be specified by <a href=\"option.html#series-scatter.emphasis\" target=\"_blank\">emphasis</a> property. The options in <a href=\"option.html#series-scatter.emphasis\" target=\"_blank\">emphasis</a> is the same as the ones for normal state, for example:</p>\n<pre><code class=\"lang-js\">option = {\n series: {\n type: 'scatter',\n\n // Styles for normal state.\n itemStyle: {\n // Color of the point.\n color: 'red'\n },\n label: {\n show: true,\n // Text of labels.\n formatter: 'This is a normal label.'\n },\n\n // Styles for emphasis state.\n emphasis: {\n itemStyle: {\n // Color in emphasis state.\n color: 'blue'\n },\n label: {\n show: true,\n // Text in emphasis.\n formatter: 'This is a emphasis label.'\n }\n }\n }\n}\n</code></pre>\n<p>Notice: Before ECharts4, the emphasis style should be written like this:</p>\n<pre><code class=\"lang-js\">option = {\n series: {\n type: 'scatter',\n\n itemStyle: {\n // Styles for normal state.\n normal: {\n color: 'red'\n },\n // Styles for emphasis state.\n emphasis: {\n color: 'blue'\n }\n },\n\n label: {\n // Styles for normal state.\n normal: {\n show: true,\n formatter: 'This is a normal label.'\n },\n // Styles for emphasis state.\n emphasis: {\n show: true,\n formatter: 'This is a emphasis label.'\n }\n }\n }\n}\n</code></pre>\n<p>The option format is still <strong>compatible</strong>, but not recommended. In fact, in most cases, users only set normal style, and use the default emphasis style. So since ECharts4, we support to write style without the "normal" term, which makes the option more simple and neat.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Visual encoding (visualMap component)</strong></p>\n<p><a href=\"option.html#visualMap\" target=\"_blank\">visualMap component</a> supports config the rule that mapping value to visual channel (color, size, ...). More details can be check in <a href=\"#Visual%20Map%20of%20Data\">Visual Map of Data</a>.</p>\n"},"Loading and Updating of Asynchronous Data":{"type":["*"],"description":"<h2 id=\"asynchronous-loading\">Asynchronous Loading</h2>\n<p>Data in <a href=\"#getting-started\">Get started</a> is directly filled in <code>setOption</code> after initialization, but in some cases, data may be filled after asynchronous loading. Data updating asynchronously in <code>ECharts</code> is very easy. After initialization, you can pass in data and configuration item through <code>setOption</code> after data obtained through jQuery and other tools at any time.</p>\n<pre><code class=\"lang-js\">var myChart = echarts.init(document.getElementById('main'));\n\n$.get('data.json').done(function (data) {\n myChart.setOption({\n title: {\n text: 'asynchronous data loading example'\n },\n tooltip: {},\n legend: {\n data:['Sales']\n },\n xAxis: {\n data: ["shirts","cardigan","chiffon shirt","pants","heels","sockes"]\n },\n yAxis: {},\n series: [{\n name: 'Sales',\n type: 'bar',\n data: [5, 20, 36, 10, 10, 20]\n }]\n });\n});\n</code></pre>\n<p>Or, you may set other styles, displaying an empty rectangular axis, and then fill in data when ready.</p>\n<pre><code class=\"lang-js\">var myChart = echarts.init(document.getElementById('main'));\n// show title. legend and empty axis\nmyChart.setOption({\n title: {\n text: 'asynchronous data loading example'\n },\n tooltip: {},\n legend: {\n data:['Sales']\n },\n xAxis: {\n data: []\n },\n yAxis: {},\n series: [{\n name: 'Sales',\n type: 'bar',\n data: []\n }]\n});\n\n// Asynchronous data loading \n$.get('data.json').done(function (data) {\n // fill in data\n myChart.setOption({\n xAxis: {\n data: data.categories\n },\n series: [{\n // find series by name\n name: 'Sales',\n data: data.data\n }]\n });\n});\n</code></pre>\n<p>For example: </p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-async&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>In ECharts, updating data need to find the corresponding series through <code>name</code>. In the above example, updating can be performed correctly according to series order if <code>name</code> is not defined. But in most cases, it is recommended to update data with series <code>name</code> information. </p>\n<h2 id=\"loading-animation\">Loading Animation</h2>\n<p>If data loading time is too long, an empty axis on the canvas may confuse users. In this case, a loading animation is needed to tell the user that it's still loading. </p>\n<p>ECharts provides a simple loading animation by default. You only need <a href=\"api.html#echartsInstance.showLoading\" target=\"_blank\">showLoading</a> to show, and then use <a href=\"api.html#echartsInstance.hideLoading\" target=\"_blank\">hideLoading</a> to hide loading animation after data loading.</p>\n<pre><code class=\"lang-js\">myChart.showLoading();\n$.get('data.json').done(function (data) {\n myChart.hideLoading();\n myChart.setOption(...);\n});\n</code></pre>\n<p>Effects are as followed: </p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-loading&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<h2 id=\"dynamic-data-updating\">Dynamic Data Updating</h2>\n<p>ECharts is driven by data. Change of data changes the presentation of chart, therefore, implementing dynamic data updating is extremely easy.</p>\n<p>All data updating are through <a href=\"#api.html#echartsInstance.setOption\">setOption</a>. You only need to get data as you wish, fill in data to <a href=\"#api.html#echartsInstance.setOption\">setOption</a> without considering the changes brought by data, ECharts will find the difference between two group of data and present the difference through proper animation. </p>\n<blockquote>\n<p>In ECharts 3, addData in ECharts 2 is removed.If a single data needs to be added, you can first data.push(value) and then setOption.</p>\n</blockquote>\n<p>See details in the following example:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/tutorial-dynamic-data&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n\n"},"Dataset":{"type":["*"],"description":"<p><code>dataset</code> component is published since ECharts 4. <code>dataset</code> brings convenience in data management separated with styles and enables data reuse by different series. More importantly, is enables data encoding from data to visual, which brings convenience in some scenarios.</p>\n<p>Before ECharts 4, data was only able to declared in each series, for example:</p>\n<pre><code class=\"lang-js\">option: {\n xAxis: {\n type: 'category',\n data: ['Matcha Latte', 'Milk Tea', 'Cheese Cocoa', 'Walnut Brownie']\n },\n yAxis: {}\n series: [\n {\n type: 'bar',\n name: '2015',\n data: [89.3, 92.1, 94.4, 85.4]\n },\n {\n type: 'bar',\n name: '2016',\n data: [95.8, 89.4, 91.2, 76.9]\n },\n {\n type: 'bar',\n name: '2017',\n data: [97.7, 83.1, 92.5, 78.1]\n }\n ]\n}\n</code></pre>\n<p>This approach is easy to be understand and is flexible when some series needs special data definitions. But the shortcomings are also obvious: some data extra works are usually needed to split the original data to each series, and it not supports sharing data in different series, moreover, it is not good for encode.</p>\n<p>ECharts4 starts to provide <code>dataset</code> component, which brings benefits below:</p>\n<ul>\n<li>Benefit from <code>dataset</code>, we can follow the common methodology of data visualization: based on data, specify the mapping (via the option <a href=\"option.html#series.encode\" target=\"_blank\">encode</a>) from data to visual.</li>\n<li>Data can be managed and configured separately from other configurations.</li>\n<li>Data can be reused by different series and components.</li>\n<li>Support more common data format (like 2d-array, object-array), to avoid data transform works for users.</li>\n</ul>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Get started</strong></p>\n<p>This is a simplest example of <code>dataset</code>:</p>\n<pre><code class=\"lang-js\">option = {\n legend: {},\n tooltip: {},\n dataset: {\n // Provide data.\n source: [\n ['product', '2015', '2016', '2017'],\n ['Matcha Latte', 43.3, 85.8, 93.7],\n ['Milk Tea', 83.1, 73.4, 55.1],\n ['Cheese Cocoa', 86.4, 65.2, 82.5],\n ['Walnut Brownie', 72.4, 53.9, 39.1]\n ]\n },\n // Declare X axis, which is a category axis, mapping\n // to the first column by default.\n xAxis: {type: 'category'},\n // Declare Y axis, which is a value axis.\n yAxis: {},\n // Declare several series, each of them mapped to a\n // column of the dataset by default.\n series: [\n {type: 'bar'},\n {type: 'bar'},\n {type: 'bar'}\n ]\n}\n</code></pre>\n<p>This is the result:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=dataset-simple0&edit=1&reset=1\" width=\"500\" height=\"300\" ></iframe>\n\n\n<p>Or the common format object-array is also supported:</p>\n<pre><code class=\"lang-js\">option = {\n legend: {},\n tooltip: {},\n dataset: {\n // Here the declared `dimensions` is mainly for providing the order of\n // the dimensions, which enables ECharts to apply the default mapping\n // from dimensions to axes.\n // Alternatively, we can declare `series.encode` to specify the mapping,\n // which will be introduced later.\n dimensions: ['product', '2015', '2016', '2017'],\n source: [\n {product: 'Matcha Latte', '2015': 43.3, '2016': 85.8, '2017': 93.7},\n {product: 'Milk Tea', '2015': 83.1, '2016': 73.4, '2017': 55.1},\n {product: 'Cheese Cocoa', '2015': 86.4, '2016': 65.2, '2017': 82.5},\n {product: 'Walnut Brownie', '2015': 72.4, '2016': 53.9, '2017': 39.1}\n ]\n },\n xAxis: {type: 'category'},\n yAxis: {},\n series: [\n {type: 'bar'},\n {type: 'bar'},\n {type: 'bar'}\n ]\n};\n</code></pre>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Mapping from data to graphic</strong></p>\n<p>In this tutorial, we make charts following this methodology: base on data, config the rule to map data to graphic, namely, encode the data to graphic.</p>\n<p>Generally, this mapping can be performed:</p>\n<ul>\n<li>Configure whether columns or rows of a dataset will mapped to series, namely, the series layout on the columns or rows of a dataset. This can be specified by <a href=\"option.html#series.seriesLayoutBy\" target=\"_blank\">series.seriesLayoutBy</a>. <code>'column'</code> is the default value.</li>\n<li>Configure the mapping rule from dimensions (a dimension means a column/row) to axes in coordinate system, tooltip, labels, color, symbol size, etc. This can be specified by <a href=\"option.html#series.encode\" target=\"_blank\">series.encode</a> and <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a> (if visual encoding is required). The example above does not give a mapping rule, so ECharts make default mapping by common sense: because x axis is a category axis, the first column is mapped to the x axis, and each series use each subsequent column in order.</li>\n</ul>\n<p>Let's illustrate them in detail below.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Mapping by column or row</strong></p>\n<p>Giving dataset, users can configure whether columns or rows of a dataset will be mapped to series, namely, the series layout on the columns or rows of a dataset. This can be specified by <a href=\"option.html#series.seriesLayoutBy\" target=\"_blank\">series.seriesLayoutBy</a>. The optional values are:</p>\n<ul>\n<li>'column': series are positioned on each columns of the dataset. Default value.</li>\n<li>'row': series are positioned on each row of the dataset.</li>\n</ul>\n<p>See the example below:</p>\n<pre><code class=\"lang-js\">option = {\n legend: {},\n tooltip: {},\n dataset: {\n source: [\n ['product', '2012', '2013', '2014', '2015'],\n ['Matcha Latte', 41.1, 30.4, 65.1, 53.3],\n ['Milk Tea', 86.5, 92.1, 85.7, 83.1],\n ['Cheese Cocoa', 24.1, 67.2, 79.5, 86.4]\n ]\n },\n xAxis: [\n {type: 'category', gridIndex: 0},\n {type: 'category', gridIndex: 1}\n ],\n yAxis: [\n {gridIndex: 0},\n {gridIndex: 1}\n ],\n grid: [\n {bottom: '55%'},\n {top: '55%'}\n ],\n series: [\n // These series is in the first cartesian (grid), and each\n // is mapped to a row.\n {type: 'bar', seriesLayoutBy: 'row'},\n {type: 'bar', seriesLayoutBy: 'row'},\n {type: 'bar', seriesLayoutBy: 'row'},\n // These series is in the second cartesian (grid), and each\n // is mapped to a column.\n {type: 'bar', xAxisIndex: 1, yAxisIndex: 1},\n {type: 'bar', xAxisIndex: 1, yAxisIndex: 1},\n {type: 'bar', xAxisIndex: 1, yAxisIndex: 1},\n {type: 'bar', xAxisIndex: 1, yAxisIndex: 1}\n ]\n}\n</code></pre>\n<p>This is the result:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=dataset-series-layout-by&edit=1&reset=1\" width=\"800\" height=\"600\" ></iframe>\n\n\n\n\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Dimension</strong></p>\n<p>Before introducing <code>encode</code>, we should clarify the concept of <code>dimension</code>.</p>\n<p>Most of common charts describe data in the format of "two-dimensions table" (note that the meaning of the word "dimension" in "two-dimension table" is not the same as the dimensions in ECharts. \bIn order not to be confusing, we use "2d-table", "2d-array" below). In the examples above, we use 2d-array to carry the 2d-table. When we set <code>seriesLayoutBy</code> as <code>'column'</code>, namely, mapping columns to series, each column is called a dimension, and each row is a data item. When we set <code>seriesLayoutBy</code> as <code>'row'</code>, namely, mapping rows to series, each row is called a dimension, and each column is a data item.</p>\n<p>Dimension can have its name to displayed on charts. Dimension name can be defined on the first row/column. Take the code above as an example, <code>'score'</code>、<code>'amount'</code>、<code>'product'</code> are dimension names, and data start from the second row. By default ECharts auto detect whether the first row/column of <code>dataset.source</code> is dimension name or data. Use can also set <code>dataset.sourceHeader</code> as <code>true</code> to mandatorily specify the first row/column is dimension name, or set as <code>false</code> to indicate the data start from the first row/column.</p>\n<p>The definitions of the dimensions can also be provided separately in <code>dataset.dimensions</code> or <code>series.dimensions</code>, where not only dimension name, but also dimension type can be specified:</p>\n<pre><code class=\"lang-js\">var option1 = {\n dataset: {\n dimensions: [\n // Each item can be object or string.\n {name: 'score'},\n // A string indicates the dimension name.\n 'amount',\n // Dimension type can be specified.\n {name: 'product', type: 'ordinal'}\n ],\n source: [...]\n },\n ...\n};\n\nvar option2 = {\n dataset: {\n source: [...]\n },\n series: {\n type: 'line',\n // Dimensions declared in series will be adapted with higher priority.\n dimensions: [\n null, // Set as null means we dont want to set dimension name.\n 'amount',\n {name: 'product', type: 'ordinal'}\n ]\n },\n ...\n};\n</code></pre>\n<p>Generally, we do not need to set dimensions types, because it can be auto detected based on data by ECharts. But in some cases, for example, the data is empty, the detection might not be accurate, where dimension type can be set manually.</p>\n<p>The optional values of dimension types can be:</p>\n<ul>\n<li><code>'number'</code>: Normal data, default value.</li>\n<li><code>'ordinal'</code>: Represents string data like category data or text data. ECharts will auto detect them by default. They can be set manually if the detection fail.</li>\n<li><code>'time'</code>: Represents time data, where it is supported that parse time string to timestamp. For example, if users need to parse '2017-05-10' to timestamp, it should be set as <code>time</code> type. If the dimension is used on a time axis (<a href=\"option.html#xAxis.type\" target=\"_blank\">axis.type</a> is <code>'time'</code>), it will be auto set to <code>time</code> type. The supported time string is listed in <a href=\"option.html#series.data\" target=\"_blank\">data</a>.</li>\n<li><code>'float'</code>: If set as <code>'float'</code>, it will be stored in <code>TypedArray</code>, which is good for performance optimization.</li>\n<li><code>'int'</code>: If set as <code>'int'</code>, it will be stored in <code>TypedArray</code>, which is good for performance optimization.</li>\n</ul>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Mapping from data to graphic (encode)</strong></p>\n<p>Having the concept of dimension clarified, we can use <a href=\"option.html#series.encode\" target=\"_blank\">encode</a> to map data to graphic:</p>\n<pre><code class=\"lang-js\">var option = {\n dataset: {\n source: [\n ['score', 'amount', 'product'],\n [89.3, 58212, 'Matcha Latte'],\n [57.1, 78254, 'Milk Tea'],\n [74.4, 41032, 'Cheese Cocoa'],\n [50.1, 12755, 'Cheese Brownie'],\n [89.7, 20145, 'Matcha Cocoa'],\n [68.1, 79146, 'Tea'],\n [19.6, 91852, 'Orange Juice'],\n [10.6, 101852, 'Lemon Juice'],\n [32.7, 20112, 'Walnut Brownie']\n ]\n },\n xAxis: {},\n yAxis: {type: 'category'},\n series: [\n {\n type: 'bar',\n encode: {\n // Map dimension "amount" to the X axis.\n x: 'amount',\n // Map dimension "product" to the Y axis.\n y: 'product'\n }\n }\n ]\n};\n</code></pre>\n<p>This is the result:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/dataset-encode-simple0&edit=1&reset=1\" width=\"500\" height=\"300\" ></iframe>\n\n\n\n<p>The basic structure of <a href=\"option.html#series.encode\" target=\"_blank\">encode</a> is illustrated as follows, where the left part of colon is the name of axis like <code>'x'</code>, <code>'y'</code>, <code>'radius'</code>, <code>'angle'</code> or some special reserved names like "tooltip", "itemName" etc., and the right part of the colon is the dimension names or dimension indices (based on 0). One or more dimensions can be specified. Usually not all of mappings need to be specified, only specify needed ones.</p>\n<p>The properties available in <code>encode</code> listed as follows:</p>\n<pre><code class=\"lang-js\">// In any of the series and coordinate systems,\n// these properties are available:\nencode: {\n // Display dimension "product" and "score" in the tooltip.\n tooltip: ['product', 'score']\n // Set the series name as the concat of the names of dimensions[1] and dimensions[3].\n // (sometimes the dimension names are too long to type in series.name manually).\n seriesName: [1, 3],\n // Using dimensions[2] as the id of each data item. This is useful when dynamically\n // update data by `chart.setOption()`, where the new and old data item can be\n // corresponded by id, by which the appropriate animation can be performed when updating.\n itemId: 2,\n // Using dimensions[3] as the name of each data item. This is useful in charts like\n // 'pie', 'funnel', where data item name can be displayed in legend.\n itemName: 3\n}\n\n// These properties only work in cartesian(grid) coordinate system:\nencode: {\n // Map dimensions[1], dimensions[5] and dimension "score" to the X axis.\n x: [1, 5, 'score'],\n // Map dimensions[0] to the Y axis.\n y: 0\n}\n\n// These properties only work in polar coordinate system:\nencode: {\n radius: 3,\n angle: 2,\n ...\n}\n\n// These properties only work in geo coordinate system:\nencode: {\n lng: 3,\n lat: 2\n}\n\n// For some type of series that are not in any coordinate system,\n// like 'pie', 'funnel' etc.:\nencode: {\n value: 3\n}\n</code></pre>\n<p>There is an other example for <code>encode</code>:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=dataset-encode1&edit=1&reset=1\" width=\"800\" height=\"600\" ></iframe>\n\n\n\n\n\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Visual encoding (color, symbol, etc.)</strong></p>\n<p>We can use <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a> component to map data to visual channel like color, symbol size, etc.. More info about it can be checked in its <a href=\"option.html#visualMap\" target=\"_blank\">doc</a>.</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=dataset-encode0&edit=1&reset=1\" width=\"500\" height=\"400\" ></iframe>\n\n\n\n\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Default encoding</strong></p>\n<p>For some common cases (line chart, bar chart, scatter plot, candlestick, pie, funnel, etc.), EChart provides default encoding settings, by which chart will be displayed even if no <code>encode</code> option is specified. (If <code>encode</code> option is specified, default encoding will not be applied.) The rule of default encoding should not be too complicated. Basically it is:</p>\n<ul>\n<li>In coordinate system (like cartesian(grid), polar):<ul>\n<li>If category axis (i.e., axis.type is <code>'category'</code>) exists, map the first column/row to the axis, and each series use a following column/row.</li>\n<li>If no category axis exists, and the coordinate system contains two axis (like X Y in cartesian), each series use two columns/rows, one for a axis.</li>\n</ul>\n</li>\n<li>If no coordinate system (like pie chart):<ul>\n<li>Use the first column/row as item name, and the second column/row as item value.</li>\n</ul>\n</li>\n</ul>\n<p>If the default rule does not meet the requirements, configure the <code>encode</code> yourself please.</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=dataset-default&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Q & A</strong></p>\n<p>Q: How to map the third column to X axis, and map the fifth column to Y axis?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">series: {\n // Notice that the dimension index is based on 0,\n // thus the third column is dimensions[2].\n encode: {x: 2, y: 4},\n ...\n}\n</code></pre>\n<p>Q: How to map the third row th X axis, and map the fifth row to Y axis?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">series: {\n encode: {x: 2, y: 4},\n seriesLayoutBy: 'row',\n ...\n}\n</code></pre>\n<p>Q: How to use the values in the second column in label.</p>\n<p>A:\nThe <a href=\"option.html#series.label.formatter\" target=\"_blank\">label.formatter</a> supports refer value in a certain dimension. For example:</p>\n<pre><code class=\"lang-js\">series: {\n label: {\n // `'{@score}'` means use the value in the "score" dimension.\n // `'{@[4]}'` means use the value in dimensions[4].\n formatter: 'aaa{@product}bbb{@score}ccc{@[4]}ddd'\n }\n}\n</code></pre>\n<p>Q: How to display the second column and the third column in tooltip?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">series: {\n encode: {\n tooltip: [1, 2]\n ...\n },\n ...\n}\n</code></pre>\n<p>Q: If there is no dimension name in dataset.source, how to give dimension name?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">dataset: {\n dimensions: ['score', 'amount'],\n source: [\n [89.3, 3371],\n [92.1, 8123],\n [94.4, 1954],\n [85.4, 829]\n ]\n}\n</code></pre>\n<p>Q: How to encode the fourth column in bubble size in bubble plot?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">var option = {\n dataset: {\n source: [\n [12, 323, 11.2],\n [23, 167, 8.3],\n [81, 284, 12],\n [91, 413, 4.1],\n [13, 287, 13.5]\n ]\n },\n // Use visualMap to perform visual encoding.\n visualMap: {\n show: false,\n dimension: 2, // Encode the third column.\n min: 2, // Min value is required in visualMap component.\n max: 15, // Max value is required in visualMap component.\n inRange: {\n // The range of bubble size, from 5 pixel to 60 pixel.\n symbolSize: [5, 60]\n }\n },\n xAxis: {},\n yAxis: {},\n series: {\n type: 'scatter'\n }\n};\n</code></pre>\n<p>Q: We have specified <code>encode</code>, but why it does not work?</p>\n<p>A: Maybe we can try to check typo, for example, the dimension name is <code>'Life Expectancy'</code>, be we typed <code>'Life Expectency'</code> in <code>encode</code> option.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Various formats in dataset</strong></p>\n<p>In lots of cases, data is described in 2d-table. For example, some data processing software like MS Excel, Numbers are based on 2d-table. The data can be exported as JSON format and input to <code>dataset.source</code>.</p>\n<blockquote>\n<p>Some csv tools can be used to export the table data to JSON, for example, <a href=\"https://github.com/d3/d3-dsv\" target=\"_blank\">dsv</a> or <a href=\"https://github.com/mholt/PapaParse\" target=\"_blank\">PapaParse</a>.</p>\n</blockquote>\n<p>In common used data transfer formats in JavaScript, 2d-array is a good choice to carry table data, which has been illustrated in the examples above.</p>\n<p>Besides, 2d-array, <code>dataset</code> also support key-value format as follows, which is also commonly used. But notice, the option <a href=\"option.html#series.seriesLayoutBy\" target=\"_blank\">seriesLayoutBy</a> is not supported in this format.</p>\n<pre><code class=\"lang-js\">dataset: [{\n // Row based key-value format, namely, object array, is a commonly used format.\n source: [\n {product: 'Matcha Latte', count: 823, score: 95.8},\n {product: 'Milk Tea', count: 235, score: 81.4},\n {product: 'Cheese Cocoa', count: 1042, score: 91.2},\n {product: 'Walnut Brownie', count: 988, score: 76.9}\n ]\n}, {\n // Column based key-value format is also supported.\n source: {\n 'product': ['Matcha Latte', 'Milk Tea', 'Cheese Cocoa', 'Walnut Brownie'],\n 'count': [823, 235, 1042, 988],\n 'score': [95.8, 81.4, 91.2, 76.9]\n }\n}]\n</code></pre>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Multiple datasets and references</strong></p>\n<p>Multiple datasets can be defined, and series can refer them by <a href=\"option.html#series.datasetIndex\" target=\"_blank\">series.datasetIndex</a>.</p>\n<pre><code class=\"lang-js\">var option = {\n dataset: [{\n source: [...],\n }, {\n source: [...]\n }, {\n source: [...]\n }],\n series: [{\n // Use the third dataset.\n datasetIndex: 2\n }, {\n // Use the second dataset.\n datasetIndex: 1\n }]\n}\n</code></pre>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>ECharts3 data setting approach (series.data) can be used normally</strong></p>\n<p>The data setting approach before ECharts4 can still be used normally. If a series has declared <a href=\"option.html#series.data\" target=\"_blank\">series.data</a>, it will be used but not <code>dataset</code>.</p>\n<pre><code class=\"lang-js\">{\n xAxis: {\n type: 'category'\n data: ['Matcha Latte', 'Milk Tea', 'Cheese Cocoa', 'Walnut Brownie']\n },\n yAxis: {},\n series: [{\n type: 'bar',\n name: '2015',\n data: [89.3, 92.1, 94.4, 85.4]\n }, {\n type: 'bar',\n name: '2016',\n data: [95.8, 89.4, 91.2, 76.9]\n }, {\n type: 'bar',\n name: '2017',\n data: [97.7, 83.1, 92.5, 78.1]\n }]\n}\n</code></pre>\n<p>In fact, setting data via <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> is not deprecated and useful in some cases. For example, for some charts, like <a href=\"option.html#series-treemap\" target=\"_blank\">treemap</a>, <a href=\"option.html#series-graph\" target=\"_blank\">graph</a>, <a href=\"option.html#series-lines\" target=\"_blank\">lines</a>, that do not apply table data, <code>dataset</code> is not supported for yet. Moreover, for the case of large data rendering (for example, millions of data), <a href=\"api.html#echartsInstance.appendData\" target=\"_blank\">appendData</a> is probably needed to load data incrementally. <code>dataset</code> is not supported in the case.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Others</strong></p>\n<p>Currently, not all types of series support dataset. Series that support dataset includes:</p>\n<p><code>line</code>, <code>bar</code>, <code>pie</code>, <code>scatter</code>, <code>effectScatter</code>, <code>parallel</code>, <code>candlestick</code>, <code>map</code>, <code>funnel</code>, <code>custom</code>.</p>\n<p>More types of series will support dataset in our further work.</p>\n<p>Finally, this is an example, multiple series sharing one <code>dataset</code> and having interactions:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=dataset-link&edit=1&reset=1\" width=\"800\" height=\"500\" ></iframe>\n\n\n\n\n\n"},"Add interaction to the chart component":{"type":["*"],"description":"<p>Echarts provides many interaction components besides chart. For example:</p>\n<p><code>legend component</code> <a href=\"option.html#legend\" target=\"_blank\">legend</a>、<code>title component</code> <a href=\"option.html#title\" target=\"_blank\">title</a>、<code>visualmap component</code> <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a>、<code>datazoom component</code> <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a>、<code>dataline component</code> <a href=\"option.html#timeline\" target=\"_blank\">timeline</a></p>\n<p>Following is an example of <code>datazoom component</code> <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a> as an introduction of how to add this kind of component.</p>\n<p><br></p>\n<h2>Introduction of data zoom component (dataZoom)</h2>\n\n<p>Data overview by default, and detail by requirement is a basic interaction need of data visualization. <code>dataZoom</code> component can implement this function in rectangular coordinate (<a href=\"option.html#grid\" target=\"_blank\">grid</a>) and polar coordinate (<a href=\"option.html#polar\" target=\"_blank\">polar</a>.</p>\n<p><strong>For example: </strong></p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/scatter-dataZoom-all&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n<p><br></p>\n<ul>\n<li><code>dataZoom</code> component operates <em>data window zoom</em> and <em>data window translation</em> on <code>axis</code>.</li>\n</ul>\n<blockquote>\n<p>Use <a href=\"option.html#dataZoom.xAxisIndex\" target=\"_blank\">dataZoom.xAxisIndex</a>, <a href=\"option.html#dataZoom.yAxisIndex\" target=\"_blank\">dataZoom.yAxisIndex</a> to specify which axis <code>dataZoom</code> controls.</p>\n</blockquote>\n<ul>\n<li><p>Multiple <code>dataZoom</code> components can exist at the same time to control function together. Components controling the same axis will be connected automatically. The example below explains in detail.</p>\n</li>\n<li><p>Operation principle of <code>dataZoom</code> achieves <em>data window zooming</em> through <em>data filtering</em>.</p>\n<p> Different settings of data filtering modes lead to different data window zooming effects, please see: <a href=\"option.html#dataZoom.filterMode\" target=\"_blank\">dataZoom.filterMode</a>.</p>\n</li>\n<li><p>Setting of <code>dataZoom</code> data window range supports two formats currently:</p>\n<ul>\n<li><p>Percentage: see <a href=\"option.html#dataZoom.start\" target=\"_blank\">dataZoom.start</a> and <a href=\"option.html#dataZoom.end\" target=\"_blank\">dataZoom.end</a>.</p>\n</li>\n<li><p>Absolute value: see <a href=\"option.html#dataZoom.startValue\" target=\"_blank\">dataZoom.startValue</a> and <a href=\"option.html#dataZoom.endValue\" target=\"_blank\">dataZoom.endValue</a>.</p>\n</li>\n</ul>\n</li>\n</ul>\n<p><strong>dataZoom component supports several child components: </strong></p>\n<ul>\n<li><p><a href=\"option.html#dataZoom-inside\" target=\"_blank\">Inside data zoom component (dataZoomInside)</a>: inside coordinates.</p>\n</li>\n<li><p><a href=\"option.html#dataZoom-slider\" target=\"_blank\">Slider data zoom component (dataZoomSlider)</a>: has seperate slide option.</p>\n</li>\n<li><p><a href=\"option.html#toolbox.feature.dataZoom\" target=\"_blank\">Select data zoom component (dataZoomSelect)</a>: full-screen box for zoom data area. Entrance and configuration item are both in <code>toolbox</code>.</p>\n</li>\n</ul>\n<p><br></p>\n<h2>Adding dataZoom component</h2>\n\n<p>First, only add dataZoom component to x-axis. Following examples shows the code.</p>\n<pre><code class=\"lang-javascript\">\noption = {\n xAxis: {\n type: 'value'\n },\n yAxis: {\n type: 'value'\n },\n dataZoom: [\n { // This dataZoom component controls x-axis by dafault\n type: 'slider', // this dataZoom component is dataZoom component of slider\n start: 10, // the left is located at 10%\n end: 60 // the right is located at 60%\n }\n ],\n series: [\n {\n type: 'scatter', // this is scatter chart\n itemStyle: {\n opacity: 0.8\n },\n symbolSize: function (val) {\n return val[2] * 40;\n },\n data: [["14.616","7.241","0.896"],["3.958","5.701","0.955"],["2.768","8.971","0.669"],["9.051","9.710","0.171"],["14.046","4.182","0.536"],["12.295","1.429","0.962"],["4.417","8.167","0.113"],["0.492","4.771","0.785"],["7.632","2.605","0.645"],["14.242","5.042","0.368"]]\n }\n ]\n}\n</code></pre>\n<p>which will show the following result:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/scatter-tutorial-dataZoom-1&edit=1&reset=1\" width=\"600\" height=\"300\" ></iframe>\n\n\n<p><br></p>\n<p>The chart above can only change window by dragging dataZoom component. If you want to drag in coordinate, or use mouse wheel (or slides with two fingers on mobile) to zoom, then another inside dataZoom component needs to be added. You can just add in the <code>option.dataZoom</code> above:</p>\n<pre><code class=\"lang-javascript\">option = {\n ...,\n dataZoom: [\n { // this dataZoom component controls x-axis by dafault\n type: 'slider', // this dataZoom component is dataZoom component of slider\n start: 10, // the left is located at 10%\n end: 60 // the right is located at 60%\n },\n { // This dataZoom component controls x-axis by dafault\n type: 'inside', // this dataZoom component is dataZoom component of inside\n start: 10, // the left is located at 10%\n end: 60 // the right is located at 60%\n }\n ],\n ...\n}\n</code></pre>\n<p>Following results can be seen (you can now slide or use mouse wheel to zoom in coordinate) :</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/scatter-tutorial-dataZoom-2&edit=1&reset=1\" width=\"600\" height=\"300\" ></iframe>\n\n\n\n<p><br></p>\n<p>If you want to enable zooming on y-axis, then you need to add dataZoom componet on y-axis:</p>\n<pre><code class=\"lang-javascript\">option = {\n ...,\n dataZoom: [\n {\n type: 'slider',\n xAxisIndex: 0,\n start: 10,\n end: 60\n },\n {\n type: 'inside',\n xAxisIndex: 0,\n start: 10,\n end: 60\n },\n {\n type: 'slider',\n yAxisIndex: 0,\n start: 30,\n end: 80\n },\n {\n type: 'inside',\n yAxisIndex: 0,\n start: 30,\n end: 80\n }\n ],\n ...\n}\n</code></pre>\n<p>Following result can be seen:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/scatter-tutorial-dataZoom-3&edit=1&reset=1\" width=\"600\" height=\"300\" ></iframe>\n\n\n\n\n\n\n\n\n"},"Responsive Mobile-End":{"type":["*"],"description":"<p>ECharts works in DOM nodes with user defined width and height. ECharts <em>component</em> and <em>series</em> are both in this DOM node, whose location can be assigned by user seperately. Inner components of charts are not suitable for implementing DOM flow layout. Instead, we use a simpler and more understandable layout similar to absolute layout. But sometimes when container is of extreme size, this method cannot avoid component overlapping automatically, especially on small screens on mobile-end.</p>\n<p>Besides, sometimes one chart may need to be displayed on both PC and mobile-end, which involves the ability of ECharts inner components to be responsive with different container sizes.</p>\n<p>To solve this problem, ECharts improved component location algorithm, and implemented responsive ability similar to <a href=\"http://www.w3.org/TR/css3-mediaqueries/\" target=\"_blank\">CSS Media Query</a>.</p>\n<p><br></p>\n<h2>Location and layout of ECharts components</h2>\n\n\n<p>Most <em>component</em> and <em>series</em> follow two locating methods: </p>\n<p><br>\n<strong>left/right/top/bottom/width/height locating method:</strong></p>\n<p>Each of those six parameters can be <em>absolute value</em> or <em>percentage</em> or <em>location description</em>.</p>\n<ul>\n<li><p>Absolute value</p>\n<p> in browser pixels (px); in form of <code>number</code> (no unit); e.g.: <code>{left: 23, height: 400}</code>.</p>\n</li>\n<li><p>Percentage</p>\n<p> to the width and height of DOM container; in form of <code>string</code>; e.g.: <code>{right: '30%', bottom: '40%'}</code>.</p>\n</li>\n<li><p>Location Description</p>\n<ul>\n<li>can be set to <code>left: 'center'</code>, for horizontally centering.</li>\n<li>can be set to <code>top: 'middle'</code>, for vertically centering.</li>\n</ul>\n</li>\n</ul>\n<p>The concept of these six parameters is similar to that in CSS: </p>\n<ul>\n<li>left: distance to left border of DOM container.</li>\n<li>right: distance to right border of DOM container.</li>\n<li>top: distance to top border of DOM container.</li>\n<li>bottom: distance to bottom border of DOM container.</li>\n<li>width: width.</li>\n<li>height: height.</li>\n</ul>\n<p>Two out of the three horizontal parameters, <code>left</code>, <code>right</code>, <code>width</code>, are enough to determine the component location. For example, <code>left</code> and <code>right</code>, or <code>right</code> and <code>width</code> can both determine component location and size.\nThe same goes for vertical paramters <code>top</code>, <code>bottom</code> and <code>height</code>.</p>\n<p><br>\n<strong>Locating method of <code>center</code> / <code>radius</code>: </strong></p>\n<ul>\n<li><p><code>center</code></p>\n<p> an array in form of <code>[x, y]</code>, in which <code>x</code> and <code>y</code> can either be <em>absolute value</em> or <em>percentage</em>, as described above.</p>\n</li>\n<li><p><code>radius</code></p>\n<p> an array in form of <code>[innerRadius, outerRadius]</code>, in which <code>innerRadius</code> and <code>outerRadius</code> can either be <em>absolute value</em> or <em>percentage</em>, as described above.</p>\n<p> Percentage location turns out to be very useful for responsive positioning.</p>\n</li>\n</ul>\n<p><br>\n<strong>Horizontal and vertical</strong></p>\n<p>Most of ECharts's long and narrow components (such as <code>legend</code>,<code>visualMap</code>,<code>dataZoom</code>,<code>timeline</code> and so on), provide option to set them to be horizontal or vertical. For example, long and narrow screen of mobile-end, vertical layout may be a more suitable choice, while horizontal may more suit for PC's wide screen.</p>\n<p>Setting of horizontal or vertical layout is usually with component or series's <code>orient</code> or <code>layout</code> option, which can be set to <code>'horizontal'</code> or <code>'vertical'</code>.</p>\n<p><br>\n<strong>Compatibility with ECharts2: </strong></p>\n<p>Naming of <code>x/x2/y/y2</code> in ECharts2 is still compatible, as well as the newly added <code>left/right/top/bottom</code>. But <code>left/right/top/bottom</code> is recommended.</p>\n<p>To be compatible with ECharts2, there may be settings that seems to be odd, e.g.: <code>left: 'right'</code>, <code>left: 'left'</code>, <code>top: 'bottom'</code>, <code>top: 'top'</code>, which are equal to: <code>right: 0</code>, <code>left: 0</code>, <code>bottom: 0</code>, <code>top: 0</code>, in a more normal expression.</p>\n<p><br></p>\n<h2>Media Query</h2>\n\n<p><a href=\"http://www.w3.org/TR/css3-mediaqueries/#media1\" target=\"_blank\">Media Query</a> provides the ability to be responsive with container size.</p>\n<p>As shown in the following example, you may drag <strong>the circle in bottom-right corner</strong> to see the legend and series change layout position and method with container size. </p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/pie-media&edit=1&reset=1\" width=\"750\" height=\"600\" ></iframe>\n\n\n<p>The following format should be followed if you need to set Media Query in option:</p>\n<pre><code class=\"lang-javascript\">option = {\n baseOption: { // here defines base option\n title: {...},\n legend: {...},\n series: [{...}, {...}, ...],\n ...\n },\n media: [ // each rule of media query is defined here\n {\n query: {...}, // write rule here\n option: { // write options accordingly\n legend: {...},\n ...\n }\n },\n {\n query: {...}, // the second rule\n option: { // the second option\n legend: {...},\n ...\n }\n },\n { // default with no rules,\n option: { // when all rules fail, use this option\n legend: {...},\n ...\n }\n }\n ]\n};\n</code></pre>\n<p>In the above example, <code>baseOption</code> and every option in <code>media</code> are all <em>simple options</em>, which are regular options containing components and series. <code>baseOption</code> is always be used, while options of every will be merged with <code>chart.mergeOption()</code> when given <code>query</code> condition is satisfied with.</p>\n<p><strong>query: </strong></p>\n<p>A <code>query</code> is in the following format: </p>\n<pre><code class=\"lang-javascript\">{\n minWidth: 200,\n maxHeight: 300,\n minAspectRatio: 1.3\n}\n</code></pre>\n<p>Currently there are three supported attributes:<code>width</code>, <code>height</code>, <code>aspectRatio</code> (length-to-width ratio), each of which can add <code>min</code> or <code>max</code> as prefix. E.g., <code>minWidth: 200</code> stands for when width is greater than or equal to 200px. When two attributes are written together, it means <em>and</em> in Bool logic. For example, <code>{minWidth: 200, maxHeight: 300}</code> stands for when width is greater than or equal to 200px and height is smaller than or equal to 300px.</p>\n<p><strong>option: </strong></p>\n<p>Since option in <code>media</code> is <em>simple option</em>, technically speaking, you can write every option configuration item. But usually we only write those related to layout. Take part of the above query option as example:</p>\n<pre><code class=\"lang-javascript\">media: [\n ...,\n {\n query: {\n maxAspectRatio: 1 // when length-to-width ratio is less than 1\n },\n option: {\n legend: { // legend is placed in middle-bottom\n right: 'center',\n bottom: 0,\n orient: 'horizontal' // horizontal layout of legend\n },\n series: [ // left and right layout of two pie charts\n {\n radius: [20, '50%'],\n center: ['50%', '30%']\n },\n {\n radius: [30, '50%'],\n center: ['50%', '70%']\n }\n ]\n }\n },\n {\n query: {\n maxWidth: 500 // when container width is smaller than 500\n },\n option: {\n legend: {\n right: 10, // legend is placed in middle-right\n top: '15%',\n orient: 'vertical' // vertical layout\n },\n series: [ // top and bottom layout of two pie charts\n {\n radius: [20, '50%'],\n center: ['50%', '30%']\n },\n {\n radius: [30, '50%'],\n center: ['50%', '75%']\n }\n ]\n }\n },\n ...\n]\n</code></pre>\n<p><strong>Priority when multiple queries are satisfied: </strong></p>\n<p>Attention: When multiple <code>query</code> are satisfied at the same time, all of them will be merged with <code>mergeOption</code> and those are defined later will be merged later, thus provides them with higher priority.</p>\n<p><strong>Query by default: </strong></p>\n<p>If an item in <code>media</code> has no not <code>query</code>, then it means <em>default value</em>, which will be used when all other rules fail.</p>\n<p><strong>Pay attention when container size changes:</strong></p>\n<p>In many cases, container DOM node doesn't need to change size with user dragging. Instead, it may set to several sizes on varied ends.</p>\n<p>But if the container DOM node needs to change size with dragging, you need to pay attention to this: if certain configuration item appears in one <code>query option</code>, then it should also appeared in other <code>query option</code>, or it will not be able to return to the original state. (<code>left/right/top/bottom/width/height</code> are not restricted to this rule.)</p>\n<p><strong><code>media</code> in <em>composite option</em> does not support merge</strong></p>\n<p>When <code>chart.setOption(rawOption)</code> for the second, third, fourth, fifth, and etc. times, if <code>rawOption</code> is <code>composite option</code> (which means it contains <code>media</code> list), then, the new <code>rawOption.media</code> list will not merge with the old <code>media</code>. instead, it will simply replace the option. Of course, <code>rawOption.baseOption</code> will still merge with the old option normally.</p>\n<p><br>\nFinally, let's see an example combining with timeline:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/bar-media-timeline&edit=1&reset=1\" width=\"750\" height=\"700\" ></iframe>\n\n\n\n\n\n\n"},"Visual Map of Data":{"type":["*"],"description":"<p>Data visualization is a procedure of mapping data into visual elements. This procedure can also be called visual coding, and visual elements can also be called visual tunnels.</p>\n<p>Every type of charts in ECharts has this built-in mapping procedure. For example, line charts map data into <em>lines</em>, bar charts map data into <em>length</em>. Some more complicated charts, like <code>graph</code>, <code>themeRiver</code>, and <code>treemap</code> have their own built-in mapping.</p>\n<p>Besides, ECharts provides <a href=\"option.html#visualMap\" target=\"_blank\">visualMap component</a> for general visual mapping. Visual elements allowed in <code>visualMap</code> component are:<br>\n<code>symbol</code>, <code>symbolSize</code><br>\n<code>color</code>, <code>opacity</code>, <code>colorAlpha</code>, <br>\n<code>colorLightness</code>, <code>colorSaturation</code>, <code>colorHue</code></p>\n<p>Next, we are going to introduce how to use <code>visualMap</code> component.</p>\n<p><br></p>\n<h2>Data and Dimension</h2>\n\n<p>Data are usually stored in <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> in ECharts. Depending on chart types, like list, tree, graph, and so on, the form of data may vary somehow. But they have one common feature, that they are a collection of <code>dataItem</code>s. Every data item contains data value, and other information if needed. Every data value can be a single value (one dimension) or an array (multiple dimensions).</p>\n<p>For example, <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> is the most common form, which is a <code>list</code>, a common array:</p>\n<pre><code class=\"lang-javascript\">series: {\n data: [\n { // every item here is a dataItem\n value: 2323, // this is data value\n itemStyle: {...}\n },\n 1212, // it can also be a value of dataItem, which is a more common case\n 2323, // every data value here is one dimension\n 4343,\n 3434\n ]\n}\n</code></pre>\n<pre><code class=\"lang-javascript\">series: {\n data: [\n { // every item here is a dataItem\n value: [3434, 129, 'San Marino'], // this is data value\n itemStyle: {...}\n },\n [1212, 5454, 'Vatican'], // it can also be a value of dataItem, which is a more common case\n [2323, 3223, 'Nauru'], // every data value here is three dimension\n [4343, 23, 'Tuvalu'] // If is scatter chart, usually map the first dimension to x axis,\n // the second dimension to y axis,\n // and the third dimension to symbolSize\n ]\n}\n</code></pre>\n<p>Usually the first one or two dimensions are used for mapping. For example, map the first dimension to x axis, and the second dimension to y axis. If you want to represent more dimensions, <code>visualMap</code> is what you need. Most likely, <a href=\"option.html#series-scatter\" target=\"_blank\">scatter charts</a> use radius to represent the third dimension.</p>\n<p><br></p>\n<h2>visualMap Component</h2>\n\n<p>visualMap component defines the mapping from <em>which dimension of data</em> to <em>what visual elements</em>.</p>\n<p>The following two types of visualMap components are supported, identified with <a href=\"option.html#visualMap.type\" target=\"_blank\">visualMap.type</a>.</p>\n<p>Its structure is defined as:</p>\n<pre><code class=\"lang-javascript\">option = {\n visualMap: [ // can define multiple visualMap components at the same time\n { // the first visualMap component\n type: 'continuous', // defined as continuous visualMap\n ...\n },\n { // the second visualMap component\n type: 'piecewise', // defined as discrete visualMap\n ...\n }\n ],\n ...\n};\n</code></pre>\n<p><br>\n<a href=\"option.html#visualMap-continuous\" target=\"_blank\">visualMapContinuous</a>：</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/map-visualMap-continuous&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n<p><a href=\"option.html#visualMap-piecewise\" target=\"_blank\">visualMapPiecewise</a>：</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/scatter-visualMap-piecewise&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n<p><br></p>\n<p>Piecewise visual map component has three types:</p>\n<p>分段型视觉映射组件（visualMapPiecewise），有三种模式：</p>\n<ul>\n<li>Equal division of continuous data: divide equally based on <a href=\"option.html#visualMap-piecewise.splitNumber\" target=\"_blank\">visualMap-piecewise.splitNumber</a>;</li>\n<li>User-defined division of continuous data: divide with range in <a href=\"option.html#visualMap-piecewise.pieces\" target=\"_blank\">visualMap-piecewise.pieces</a>;</li>\n<li>Discrete data (data in category type): divide with <a href=\"option.html#visualMap-piecewise.categories\" target=\"_blank\">visualMap-piecewise.categories</a>.</li>\n</ul>\n<p><br>\n<strong>Configuration of visualMap mapping method</strong></p>\n<p>As we have introduced above, <code>visualMap</code> maps a certain dimension to a certain visual element, we can configure which dimension of the data (see in <a href=\"#visualMap.dimension\">visualMap.dimension</a>) to be mapped to which visual elements (see in <a href=\"option.html#visualMap.inRange\" target=\"_blank\">visualMap.inRange</a> and <a href=\"option.html#visualMap.outOfRange\" target=\"_blank\">visualMap.outOfRange</a>).</p>\n<p>Example A:</p>\n<pre><code class=\"lang-javascript\">option = {\n visualMap: [\n {\n type: 'piecewise'\n min: 0,\n max: 5000,\n dimension: 3, // the fourth dimension of series.data, or value[3], is mapped\n seriesIndex: 4, // map with the fourth series\n inRange: { // visual configuration items in selected range\n color: ['blue', '#121122', 'red'], // defines color list of mapping\n // The largest value will be mapped to 'red',\n // and others will be interpolated\n symbolSize: [30, 100] // the smallest value will be mapped to size of 30,\n // the largest to 100,\n // and others will be interpolated\n },\n outOfRange: { // visual configuration items out of selected range\n symbolSize: [30, 100]\n }\n },\n ...\n ]\n};\n</code></pre>\n<p>Example B:</p>\n<pre><code class=\"lang-javascript\">option = {\n visualMap: [\n {\n ...,\n inRange: { // visual configuration items in selected range\n colorLightness: [0.2, 1], // map to lightness, which will process lightness based on original color\n // original color may be selected from global color palette,\n // which is not concerned by visualMap component\n symbolSize: [30, 100]\n },\n ...\n },\n ...\n ]\n};\n</code></pre>\n<p>For more information, please refer to <a href=\"option.html#visualMap.inRange\" target=\"_blank\">visualMap.inRange</a> and <a href=\"option.html#visualMap.outOfRange\" target=\"_blank\">visualMap.outOfRange</a>.</p>\n"},"Events and Actions in ECharts":{"type":["*"],"description":"<p>User interactions trigger corresponding events in ECharts. Developers can listen to these events and handle accordingly through callback functions, e.g., redirecting to an address, popping out a dialog box, or drilling down data and so on.</p>\n<p>Binding events in ECharts 3 is though <a href=\"api.html#EChartsInstance.on\" target=\"_blank\">on</a> method, same as in ECharts 2. But event names are much simpler than it is in 2. Event names in ECharts 3 are the same as DOM event names, in lowercases. Below is an example of binding clicking operation.</p>\n<pre><code class=\"lang-js\">myChart.on('click', function (params) {\n // printing data name in console\n console.log(params.name);\n});\n</code></pre>\n<p>Event in ECharts can be divided in two kinds. One is mouse event, which is triggered when mouse clicks on certain component, the other is triggered with interaction components, such as triggering <a href=\"api.html#events.legendselectchanged\" target=\"_blank\">'legendselectchanged'</a> event when toggling legend (Notice here, that <code>'legendselected'</code> event will not be triggered when toggling legend), triggering <a href=\"api.html#events.legendselectchanged\" target=\"_blank\">'datazoom'</a> event when data zooming in some area.</p>\n<h2 id=\"mouse-events-handling\">Mouse Events Handling</h2>\n<p>ECharts support regular mouse events, which includes <code>'click'</code>, <code>'dblclick'</code>, <code>'mousedown'</code>, <code>'mousemove'</code>, <code>'mouseup'</code>, <code>'mouseover'</code>, <code>'mouseout'</code>, <code>'globalout'</code>, <code>'contextmenu'</code>. Next let's see an example of opening Baidu search page when clicks a bar chart.</p>\n<pre><code class=\"lang-js\">// initialize ECharts instance based on prepared dom\nvar myChart = echarts.init(document.getElementById('main'));\n\n// data and configuration item of specific chart\nvar option = {\n xAxis: {\n data: ["shirt","cardign","chiffon shirt","pants","heels","socks"]\n },\n yAxis: {},\n series: [{\n name: 'sales',\n type: 'bar',\n data: [5, 20, 36, 10, 10, 20]\n }]\n};\n// use specified configuration item and data to show chart\nmyChart.setOption(option);\n// handle click event and redirect to corresponding Baidu search page\nmyChart.on('click', function (params) {\n window.open('https://www.baidu.com/s?wd=' + encodeURIComponent(params.name));\n});\n</code></pre>\n<p>All types of mouse events have a common parameter called <code>params</code>, which is an object that contains data information of the clicked chart, whose format is as followed:</p>\n<pre><code class=\"lang-js\">{\n // component name of clicked component\n // e.g., 'series', 'markLine', 'markPoint', 'timeLine'\n componentType: string,\n // series type (useful when componentType is 'series')\n // e.g., 'line', 'bar', 'pie'\n seriesType: string,\n // series index in option.series (useful when componentType is 'series')\n seriesIndex: number,\n // series name (useful when componentType is 'series')\n seriesName: string,\n // data name, or category name\n name: string,\n // data index in input data array\n dataIndex: number,\n // raw input data item\n data: Object,\n // Some series, such as sankey or graph, maintains both nodeData and edgeData,\n // in which case, dataType is set to be 'node' or 'edge' to identify.\n // On the other hand, most other series have only one type of data,\n // where dataType is not needed.\n dataType: string,\n // input data value\n value: number|Array\n // color of component (useful when componentType is 'series')\n color: string\n}\n</code></pre>\n<p>How to know where the mouse clicked:</p>\n<pre><code class=\"lang-js\">myChart.on('click', function (params) {\n if (params.componentType === 'markPoint') {\n // clicked on markPoint\n if (params.seriesIndex === 5) {\n // clicked on a markPoint which belongs to a series indexed with 5\n }\n }\n else if (params.componentType === 'series') {\n if (params.seriesType === 'graph') {\n if (params.dataType === 'edge') {\n // clicked on an edge of the graph\n }\n else {\n // clicked on a node of the graph\n }\n }\n }\n});\n</code></pre>\n<p>Use <code>query</code> to call handler only on the graphic elements of the specified components:</p>\n<pre><code class=\"lang-js\">chart.on(eventName, query, handler);\n</code></pre>\n<p><code>query</code> can be <code>string</code> or <code>Object</code>.</p>\n<p>If <code>string</code>, the formatter can be 'mainType' or 'mainType.subType'. For example:</p>\n<pre><code class=\"lang-js\">chart.on('click', 'series', function () {...});\nchart.on('click', 'series.line', function () {...});\nchart.on('click', 'dataZoom', function () {...});\nchart.on('click', 'xAxis.category', function () {...});\n</code></pre>\n<p>If <code>Object</code>, one or more properties below can be included, and any of them is optional.</p>\n<pre><code class=\"lang-js\">{\n <mainType>Index: number // component index\n <mainType>Name: string // component name\n <mainType>Id: string // component id\n dataIndex: number // data item index\n name: string // data item name\n dataType: string // data item type, e.g.,\n // 'node' and 'edge' in graph.\n element: string // element name in custom series\n}\n</code></pre>\n<p>For example:</p>\n<pre><code class=\"lang-js\">chart.setOption({\n // ...\n series: [{\n name: 'uuu'\n // ...\n }]\n});\nchart.on('mouseover', {seriesName: 'uuu'}, function () {\n // When the graphic elements in the series with name 'uuu' mouse overed, this method called.\n});\n</code></pre>\n<p>For example:</p>\n<pre><code class=\"lang-js\">chart.setOption({\n // ...\n series: [{\n // ...\n }, {\n // ...\n data: [\n {name: 'xx', value: 121},\n {name: 'yy', value: 33}\n ]\n }]\n});\nchart.on('mouseover', {seriesIndex: 1, name: 'xx'}, function () {\n // When the graphic elements of the data item with name 'xx' in the series with index 1 mouse overed, this method called.\n});\n</code></pre>\n<p>For example:</p>\n<pre><code class=\"lang-js\">chart.setOption({\n // ...\n series: [{\n type: 'graph',\n nodes: [{name: 'a', value: 10}, {name: 'b', value: 20}],\n edges: [{source: 0, target: 1}]\n }]\n});\nchart.on('click', {dataType: 'node'}, function () {\n // When the nodes of the graph clicked, this method is called.\n});\nchart.on('click', {dataType: 'edge'}, function () {\n // When the edges of the graph clicked, this method is called.\n});\n</code></pre>\n<p>For example:</p>\n<pre><code class=\"lang-js\">chart.setOption({\n // ...\n series: {\n // ...\n type: 'custom',\n renderItem: function (params, api) {\n return {\n type: 'group',\n children: [{\n type: 'circle',\n name: 'my_el',\n // ...\n }, {\n // ...\n }]\n }\n },\n data: [[12, 33]]\n }\n})\nchart.on('click', {element: 'my_el'}, function () {\n // When the element with name 'my_el' clicked, this method called.\n});\n</code></pre>\n<p>You may update chart or show customized layer with information got from your own data warehouse, indexed from data name or series name of an object received from a callback function. Sample code is shown as followed:</p>\n<pre><code class=\"lang-js\">myChart.on('click', function (parmas) {\n $.get('detail?q=' + params.name, function (detail) {\n myChart.setOption({\n series: [{\n name: 'pie',\n // present data distribution of a single bar through pie chart\n data: [detail.data]\n }]\n });\n });\n});\n</code></pre>\n<h2 id=\"interaction-events-with-components\">Interaction Events with Components</h2>\n<p>Basically all component interactions in ECharts trigger corresponding events. Frequently used events and corresponding parameters are listed in <a href=\"api.html#events\" target=\"_blank\">events</a>.</p>\n<p>Below is example that listens to a legend toggling:</p>\n<pre><code class=\"lang-js\">// legend toggling triggers legendselectchanged event only\nmyChart.on('legendselectchanged', function (params) {\n // obtain selecting status of clicked legend\n var isSelected = params.selected[params.name];\n // print in console\n console.log((isSelected ? 'select' : 'unselect') + 'legend' + params.name);\n // print all legend status\n console.log(params.selected);\n});\n</code></pre>\n<h2 id=\"triggering-component-actions-through-code-in-echarts\">Triggering Component Actions through Code in ECharts</h2>\n<p>Actions like <code>'legendselectchanged'</code> mentioned above will be triggered by component interaction. Besides that, sometimes we need to trigger certain actions in our program, such as showing tooltip, or selecting legend.</p>\n<p>ECharts 2.x triggers actions through <code>myChart.component.tooltip.showTip</code>, whose entrance is deep and involves organization of inner components. On the other hand, ECharts 3 triggers actions through <code>myChart.dispatchAction({ type: '' })</code>, which manages all actions in a uniformed way, and may record user's event path when need.</p>\n<p>Frequently used actions and the parameters are listed in <a href=\"api.html#action\" target=\"_blank\">action</a>.</p>\n<p>Below displays how to highlight each sector of pie chart in turn through <code>dispatchAction</code>.</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/pie-highlight&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n\n\n"},"An Example: Implement Dragging":{"type":["*"],"description":"<p>This is a tiny example, introducing how to implement dragging of graphic elements in echarts. From this example, we will see how to make an application with rich intractivity based on echarts API.</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=line-draggable&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n<p>This example mainly implements that dragging points of a curve and by which the curve is modified. Although it is simple example, but we can do more based on that, like edit charts viually. So let's get started from this simple example.</p>\n<p><br></p>\n<h2>[ Part 1 ] Implement basic dragging</h2>\n\n<p>First of all, we create a basic <a href=\"http://echarts.baidu.com/option.html#series-line\" target=\"_blank\">line chart (line series)</a>:</p>\n<pre><code class=\"lang-js\">var symbolSize = 20;\nvar data = [[15, 0], [-50, 10], [-56.5, 20], [-46.5, 30], [-22.1, 40]];\n\nmyChart.setOption({\n xAxis: {\n min: -100,\n max: 80,\n type: 'value',\n axisLine: {onZero: false}\n },\n yAxis: {\n min: -30,\n max: 60,\n type: 'value',\n axisLine: {onZero: false}\n },\n series: [\n {\n id: 'a',\n type: 'line',\n smooth: true,\n // Set a big symbolSize for dragging convenience.\n symbolSize: symbolSize,\n data: data\n }\n ]\n});\n</code></pre>\n<p>Since the symbols in line is not draggable, we make them draggable by using <a href=\"http://echarts.baidu.com/option.html#graphic\" target=\"_blank\">graphic component</a> to add draggable circular elements to symbols respectively.</p>\n<pre><code class=\"lang-js\">myChart.setOption({\n // Declare a graphic component, which contains some graphic elements\n // with the type of 'circle'.\n // Here we have used the method `echarts.util.map`, which has the same\n // behavior as Array.prototype.map, and is compatible with ES5-.\n graphic: echarts.util.map(data, function (dataItem, dataIndex) {\n return {\n // 'circle' means this graphic element is a shape of circle.\n type: 'circle',\n\n shape: {\n // The radius of the circle.\n r: symbolSize / 2\n },\n // Transform is used to located the circle. position:\n // [x, y] means translate the circle to the position [x, y].\n // The API `convertToPixel` is used to get the position of\n // the circle, which will introduced later.\n position: myChart.convertToPixel('grid', dataItem),\n\n // Make the circle invisible (but mouse event works as normal).\n invisible: true,\n // Make the circle draggable.\n draggable: true,\n // Give a big z value, which makes the circle cover the symbol\n // in line series.\n z: 100,\n // This is the event handler of dragging, which will be triggered\n // repeatly while dragging. See more details below.\n // A util method `echarts.util.curry` is used here to generate a\n // new function the same as `onPointDragging`, except that the\n // first parameter is fixed to be the `dataIndex` here.\n ondrag: echarts.util.curry(onPointDragging, dataIndex)\n };\n })\n});\n</code></pre>\n<p>In the code above, API <a href=\"http://echarts.baidu.com/api.html#echartsInstance.convertToPixel\" target=\"_blank\">convertToPixel</a> is used to convert data to its "pixel coodinate", based on which each graphic elements can be rendered on canvas. The term "pixel coodinate" means the coordinate is in canvas pixel, whose origin is the top-left of the canvas. In the sentence <code>myChart.convertToPixel('grid', dataItem)</code>, the first parameter <code>'grid'</code> indicates that <code>dataItem</code> should be converted in the first <a href=\"http://echarts.baidu.com/option.html#grid\" target=\"_blank\">grid component (cartesian)</a>.</p>\n<p><strong>Notice:</strong> <code>convertToPixel</code> should not be called before the first time that <code>setOption</code> called. Namely, it can only be used after coordinate systems (grid/polar/...) initialized.</p>\n<p>Now points have been made draggable. Then we will bind event listeners on dragging to those points.</p>\n<pre><code class=\"lang-js\">// This function will be called repeatly while dragging.\n// The mission of this function is to update `series.data` based on\n// the new points updated by dragging, and to re-render the line\n// series based on the new data, by which the graphic elements of the\n// line series can be synchronized with dragging.\nfunction onPointDragging(dataIndex) {\n // Here the `data` is declared in the code block in the beginning\n // of this article. The `this` refers to the dragged circle.\n // `this.position` is the current position of the circle.\n data[dataIndex] = myChart.convertFromPixel('grid', this.position);\n // Re-render the chart based on the updated `data`.\n myChart.setOption({\n series: [{\n id: 'a',\n data: data\n }]\n });\n}\n</code></pre>\n<p>In the code above, API <a href=\"http://echarts.baidu.com/api.html#echartsInstance.convertFromPixel\" target=\"_blank\">convertFromPixel</a> is used, which is the reversed process of <a href=\"http://echarts.baidu.com/api.html#echartsInstance.convertToPixel\" target=\"_blank\">convertToPixel</a>. <code>myChart.convertFromPixel('grid', this.position)</code> converts a pixel coordinate to data item in <a href=\"http://echarts.baidu.com/option.html#grid\" target=\"_blank\">grid (cartesian)</a>.</p>\n<p>Finally, add those code to make graphic elements responsive to change of canvas size.</p>\n<pre><code class=\"lang-js\">window.addEventListener('resize', function () {\n // Re-calculate the position of each circle and update chart using `setOption`.\n myChart.setOption({\n graphic: echarts.util.map(data, function (item, dataIndex) {\n return {\n position: myChart.convertToPixel('grid', item)\n };\n })\n });\n});\n</code></pre>\n<p><br></p>\n<h2>[ Part 2 ] Add tooltip component</h2>\n\n<p>Now basic functionality have been implemented by parte 1. If we need the data can be displayed realtime when dragging, we can use <a href=\"http://echarts.baidu.com/option.html#tooltip\" target=\"_blank\">tooltip component</a> to do that. Nevertheless, tooltip component has its default "show/hide rule", which is not applicable in this case. So we need to customize the "show/hide rule" for our case.</p>\n<p>Add these snippets to the code block above:</p>\n<pre><code class=\"lang-js\">myChart.setOption({\n ...,\n tooltip: {\n // Means disable default "show/hide rule".\n triggerOn: 'none',\n formatter: function (params) {\n return 'X: ' + params.data[0].toFixed(2) + '<br>Y: ' + params.data[1].toFixed(2);\n }\n }\n});\n</code></pre>\n<pre><code class=\"lang-js\">myChart.setOption({\n graphic: echarts.util.map(data, function (item, dataIndex) {\n return {\n type: 'circle',\n ...,\n // Customize "show/hide rule", show when mouse over, hide when mouse out.\n onmousemove: echarts.util.curry(showTooltip, dataIndex),\n onmouseout: echarts.util.curry(hideTooltip, dataIndex),\n };\n })\n});\n\nfunction showTooltip(dataIndex) {\n myChart.dispatchAction({\n type: 'showTip',\n seriesIndex: 0,\n dataIndex: dataIndex\n });\n}\n\nfunction hideTooltip(dataIndex) {\n myChart.dispatchAction({\n type: 'hideTip'\n });\n}\n</code></pre>\n<p>The API <a href=\"http://echarts.baidu.com/api.html#echartsInstance.dispatchAction\" target=\"_blank\">dispatchAction</a> is used to show/hide tooltip content, where actions <a href=\"http://echarts.baidu.com/api.html#action.tooltip.showTip\" target=\"_blank\">showTip</a> and <a href=\"http://echarts.baidu.com/api.html#action.tooltip.hideTip\" target=\"_blank\">hideTip</a> is dispatched.</p>\n<p><br></p>\n<h2>[ Part 3 ] Full code</h2>\n\n<p>Full code is shown as follow:</p>\n<pre><code><!DOCTYPE html>\n<html>\n<head>\n <meta charset="utf-8">\n <script src="http://echarts.baidu.com/dist/echarts.min.js"></script>\n</head>\n<body>\n <div id="main" style="width: 600px;height:400px;"></div>\n <script type="text/javascript">\n\n var symbolSize = 20;\n var data = [[15, 0], [-50, 10], [-56.5, 20], [-46.5, 30], [-22.1, 40]];\n\n var myChart = echarts.init(document.getElementById('main'));\n\n myChart.setOption({\n tooltip: {\n triggerOn: 'none',\n formatter: function (params) {\n return 'X: ' + params.data[0].toFixed(2) + '<br>Y: ' + params.data[1].toFixed(2);\n }\n },\n xAxis: {\n min: -100,\n max: 80,\n type: 'value',\n axisLine: {onZero: false}\n },\n yAxis: {\n min: -30,\n max: 60,\n type: 'value',\n axisLine: {onZero: false}\n },\n series: [\n {\n id: 'a',\n type: 'line',\n smooth: true,\n symbolSize: symbolSize,\n data: data\n }\n ],\n });\n\n myChart.setOption({\n graphic: echarts.util.map(data, function (item, dataIndex) {\n return {\n type: 'circle',\n position: myChart.convertToPixel('grid', item),\n shape: {\n r: symbolSize / 2\n },\n invisible: true,\n draggable: true,\n ondrag: echarts.util.curry(onPointDragging, dataIndex),\n onmousemove: echarts.util.curry(showTooltip, dataIndex),\n onmouseout: echarts.util.curry(hideTooltip, dataIndex),\n z: 100\n };\n })\n });\n\n window.addEventListener('resize', function () {\n myChart.setOption({\n graphic: echarts.util.map(data, function (item, dataIndex) {\n return {\n position: myChart.convertToPixel('grid', item)\n };\n })\n });\n });\n\n function showTooltip(dataIndex) {\n myChart.dispatchAction({\n type: 'showTip',\n seriesIndex: 0,\n dataIndex: dataIndex\n });\n }\n\n function hideTooltip(dataIndex) {\n myChart.dispatchAction({\n type: 'hideTip'\n });\n }\n\n function onPointDragging(dataIndex, dx, dy) {\n data[dataIndex] = myChart.convertFromPixel('grid', this.position);\n myChart.setOption({\n series: [{\n id: 'a',\n data: data\n }]\n });\n }\n\n</script>\n</body>\n</html>\n</code></pre><p><br></p>\n<p>With knowledge introduced above, more feature can be implemented. For example, <a href=\"http://echarts.baidu.com/option.html#dataZoom\" target=\"_blank\">dataZoom component</a> can be added to cooperate with the cartesian, or we can make a plotting board on coordinate systems. Use your imagination ~</p>\n"},"Custom Series":{"type":["*"],"description":"<p><a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom\" target=\"_blank\">custom series</a> is a type of series, which enable develpers to customize graphic elements rendering and generate new types of chart.</p>\n<p>Why echarts supports <code>custom series</code>? There are endless chart types in the world of data visualization, which are not enumerable. Thus only most common used chart types are built-in supported in echarts. For other chart types, it is necessary to provide an approach to make new types of chart for developers. This approach should be as simple as possible, which had better not to bothered developers with some details of implementation, such as creating and deleting graphic elements, transition animation, tooltip supporting, working with <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#dataZoom\" target=\"_blank\">dataZoom</a> or <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#visualMap\" target=\"_blank\">visualMap</a>. Having considered the factors above, a solution <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom\" target=\"_blank\">custom series</a> is published.</p>\n<p><strong>For example, a "x-range" chart is made by custom sereis:</strong></p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=custom-profile&reset=1&edit=1\" width=\"800\" height=\"500\" ></iframe>\n\n\n<p><strong><a href=\"https://ecomfe.github.io/echarts-examples/public/index.html#chart-type-custom\" target=\"_blank\">More samples of custom series</a></strong></p>\n<p>Let's begin the tutorial.</p>\n<p><br></p>\n<h2>(I) The method <code>renderItem</code></h2>\n\n<p>The snippet of graphic elements rendering should be written in <code>renderItem</code> method my developers. For example:</p>\n<pre><code class=\"lang-js\">var option = {\n ...,\n series: [{\n type: 'custom',\n renderItem: function (params, api) {\n // ...\n },\n data: data\n }]\n}\n</code></pre>\n<p>In the rendering phase of echarts workflow, <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> is called respectively for each <code>dataItem</code> in <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.data\" target=\"_blank\">series.data</a>. <code>renderItem</code> is responsible for build a group of definitions of graphic elements, including graphic type, size, location, style, etc. echarts will then build graphic elements according to those definitions. For example:</p>\n<pre><code class=\"lang-js\">var option = {\n ...,\n series: [{\n type: 'custom',\n renderItem: function (params, api) {\n // This method will be called for each dataItem repectively.\n // Notice: it does not ensure that called according to the order\n // of `dataItem`.\n\n // Some processes, such as coordinate conversion.\n // `api.value(0)` is used to retrieve the value on the first\n // dimension in the current `dataItem`.\n var categoryIndex = api.value(0);\n // `api.coord(...)` is used to convert data values to pixel values,\n // will are necessary for graphic elements rendering.\n var startPoint = api.coord([api.value(1), categoryIndex]);\n var endPoint = api.coord([api.value(2), categoryIndex]);\n // `api.size(...)` is used to calculate the pixel size corresponding to\n // the a value range that the length is 1 on Y axis.\n var height = api.size([0, 1])[1] * 0.6;\n\n // The property `shape` incicates the location and size of thsi\n // element.\n // `echarts.graphic.clipRectByRect` is used for clipping the\n // rectangular when it overflow the bounding box of the current\n // coordinate system (cartesian).\n // If the rect is totally clipped, returns undefined.\n var rectShape = echarts.graphic.clipRectByRect({\n // position and location of the rectangular.\n x: startPoint[0],\n y: startPoint[1] - height / 2,\n width: endPoint[0] - startPoint[0],\n height: height\n }, {\n // Bounding box of the current cooridinate system (cartesian).\n x: params.coordSys.x,\n y: params.coordSys.y,\n width: params.coordSys.width,\n height: params.coordSys.height\n })\n\n // Returns definitions for the current `dataItem`.\n return rectShape && {\n // 'rect' indicates that the graphic element is rectangular.\n // Can also be 'circle', 'sector', 'polygon', ...\n type: 'rect',\n shape: rectShape,\n // `api.style(...)` is used to obtain style settings, which\n // includes itemStyle settings in optino and the result of\n // visual mapping.\n style: api.style()\n };\n },\n data: [\n [12, 44, 55, 60], // The first dataItem.\n [53, 31, 21, 56], // The second dataItem.\n [71, 33, 10, 20], // The third dataItem.\n ...\n ]\n }]\n}\n</code></pre>\n<p><a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> provides two parameters:</p>\n<ul>\n<li><a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.arguments.params\" target=\"_blank\">params</a>：provides info about the current series (such as <code>seriesIndex</code>、<code>dataIndex</code>, etc.) and data (such as <code>dataIndex</code>, <code>dataIndexInside</code>, etc.) and coordinate system (such as location and size of bounding box of the current coordinate system)</li>\n<li><a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.arguments.api\" target=\"_blank\">api</a> provides some methods to developers (such as <code>api.value()</code>, <code>api.coord()</code>).</li>\n</ul>\n<p><a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> method should return definitions of graphic elements for the current <code>dataItem</code>. See <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.return\" target=\"_blank\">renderItem.return</a>.</p>\n<p>Generally, the main process of <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> is that retrieve value from data and convert them to graphic elements on the current coordinate system. Two methods in <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.arguments.api\" target=\"_blank\">renderItem.arguments.api</a> are always used in this procedure:</p>\n<ul>\n<li><a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.arguments.api.value\" target=\"_blank\">api.value(...)</a> is used to retrieve value from data. For example, <code>api.value(0)</code> retrieve the value of the first dimension in the current data item.</li>\n<li><a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.arguments.api.coord\" target=\"_blank\">api.coord(...)</a> is used to convert data to coordinate. For example, <code>var point = api.coord([api.value(0), api.value(1)])</code> converet the data to the point on the current coordinate system.</li>\n</ul>\n<p>Sometimes <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.arguments.api.size\" target=\"_blank\">api.size(...)</a> method is needed, which calculates the size on the coordinate system by a given data range.</p>\n<p>Moreover, <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.arguments.api.style\" target=\"_blank\">api.style(...)</a> method can be used to set style. It provides not only the style settings specified in <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.itemStyle\" target=\"_blank\">series.itemStyle</a>, but also the result of visual mapping. This method can also be called like <code>api.style({fill: 'green', stroke: 'yellow'})</code> to override those style settings.</p>\n<p>Having <code>renderItem</code> provided, 90% of the work of creating custom series has been accomplished. The rest of this work is to refine and polish them.</p>\n<p><br></p>\n<h2>(II) Make the extent of axes fit the data</h2>\n\n<p>There is axes in some coordinate systems, such as <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#grid\" target=\"_blank\">cartesian2d (grid)</a>and <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#polar\" target=\"_blank\">polar</a>. The extent of an axis should fit the data automatically, otherwise the graphic elements would be overflow the bounding box of the coordinate system. So, for example, in <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#grid\" target=\"_blank\">cartesian2d (grid)</a>, developers should specify that which dimensions correspond to <code>x</code> axis and which to <code>y</code> axis use the property <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.encode\" target=\"_blank\">encode</a>:</p>\n<pre><code class=\"lang-js\">option = {\n series: [{\n type: 'custom',\n renderItem: function () {\n ...\n },\n encode: {\n // `dim1` and `dim2` correspond to `x` axis.\n x: [1, 2],\n // `dim0` corresponds to `y` axis.\n y: 0\n },\n data: [\n // dim0 dim1 dim2 dim3\n [ 12, 44, 55, 60 ], // The first dataItem.\n [ 53, 31, 21, 56 ], // The second dataItem.\n [ 71, 33, 10, 20 ], // The third dataItem.\n ...\n ]\n }]\n};\n</code></pre>\n<p><br></p>\n<h2>(III) Set tooltip content</h2>\n\n<p>Of course <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#tooltip.formatter\" target=\"_blank\">tooltip.formatter</a> can be used to define the content in tooltip. But it is easier to do that by setting <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.encode\" target=\"_blank\">encode</a> and <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.dimensions\" target=\"_blank\">dimensions</a>:</p>\n<pre><code class=\"lang-js\">option = {\n series: [{\n type: 'custom',\n renderItem: function () {\n ...\n },\n encode: {\n x: [1, 2],\n y: 0,\n // `dim2` and `dim3` will displayed in tooltip.\n tooltip: [2, 3]\n },\n // `dim2` is named as "Age" and `dim3` is named as "Satisfaction".\n dimensions: [null, null, 'Age', 'Satisfaction'],\n data: [\n // dim0 dim1 dim2 dim3\n [ 12, 44, 55, 60 ],\n [ 53, 31, 21, 56 ],\n [ 71, 33, 10, 20 ],\n ...\n ]\n }]\n};\n</code></pre>\n<p><br>\n<br>\n<br></p>\n<hr>\n<p>Several other issues about <code>custom series</code> are introduced below.</p>\n<p><br></p>\n<h2>(IV) Shape clipping when overflow the coordinates area</h2>\n\n<p>When use <code>custom series</code> with <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#dataZoom\" target=\"_blank\">dataZoom</a>, <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#dataZoom.filterMode\" target=\"_blank\">dataZoom.filterMode</a> usually be set as <code>'weakFilter'</code>, which prevent <code>dataItem</code> from being filtered when only part of its dimensions are out of the current data window. For example:</p>\n<pre><code class=\"lang-js\">option = {\n dataZoom: {\n xAxisIndex: 0,\n filterMode: 'weakFilter'\n },\n series: [{\n type: 'custom',\n renderItem: function () {\n ...\n },\n encode: {\n x: [1, 2],\n y: 0\n },\n data: [\n // dim0 dim1 dim2 dim3\n [ 12, 44, 55, 60 ], // The first dataItem.\n [ 53, 31, 21, 56 ], // The second dataItem.\n [ 71, 33, 10, 20 ], // The third dataItem.\n ...\n ]\n }]\n};\n</code></pre>\n<p>In the example above, <code>dim</code> and <code>dim2</code> corresponds to <code>x</code> axis, and the <code>dataZoom</code> component constrols the data window of <code>x</code> axis. If part of a <code>dataItem</code> is overflow the extent of <code>x</code> axis (the value on <code>dim1</code> is overflow and the value on <code>dim2</code> is not) while zooming, the <code>dataItem</code> will not be filtered if <code>dataZoom.filterMode = 'weakFilter'</code> set. Thus the <code>dataItem</code> can be still rendered (usually be partially rendered by using <code>echarts.graphic.clipRectByRect</code> to clip the exceeding part).\nSee the example mentioned above <a href=\"https://www.echartsjs.com/examples/en/editor.html?c=custom-profile\" target=\"_blank\">Profile</a>.</p>\n<p><br></p>\n<p><br></p>\n<h2>(V) About dataIndex</h2>\n\n\n<p>Developers had better notice that in <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.arguments.params\" target=\"_blank\">renderItem.arguments.params</a> <code>dataIndexInside</code> and <code>dataIndex</code> is different:</p>\n<ul>\n<li><code>dataIndex</code> is the index of a <code>dataItem</code> in the original data.</li>\n<li><code>dataIndexInside</code> is the index of a <code>dataItem</code> in the current data window (see <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#dataZoom\" target=\"_blank\">dataZoom</a>.</li>\n</ul>\n<p><a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.arguments.api\" target=\"_blank\">renderItem.arguments.api</a> uses <code>dataIndexInside</code> as the input parameter but not <code>dataIndex</code>, because conversion from <code>dataIndex</code> to <code>dataIndexInside</code> is time-consuming.</p>\n<p><br></p>\n<h2>(VI) Event listener</h2>\n\n\n<pre><code class=\"lang-js\">chart.setOption({\n // ...\n series: {\n type: 'custom',\n renderItem: function () {\n // ...\n return {\n type: 'group',\n children: [{\n type: 'circle'\n // ...\n }, {\n type: 'circle',\n name: 'aaa',\n // User specified info, available\n // in event handler.\n info: 12345,\n // ...\n }]\n };\n }\n }\n});\nchart.on('click', {element: 'aaa'}, function (params) {\n // When the element with name 'aaa' clicked,\n // this method called.\n console.log(params.info);\n});\n</code></pre>\n<p><br></p>\n<h2>(VII) Custom vector shapes</h2>\n\n\n<p><a href=\"http://www.w3.org/TR/SVG/paths.html#PathData\" target=\"_blank\">SVG PathData</a> is supported, which enables to use shapes that are created in vector tool. See <a href=\"https://ecomfe.github.io/echarts-doc/public/en/option.html#series-custom.renderItem.return_path\" target=\"_blank\">path</a>, and examples: <a href=\"https://ecomfe.github.io/echarts-examples/public/index.html?c=custom-calendar-icon\" target=\"_blank\">icons</a>, <a href=\"https://ecomfe.github.io/echarts-examples/public/index.html?c=custom-gantt-flight\" target=\"_blank\">shapes</a>.</p>\n<p><br></p>\n<p><strong><a href=\"https://ecomfe.github.io/echarts-examples/public/index.html#chart-type-custom\" target=\"_blank\">More examples about custom series</a></strong></p>\n"},"Rich Text":{"type":["*"],"description":"<p>Rich text can be used in labels of series, axis or other components. For example:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=pie-rich-text&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=treemap-obama&edit=1&reset=1\" width=\"800\" height=\"550\" ></iframe>\n\n\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=bar-rich-text&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n<p><br></p>\n<p>More examples:\n<a href=\"https://www.echartsjs.com/examples/en/editor.html?c=map-labels&edit=1&reset=1\" target=\"_blank\">Map Labels</a>,\n<a href=\"https://www.echartsjs.com/examples/en/editor.html?c=pie-nest&edit=1&reset=1\" target=\"_blank\">Pie Labels</a>,\n<a href=\"https://www.echartsjs.com/examples/en/editor.html?c=gauge-car&edit=1&reset=1\" target=\"_blank\">Gauge</a>.</p>\n<p><br></p>\n<p>Before v3.7, the style options was only able to applied to the whole label text block, and only color and font can be configured, which restricted the expressability of text descriptions.</p>\n<p>Since v3.7, rich text has been supported:</p>\n<ul>\n<li>Box styles (background, border, shadow, etc.), rotation, position of a text block can be specified.</li>\n<li>Styles (color, font, width/height, background, shadow, etc.) and alignment can be customzied on fregments of text.</li>\n<li>Image can be used in text as icon or background.</li>\n<li>Combine these configurations, some special effects can be made, such as simple table, horizontal rule (hr).</li>\n</ul>\n<p>At the begining, the meanings of two terms that will be used below should be clarified:</p>\n<ul>\n<li>Text Block: The whole block of label text.</li>\n<li>Text Fregment: Some piece of text in a text block.</li>\n</ul>\n<p>For example:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/text-block-fregment&edit=1&reset=1\" width=\"340\" height=\"240\" ></iframe>\n\n\n\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Options about Text</strong></p>\n<p>echarts provides plenty of text options, including:</p>\n<ul>\n<li>Basic font style: <code>fontStyle</code>, <code>fontWeight</code>, <code>fontSize</code>, <code>fontFamily</code>.</li>\n<li>Fill of text: <code>color</code>.</li>\n<li>Stroke of text: <code>textBorderColor</code>, <code>textBorderWidth</code>.</li>\n<li>Shadow of text: <code>textShadowColor</code>, <code>textShadowBlur</code>, <code>textShadowOffsetX</code>, <code>textShadowOffsetY</code>.</li>\n<li>Box size of text block or text fregment: <code>lineHeight</code>, <code>width</code>, <code>height</code>, <code>padding</code>.</li>\n<li>Alignment of text block or text fregment: <code>align</code>, <code>verticalAlign</code>.</li>\n<li>Border, background (color or image) of text block or text fregment: <code>backgroundColor</code>, <code>borderColor</code>, <code>borderWidth</code>, <code>borderRadius</code>.</li>\n<li>Shadow of text block or text fregment: <code>shadowColor</code>, <code>shadowBlur</code>, <code>shadowOffsetX</code>, <code>shadowOffsetY</code>.</li>\n<li>Position and rotation of text block: <code>position</code>, <code>distance</code>, <code>rotate</code>.</li>\n</ul>\n<p>User can defined styles for text fregment in <code>rich</code> property. For example, <a href=\"option.html#series-bar.label.rich\" target=\"_blank\">series-bar.label.rich</a></p>\n<p>For example:</p>\n<pre><code class=\"lang-js\">label: {\n // Styles defined in 'rich' can be applied to some fregments\n // of text by adding some markers to those fregment, like\n // `{styleName|text content text content}`.\n // `'\\n'` is the newline character.\n formatter: [\n '{a|Style "a" is applied to this fregment}'\n '{b|Style "b" is applied to this fregment}This fregment use default style{x|use style "x"}'\n ].join('\\n'),\n\n // Styles for the whole text block are defined here:\n color: '#333',\n fontSize: 5,\n fontFamily: 'Arial',\n borderWidth: 3,\n backgroundColor: '#984455',\n padding: [3, 10, 10, 5],\n lineHeight: 20,\n\n // Styles for text fregments are defined here:\n rich: {\n a: {\n color: 'red',\n lineHeight: 10\n },\n b: {\n backgroundColor: {\n image: 'xxx/xxx.jpg'\n },\n height: 40\n },\n x: {\n fontSize: 18,\n fontFamily: 'Microsoft YaHei',\n borderColor: '#449933',\n borderRadius: 4\n },\n ...\n }\n}\n</code></pre>\n<blockquote>\n<p>Notice: <code>width</code> 和 <code>height</code> only work when <code>rich</code> specified.</p>\n</blockquote>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Basic Styles of Text, Text Block and Text Fragment</strong></p>\n<p>Basic font style can be set to text: <code>fontStyle</code>, <code>fontWeight</code>, <code>fontSize</code>, <code>fontFamily</code>.</p>\n<p>Fill color and stroke color can be set to text: <code>color</code>, <code>textBorderColor</code>, <code>textBorderWidth</code>.</p>\n<p>Border style and background style can be set to text block: <code>borderColor</code>, <code>borderWidth</code>, <code>backgroundColor</code>, <code>padding</code>.</p>\n<p>Border style and background style can be set to text fregment too: <code>borderColor</code>, <code>borderWidth</code>, <code>backgroundColor</code>, <code>padding</code>.</p>\n<p>For example:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/text-options&edit=1&reset=1\" width=\"700\" height=\"300\" ></iframe>\n\n\n\n\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Label Position</strong></p>\n<p><code>label</code> option can be use in charts like <code>bar</code>, <code>line</code>, <code>scatter</code>, etc. The position of a label, can be specified by <a href=\"option.html#series-scatter.label.position\" target=\"_blank\">label.position</a>、<a href=\"option.html#series-scatter.label.distance\" target=\"_blank\">label.distance</a>.</p>\n<p>For example:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/label-position&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n<blockquote>\n<p>Notice, there are different optional values of <code>position</code> by different chart types. And <code>distance</code> is not supported in every chart. More detailed info can be checked in <a href=\"option.html\" target=\"_blank\">option doc</a>.</p>\n</blockquote>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Label Rotation</strong></p>\n<p>Sometimes label is needed to be rotated. For example:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=bar-label-rotation&edit=1&reset=1\" width=\"900\" height=\"500\" ></iframe>\n\n\n<p><a href=\"option.html#series-bar.label.align\" target=\"_blank\">align</a> and<a href=\"option.html#series-bar.label.verticalAlign\" target=\"_blank\">verticalAlign</a> can be used to adjust location of label in this scenario.</p>\n<p>Notice, <code>align</code> and <code>verticalAlign</code> are applied firstly, then rotate.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Layout and Alignment of Text Fregment</strong></p>\n<p>To understand the layout rule, every text fregment can be imagined as a <code>inline-block</code> dom element in CSS.</p>\n<p><code>content box size</code> of a text fregment is determined by its font size by default. It can also be specified directly by <code>width</code> and <code>height</code>, although they are rarely set. <code>border box size</code> of a text fregment is calculated by adding the <code>border box size</code> and <code>padding</code>.</p>\n<p>Only <code>'\\n'</code> is the newline character, which breaks a line.</p>\n<p>Multiple text fregment exist in a single line. The height of a line is determined by the biggest <code>lineHeight</code> of text fregments. <code>lineHeight</code> of a text fregment can be specified in <code>rich</code>, or in the parent level of <code>rich</code>, otherwise using <code>box size</code> of the text fregment.</p>\n<p>Having <code>lineHeight</code> determined, the vertical position of text fregments can be determined by <code>verticalAlign</code> (there is a little different from the rule in CSS):</p>\n<ul>\n<li><code>'bottom'</code>: The bottom edge of the text fregment sticks to the bottom edge of the line.</li>\n<li><code>'top'</code>: The top edge of the text fregment sticks to the top edge of the line.</li>\n<li><code>'middle'</code>: In the middle of the line.</li>\n</ul>\n<p>The width of a text block can be specified by <code>width</code>, otherwise, by the longest line. Having the width determined, text fregment can be placed in each line, where the horizontal position of text fregments can be determined by its <code>align</code>.</p>\n<ul>\n<li>Firstly, place text fregments whose <code>align</code> is <code>'left'</code> from left to right continuously.</li>\n<li>Secondly, place text fregments whose <code>align</code> is <code>'right'</code> from right to left continuously.</li>\n<li>Finally, the text fregments remained will be sticked and placed in the center of the rest of space.</li>\n</ul>\n<p>The position of text in a text fregment:</p>\n<ul>\n<li>If <code>align</code> is <code>'center'</code>, text aligns at the center of the text fregment box.</li>\n<li>If <code>align</code> is <code>'left'</code>, text aligns at the left of the text fregment box.</li>\n<li>If <code>align</code> is <code>'right'</code>, text aligns at the right of the text fregment box.</li>\n</ul>\n<p>For example:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/text-fregment-align&edit=1&reset=1\" width=\"800\" height=\"220\" ></iframe>\n\n\n\n\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Effects: Icon, Horizontal Rule, Title Block, Simple Table</strong></p>\n<p>See example:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/title-block&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n<p>Icon is implemented by using image in <code>backgroundColor</code>.</p>\n<pre><code class=\"lang-js\">rich: {\n Sunny: {\n backgroundColor: {\n image: './data/asset/img/weather/sunny_128.png'\n },\n // Can only height specified, but leave width auto obtained\n // from the image, where the aspect ratio kept.\n height: 30\n }\n}\n</code></pre>\n<p>Horizontal rule (like HTML <hr> tag) can be implemented by border:</p>\n<pre><code class=\"lang-js\">rich: {\n hr: {\n borderColor: '#777',\n // width is set as '100%' to fullfill the text block.\n // Notice, the percentage is based on the content box, without\n // padding. Although it is a little different from CSS rule,\n // it is convinent in most cases.\n width: '100%',\n borderWidth: 0.5,\n height: 0\n }\n}\n</code></pre>\n<p>Title block can be implemented by <code>backgroundColor</code>:</p>\n<pre><code class=\"lang-js\">// Title is at left.\nformatter: '{titleBg|Left Title}',\nrich: {\n titleBg: {\n backgroundColor: '#000',\n height: 30,\n borderRadius: [5, 5, 0, 0],\n padding: [0, 10, 0, 10],\n width: '100%',\n color: '#eee'\n }\n}\n\n// Title is in the center of the line.\n// This implementation is a little tricky, but is works\n// without more complicated layout mechanism involved.\nformatter: '{tc|Center Title}{titleBg|}',\nrich: {\n titleBg: {\n align: 'right',\n backgroundColor: '#000',\n height: 30,\n borderRadius: [5, 5, 0, 0],\n padding: [0, 10, 0, 10],\n width: '100%',\n color: '#eee'\n }\n}\n</code></pre>\n<p>Simple table can be implemented by specify the same width to text fregments that are in the same column of different lines. See the <a href=\"https://www.echartsjs.com/examples/en/view.html?c=pie-rich-text&edit=1&reset=1\" target=\"_blank\">example</a> at the mentioned above.</p>\n"},"Server-side Rendering":{"type":["*"],"description":"<p>ECharts can be rendered at server-side. For example, the thumbnails in the <a href=\"http://www.echartsjs.com/examples/\" target=\"_blank\">official examples page</a> are generated at a server.</p>\n<p>Commonly used headless tool is required, for example, <a href=\"https://github.com/GoogleChrome/puppeteer\" target=\"_blank\">puppeteer</a>, <a href=\"https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md\" target=\"_blank\">headless chrome</a>, <a href=\"https://github.com/Automattic/node-canvas\" target=\"_blank\">node-canvas</a>, <a href=\"https://github.com/jsdom/jsdom\" target=\"_blank\">jsdom</a>, <a href=\"http://phantomjs.org/\" target=\"_blank\">PhantomJS</a>, etc.</p>\n<p>Some solutions contributed by the community are list as follows:</p>\n<ul>\n<li><a href=\"https://github.com/hellosean1025/node-echarts\" target=\"_blank\">https://github.com/hellosean1025/node-echarts</a></li>\n<li><a href=\"https://github.com/chfw/echarts-scrappeteer\" target=\"_blank\">https://github.com/chfw/echarts-scrappeteer</a></li>\n<li><a href=\"https://github.com/chfw/pyecharts-snapshot/blob/master/pyecharts_snapshot/phantomjs/snapshot.js\" target=\"_blank\">https://github.com/chfw/pyecharts-snapshot/blob/master/pyecharts_snapshot/phantomjs/snapshot.js</a></li>\n</ul>\n"},"Render by Canvas or SVG":{"type":["*"],"description":"<p>Most of browser-side charting libraries use SVG or Canvas as their underlying renderer. In the scope of charts, they are usually alternative, without critical differences. But in some environment and scenarios, they show notable differences in performance or functionality.</p>\n<p>ECharts has been using Canvas as its renderer (use VML for IE8-) from the begining. Now, from <a href=\"https://github.com/ecomfe/echarts/releases\" target=\"_blank\">ECharts v3.8</a> we provide a SVG renderer (beta version) as another option. Either of them can be used by specifing parameter <a href=\"https://ecomfe.github.io/echarts-doc/public/en/api.html#echarts.init\" target=\"_blank\">renderer</a> as <code>'canvas'</code> or <code>'svg'</code> when initailizing a chart instance.</p>\n<blockquote>\n<p>That both SVG and Canvas, who are very different in use, are able to be supported in ECharts owns to the abstruction in its underlying render library <a href=\"https://github.com/ecomfe/zrender\" target=\"_blank\">zender</a>, where they are implemented as a Canvas renderer and a alternative SVG renderer.</p>\n</blockquote>\n<h2 id=\"how-to-make-a-choice-\">How to make a choice?</h2>\n<p>Generally speaking, Canvas is suitable for the case that there is a large amount of grpahic elements (which basically due to a large amount of data), like heatmap and lines or scatter plot with large data in geo or parallel coordinates. Besides it supports some <a href=\"https://ecomfe.github.io/echarts-examples/public/editor.html?c=lines-bmap-effect\" target=\"_blank\">special visual effect</a>. But in some other scenarios SVG has some critical advantages: it consumes less memory then Canvas (especially in mobile device), and gives better performance in rendering. Moreover, it never blurs when zooming the viewport of browser whereas Canvas may blurs. For example, we have tried to render line, bar, pie charts with the Canvas renderer and the SVG renderer, and recorded the frame rate during the the stage that the initial animation performed:</p>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/canvas-vs-svg-en&reset=1\" width=\"90%\" height=\"400\" ></iframe>\n\n\n<p>In the scenarios above, the SVG renderer has provided a better FPS performance in mobile devices. In some other scenarios, where big data amount or certain kinds of human interactions exists, the SVG renderer is still not as good as the Canvas renderer in performance, but two options provides the ability to optimize the performance according to the requirements of each developer.</p>\n<p>How to make a choice? These factors, hardware and software environment, data amount and functional requirements, should be considered.</p>\n<ul>\n<li>If the environment is not harsh and the data amount is not large, both of them can be used, no need to pay attention too much.</li>\n<li>If some harsh environment caused performance problem, we can attempt to get better result by choose appropriate renderer.<ul>\n<li>If lots of echarts instances have to be created and it cause browser crash (it probably caused by that the large memory consumption of those Canvas instances is beyond the limit of some mobile devices) we can try the SVG renderer. Or, generally, if charts runs in some old Android devices, or if we are using some kind of charts like <a href=\"https://ecomfe.github.io/echarts-liquidfill/example/\" target=\"_blank\">liquidfill</a>, the SVG renderer probably gives a better performance.</li>\n<li>If visualizing a large amount of data, or complicated human interactions with data is required, the Canvas renderer works better currently.</li>\n</ul>\n</li>\n</ul>\n<p>Therefore <a href=\"https://github.com/ecomfe/echarts/issues/new\" target=\"_blank\">feedback</a> of experiences and usage scenarios are strongly welcomed, which will make the these renderers better and better.</p>\n<p>Notice: The features of rich text, shadow and texture have not been supported yet in the current beta version of the SVG renderer.</p>\n<h2 id=\"how-to-use-specify-a-renderer-\">How to use specify a renderer?</h2>\n<p>ECharts uses Canvas by default. If user intends to use the SVG renderer, the module of the SVG renderer should be included in ECharts bundle.</p>\n<ul>\n<li>In the <a href=\"https://ecomfe.github.io/echarts-doc/public/en/download.html\" target=\"_blank\">pre-build</a> of ECharts, the SVG renderer has been included in <a href=\"https://raw.githubusercontent.com/ecomfe/echarts/3.7.2/dist/echarts.common.min.js\" target=\"_blank\">common version</a> and <a href=\"https://raw.githubusercontent.com/ecomfe/echarts/3.7.2/dist/echarts.min.js\" target=\"_blank\">complete version</a>. But not in <a href=\"https://raw.githubusercontent.com/ecomfe/echarts/3.7.2/dist/echarts.simple.min.js\" target=\"_blank\">simple version</a>.</li>\n<li>If <a href=\"http://echarts.baidu.com/builder.html\" target=\"_blank\">build ECharts online</a>, the checkbox "SVG 渲染" should be checked.</li>\n<li>If <a href=\"http://echarts.baidu.com/tutorial.html#Create%20Custom%20Build%20of%20ECharts\" target=\"_blank\">build ECharts offline</a>, the module of the SVG renderer should be imported:</li>\n</ul>\n<pre><code class=\"lang-js\">import 'zrender/lib/svg/svg';\n</code></pre>\n<p>Then wen can specify renderer by <a href=\"https://ecomfe.github.io/echarts-doc/public/en/api.html#echarts.init\" target=\"_blank\">parameter</a>:</p>\n<pre><code class=\"lang-js\">// Use the Canvas renderer (default).\nvar chart = echarts.init(containerDom, null, {renderer: 'canvas'});\n// which is equal to:\nvar chart = echarts.init(containerDom, null, {renderer: 'canvas'});\n\n// Use the SVG renderer.\nvar chart = echarts.init(containerDom, null, {renderer: 'svg'});\n</code></pre>\n"},"Supporting ARIA in Charts":{"type":["*"],"description":"<p>W3C defined the Accessible Rich Internet Applications Suite (<a href=\"https://www.w3.org/WAI/intro/aria\" target=\"_blank\">WAI-ARIA</a>) to make Web content and Web applications more accessible to the disabled. From ECharts 4.0, we support ARIA by generating description for charts automatically.</p>\n<p>By default, ARIA is disabled. To enable it, you should set <a href=\"#aria.show\">aria.show</a> to be <code>true</code>. After enabling, it will generate descriptions based on charts, series, data, and so on. Users may change the generated description.</p>\n<p><strong>For example:</strong></p>\n<p>For config:</p>\n<pre><code class=\"lang-js\">option = {\n aria: {\n show: true\n },\n title: {\n text: '某站点用户访问来源',\n x: 'center'\n },\n series: [\n {\n name: '访问来源',\n type: 'pie',\n data: [\n { value: 335, name: '直接访问' },\n { value: 310, name: '邮件营销' },\n { value: 234, name: '联盟广告' },\n { value: 135, name: '视频广告' },\n { value: 1548, name: '搜索引擎' }\n ]\n }\n ]\n};\n</code></pre>\n<iframe data-src=\"https://www.echartsjs.com/examples/en/view.html?c=doc-example/aria-pie&edit=1&reset=1\" width=\"700\" height=\"300\" ></iframe>\n\n\n<p>There should be an <code>aria-label</code> attribute on the chart DOM, which can help the disabled understand the content of charts with the help of certain devices. The value of the label is:</p>\n<pre><code>这是一个关于“某站点用户访问来源”的图表。图表类型是饼图，表示访问来源。其数据是——直接访问的数据是335，邮件营销的数据是310，联盟广告的数据是234，视频广告的数据是135，搜索引擎的数据是1548。\n</code></pre><p>The default language is in Chinese, but you can configure it with templates.</p>\n<p>Please refer to <a href=\"option.html#aria\" target=\"_blank\">ARIA option</a> for more detail.</p>\n"}}}} |