| { |
| "Get Started with ECharts in 5 minutes": { |
| "desc": "<h2 id=\"installing-echarts\">Installing ECharts</h2>\n<p>First, install Apache ECharts<sup>TM</sup> using one of the following methods:</p>\n<ul>\n<li><p>Download official source release from <a href=\"https://echarts.apache.org/en/download.html\" target=\"_blank\">Apache ECharts website</a>. Then <a href=\"https://github.com/apache/echarts#build\" target=\"_blank\">build</a> from the source release.</p>\n</li>\n<li><p>Download from <a href=\"https://github.com/apache/echarts/releases\" target=\"_blank\">GitHub</a></p>\n</li>\n<li><p>Using npm: <code class=\"codespan\">npm install echarts --save</code>. <a href=\"tutorial.html#Use%20ECharts%20with%20webpack\" target=\"_blank\">Using ECharts with webpack</a></p>\n</li>\n<li><p>Use CDN like <a href=\"https://www.jsdelivr.com/package/npm/echarts\" target=\"_blank\">jsDelivr</a>.</p>\n</li>\n</ul>\n<h2 id=\"including-echarts\">Including ECharts</h2>\n<p>Load <code class=\"codespan\">echarts.min.js</code> with a script 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://echarts.apache.org/examples/zh/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://echarts.apache.org/examples/zh/editor.html?c=doc-example/getting-started\" target=\"_blank\">ECharts Gallery</a></p>\n" |
| }, |
| "Create Custom Build of ECharts": { |
| "desc": "<p>In most cases, Apache ECharts<sup>TM</sup> builds can be get from <a href=\"https://www.jsdelivr.com/package/npm/echarts\" target=\"_blank\">CDN</a> or from the <code class=\"codespan\">echarts/dist</code> directory in our <a href=\"https://github.com/apache/echarts/releases\" target=\"_blank\">GitHub project</a>, where\nthese pre-builds are provided:</p>\n<ul>\n<li>Complete verion: <code class=\"codespan\">echarts/dist/echarts.js</code>, including all charts and components (see <code class=\"codespan\">echarts/echarts.all.js</code> for detail), but has maximum file size.</li>\n<li>Common version: <code class=\"codespan\">echarts/dist/echarts.common.js</code>, including common charts and components (see <code class=\"codespan\">echarts/echarts.common.js</code> for detail), moderate file size.</li>\n<li>Simple version: <code class=\"codespan\">echarts/dist/echarts.simple.js</code>, including a smaller subset of the most common charts and components (see <code class=\"codespan\">echarts/echarts.simple.js</code> for detail), small file size.</li>\n</ul>\n<p>We can also build echarts ourselves, which enables to only include the charts and components you needed. You can customize your ECharts build by using one of these approaches:</p>\n<ul>\n<li><a href=\"https://echarts.apache.org/en/builder.html\" target=\"_blank\">Online custom build tool</a> is relatively convenient.</li>\n<li>The script <code class=\"codespan\">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.js.org/\" target=\"_blank\">webpack</a>, <a href=\"http://browserify.org/\" target=\"_blank\">browserify</a></li>\n</ul>\n<p>There are some examples to illustrate the latter two approaches below.</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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">-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 class=\"codespan\">-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 class=\"codespan\">--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 class=\"codespan\">--lang <language shortcut or file path></code>: Whether to use the specified language (Chinese by default). For example: <code class=\"codespan\">--lang en</code> means using English, <code class=\"codespan\">--lang my/langXX.js</code> means using <code class=\"codespan\"><cwd>/my/langXX.js</code> to substitute <code class=\"codespan\">echarts/lib/lang.js</code> while buiding.</li>\n<li><code class=\"codespan\">--sourcemap</code>: Whether to output source map, which is useful in debug.</li>\n<li><code class=\"codespan\">--format</code>: The format of output. Can be <code class=\"codespan\">'umb'</code>(default), <code class=\"codespan\">'amd'</code>, <code class=\"codespan\">'iife'</code>, <code class=\"codespan\">'cjs'</code>, <code class=\"codespan\">'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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">myProject/lib/echarts.custom.min.js</code> has been created. Then we can create a web page (say <code class=\"codespan\">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 class=\"codespan\">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/apache/echarts/blob/master/echarts.all.js\" target=\"_blank\"><code class=\"codespan\">myProject/node_module/echarts/echarts.all.js</code></a> and <a href=\"https://github.com/apache/echarts/blob/master/src/export.js\" target=\"_blank\"><code class=\"codespan\">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 class=\"codespan\">echarts/lib/**</code> or <code class=\"codespan\">echarts/src/**</code>?</h2>\n<ul>\n<li>If intending to import part of echarts modules in your project and build yourself, only <code class=\"codespan\">echarts/lib/**</code> can be used, <code class=\"codespan\">echarts/src/**</code> should not be used.</li>\n<li>If using <code class=\"codespan\">echarts/build/build.js</code> to make a bundle, either <code class=\"codespan\">echarts/lib/**</code> or <code class=\"codespan\">echarts/src/**</code> can be used (should not be mixed), where <code class=\"codespan\">echarts/src/**</code> brings smaller bundle size a little.</li>\n</ul>\n<blockquote>\n<p>Reason: currently, <code class=\"codespan\">echarts/src/**</code> is the source code that using ES Module, and they are transpiled to CommonJS code and placed in <code class=\"codespan\">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 class=\"codespan\">echarts/lib/**</code>. So it should not be changed, otherwise, mixed using both <code class=\"codespan\">echarts/src/**</code> and <code class=\"codespan\">echarts/lib/**</code> will generate two echarts namespace and bring some problems. But it is not an issue when using <code class=\"codespan\">echarts/build/build.js</code> to create a bundle, where ES modules in <code class=\"codespan\">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 class=\"codespan\">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.js.org/\" 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.js.org/\" 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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">-c</code> indicate <code class=\"codespan\">rollup</code> to use <code class=\"codespan\">myProject/rollup.config.js</code> as the config file.</p>\n</blockquote>\n<p>The created bundle <code class=\"codespan\">myProject/lib/line.min.js</code> includes project code and part of echarts code that we requried. Now we create a web page <code class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">toolbox</code> component is in English. Essentially any text can be customized by <code class=\"codespan\">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 class=\"codespan\">--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 class=\"codespan\">myProject/my/langXX.js</code> is used to substitute <code class=\"codespan\">myProject/node_modules/echarts/lib/lang.js</code> while performing build. So we can customize text in our language in <code class=\"codespan\">myProject/my/langXX.js</code>. Notice, <code class=\"codespan\">-o</code> or <code class=\"codespan\">--output</code> must be specified in the approach.</p>\n<p>Besides, the same lang parameter can be pass to <code class=\"codespan\">echarts/build/rollup-plugin-ec-lang</code>.</p>\n" |
| }, |
| "Use ECharts with webpack": { |
| "desc": "<p><a href=\"https://webpack.js.org/\" target=\"_blank\">Webpack</a> is a popular module packaging tool, which can be used easily to import and packaging Apache ECharts<sup>TM</sup>. 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>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 class=\"codespan\">node_modules</code>. You can obtain echarts directly in project with <code class=\"codespan\">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 class=\"codespan\">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/apache/echarts/blob/master/src/echarts.all.ts\" target=\"_blank\">https://github.com/apache/echarts/blob/master/src/echarts.all.ts</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=\"tutorial.html#Create%20Custom%20Build%20of%20ECharts\" target=\"_blank\">Create Custom Build of ECharts</a></p>\n" |
| }, |
| "ECharts Basic Concepts Overview": { |
| "desc": "<p>This chapter describes some of the common concepts and terms of Apache ECharts<sup>TM</sup>.</p>\n<h2 id=\"echarts-instance\">ECharts instance</h2>\n<p>We can create multiple <code class=\"codespan\">echarts instances</code> in a webpage. In each <code class=\"codespan\">echarts instance</code> we can create multiple diagrams, coordinate systems, etc. (described by <code class=\"codespan\">option</code>). With a DOM element prepared (as the container of an echarts instance), we can create a <code class=\"codespan\">echarts instance</code> based on that element. Each <code class=\"codespan\">echarts instance</code> takes its DOM element exclusively.</p>\n<p><br></p>\n<p><img width=\"500\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/multiple-ec-instance.jpg\"></p>\n<h2 id=\"series\">Series</h2>\n<p><a href=\"option.html#series\" target=\"_blank\">series</a> is a very common term. In echarts, <a href=\"option.html#series\" target=\"_blank\">series</a> represents a series of value and the diagram generated from them. So the concept <a href=\"option.html#series\" target=\"_blank\">series</a> includes these key points: a series of value, the type of the diagram (<code class=\"codespan\">series.type</code>) and other parameters specified for the mapping from the values to a diagram.</p>\n<p>In echarts, the <code class=\"codespan\">series.type</code> and the "diagram type" are the same concept. <code class=\"codespan\">series.type</code> includes: <a href=\"option.html#series-line\" target=\"_blank\">line</a> (line plot), <a href=\"option.html#series-bar\" target=\"_blank\">bar</a> (bar chart), <a href=\"option.html#series-pie\" target=\"_blank\">pie</a> (pie chart), <a href=\"option.html#series-scatter\" target=\"_blank\">scatter</a> (scatter plot), <a href=\"option.html#series-graph\" target=\"_blank\">graph</a> (graph plot), <a href=\"option.html#series-tree\" target=\"_blank\">tree</a> (tree plot), etc.</p>\n<p>In the example below, there are three <a href=\"option.html#series\" target=\"_blank\">series</a> (<a href=\"option.html#series-pie\" target=\"_blank\">pie</a>, <a href=\"option.html#series-line\" target=\"_blank\">line</a>, <a href=\"option.html#series-bar\" target=\"_blank\">bar</a>) declared in the <code class=\"codespan\">option</code> on the right, where <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> are declared in each series:</p>\n<p><br></p>\n<p><img width=\"700\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/series-all-a.jpg\"></p>\n<p><br></p>\n<p>Similarly, the following example shows another style of <code class=\"codespan\">option</code>, where each series retrieves data from <a href=\"option.html#dataset\" target=\"_blank\">dataset</a>:</p>\n<p><br></p>\n<p><img width=\"600\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/series-all-b.jpg\"></p>\n<h2 id=\"component\">Component</h2>\n<p>Over series, the entities in echarts are abstracted using the term "component". For example, echarts includes these components: <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a> (the x axis of Cartesian coordinate system), <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> (the y axis of Cartesian coordinate system), <a href=\"option.html#grid\" target=\"_blank\">grid</a> (the baseboard of Cartesian coordinate system), <a href=\"option.html#angleAxis\" target=\"_blank\">angleAxis</a> (the angle axis of polar coordinate system), <a href=\"option.html#radiusAxis\" target=\"_blank\">radiusAxis</a> (the radius axis of polar coordinate system), <a href=\"option.html#polar\" target=\"_blank\">polar</a> (the baseboard of polar coordinate system), <a href=\"option.html#geo\" target=\"_blank\">geo</a> (GEO coordinate system), <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a> (the component for changing the displayed range of data), <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a> (the component for specifying the visual mapping), <a href=\"option.html#tooltip\" target=\"_blank\">tooltip</a> (the tooltip component), <a href=\"option.html#toolbox\" target=\"_blank\">toolbox</a> (the toolbox component), <a href=\"option.html#series\" target=\"_blank\">series</a>, etc.</p>\n<p>Notice that <a href=\"option.html#series\" target=\"_blank\">series</a> is a kind of component, a component for rendering diagram.</p>\n<p>Check the example below. Components (including series) are declared in <code class=\"codespan\">option</code> on the right, and the are finally rendered in the echarts instance.</p>\n<p><br></p>\n<p><img width=\"800\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/components.jpg\"></p>\n<p><br></p>\n<p>Notice: although <a href=\"option.html#series\" target=\"_blank\">series</a> is a kind of component, sometimes we can see phrases like "series and components". The term "component" in this context actually means "components except series".</p>\n<h2 id=\"define-charts-using-option\">Define charts using option</h2>\n<p>We have met the term <code class=\"codespan\">option</code> above. Users should use <code class=\"codespan\">option</code> to describe all of their requirements and input it to echarts. The requirements includes: "what does the data like", "what the diagram we need", "what components we need", "what the user interactions we need", etc. In short, <code class=\"codespan\">option</code> defines: <code class=\"codespan\">data</code>, <code class=\"codespan\">visual mapping</code>, <code class=\"codespan\">interaction</code>.</p>\n<pre><code class=\"lang-js\">// Create an echarts instance.\nvar dom = document.getElementById('dom-id');\nvar chart = echarts.init(dom);\n\n// Use option to describe `data`, `visual mapping`, `interaction`, ...\n// `option` is a big JavaScript object.\nvar option = {\n // Each property represents a kind of components.\n legend: {...},\n grid: {...},\n tooltip: {...},\n toolbox: {...},\n dataZoom: {...},\n visualMap: {...},\n // If there are more than one components in one kind, we use an array.\n // For example, there are three x axes here.\n xAxis: [\n // Each item represents an instance of component.\n // `type` is used to indicate the sub-type of the component.\n {type: 'category', ...},\n {type: 'category', ...},\n {type: 'value', ...}\n ],\n yAxis: [{...}, {...}],\n // There are multiple series, using an array.\n series: [\n // `type` is also used to indicate the sub-type\n // (i.e., diagram type) of each series.\n {type: 'line', data: [['AA', 332], ['CC', 124], ['FF', 412], ... ]},\n {type: 'line', data: [2231, 1234, 552, ... ]},\n {type: 'line', data: [[4, 51], [8, 12], ... ]}\n }]\n};\n\n// Call `setOption` and input the `option`. And then the\n// echarts instance processes data and renders charts.\nchart.setOption(option);\n</code></pre>\n<p>Data is put in <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> in the above example. And we give another example showing another way, where each series retrieves data from <a href=\"option.html#dataset\" target=\"_blank\">dataset</a>:</p>\n<pre><code class=\"lang-js\">var option = {\n dataset: {\n source: [\n [121, 'XX', 442, 43.11],\n [663, 'ZZ', 311, 91.14],\n [913, 'ZZ', 312, 92.12],\n ...\n ]\n },\n xAxis: {},\n yAxis: {},\n series: [\n // Each series retrieves data from `dataset`. The values in `encode`\n // are the indices of the dimensions (i.e., column) of `dataset.source`.\n {type: 'bar', encode: {x: 1, y: 0}},\n {type: 'bar', encode: {x: 1, y: 2}},\n {type: 'scatter', encode: {x: 1, y: 3}},\n ...\n ]\n};\n</code></pre>\n<h2 id=\"position-a-component\">Position a component</h2>\n<p>These approaches are used to Position a component.</p>\n<p><br></p>\n<p><strong>[Absolute positioning like CSS]</strong></p>\n<p><br></p>\n<p>Most components and series can be absolutely positioned according to <code class=\"codespan\">top</code> / <code class=\"codespan\">right</code> / <code class=\"codespan\">down</code> / <code class=\"codespan\">left</code> / <code class=\"codespan\">width</code> / <code class=\"codespan\">height</code>. This approach is like the absolute positioning in CSS. The absolute positioning is based on the container DOM element of the echarts.</p>\n<p>The value of each attribute can be:</p>\n<ul>\n<li>Absolute value (like <code class=\"codespan\">bottom: 54</code>, means: the distance from the boundary of the echarts container to bottom boundary of the component is <code class=\"codespan\">54</code> pixel).</li>\n<li>Or the percentage based on the width/height of the echarts container (like <code class=\"codespan\">right: '20%'</code>, means: the distance from the boundary of the echarts container to the right boundary of this component is <code class=\"codespan\">20%</code> of the width of the echarts container).</li>\n</ul>\n<p>Check the example below, where the <a href=\"option.html#grid\" target=\"_blank\">grid</a> component (that is the baseboard of a Cartesian coordinate system) are configured with <code class=\"codespan\">left</code>、<code class=\"codespan\">right</code>、<code class=\"codespan\">height</code>、<code class=\"codespan\">bottom</code>.</p>\n<p><br></p>\n<p><img width=\"800\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/locate.jpg\"></p>\n<p><br></p>\n<p>Note that <code class=\"codespan\">left</code> <code class=\"codespan\">right</code> <code class=\"codespan\">width</code> are one group of attributes for horizontal layout, while <code class=\"codespan\">top</code> <code class=\"codespan\">bottom</code> <code class=\"codespan\">height</code> are another group of attributes for vertical layout. The two groups have nothing to do with each other. In each group, it is enough to set only one or at most two attributes. For example, when <code class=\"codespan\">left</code> and <code class=\"codespan\">right</code> have been specified, <code class=\"codespan\">width</code> can be automatically calculated by them.</p>\n<p><br></p>\n<p><strong>[Center-radius positioning]</strong></p>\n<p><br></p>\n<p>A few circular components or series need to be positioned by "center" and "radius". For example, <a href=\"option.html#series-pie\" target=\"_blank\">pie</a> (pie chart)、<a href=\"option.html#series-sunburst\" target=\"_blank\">sunburst</a> (sunburst chart)、<a href=\"option.html#polar\" target=\"_blank\">polar</a> (polar coordinate system).</p>\n<p>As the name implies, it position the component according to <a href=\"option.html#series-pie.center\" target=\"_blank\">center</a> and <a href=\"option.html#series-pie.radius\" target=\"_blank\">radius</a>.</p>\n<p><br></p>\n<p><strong>[Other positioning]</strong></p>\n<p><br></p>\n<p>A few other components may has their own specific positioning approach. Check their docs before using them.</p>\n<h2 id=\"coordinate-system\">Coordinate system</h2>\n<p>Many series, like <a href=\"option.html#series-line\" target=\"_blank\">line</a>, <a href=\"option.html#series-bar\" target=\"_blank\">bar</a>, <a href=\"option.html#series-scatter\" target=\"_blank\">scatter</a>, <a href=\"option.html#series-heatmap\" target=\"_blank\">heatmap</a>, etc., need to work on a coordinate system. Coordinate system is used to layout each graphic elements and display some ticks and labels. For example, echarts at least provides these coordinate systems: <a href=\"option.html#grid\" target=\"_blank\">Cartesian coordinate system</a>, <a href=\"option.html#polar\" target=\"_blank\">polar coordinate system</a>, <a href=\"option.html#geo\" target=\"_blank\">GEO coordinate system</a>, <a href=\"option.html#singleAxis\" target=\"_blank\">single axis coordinate system</a>, <a href=\"option.html#calendar\" target=\"_blank\">calendar coordinate system</a>, etc. Some other series like <a href=\"option.html#series-pie\" target=\"_blank\">pie</a>, <a href=\"option.html#series-tree\" target=\"_blank\">tree</a>, work independently without any coordinate systems. And still some other series like <a href=\"option.html#series-graph\" target=\"_blank\">graph</a> are available either independently or on some coordinate system, depending on user settings.</p>\n<p>A coordinate system may consist of several components. For example, Cartesian coordinate system consists of <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a>, <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> and <a href=\"option.html#grid\" target=\"_blank\">grid</a> (the baseboard). <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a> and <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> are referenced and assembled by <code class=\"codespan\">grid</code> and work together cooperatively.</p>\n<p>The following example demonstrates the most simple way to use a Cartesian coordinate system, where only <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a>, <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> and a <a href=\"option.html#series-scatter\" target=\"_blank\">scatter series</a> are declared, and <code class=\"codespan\">echarts</code> create and a <code class=\"codespan\">grid</code> implicitly to link them.</p>\n<p><br></p>\n<p><img width=\"450\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/coord-sys-0.jpg\"></p>\n<p><br></p>\n<p>And the following example demonstrates a more complicated case, where two <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> share one <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a>. And the two <code class=\"codespan\">series</code> are also share the <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a>, but use different <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> respectively. The property <a href=\"option.html#series-line.yAxisIndex\" target=\"_blank\">yAxisIndex</a> is used to specify which <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> is used.</p>\n<p><br></p>\n<p><img width=\"600\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/coord-sys-1.jpg\"></p>\n<p><br></p>\n<p>The following echarts instance contain more than one <a href=\"option.html#grid\" target=\"_blank\">grid</a>. Each <a href=\"option.html#grid\" target=\"_blank\">grid</a> has its own <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a> and <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a>. The properties <a href=\"option.html#series-line.xAxisIndex\" target=\"_blank\">xAxisIndex</a>, <a href=\"option.html#series-line.yAxisIndex\" target=\"_blank\">yAxisIndex</a> and <a href=\"option.html#yAxis.gridIndex\" target=\"_blank\">gridIndex</a> are used to specify the reference relationships.</p>\n<p><br></p>\n<p><img width=\"600\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/coord-sys-2.jpg\"></p>\n<p><br></p>\n<p>Moreover, a type of series is usually available on various coordinate systems. For example, a <a href=\"option.html#series-scatter\" target=\"_blank\">scatter series</a> can work on <a href=\"option.html#grid\" target=\"_blank\">Cartesian coordinate system</a>, <a href=\"option.html#polar\" target=\"_blank\">polar coordinate system</a>, <a href=\"option.html#geo\" target=\"_blank\">GEO coordinate system</a> or other coordinate systems. Similarly, a coordinate system can serve different type of series. As the examples shown above, a <a href=\"option.html#grid\" target=\"_blank\">Cartesian coordinate system</a> serves several <a href=\"option.html#series-line\" target=\"_blank\">line series</a> and <a href=\"option.html#series-bar\" target=\"_blank\">bar series</a>.</p>\n" |
| }, |
| "Customized Chart Styles": { |
| "desc": "<p>Apache ECharts<sup>TM</sup> 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://echarts.apache.org/examples/zh/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 class=\"codespan\">xAxis</code>、<code class=\"codespan\">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://echarts.apache.org/examples/zh/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 class=\"codespan\">data</code> is not a single value, as that of the example in get started. Instead, it's an object containing <code class=\"codespan\">name</code> and <code class=\"codespan\">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://echarts.apache.org/examples/zh/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://echarts.apache.org/examples/zh/view.html?c=doc-example/tutorial-styling-step2&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>Each <code class=\"codespan\">itemStyle</code> has <code class=\"codespan\">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://echarts.apache.org/examples/zh/view.html?c=doc-example/tutorial-styling-step3&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>Similar to <code class=\"codespan\">itemStyle</code>, <code class=\"codespan\">label</code> and <code class=\"codespan\">labelLine</code> also have <code class=\"codespan\">emphasis</code> children.</p>\n<h2 id=\"setting-fan-colors\">Setting Fan Colors</h2>\n<p>Fan colors can be set in <code class=\"codespan\">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://echarts.apache.org/examples/zh/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 class=\"codespan\">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\" target=\"_blank\">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://echarts.apache.org/examples/zh/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": { |
| "desc": "<p>This article provides an overview of the different approaches about Apache ECharts<sup>TM</sup> 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://echarts.apache.org/examples/en/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 class=\"codespan\">'light'</code> and <code class=\"codespan\">'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>or</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=\"https://echarts.apache.org/en/theme-builder.html\" 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 class=\"codespan\">itemStyle</code>, <code class=\"codespan\">lineStyle</code>, <code class=\"codespan\">areaStyle</code>, <code class=\"codespan\">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": { |
| "desc": "<h2 id=\"asynchronous-loading\">Asynchronous Loading</h2>\n<p>Data in <a href=\"#getting-started\">Get started</a> is directly filled in <code class=\"codespan\">setOption</code> after initialization, but in some cases, data may be filled after asynchronous loading. Data updating asynchronously in Apache ECharts<sup>TM</sup> is very easy. After initialization, you can pass in data and configuration item through <code class=\"codespan\">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://echarts.apache.org/examples/zh/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 class=\"codespan\">name</code>. In the above example, updating can be performed correctly according to series order if <code class=\"codespan\">name</code> is not defined. But in most cases, it is recommended to update data with series <code class=\"codespan\">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://echarts.apache.org/examples/zh/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://echarts.apache.org/examples/zh/view.html?c=doc-example/tutorial-dynamic-data&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n\n" |
| }, |
| "Dataset": { |
| "desc": "<p><code class=\"codespan\">dataset</code> component is published since Apache ECharts<sup>TM</sup> 4. <code class=\"codespan\">dataset</code> brings convenience in data management separated with styles and enables data reuse by different series. More importantly, it 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 class=\"codespan\">dataset</code> component, which brings benefits below:</p>\n<ul>\n<li>Benefit from <code class=\"codespan\">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<h2 id=\"get-started\">Get started</h2>\n<p>This is a simplest example of <code class=\"codespan\">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://echarts.apache.org/examples/zh/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<h2 id=\"mapping-from-data-to-graphic\">Mapping from data to graphic</h2>\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 class=\"codespan\">'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<h2 id=\"mapping-by-column-or-row\">Mapping by column or row</h2>\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://echarts.apache.org/examples/zh/view.html?c=dataset-series-layout-by&edit=1&reset=1\" width=\"800\" height=\"600\" ></iframe>\n\n\n\n<h2 id=\"dimension\">Dimension</h2>\n<p>Before introducing <code class=\"codespan\">encode</code>, we should clarify the concept of <code class=\"codespan\">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 class=\"codespan\">seriesLayoutBy</code> as <code class=\"codespan\">'column'</code>, namely, mapping columns to series, each column is called a dimension, and each row is a data item. When we set <code class=\"codespan\">seriesLayoutBy</code> as <code class=\"codespan\">'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 class=\"codespan\">'score'</code>、<code class=\"codespan\">'amount'</code>、<code class=\"codespan\">'product'</code> are dimension names, and data start from the second row. By default ECharts auto detect whether the first row/column of <code class=\"codespan\">dataset.source</code> is dimension name or data. Use can also set <code class=\"codespan\">dataset.sourceHeader</code> as <code class=\"codespan\">true</code> to mandatorily specify the first row/column is dimension name, or set as <code class=\"codespan\">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 class=\"codespan\">dataset.dimensions</code> or <code class=\"codespan\">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 class=\"codespan\">'number'</code>: Normal data, default value.</li>\n<li><code class=\"codespan\">'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 class=\"codespan\">'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 class=\"codespan\">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 class=\"codespan\">'time'</code>), it will be auto set to <code class=\"codespan\">time</code> type. The supported time string is listed in <a href=\"option.html#series.data\" target=\"_blank\">data</a>.</li>\n<li><code class=\"codespan\">'float'</code>: If set as <code class=\"codespan\">'float'</code>, it will be stored in <code class=\"codespan\">TypedArray</code>, which is good for performance optimization.</li>\n<li><code class=\"codespan\">'int'</code>: If set as <code class=\"codespan\">'int'</code>, it will be stored in <code class=\"codespan\">TypedArray</code>, which is good for performance optimization.</li>\n</ul>\n<h2 id=\"mapping-from-data-to-graphic-encode-\">Mapping from data to graphic (encode)</h2>\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://echarts.apache.org/examples/zh/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 class=\"codespan\">'x'</code>, <code class=\"codespan\">'y'</code>, <code class=\"codespan\">'radius'</code>, <code class=\"codespan\">'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 class=\"codespan\">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 class=\"codespan\">encode</code>:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/view.html?c=dataset-encode1&edit=1&reset=1\" width=\"800\" height=\"600\" ></iframe>\n\n\n\n\n\n<h2 id=\"visual-encoding-color-symbol-etc-\">Visual encoding (color, symbol, etc.)</h2>\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://echarts.apache.org/examples/zh/view.html?c=dataset-encode0&edit=1&reset=1\" width=\"500\" height=\"400\" ></iframe>\n\n\n\n\n<h2 id=\"default-encoding\">Default encoding</h2>\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 class=\"codespan\">encode</code> option is specified. (If <code class=\"codespan\">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 class=\"codespan\">'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 class=\"codespan\">encode</code> yourself please.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/view.html?c=dataset-default&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n\n<h2 id=\"q-a\">Q & A</h2>\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 third 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 class=\"codespan\">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 class=\"codespan\">'Life Expectancy'</code>, be we typed <code class=\"codespan\">'Life Expectency'</code> in <code class=\"codespan\">encode</code> option.</p>\n<h2 id=\"various-formats-in-dataset\">Various formats in dataset</h2>\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 class=\"codespan\">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 class=\"codespan\">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<h2 id=\"multiple-datasets-and-references\">Multiple datasets and references</h2>\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<h2 id=\"echarts3-data-setting-approach-series-data-can-be-used-normally\">ECharts3 data setting approach (series.data) can be used normally</h2>\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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">dataset</code> is not supported in the case.</p>\n<h2 id=\"others\">Others</h2>\n<p>Currently, not all types of series support dataset. Series that support dataset includes:</p>\n<p><code class=\"codespan\">line</code>, <code class=\"codespan\">bar</code>, <code class=\"codespan\">pie</code>, <code class=\"codespan\">scatter</code>, <code class=\"codespan\">effectScatter</code>, <code class=\"codespan\">parallel</code>, <code class=\"codespan\">candlestick</code>, <code class=\"codespan\">map</code>, <code class=\"codespan\">funnel</code>, <code class=\"codespan\">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 class=\"codespan\">dataset</code> and having interactions:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/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": { |
| "desc": "<p>Apache ECharts<sup>TM</sup> provides many interaction components besides chart. For example:</p>\n<p><code class=\"codespan\">legend component</code> <a href=\"option.html#legend\" target=\"_blank\">legend</a>、<code class=\"codespan\">title component</code> <a href=\"option.html#title\" target=\"_blank\">title</a>、<code class=\"codespan\">visualmap component</code> <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a>、<code class=\"codespan\">datazoom component</code> <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a>、<code class=\"codespan\">dataline component</code> <a href=\"option.html#timeline\" target=\"_blank\">timeline</a></p>\n<p>Following is an example of <code class=\"codespan\">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<h2 id=\"introduction-of-data-zoom-component-datazoom-\">Introduction of data zoom component (dataZoom)</h2>\n<p>Data overview by default, and detail by requirement is a basic interaction need of data visualization. <code class=\"codespan\">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://echarts.apache.org/examples/zh/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 class=\"codespan\">dataZoom</code> component operates <em>data window zoom</em> and <em>data window translation</em> on <code class=\"codespan\">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 class=\"codespan\">dataZoom</code> controls.</p>\n</blockquote>\n<ul>\n<li><p>Multiple <code class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">toolbox</code>.</p>\n</li>\n</ul>\n<h2 id=\"adding-datazoom-component\">Adding dataZoom component</h2>\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://echarts.apache.org/examples/zh/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 class=\"codespan\">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://echarts.apache.org/examples/zh/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://echarts.apache.org/examples/zh/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": { |
| "desc": "<p>Apache ECharts<sup>TM</sup> 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=\"https://www.w3.org/TR/css3-mediaqueries/\" target=\"_blank\">CSS Media Query</a>.</p>\n<h2 id=\"location-and-layout-of-echarts-components\">Location and layout of ECharts components</h2>\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 class=\"codespan\">number</code> (no unit); e.g.: <code class=\"codespan\">{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 class=\"codespan\">string</code>; e.g.: <code class=\"codespan\">{right: '30%', bottom: '40%'}</code>.</p>\n</li>\n<li><p>Location Description</p>\n<ul>\n<li>can be set to <code class=\"codespan\">left: 'center'</code>, for horizontally centering.</li>\n<li>can be set to <code class=\"codespan\">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 class=\"codespan\">left</code>, <code class=\"codespan\">right</code>, <code class=\"codespan\">width</code>, are enough to determine the component location. For example, <code class=\"codespan\">left</code> and <code class=\"codespan\">right</code>, or <code class=\"codespan\">right</code> and <code class=\"codespan\">width</code> can both determine component location and size.\nThe same goes for vertical paramters <code class=\"codespan\">top</code>, <code class=\"codespan\">bottom</code> and <code class=\"codespan\">height</code>.</p>\n<p><br>\n<strong>Locating method of <code class=\"codespan\">center</code> / <code class=\"codespan\">radius</code>: </strong></p>\n<ul>\n<li><p><code class=\"codespan\">center</code></p>\n<p> an array in form of <code class=\"codespan\">[x, y]</code>, in which <code class=\"codespan\">x</code> and <code class=\"codespan\">y</code> can either be <em>absolute value</em> or <em>percentage</em>, as described above.</p>\n</li>\n<li><p><code class=\"codespan\">radius</code></p>\n<p> an array in form of <code class=\"codespan\">[innerRadius, outerRadius]</code>, in which <code class=\"codespan\">innerRadius</code> and <code class=\"codespan\">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 class=\"codespan\">legend</code>,<code class=\"codespan\">visualMap</code>,<code class=\"codespan\">dataZoom</code>,<code class=\"codespan\">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 class=\"codespan\">orient</code> or <code class=\"codespan\">layout</code> option, which can be set to <code class=\"codespan\">'horizontal'</code> or <code class=\"codespan\">'vertical'</code>.</p>\n<p><br>\n<strong>Compatibility with ECharts2: </strong></p>\n<p>Naming of <code class=\"codespan\">x/x2/y/y2</code> in ECharts2 is still compatible, as well as the newly added <code class=\"codespan\">left/right/top/bottom</code>. But <code class=\"codespan\">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 class=\"codespan\">left: 'right'</code>, <code class=\"codespan\">left: 'left'</code>, <code class=\"codespan\">top: 'bottom'</code>, <code class=\"codespan\">top: 'top'</code>, which are equal to: <code class=\"codespan\">right: 0</code>, <code class=\"codespan\">left: 0</code>, <code class=\"codespan\">bottom: 0</code>, <code class=\"codespan\">top: 0</code>, in a more normal expression.</p>\n<h2 id=\"media-query\">Media Query</h2>\n<p><a href=\"https://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://echarts.apache.org/examples/zh/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 class=\"codespan\">baseOption</code> and every option in <code class=\"codespan\">media</code> are all <em>simple options</em>, which are regular options containing components and series. <code class=\"codespan\">baseOption</code> is always be used, while options of every will be merged with <code class=\"codespan\">chart.mergeOption()</code> when given <code class=\"codespan\">query</code> condition is satisfied with.</p>\n<p><strong>query: </strong></p>\n<p>A <code class=\"codespan\">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 class=\"codespan\">width</code>, <code class=\"codespan\">height</code>, <code class=\"codespan\">aspectRatio</code> (length-to-width ratio), each of which can add <code class=\"codespan\">min</code> or <code class=\"codespan\">max</code> as prefix. E.g., <code class=\"codespan\">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 class=\"codespan\">{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 class=\"codespan\">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 class=\"codespan\">query</code> are satisfied at the same time, all of them will be merged with <code class=\"codespan\">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 class=\"codespan\">media</code> has no not <code class=\"codespan\">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 class=\"codespan\">query option</code>, then it should also appeared in other <code class=\"codespan\">query option</code>, or it will not be able to return to the original state. (<code class=\"codespan\">left/right/top/bottom/width/height</code> are not restricted to this rule.)</p>\n<p><strong><code class=\"codespan\">media</code> in <em>composite option</em> does not support merge</strong></p>\n<p>When <code class=\"codespan\">chart.setOption(rawOption)</code> for the second, third, fourth, fifth, and etc. times, if <code class=\"codespan\">rawOption</code> is <code class=\"codespan\">composite option</code> (which means it contains <code class=\"codespan\">media</code> list), then, the new <code class=\"codespan\">rawOption.media</code> list will not merge with the old <code class=\"codespan\">media</code>. instead, it will simply replace the option. Of course, <code class=\"codespan\">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://echarts.apache.org/examples/zh/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": { |
| "desc": "<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 Apache ECharts<sup>TM</sup> 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 class=\"codespan\">graph</code>, <code class=\"codespan\">themeRiver</code>, and <code class=\"codespan\">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 class=\"codespan\">visualMap</code> component are:<br>\n<code class=\"codespan\">symbol</code>, <code class=\"codespan\">symbolSize</code><br>\n<code class=\"codespan\">color</code>, <code class=\"codespan\">opacity</code>, <code class=\"codespan\">colorAlpha</code>, <br>\n<code class=\"codespan\">colorLightness</code>, <code class=\"codespan\">colorSaturation</code>, <code class=\"codespan\">colorHue</code></p>\n<p>Next, we are going to introduce how to use <code class=\"codespan\">visualMap</code> component.</p>\n<h2 id=\"data-and-dimension\">Data and Dimension</h2>\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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">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<h2 id=\"visualmap-component\">visualMap Component</h2>\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<p><a href=\"option.html#visualMap-piecewise\" target=\"_blank\">visualMapPiecewise</a>：</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/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（visualMapPiecewise）has three types:</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 class=\"codespan\">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": { |
| "desc": "<p>User interactions trigger corresponding events in Apache ECharts<sup>TM</sup>. 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 class=\"codespan\">'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 class=\"codespan\">'click'</code>, <code class=\"codespan\">'dblclick'</code>, <code class=\"codespan\">'mousedown'</code>, <code class=\"codespan\">'mousemove'</code>, <code class=\"codespan\">'mouseup'</code>, <code class=\"codespan\">'mouseover'</code>, <code class=\"codespan\">'mouseout'</code>, <code class=\"codespan\">'globalout'</code>, <code class=\"codespan\">'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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">query</code> can be <code class=\"codespan\">string</code> or <code class=\"codespan\">Object</code>.</p>\n<p>If <code class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">'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 class=\"codespan\">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 class=\"codespan\">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 class=\"codespan\">dispatchAction</code>.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/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": { |
| "desc": "<p>This is a tiny example, introducing how to implement dragging of graphic elements in Apache ECharts<sup>TM</sup>. From this example, we will see how to make an application with rich intractivity based on echarts API.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/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<h2 id=\"-part-1-implement-basic-dragging\">[ Part 1 ] Implement basic dragging</h2>\n<p>First of all, we create a basic <a href=\"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=\"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=\"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 class=\"codespan\">myChart.convertToPixel('grid', dataItem)</code>, the first parameter <code class=\"codespan\">'grid'</code> indicates that <code class=\"codespan\">dataItem</code> should be converted in the first <a href=\"option.html#grid\" target=\"_blank\">grid component (cartesian)</a>.</p>\n<p><strong>Notice:</strong> <code class=\"codespan\">convertToPixel</code> should not be called before the first time that <code class=\"codespan\">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=\"api.html#echartsInstance.convertFromPixel\" target=\"_blank\">convertFromPixel</a> is used, which is the reversed process of <a href=\"api.html#echartsInstance.convertToPixel\" target=\"_blank\">convertToPixel</a>. <code class=\"codespan\">myChart.convertFromPixel('grid', this.position)</code> converts a pixel coordinate to data item in <a href=\"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\n</code></pre>\n<h2 id=\"-part-2-add-tooltip-component\">[ Part 2 ] Add tooltip component</h2>\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=\"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=\"api.html#echartsInstance.dispatchAction\" target=\"_blank\">dispatchAction</a> is used to show/hide tooltip content, where actions <a href=\"api.html#action.tooltip.showTip\" target=\"_blank\">showTip</a> and <a href=\"api.html#action.tooltip.hideTip\" target=\"_blank\">hideTip</a> is dispatched.</p>\n<h2 id=\"-part-3-full-code\">[ Part 3 ] Full code</h2>\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="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=\"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": { |
| "desc": "<p><a href=\"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 does Apache ECharts<sup>TM</sup> supports <code class=\"codespan\">custom series</code>?</p>\n<p>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=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a> or <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a>. Having considered the factors above, a solution <a href=\"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://echarts.apache.org/examples/zh/view.html?c=custom-profile&reset=1&edit=1\" width=\"800\" height=\"500\" ></iframe>\n\n\n<p><strong><a href=\"https://echarts.apache.org/examples/en/index.html#chart-type-custom\" target=\"_blank\">More samples of custom series</a></strong></p>\n<p>Let's begin the tutorial.</p>\n<h2 id=\"-i-the-method-renderitem\">(I) The method <code class=\"codespan\">renderItem</code></h2>\n<p>The snippet of graphic elements rendering should be written in <code class=\"codespan\">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=\"option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> is called respectively for each <code class=\"codespan\">dataItem</code> in <a href=\"option.html#series-custom.data\" target=\"_blank\">series.data</a>. <code class=\"codespan\">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=\"option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> provides two parameters:</p>\n<ul>\n<li><a href=\"option.html#series-custom.renderItem.arguments.params\" target=\"_blank\">params</a>：provides info about the current series (such as <code class=\"codespan\">seriesIndex</code>、<code class=\"codespan\">dataIndex</code>, etc.) and data (such as <code class=\"codespan\">dataIndex</code>, <code class=\"codespan\">dataIndexInside</code>, etc.) and coordinate system (such as location and size of bounding box of the current coordinate system)</li>\n<li><a href=\"option.html#series-custom.renderItem.arguments.api\" target=\"_blank\">api</a> provides some methods to developers (such as <code class=\"codespan\">api.value()</code>, <code class=\"codespan\">api.coord()</code>).</li>\n</ul>\n<p><a href=\"option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> method should return definitions of graphic elements for the current <code class=\"codespan\">dataItem</code>. See <a href=\"option.html#series-custom.renderItem.return\" target=\"_blank\">renderItem.return</a>.</p>\n<p>Generally, the main process of <a href=\"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=\"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=\"option.html#series-custom.renderItem.arguments.api.value\" target=\"_blank\">api.value(...)</a> is used to retrieve value from data. For example, <code class=\"codespan\">api.value(0)</code> retrieve the value of the first dimension in the current data item.</li>\n<li><a href=\"option.html#series-custom.renderItem.arguments.api.coord\" target=\"_blank\">api.coord(...)</a> is used to convert data to coordinate. For example, <code class=\"codespan\">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=\"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=\"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=\"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 class=\"codespan\">api.style({fill: 'green', stroke: 'yellow'})</code> to override those style settings.</p>\n<p>Having <code class=\"codespan\">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<h2 id=\"-ii-make-the-extent-of-axes-fit-the-data\">(II) Make the extent of axes fit the data</h2>\n<p>There is axes in some coordinate systems, such as <a href=\"option.html#grid\" target=\"_blank\">cartesian2d (grid)</a>and <a href=\"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=\"option.html#grid\" target=\"_blank\">cartesian2d (grid)</a>, developers should specify that which dimensions correspond to <code class=\"codespan\">x</code> axis and which to <code class=\"codespan\">y</code> axis use the property <a href=\"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<h2 id=\"-iii-set-tooltip-content\">(III) Set tooltip content</h2>\n<p>Of course <a href=\"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=\"option.html#series-custom.encode\" target=\"_blank\">encode</a> and <a href=\"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 class=\"codespan\">custom series</code> are introduced below.</p>\n<h2 id=\"-iv-shape-clipping-when-overflow-the-coordinates-area\">(IV) Shape clipping when overflow the coordinates area</h2>\n<p>When use <code class=\"codespan\">custom series</code> with <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a>, <a href=\"option.html#dataZoom.filterMode\" target=\"_blank\">dataZoom.filterMode</a> usually be set as <code class=\"codespan\">'weakFilter'</code>, which prevent <code class=\"codespan\">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 class=\"codespan\">dim</code> and <code class=\"codespan\">dim2</code> corresponds to <code class=\"codespan\">x</code> axis, and the <code class=\"codespan\">dataZoom</code> component constrols the data window of <code class=\"codespan\">x</code> axis. If part of a <code class=\"codespan\">dataItem</code> is overflow the extent of <code class=\"codespan\">x</code> axis (the value on <code class=\"codespan\">dim1</code> is overflow and the value on <code class=\"codespan\">dim2</code> is not) while zooming, the <code class=\"codespan\">dataItem</code> will not be filtered if <code class=\"codespan\">dataZoom.filterMode = 'weakFilter'</code> set. Thus the <code class=\"codespan\">dataItem</code> can be still rendered (usually be partially rendered by using <code class=\"codespan\">echarts.graphic.clipRectByRect</code> to clip the exceeding part).\nSee the example mentioned above <a href=\"https://echarts.apache.org/examples/zh/editor.html?c=custom-profile\" target=\"_blank\">Profile</a>.</p>\n<h2 id=\"-v-about-dataindex\">(V) About dataIndex</h2>\n<p>Developers had better notice that in <a href=\"option.html#series-custom.renderItem.arguments.params\" target=\"_blank\">renderItem.arguments.params</a> <code class=\"codespan\">dataIndexInside</code> and <code class=\"codespan\">dataIndex</code> is different:</p>\n<ul>\n<li><code class=\"codespan\">dataIndex</code> is the index of a <code class=\"codespan\">dataItem</code> in the original data.</li>\n<li><code class=\"codespan\">dataIndexInside</code> is the index of a <code class=\"codespan\">dataItem</code> in the current data window (see <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a>.</li>\n</ul>\n<p><a href=\"option.html#series-custom.renderItem.arguments.api\" target=\"_blank\">renderItem.arguments.api</a> uses <code class=\"codespan\">dataIndexInside</code> as the input parameter but not <code class=\"codespan\">dataIndex</code>, because conversion from <code class=\"codespan\">dataIndex</code> to <code class=\"codespan\">dataIndexInside</code> is time-consuming.</p>\n<h2 id=\"-vi-event-listener\">(VI) Event listener</h2>\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<h2 id=\"-vii-custom-vector-shapes\">(VII) Custom vector shapes</h2>\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=\"option.html#series-custom.renderItem.return_path\" target=\"_blank\">path</a>, and examples: <a href=\"https://echarts.apache.org/examples/zh/editor.html?c=custom-calendar-icon\" target=\"_blank\">icons</a>, <a href=\"https://echarts.apache.org/examples/zh/editor.html?c=custom-gantt-flight\" target=\"_blank\">shapes</a>.</p>\n<p><br></p>\n<p><strong><a href=\"https://echarts.apache.org/examples/en/index.html#chart-type-custom\" target=\"_blank\">More examples about custom series</a></strong></p>\n" |
| }, |
| "Rich Text": { |
| "desc": "<p>Rich text can be used in Apache ECharts<sup>TM</sup> labels of series, axis or other components. For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/view.html?c=pie-rich-text&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n<iframe data-src=\"https://echarts.apache.org/examples/zh/view.html?c=treemap-obama&edit=1&reset=1\" width=\"800\" height=\"550\" ></iframe>\n\n\n<iframe data-src=\"https://echarts.apache.org/examples/zh/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://echarts.apache.org/examples/zh/editor.html?c=map-labels&edit=1&reset=1\" target=\"_blank\">Map Labels</a>,\n<a href=\"https://echarts.apache.org/examples/zh/editor.html?c=pie-nest&edit=1&reset=1\" target=\"_blank\">Pie Labels</a>,\n<a href=\"https://echarts.apache.org/examples/zh/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 fragments 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 beginning, 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 fragment: Some piece of text in a text block.</li>\n</ul>\n<p>For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/view.html?c=doc-example/text-block-fragment&edit=1&reset=1\" width=\"340\" height=\"240\" ></iframe>\n\n\n\n<h2 id=\"options-about-text\">Options about Text</h2>\n<p>echarts provides plenty of text options, including:</p>\n<ul>\n<li>Basic font style: <code class=\"codespan\">fontStyle</code>, <code class=\"codespan\">fontWeight</code>, <code class=\"codespan\">fontSize</code>, <code class=\"codespan\">fontFamily</code>.</li>\n<li>Fill of text: <code class=\"codespan\">color</code>.</li>\n<li>Stroke of text: <code class=\"codespan\">textBorderColor</code>, <code class=\"codespan\">textBorderWidth</code>.</li>\n<li>Shadow of text: <code class=\"codespan\">textShadowColor</code>, <code class=\"codespan\">textShadowBlur</code>, <code class=\"codespan\">textShadowOffsetX</code>, <code class=\"codespan\">textShadowOffsetY</code>.</li>\n<li>Box size of text block or text fragment: <code class=\"codespan\">lineHeight</code>, <code class=\"codespan\">width</code>, <code class=\"codespan\">height</code>, <code class=\"codespan\">padding</code>.</li>\n<li>Alignment of text block or text fragment: <code class=\"codespan\">align</code>, <code class=\"codespan\">verticalAlign</code>.</li>\n<li>Border, background (color or image) of text block or text fragment: <code class=\"codespan\">backgroundColor</code>, <code class=\"codespan\">borderColor</code>, <code class=\"codespan\">borderWidth</code>, <code class=\"codespan\">borderRadius</code>.</li>\n<li>Shadow of text block or text fragment: <code class=\"codespan\">shadowColor</code>, <code class=\"codespan\">shadowBlur</code>, <code class=\"codespan\">shadowOffsetX</code>, <code class=\"codespan\">shadowOffsetY</code>.</li>\n<li>Position and rotation of text block: <code class=\"codespan\">position</code>, <code class=\"codespan\">distance</code>, <code class=\"codespan\">rotate</code>.</li>\n</ul>\n<p>User can defined styles for text fragment in <code class=\"codespan\">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 fragments\n // of text by adding some markers to those fragment, like\n // `{styleName|text content text content}`.\n // `'\\n'` is the newline character.\n formatter: [\n '{a|Style "a" is applied to this fragment}'\n '{b|Style "b" is applied to this fragment}This fragment 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 fragments 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 class=\"codespan\">width</code> 和 <code class=\"codespan\">height</code> only work when <code class=\"codespan\">rich</code> specified.</p>\n</blockquote>\n<h2 id=\"basic-styles-of-text-text-block-and-text-fragment\">Basic Styles of Text, Text Block and Text Fragment</h2>\n<p>Basic font style can be set to text: <code class=\"codespan\">fontStyle</code>, <code class=\"codespan\">fontWeight</code>, <code class=\"codespan\">fontSize</code>, <code class=\"codespan\">fontFamily</code>.</p>\n<p>Fill color and stroke color can be set to text: <code class=\"codespan\">color</code>, <code class=\"codespan\">textBorderColor</code>, <code class=\"codespan\">textBorderWidth</code>.</p>\n<p>Border style and background style can be set to text block: <code class=\"codespan\">borderColor</code>, <code class=\"codespan\">borderWidth</code>, <code class=\"codespan\">backgroundColor</code>, <code class=\"codespan\">padding</code>.</p>\n<p>Border style and background style can be set to text fragment too: <code class=\"codespan\">borderColor</code>, <code class=\"codespan\">borderWidth</code>, <code class=\"codespan\">backgroundColor</code>, <code class=\"codespan\">padding</code>.</p>\n<p>For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/view.html?c=doc-example/text-options&edit=1&reset=1\" width=\"700\" height=\"300\" ></iframe>\n\n\n\n<h2 id=\"label-position\">Label Position</h2>\n<p><code class=\"codespan\">label</code> option can be use in charts like <code class=\"codespan\">bar</code>, <code class=\"codespan\">line</code>, <code class=\"codespan\">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://echarts.apache.org/examples/zh/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 class=\"codespan\">position</code> by different chart types. And <code class=\"codespan\">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<h2 id=\"label-rotation\">Label Rotation</h2>\n<p>Sometimes label is needed to be rotated. For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/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 class=\"codespan\">align</code> and <code class=\"codespan\">verticalAlign</code> are applied firstly, then rotate.</p>\n<h2 id=\"layout-and-alignment-of-text-fragment\">Layout and Alignment of Text fragment</h2>\n<p>To understand the layout rule, every text fragment can be imagined as a <code class=\"codespan\">inline-block</code> dom element in CSS.</p>\n<p><code class=\"codespan\">content box size</code> of a text fragment is determined by its font size by default. It can also be specified directly by <code class=\"codespan\">width</code> and <code class=\"codespan\">height</code>, although they are rarely set. <code class=\"codespan\">border box size</code> of a text fragment is calculated by adding the <code class=\"codespan\">border box size</code> and <code class=\"codespan\">padding</code>.</p>\n<p>Only <code class=\"codespan\">'\\n'</code> is the newline character, which breaks a line.</p>\n<p>Multiple text fragment exist in a single line. The height of a line is determined by the biggest <code class=\"codespan\">lineHeight</code> of text fragments. <code class=\"codespan\">lineHeight</code> of a text fragment can be specified in <code class=\"codespan\">rich</code>, or in the parent level of <code class=\"codespan\">rich</code>, otherwise using <code class=\"codespan\">box size</code> of the text fragment.</p>\n<p>Having <code class=\"codespan\">lineHeight</code> determined, the vertical position of text fragments can be determined by <code class=\"codespan\">verticalAlign</code> (there is a little different from the rule in CSS):</p>\n<ul>\n<li><code class=\"codespan\">'bottom'</code>: The bottom edge of the text fragment sticks to the bottom edge of the line.</li>\n<li><code class=\"codespan\">'top'</code>: The top edge of the text fragment sticks to the top edge of the line.</li>\n<li><code class=\"codespan\">'middle'</code>: In the middle of the line.</li>\n</ul>\n<p>The width of a text block can be specified by <code class=\"codespan\">width</code>, otherwise, by the longest line. Having the width determined, text fragment can be placed in each line, where the horizontal position of text fragments can be determined by its <code class=\"codespan\">align</code>.</p>\n<ul>\n<li>Firstly, place text fragments whose <code class=\"codespan\">align</code> is <code class=\"codespan\">'left'</code> from left to right continuously.</li>\n<li>Secondly, place text fragments whose <code class=\"codespan\">align</code> is <code class=\"codespan\">'right'</code> from right to left continuously.</li>\n<li>Finally, the text fragments 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 fragment:</p>\n<ul>\n<li>If <code class=\"codespan\">align</code> is <code class=\"codespan\">'center'</code>, text aligns at the center of the text fragment box.</li>\n<li>If <code class=\"codespan\">align</code> is <code class=\"codespan\">'left'</code>, text aligns at the left of the text fragment box.</li>\n<li>If <code class=\"codespan\">align</code> is <code class=\"codespan\">'right'</code>, text aligns at the right of the text fragment box.</li>\n</ul>\n<p>For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/view.html?c=doc-example/text-fragment-align&edit=1&reset=1\" width=\"800\" height=\"220\" ></iframe>\n\n\n\n\n<h2 id=\"effects-icon-horizontal-rule-title-block-simple-table\">Effects: Icon, Horizontal Rule, Title Block, Simple Table</h2>\n<p>See example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/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 class=\"codespan\">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 class=\"codespan\">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 fragments that are in the same column of different lines. See the <a href=\"https://echarts.apache.org/examples/zh/view.html?c=pie-rich-text&edit=1&reset=1\" target=\"_blank\">example</a> at the mentioned above.</p>\n" |
| }, |
| "Server-side Rendering": { |
| "desc": "<p>Apache ECharts<sup>TM</sup> can be rendered at server-side. For example, the thumbnails in the <a href=\"https://echarts.apache.org/examples/en/index.html/\" 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<li><a href=\"https://gist.github.com/pissang/4c32ee30e35c91336af72b129a1a4a73\" target=\"_blank\">https://gist.github.com/pissang/4c32ee30e35c91336af72b129a1a4a73</a></li>\n</ul>\n" |
| }, |
| "Render by Canvas or SVG": { |
| "desc": "<p>Most browser-side charting libraries use SVG or Canvas as their underlying renderer. In the scope of Apache ECharts<sup>TM</sup>, they are usually interchangeable, without critical differences. However, in some cases, 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 beginning. As of <a href=\"https://github.com/apache/echarts/releases\" target=\"_blank\">ECharts v3.8</a> we provide an SVG renderer (beta version) as another option. Either of them can be used by specifing parameter <a href=\"api.html#echarts.init\" target=\"_blank\">renderer</a> as <code class=\"codespan\">'canvas'</code> or <code class=\"codespan\">'svg'</code> when initailizing a chart instance.</p>\n<blockquote>\n<p>Both SVG and Canvas, which are very different rendering implementations, are supported in ECharts by leveraging the Canvas and SVG renderers offered by the <a href=\"https://github.com/ecomfe/zrender\" target=\"_blank\">zender</a> library.</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 cases where there is a large amount of graphical elements (usually due to a large amount of data points), like heatmap and lines or scatter plot with large data in geo or parallel coordinates. In addition, it supports some <a href=\"https://echarts.apache.org/examples/en/editor.html?c=lines-bmap-effect\" target=\"_blank\">special visual effect</a> not supported by SVG. However, in some other scenarios SVG has some critical advantages: it consumes less memory than Canvas (especially in mobile devices), and gives better performance in rendering. Moreover, it never blurs when zooming the viewport of the browser whereas Canvas may blur.</p>\n<p>Below is a comparison of frame rate during the initial animation stage when rendering line, bar, pie charts with the Canvas renderer and the SVG renderer:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/view.html?c=doc-example/canvas-vs-svg-en&reset=1\" width=\"90%\" height=\"400\" ></iframe>\n\n\n<p>In the example above, the SVG renderer provides better FPS performance in mobile devices. In some other scenarios with large amounts of data or with certain kinds of user interaction, the SVG renderer is still not as good as the Canvas renderer in performance, but two options provide 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>When not constrained by hardware/software, and the data amount is not large, both should provide equally satisfactory results.</li>\n<li>When encountering performance issues, 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 causes the browser crash (probably caused by that the large memory consumption) we can try the SVG renderer. Or, generally, when running on 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/apache/echarts/issues/new\" target=\"_blank\">feedback</a> of experiences and usage scenarios are strongly welcomed, which will help improve the these renderers.</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 a 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://www.jsdelivr.com/package/npm/echarts\" target=\"_blank\">pre-build</a> of ECharts, the SVG renderer has been included in <a href=\"https://cdn.jsdelivr.net/npm/echarts/dist/echarts.common.min.js\" target=\"_blank\">common version</a> and <a href=\"https://cdn.jsdelivr.net/npm/echarts/dist/echarts.min.js\" target=\"_blank\">complete version</a>. But not in <a href=\"https://cdn.jsdelivr.net/npm/echarts/dist/echarts.simple.min.js\" target=\"_blank\">simple version</a>.</li>\n<li>When <a href=\"https://echarts.apache.org/en/builder.html\" target=\"_blank\">building ECharts online</a>, the checkbox "SVG Renderer" should be checked.</li>\n<li>When <a href=\"tutorial.html#Create%20Custom%20Build%20of%20ECharts\" target=\"_blank\">buildin ECharts offline</a>, the SVG renderer module should be imported:</li>\n</ul>\n<pre><code class=\"lang-js\">import 'zrender/lib/svg/svg';\n</code></pre>\n<p>Then we can specify renderer by <a href=\"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": { |
| "desc": "<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 Apache ECharts<sup>TM</sup> 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 class=\"codespan\">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: 'Source of user access to a site',\n x: 'center'\n },\n series: [\n {\n Name: 'access source',\n type: 'pie',\n data: [\n { value: 335, name: 'direct access' },\n { value: 310, name: 'mail marketing' },\n { value: 234, name: 'union ad' },\n { value: 135, name: 'video ad' },\n { value: 1548, name: 'search engine' }\n ]\n }\n ]\n};\n</code></pre>\n<iframe data-src=\"https://echarts.apache.org/examples/zh/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 class=\"codespan\">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>This is a chart of "Source of user access to a site." The chart type is a pie chart that indicates the source of the visit. The data is - direct access data is 335, mail marketing data is 310, union ad data is 234, video ad data is 135, search engine data is 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" |
| }, |
| "ECharst 5 Upgrade Guide": { |
| "desc": "<p>This guide is primarily for users who wish to upgrade their echarts 4.x to echarts 5. The notable new features of echarts 5 can be checked in this <a href=\"xxx\" target=\"_blank\">docucment</a>. In most cases we do not have to do anything for this migration because echarts has always tried to keep the API as stable and backward compatible as possible. But there are still some changes that breaks from echarts 4, as well as some cases that echarts 5 provides better API and deprecated the previous one. We attempt to explain them as thorough as possible in this document.</p>\n<p>??? based on 5.0.1</p>\n<h2 id=\"breaking-changes\">Breaking Changes</h2>\n<h3 id=\"default-theme\">Default theme</h3>\n<p>The color in the default theme has been changed in v5.x. If users intend to roll back to the color theme of v4.x, please manually declare the color palette of v4.x, for example:</p>\n<pre><code class=\"lang-js\">chart.setOption({\n color: [\n '#c23531', '#2f4554', '#61a0a8', '#d48265', '#91c7ae', '#749f83',\n '#ca8622', '#bda29a', '#6e7074', '#546570', '#c4ccd3'\n ],\n // ...\n});\n</code></pre>\n<p>or make a theme:</p>\n<pre><code class=\"lang-js\">var themeEC4 = {\n color: [\n '#c23531', '#2f4554', '#61a0a8', '#d48265', '#91c7ae', '#749f83',\n '#ca8622', '#bda29a', '#6e7074', '#546570', '#c4ccd3'\n ]\n};\nvar chart = echarts.init(dom, themeEC4);\nchart.setOption(/* ... */);\n</code></pre>\n<h3 id=\"echarts-import\">ECharts Import</h3>\n<p>About echarts importing, users need to modify their code only in this cases below:</p>\n<p>If the users previously import echarts in <code class=\"codespan\">v4.x</code> like this:</p>\n<pre><code class=\"lang-js\">import echarts from 'echarts/lib/echarts';\n</code></pre>\n<p>or</p>\n<pre><code class=\"lang-js\">import echarts from 'echarts';\n</code></pre>\n<p>They do not work in <code class=\"codespan\">v5.x</code> any more.\nUsers should modify it to:</p>\n<pre><code class=\"lang-js\">import * as echarts from 'echarts/lib/echarts';\n</code></pre>\n<p>or</p>\n<pre><code class=\"lang-js\">import * as echarts from 'echarts';\n</code></pre>\n<hr>\n<h3 id=\"-\">参考</h3>\n<p>js 用户：</p>\n<p>ts 用户：</p>\n<p>参考：\n <a href=\"https://v3.vuejs.org/guide/migration/introduction.html#template-directives\" target=\"_blank\">https://v3.vuejs.org/guide/migration/introduction.html#template-directives</a>\n我感觉要需要开发者重点注意的几个：\n use\n 相关插件的兼容性。\n wordcloud，liquidfill，gl 等插件需要同步升级到最新的版本\ngithub 上也有 faq v5 的标签，可以参考</p>\n<p>然后是 api 接口的 breaking change（比如事件），然后是配置项的改动</p>\n<ul>\n<li>[Break] Breaking changes against v4.9:<ul>\n<li>Remove built-in map geoJSON. <a href=\"https://github.com/apache/incubator-echarts/pull/13565\" target=\"_blank\">#13565</a>.</li>\n<li>Drop the support of the legacy IE8. The previous VML renderer (necessary in IE8) will not be updated to work in v5.0.</li>\n<li>If the upper application previously imported <code class=\"codespan\">src/echarts.js</code>, <code class=\"codespan\">src/chart/*.js</code> and <code class=\"codespan\">src/component/*.js</code>, it can not work any more because all of the files in <code class=\"codespan\">/src</code> folder are migrated to <code class=\"codespan\">*.ts</code>.</li>\n<li>The priority of the visuals between <code class=\"codespan\">visualMap</code> and <code class=\"codespan\">itemStyle</code>|<code class=\"codespan\">lineStyle</code>|<code class=\"codespan\">areaStyle</code> are reversed. That is, previously, the visuals (i.e., color, symbol, symbolSize, ...) that generated by the component <code class=\"codespan\">visualMap</code> has highest priority, which will overwrite the same visuals specified in <code class=\"codespan\">itemStyle</code>|<code class=\"codespan\">lineStyle</code>|<code class=\"codespan\">areaStyle</code>. That brought trouble to specify specific style to some certain data items. Since v5.0, the visuals specified in <code class=\"codespan\">itemStyle</code>|<code class=\"codespan\">lineStyle</code>|<code class=\"codespan\">areaStyle</code> has highest priority.</li>\n<li>The behavior of <code class=\"codespan\">rich.?.padding</code> are changed. Previously <code class=\"codespan\">rich.?.padding: [11, 22, 33, 44]</code> indicates that padding-top is <code class=\"codespan\">33</code> and padding-bottom is <code class=\"codespan\">11</code>, which is a buggy implementation because it is different from what CSS did. Since v5.0, we fix it: <code class=\"codespan\">rich.?.padding: [11, 22, 33, 44]</code> indicates padding-top is <code class=\"codespan\">11</code> and padding-bottom is <code class=\"codespan\">33</code>.</li>\n<li><code class=\"codespan\">aria</code> is not included in <code class=\"codespan\">dist/echarts.simple(.min).js</code> since v5.0. But it is still included in <code class=\"codespan\">dist/echarts.common(.min).js</code> and <code class=\"codespan\">dist/echarts(.min).js</code>.</li>\n</ul>\n</li>\n<li>[Deprecated] Deprecated usages since v5.0:<ul>\n<li>Transform related props of a graphic element are changed:<ul>\n<li>Changes:<ul>\n<li><code class=\"codespan\">position: [number, number]</code> are changed to <code class=\"codespan\">x: number</code>/<code class=\"codespan\">y: number</code>.</li>\n<li><code class=\"codespan\">scale: [number, number]</code> are changed to <code class=\"codespan\">scaleX: number</code>/<code class=\"codespan\">scaleY: number</code>.</li>\n<li><code class=\"codespan\">origin: [number, number]</code> are changed to <code class=\"codespan\">originX: number</code>/<code class=\"codespan\">originY: number</code>.</li>\n</ul>\n</li>\n<li>The <code class=\"codespan\">position</code>, <code class=\"codespan\">scale</code> and <code class=\"codespan\">origin</code> are still supported but deprecated.</li>\n<li>It effects these places:<ul>\n<li>In the <code class=\"codespan\">graphic</code> components: the declarations of each element.</li>\n<li>In <code class=\"codespan\">custom series</code>: the declarations of each element in the return of <code class=\"codespan\">renderItem</code>.</li>\n<li>Directly use zrender graphic elements.</li>\n</ul>\n</li>\n</ul>\n</li>\n<li>Text related props on graphic elements are changed:<ul>\n<li>Changes:<ul>\n<li>The declaration of attached text (or say, rect text) are changed.<ul>\n<li>Prop <code class=\"codespan\">style.text</code> are deprecated in elements except <code class=\"codespan\">Text</code>. Instead, Prop set <code class=\"codespan\">textContent</code> and <code class=\"codespan\">textConfig</code> are provided to support more powerful capabilities.</li>\n<li>These related props at the left part below are deprecated. Use the right part below instead.<ul>\n<li>textPosition => textConfig.position</li>\n<li>textOffset => textConfig.offset</li>\n<li>textRotation => textConfig.rotation</li>\n<li>textDistance => textConfig.distance</li>\n</ul>\n</li>\n</ul>\n</li>\n<li>The props at the left part below are deprecated in <code class=\"codespan\">style</code> and <code class=\"codespan\">style.rich.?</code>. Use the props at the right part below instead.<ul>\n<li>textFill => fill</li>\n<li>textStroke => stroke</li>\n<li>textFont => font</li>\n<li>textStrokeWidth => lineWidth</li>\n<li>textAlign => align</li>\n<li>textVerticalAlign => verticalAlign);</li>\n<li>textLineHeight =></li>\n<li>textWidth => width</li>\n<li>textHeight => hight</li>\n<li>textBackgroundColor => backgroundColor</li>\n<li>textPadding => padding</li>\n<li>textBorderColor => borderColor</li>\n<li>textBorderWidth => borderWidth</li>\n<li>textBorderRadius => borderRadius</li>\n<li>textBoxShadowColor => shadowColor</li>\n<li>textBoxShadowBlur => shadowBlur</li>\n<li>textBoxShadowOffsetX => shadowOffsetX</li>\n<li>textBoxShadowOffsetY => shadowOffsetY</li>\n</ul>\n</li>\n<li>Note: these props are not changed:<ul>\n<li>textShadowColor</li>\n<li>textShadowBlur</li>\n<li>textShadowOffsetX</li>\n<li>textShadowOffsetY</li>\n</ul>\n</li>\n</ul>\n</li>\n<li>It effects these places:<ul>\n<li>In the <code class=\"codespan\">graphic</code> components: the declarations of each element. [compat, but not accurately the same in some complicated cases.]</li>\n<li>In <code class=\"codespan\">custom series</code>: the declarations of each element in the return of <code class=\"codespan\">renderItem</code>. [compat, but not accurately the same in some complicated cases].</li>\n<li>Directly use zrender API to create graphic elements. [No compat, breaking change].</li>\n</ul>\n</li>\n</ul>\n</li>\n<li>API on chart instance:<ul>\n<li><code class=\"codespan\">chart.one(...)</code> is deprecated.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">label</code>:<ul>\n<li>In props <code class=\"codespan\">color</code>, <code class=\"codespan\">textBorderColor</code>, <code class=\"codespan\">backgroundColor</code> and <code class=\"codespan\">borderColor</code>, the value <code class=\"codespan\">'auto'</code> is deprecated. Use the value <code class=\"codespan\">'inherit'</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">hoverAnimation</code>:<ul>\n<li>option <code class=\"codespan\">series.hoverAnimation</code> is deprecated. Use <code class=\"codespan\">series.emphasis.scale</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">line series</code>:<ul>\n<li>option <code class=\"codespan\">series.clipOverflow</code> is deprecated. Use <code class=\"codespan\">series.clip</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">custom series</code>:<ul>\n<li>In <code class=\"codespan\">renderItem</code>, the <code class=\"codespan\">api.style(...)</code> and <code class=\"codespan\">api.styleEmphasis(...)</code> are deprecated. Because it is not really necessary and hard to ensure backward compatibility. Users can fetch system designated visual by <code class=\"codespan\">api.visual(...)</code>.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">sunburst series</code>:<ul>\n<li>Action type <code class=\"codespan\">highlight</code> is deprecated. Use <code class=\"codespan\">sunburstHighlight</code> instead.</li>\n<li>Action type <code class=\"codespan\">downplay</code> is deprecated. Use <code class=\"codespan\">sunburstUnhighlight</code> instead.</li>\n<li>option <code class=\"codespan\">series.downplay</code> is deprecated. Use <code class=\"codespan\">series.blur</code> instead.</li>\n<li>option <code class=\"codespan\">series.highlightPolicy</code> is deprecated. Use <code class=\"codespan\">series.emphasis.focus</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">pie series</code>:<ul>\n<li>The action type at the left part below are deprecated. Use the right part instead:<ul>\n<li><code class=\"codespan\">pieToggleSelect</code> => <code class=\"codespan\">toggleSelect</code></li>\n<li><code class=\"codespan\">pieSelect</code> => <code class=\"codespan\">select</code></li>\n<li><code class=\"codespan\">pieUnSelect</code> => <code class=\"codespan\">unselect</code></li>\n</ul>\n</li>\n<li>The event type at the left part below are deprecated. Use the right part instead:<ul>\n<li><code class=\"codespan\">pieselectchanged</code> => <code class=\"codespan\">selectchanged</code></li>\n<li><code class=\"codespan\">pieselected</code> => <code class=\"codespan\">selected</code></li>\n<li><code class=\"codespan\">pieunselected</code> => <code class=\"codespan\">unselected</code></li>\n</ul>\n</li>\n<li>option <code class=\"codespan\">series.label.margin</code> is deprecated. Use <code class=\"codespan\">series.label.edgeDistance</code> instead.</li>\n<li>option <code class=\"codespan\">series.clockWise</code> is deprecated. Use <code class=\"codespan\">series.clockwise</code> instead.</li>\n<li>option <code class=\"codespan\">series.hoverOffset</code> is deprecated. Use <code class=\"codespan\">series.emphasis.scaleSize</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">map series</code>:<ul>\n<li>The action type at the left part below are deprecated. Use the right part instead:<ul>\n<li><code class=\"codespan\">mapToggleSelect</code> => <code class=\"codespan\">toggleSelect</code></li>\n<li><code class=\"codespan\">mapSelect</code> => <code class=\"codespan\">select</code></li>\n<li><code class=\"codespan\">mapUnSelect</code> => <code class=\"codespan\">unselect</code></li>\n</ul>\n</li>\n<li>The event type at the left part below are deprecated. Use the right part instead:<ul>\n<li><code class=\"codespan\">mapselectchanged</code> => <code class=\"codespan\">selectchanged</code></li>\n<li><code class=\"codespan\">mapselected</code> => <code class=\"codespan\">selected</code></li>\n<li><code class=\"codespan\">mapunselected</code> => <code class=\"codespan\">unselected</code></li>\n</ul>\n</li>\n<li>option <code class=\"codespan\">series.mapType</code> is deprecated. Use <code class=\"codespan\">series.map</code> instead.</li>\n<li>option <code class=\"codespan\">series.mapLocation</code> is deprecated.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">graph series</code>:<ul>\n<li>option <code class=\"codespan\">series.focusNodeAdjacency</code> is deprecated. Use <code class=\"codespan\">series.emphasis: { focus: 'adjacency'}</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">gauge series</code>:<ul>\n<li>option <code class=\"codespan\">series.clockWise</code> is deprecated. Use <code class=\"codespan\">series.clockwise</code> instead.</li>\n<li>option <code class=\"codespan\">series.hoverOffset</code> is deprecated. Use <code class=\"codespan\">series.emphasis.scaleSize</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">dataZoom component</code>:<ul>\n<li>option <code class=\"codespan\">dataZoom.handleIcon</code> need prefix <code class=\"codespan\">path://</code> if using SVGPath.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">radar</code>:<ul>\n<li>option <code class=\"codespan\">radar.name</code> is deprecated. Use <code class=\"codespan\">radar.axisName</code> instead.</li>\n<li>option <code class=\"codespan\">radar.nameGap</code> is deprecated. Use <code class=\"codespan\">radar.axisNameGap</code> instead.</li>\n</ul>\n</li>\n<li>Parse and format:<ul>\n<li><code class=\"codespan\">echarts.format.formatTime</code> is deprecated. Use <code class=\"codespan\">echarts.time.format</code> instead.</li>\n<li><code class=\"codespan\">echarts.number.parseDate</code> is deprecated. Use <code class=\"codespan\">echarts.time.parse</code> instead.</li>\n<li><code class=\"codespan\">echarts.format.getTextRect</code> is deprecated.</li>\n</ul>\n</li>\n</ul>\n</li>\n</ul>\n<hr>\n<p>DEL</p>\n<p>Users can check this list below. Only in this cases, users need to modify their code about echarts importing:</p>\n<p>If the users previously import echarts from <a href=\"https://cdn.jsdelivr.net/npm/echarts@4.9.0/lib/echarts.js\" target=\"_blank\">echarts/lib/echarts.js</a> in <code class=\"codespan\">v4.x</code>, and use any of the modules listed by <a href=\"https://cdn.jsdelivr.net/npm/echarts@4.9.0/lib/export.js\" target=\"_blank\">echarts/lib/export.js</a>, for example,</p>\n<pre><code class=\"lang-js\">import * as echarts from 'echarts/lib/echarts';\n\nfunction someFn() {\n // For example, use `echarts.util`, which is\n // listed in `echarts/lib/export.js`.\n echarts.util.each(...);\n}\n</code></pre>\n<p>They do not work in <code class=\"codespan\">v5.x</code> any more, because <a href=\"https://cdn.jsdelivr.net/npm/echarts@5.0.1/lib/echarts.js\" target=\"_blank\">echarts/lib/echarts.js</a> does not import <code class=\"codespan\">echarts/lib/export.js</code> internally any more.</p>\n<p>For this case, user should manually add an import of <a href=\"https://cdn.jsdelivr.net/npm/echarts@5.0.1/core.js\" target=\"_blank\">echarts/core</a>. For example:</p>\n<pre><code class=\"lang-js\">import * as echarts from 'echarts/lib/echarts';\nimport { util } from 'echarts/core';\n\nfunction someFn() {\n util.each(...);\n}\n</code></pre>\n<p>or</p>\n<pre><code class=\"lang-js\">import * as echarts from 'echarts/lib/echarts';\nimport * as ecCore from 'echarts/core';\n\n(function () {\n for (var key in ecCore) {\n if (ecCore.hasOwnProperty(key) || key === 'default' || key === '__esModule') return;\n exports[key] = _export[key];\n }\n }\n})();\n</code></pre>\n<pre><code>+ The exported modules from `'echarts/lib/export.js'` is not mounted to `'echarts/lib/echarts.js'` by default. If the upper application previously used `import * as echarts from 'echarts/lib/echarts'` and used any of the exported modules in `'echarts/lib/export.js'`, please change the import code to `import echarts from 'echarts/index.blank'`, where the modules from `'echarts/lib/export.js'` are mounted by default.\n</code></pre>" |
| } |
| } |
