You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@echarts.apache.org by sh...@apache.org on 2021/01/12 08:15:38 UTC
[echarts-doc] branch next updated: add new minimal import tutorial,
remove custom build doc
This is an automated email from the ASF dual-hosted git repository.
shenyi pushed a commit to branch next
in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
The following commit(s) were added to refs/heads/next by this push:
new 58c2a98 add new minimal import tutorial, remove custom build doc
58c2a98 is described below
commit 58c2a98ad5727e924ef23d3a1e674c0e1e3cddba
Author: pissang <bm...@gmail.com>
AuthorDate: Tue Jan 12 16:15:23 2021 +0800
add new minimal import tutorial, remove custom build doc
---
en/tutorial/custom-build.md | 268 ------------------------------------------
en/tutorial/minimal-import.md | 111 +++++++++++++++++
en/tutorial/npm-webpack.md | 80 -------------
zh/tutorial/custom-build.md | 266 -----------------------------------------
zh/tutorial/minimal-import.md | 111 +++++++++++++++++
zh/tutorial/npm-webpack.md | 81 -------------
6 files changed, 222 insertions(+), 695 deletions(-)
diff --git a/en/tutorial/custom-build.md b/en/tutorial/custom-build.md
deleted file mode 100644
index a5cef7c..0000000
--- a/en/tutorial/custom-build.md
+++ /dev/null
@@ -1,268 +0,0 @@
-
-{{target: custom-build}}
-
-# Create Custom Build of ECharts
-
-In most cases, Apache ECharts (incubating)<sup>TM</sup> builds can be get from [CDN](https://www.jsdelivr.com/package/npm/echarts) or from the `echarts/dist` directory in our [GitHub project](https://github.com/apache/incubator-echarts/releases), where
-these pre-builds are provided:
-
-+ Complete verion: `echarts/dist/echarts.js`, including all charts and components (see `echarts/echarts.all.js` for detail), but has maximum file size.
-+ Common version: `echarts/dist/echarts.common.js`, including common charts and components (see `echarts/echarts.common.js` for detail), moderate file size.
-+ Simple version: `echarts/dist/echarts.simple.js`, including a smaller subset of the most common charts and components (see `echarts/echarts.simple.js` for detail), small file size.
-
-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:
-
-+ [Online custom build tool](${websitePath}/en/builder.html) is relatively convenient.
-+ The script `echarts/build/build.js` found in the project is flexible for module selecting, and supports multi-language builds
-+ Build ECharts and your project directly by using tools such as [rollup](https://rollupjs.org/), [webpack](https://webpack.js.org/), [browserify](http://browserify.org/)
-
-There are some examples to illustrate the latter two approaches below.
-
-## Prepare: create our project and install echarts
-
-Create a sample project using the command line
-
-```shell
-mkdir myProject
-cd myProject
-```
-
-Then in the `myProject` directory, initialize [npm](https://www.npmjs.com/) environment and install echarts (assume that [npm](https://www.npmjs.com/) has been installed):
-
-```shell
-npm init
-npm install echarts --save
-```
-
-The installed echarts is in the `myProject/node_modules` directory, which can be used in our project directly. For example:
-
-Use ES Module:
-```js
-import * as echarts from 'echarts';
-```
-
-Use CommonJS:
-```js
-var echarts = require('echarts')
-```
-
-Next, we just describe our examples in ES Module way.
-
-
-
-## Create custom build by `echarts/build/build.js`
-
-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.
-
-echarts has provided a script `echarts/build/build.js` as a build tool ([Node.js](https://nodejs.org) is required to execute it). Now we can use the command below in the `myProject` directory to check its help info:
-
-```shell
-node node_modules/echarts/build/build.js --help
-```
-
-These options can be used in this example:
-
-+ `-i`: Entry file of the echarts code. Can be an absolute path or a relative path relative to the current working directory.
-+ `-o`: The bundle file path. Can be an absolute path or a relative path relative to the current working directory.
-+ `--min`: Whether to compress file (not by default), and remove the code that is for printing error and warning info.
-+ `--lang <language shortcut or file path>`: Whether to use the specified language (Chinese by default). For example: `--lang en` means using English, `--lang my/langXX.js` means using `<cwd>/my/langXX.js` to substitute `echarts/lib/lang.js` while buiding.
-+ `--sourcemap`: Whether to output source map, which is useful in debug.
-+ `--format`: The format of output. Can be `'umb'`(default), `'amd'`, `'iife'`, `'cjs'`, `'es'`.
-
-Now we want to create a echarts bundle that only supports pie chart, we should firstly create an entry file (say `myProject/echarts.custom.js`) to import modules we need:
-
-```js
-// Import the main module of echarts and export them.
-export * from 'echarts/src/echarts';
-// Import pie chart.
-import 'echarts/src/chart/pie';
-// In this case, modules in either `echarts/src` or `echarts/lib`
-// can be imported (but should not be mixed). See
-// "Use `echarts/lib/**` or `echarts/src/**`" below.
-```
-
-Then we can use command below in `myProject` directory to build the bundle:
-
-```shell
-node node_modules/echarts/build/build.js --min -i echarts.custom.js -o lib/echarts.custom.min.js --lang en
-```
-
-Now the bundle `myProject/lib/echarts.custom.min.js` has been created. Then we can create a web page (say `myProject/pie.html`) to test it:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
- <meta charset="utf-8">
- <title>myProject</title>
- <!-- import the bundle `lib/echarts.custom.js`. -->
- <script src="lib/echarts.custom.js"></script>
-</head>
-<body>
- <div id="main" style="width: 600px;height:400px;"></div>
- <script>
- // Create a pie chart:
- echarts.init(document.getElementById('main')).setOption({
- series: {
- type: 'pie',
- data: [
- {name: 'A', value: 1212},
- {name: 'B', value: 2323},
- {name: 'C', value: 1919}
- ]
- }
- });
- </script>
-</body>
-</html>
-```
-
-Open `myProject/pie.html` in a browser, we can see the pie chart:
-
-
-
-
-## Modules that are permitted to be imported
-
-All of the permitted modules are declared in [`myProject/node_module/echarts/echarts.all.js`](https://github.com/apache/incubator-echarts/blob/master/echarts.all.js) and [`myProject/node_module/echarts/src/export.js`](https://github.com/apache/incubator-echarts/blob/master/src/export.js). Other modules in the source code of echarts and zrender **SHOULD NOT BE IMPORTED**, because they are inner modules, whose interfaces and functionalities may be modified in the subsequent upgrades of echarts.
-
-
-## Use `echarts/lib/**` or `echarts/src/**`?
-
-+ If intending to import part of echarts modules in your project and build yourself, only `echarts/lib/**` can be used, `echarts/src/**` should not be used.
-+ If using `echarts/build/build.js` to make a bundle, either `echarts/lib/**` or `echarts/src/**` can be used (should not be mixed), where `echarts/src/**` brings smaller bundle size a little.
-
-> Reason: currently, `echarts/src/**` is the source code that using ES Module, and they are transpiled to CommonJS code and placed in `echarts/lib/**`. (This transformation is for backward compatible with old version of NodeJS and webpack that do not support ES Module.)
-> Historically, echarts extensions and user projects have been using the package path `echarts/lib/**`. So it should not be changed, otherwise, mixed using both `echarts/src/**` and `echarts/lib/**` will generate two echarts namespace and bring some problems. But it is not an issue when using `echarts/build/build.js` to create a bundle, where ES modules in `echarts/src/**` can be analyzed statically for smaller bundle size.
-
-
-## Build echarts and our project directly by rollup
-
-Now we have known that how to create custom build by `echarts/build/build.js`. Alternatively, we can bundle echarts and our project directly by the tool like [rollup](https://rollupjs.org/), [webpack](https://webpack.js.org/) or [browserify](http://browserify.org/). In some project, this approach is required. Next we only go with [rollup](https://rollupjs.org/), because [webpack](https://webpack.js.org/) and [browserify](http://browserify.org/) are in the similar way.
-
-
-Firstly install [rollup](https://rollupjs.org/) in `myProject` directory:
-
-```shell
-npm install rollup --save-dev
-npm install rollup-plugin-node-resolve --save-dev
-npm install rollup-plugin-uglify --save-dev
-```
-
-Then we create a project JS file `myProject/line.js` for line chart rendering:
-
-```js
-// Import the main module of echarts.
-import * as echarts from 'echarts/lib/echarts';
-// Import line chart.
-import 'echarts/lib/chart/line';
-// Import components of tooltip, title and toolbox.
-import 'echarts/lib/component/tooltip';
-import 'echarts/lib/component/title';
-import 'echarts/lib/component/toolbox';
-
-// Render line chart and components.
-echarts.init(document.getElementById('main')).setOption({
- title: {text: 'Line Chart'},
- tooltip: {},
- toolbox: {
- feature: {
- dataView: {},
- saveAsImage: {
- pixelRatio: 2
- },
- restore: {}
- }
- },
- xAxis: {},
- yAxis: {},
- series: [{
- type: 'line',
- smooth: true,
- data: [[12, 5], [24, 20], [36, 36], [48, 10], [60, 10], [72, 20]]
- }]
-});
-```
-
-The created module `myProject/line.js` can not work directly in the browsers that do not support ES Module. So we need to build them. Before we run [rollup](https://rollupjs.org/), a config file `myProject/rollup.config.js` should be created:
-
-```js
-// Responsible for looking for modules in `node_module` directory. For example,
-// if there is code `import 'echarts/lib/chart/line';`, the module file
-// `node_module/echarts/lib/chart/line.js` can be find by this plugin.
-import nodeResolve from 'rollup-plugin-node-resolve';
-// Responsible for compress code.
-import uglify from 'rollup-plugin-uglify';
-// Support multi-language.
-import ecLangPlugin from 'echarts/build/rollup-plugin-ec-lang';
-
-export default {
- name: 'myProject',
- // The entry file.
- input: './line.js',
- plugins: [
- nodeResolve(),
- ecLangPlugin({lang: 'en'}), // Use english
- // Remove the snippet in `__DEV__`, which mainly prints error log.
- uglify()
- ],
- output: {
- // Output file in the format of 'umd'.
- format: 'umd',
- // Output source map.
- sourcemap: true,
- // The path of the output bundle.
- file: 'lib/line.min.js'
- }
-};
-```
-
-Then execute the following command in `myProject` directory to start the build:
-
-```shell
-./node_modules/.bin/rollup -c
-```
-
-> `-c` indicate `rollup` to use `myProject/rollup.config.js` as the config file.
-
-The created bundle `myProject/lib/line.min.js` includes project code and part of echarts code that we requried. Now we create a web page `myProject/line.html` to test it:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
- <meta charset="utf-8">
- <title>myProject</title>
-</head>
-<body>
- <div id="main" style="width: 600px;height:400px;"></div>
- <!-- Import the created bundle: -->
- <script src="lib/line.min.js"></script>
-</body>
-</html>
-```
-
-Open `myProject/line.html` in a browser, we will get:
-
-
-
-
-## Multi-language
-
-In the example above, we can notice that the label of the `toolbox` component is in English. Essentially any text can be customized by `echarts option`, but if we want to show label in a certain language by default, we have to specify the language while building the code.
-
-For example:
-
-```shell
-node node_modules/echarts/build/build.js --min -i echarts.custom.js -o lib/echarts.custom.min.js --lang en
-```
-
-It means that the pre-defined English text is used. Moreover, can be `--lang fi`.
-
-```shell
-node node_modules/echarts/build/build.js --min -i echarts.custom.js -o lib/echarts.custom.min.js --lang my/langXX.js
-```
-
-It means that `myProject/my/langXX.js` is used to substitute `myProject/node_modules/echarts/lib/lang.js` while performing build. So we can customize text in our language in `myProject/my/langXX.js`. Notice, `-o` or `--output` must be specified in the approach.
-
-Besides, the same lang parameter can be pass to `echarts/build/rollup-plugin-ec-lang`.
diff --git a/en/tutorial/minimal-import.md b/en/tutorial/minimal-import.md
new file mode 100644
index 0000000..3179dc6
--- /dev/null
+++ b/en/tutorial/minimal-import.md
@@ -0,0 +1,111 @@
+
+{{target: npm-webpack}}
+
+# Use Apache ECharts<sup>TM</sup> with bundler and NPM
+
+If your development environment uses a package management tool like `npm` or `yarn` and builds with a packaging tool like Webpack, this article will describe how to get a minimal bundle of Apache ECharts<sup>TM</sup> via treeshaking.
+
+## NPM installation of ECharts
+
+You can install ECharts via npm using the following command
+
+```shell
+npm install echarts --save
+```
+
+## Introduce ECharts
+
+```js
+import * as echarts from 'echarts';
+
+// initialize the echarts instance
+var myChart = echarts.init(document.getElementById('main'));
+// Draw the chart
+myChart.setOption({
+ title: {
+ text: 'ECharts Getting Started Example'
+ },
+ tooltip: {},
+ xAxis: {
+ data: ['shirt', 'cardigan', 'chiffon', 'pants', 'heels', 'socks']
+ },
+ yAxis: {},
+ series: [{
+ name: 'sales',
+ type: 'bar',
+ data: [5, 20, 36, 10, 10, 20]
+ }]
+});
+```
+
+## Importing required charts and components to have minimal bundle.
+
+The above code will import all the charts and components in ECharts, but if you don't want to bring in all the components, you can use the tree-shakeable interface provided by ECharts to bundle the required components and get a minimal bundle.
+
+```js
+// Import the echarts core module, which provides the necessary interfaces for using echarts.
+import * as echarts from 'echarts/core';
+// Import bar charts, all with Chart suffix
+import {
+ BarChart
+} from 'echarts/charts';
+// import the prompt box, title, and rectangular coordinate system components, all suffixed with Component
+import {
+ TitleComponent,
+ TooltipComponent,
+ GridComponent
+} from 'echarts/components';
+// Import the Canvas renderer, note that introducing the CanvasRenderer or SVGRenderer is a required step
+import {
+ CanvasRenderer
+} from 'echarts/renderers';
+
+// Register the required components
+echarts.use(
+ [TitleComponent, TooltipComponent, GridComponent, BarChart, CanvasRenderer]
+);
+
+// The next step is the same as before, initialize the chart and set the configuration items
+var myChart = echarts.init(document.getElementById('main'));
+myChart.setOption({
+ ...
+});
+```
+
+> Note that in order to keep the size of the package to a minimum, ECharts does not provide any renderer in tree-shakeable interface, so you need to choose to import `CanvasRenderer` or `SVGRenderer` as the renderer. The advantage of this is that if you only need to use the svg rendering mode, the bundle will not include the `CanvasRenderer` module, which is not needed.
+
+The "Full Code" tab on our sample editor page provides a very convenient way to generate a tree-shakable code. It will generate tree-shakable code based on the current option dynamically. You can use it directly in your project.
+
+## Minimal Option Type in TypeScript
+
+For developers who are using TypeScript to develop ECharts, we provide a type interface to combine the minimal `EChartsOption` type. This stricter type can effectively help you check for missing components or charts.
+
+```ts
+import * as echarts from 'echarts/core';
+import {
+ BarChart,
+ // The series types are defined with the SeriesOption suffix
+ BarSeriesOption,
+ LineChart,
+ LineSeriesOption
+} from 'echarts/charts';
+import {
+ TitleComponent,
+ // The component types are defined with the suffix ComponentOption
+ TitleComponentOption,
+ GridComponent,
+ GridComponentOption
+} from 'echarts/components';
+import {
+ CanvasRenderer
+} from 'echarts/renderers';
+
+// Combine an Option type with only required components and charts via ComposeOption
+type ECOption = echarts.
+ BarSeriesOption | LineSeriesOption | TitleComponentOption | GridComponentOption
+>;
+
+var option: ECOption = {
+ ...
+}
+```
\ No newline at end of file
diff --git a/en/tutorial/npm-webpack.md b/en/tutorial/npm-webpack.md
deleted file mode 100644
index 63bb4ee..0000000
--- a/en/tutorial/npm-webpack.md
+++ /dev/null
@@ -1,80 +0,0 @@
-
-{{target: npm-webpack}}
-
-# Use ECharts with webpack
-
-[Webpack](https://webpack.js.org//) 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.
-
-## Use npm to install ECharts
-
-You can use the following command to install ECharts with npm.
-
-```shell
-npm install echarts --save
-```
-
-## Include ECharts
-
-ECharts and zrender installed by npm will be placed under `node_modules`. You can obtain echarts directly in project with `require('echarts')`.
-
-```js
-var echarts = require('echarts');
-
-// initialize echarts instance with prepared DOM
-var myChart = echarts.init(document.getElementById('main'));
-// draw chart
-myChart.setOption({
- title: {
- text: 'ECharts entry example'
- },
- tooltip: {},
- xAxis: {
- data: ['shirt', 'cardign', 'chiffon shirt', 'pants', 'heels', 'socks']
- },
- yAxis: {},
- series: [{
- name: 'sales',
- type: 'bar',
- data: [5, 20, 36, 10, 10, 20]
- }]
-});
-```
-
-## Include ECharts charts and components on demand
-
-By default, `require('echarts')` 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.
-
-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.
-
-```js
-// include ECharts main module
-var echarts = require('echarts/lib/echarts');
-// include bar chart
-require('echarts/lib/chart/bar');
-// include tooltip and title component
-require('echarts/lib/component/tooltip');
-require('echarts/lib/component/title');
-
-// initialize echarts instance with prepared DOM
-var myChart = echarts.init(document.getElementById('main'));
-// draw chart
-myChart.setOption({
- title: {
- text: 'ECharts introductory example'
- },
- tooltip: {},
- xAxis: {
- data: ['shirt', 'cardign', 'chiffon shirt', 'pants', 'heels', 'socks']
- },
- yAxis: {},
- series: [{
- name: 'sales',
- type: 'bar',
- data: [5, 20, 36, 10, 10, 20]
- }]
-});
-```
-
-Available modules see [https://github.com/apache/incubator-echarts/blob/master/index.js](https://github.com/apache/incubator-echarts/blob/master/index.js)
-
-The same goes for another popular packaging tools [browserify](http://browserify.org/), which will not be introduced again here. Using [rollup](https://rollupjs.org/) to make a custom build of echarts is introduced in [Create Custom Build of ECharts](tutorial.html#Create%20Custom%20Build%20of%20ECharts)
diff --git a/zh/tutorial/custom-build.md b/zh/tutorial/custom-build.md
deleted file mode 100644
index ca692e4..0000000
--- a/zh/tutorial/custom-build.md
+++ /dev/null
@@ -1,266 +0,0 @@
-{{target: custom-build}}
-
-# 自定义构建 ECharts
-
-一般来说,可以直接从 [CDN](https://www.jsdelivr.com/package/npm/echarts) 中获取构建后的 Apache ECharts (incubating)<sup>TM</sup>,也可以从 [GitHub](https://github.com/apache/incubator-echarts/releases) 中的 `echarts/dist` 文件夹中获取构建好的 echarts,这都可以直接在浏览器端项目中使用。这些构建好的 echarts 提供了下面这几种定制:
-
-+ 完全版:`echarts/dist/echarts.js`,体积最大,包含所有的图表和组件,所包含内容参见:`echarts/echarts.all.js`。
-+ 常用版:`echarts/dist/echarts.common.js`,体积适中,包含常见的图表和组件,所包含内容参见:`echarts/echarts.common.js`。
-+ 精简版:`echarts/dist/echarts.simple.js`,体积较小,仅包含最常用的图表和组件,所包含内容参见:`echarts/echarts.simple.js`。
-
-我们也可以自己构建 echarts,能够仅仅包括自己所需要的图表和组件。可以用这几种方式自定义构建:
-
-+ [在线自定义构建](${websitePath}/zh/builder.html):比较方便。
-+ 使用 `echarts/build/build.js` 脚本自定义构建:比在线构建更灵活一点,并且支持多语言。
-+ 直接使用构建工具(如 [rollup](https://rollupjs.org/)、[webpack](https://webpack.js.org/)、[browserify](http://browserify.org/))自己构建:也是一种选择。
-
-下面我们举些小例子,介绍后两种方式。
-
-
-## 准备工作:创建自己的工程和安装 echarts
-
-使用命令行,创建自己的工程:
-
-```shell
-mkdir myProject
-cd myProject
-```
-
-在 `myProject` 目录下使用命令行,初始化工程的 [npm](https://www.npmjs.com/) 环境并安装 echarts(这里前提是您已经安装了 [npm](https://www.npmjs.com/)):
-
-```shell
-npm init
-npm install echarts --save
-```
-
-通过 npm 安装的 echarts 会出现在 `myProject/node_modules` 目录下,从而可以直接在项目代码中得到 echarts,例如:
-
-使用 ES Module:
-```js
-import * as echarts from 'echarts';
-```
-
-使用 CommonJS:
-```js
-var echarts = require('echarts')
-```
-
-下面仅以使用 ES Module 的方式来举例。
-
-
-
-## 使用 echarts 提供的构建脚本自定义构建
-
-在这个例子中,我们要创建一个饼图,并且想自定义构建一个只含有饼图的 echarts 文件,从而能使 echarts 文件的大小比较小一些。
-
-echarts 已经提供了构建脚本 `echarts/build/build.js`,基于 [Node.js](https://nodejs.org) 运行。我们可以在 `myProject` 目录下使用命令行,看到它的使用方式:
-
-```shell
-node node_modules/echarts/build/build.js --help
-```
-
-其中我们在这个例子里会用到的参数有:
-
-+ `-i`:代码入口文件,可以是绝对路径或者基于当前命令行路径的相对路径。
-+ `-o`:生成的 bundle 文件,可以是绝对路径或者基于当前命令行路径的相对路径。
-+ `--min`:是否压缩文件(默认不压缩),并且去多余的打印错误信息的代码,形成生产环境可用的文件。
-+ `--lang <language shortcut or file path>`:是否使用其他语言版本,默认是中文。例如:`--lang en` 表示使用英文,`--lang my/langXX.js` 表示构建时使用 `<cwd>/my/langXX.js` 替代 `echarts/lib/lang.js` 文件。
-+ `--sourcemap`:是否输出 source map,以便于调试。
-+ `--format`:输出的格式,可选 `'umb'`(默认)、`'amd'`、`'iife'`、`'cjs'`、`'es'`。
-
-既然我们想自定义构建一个只含有饼图的 echarts 文件,我们需要创建一个入口文件,可以命名为 `myProject/echarts.custom.js`,文件里会引用所需要的 echarts 模块:
-
-```js
-// 引入 echarts 主模块。
-export * from 'echarts/src/echarts';
-// 引入饼图。
-import 'echarts/src/chart/pie';
-// 在这个场景下,可以引用 `echarts/src` 或者 `echarts/lib` 下的文件(但是不可混用),
-// 参见下方的解释:“引用 `echarts/lib/**` 还是 `echarts/src/**`”。
-```
-
-然后我们可以在 `myProject` 目录下使用命令行,这样开始构建:
-
-```shell
-node node_modules/echarts/build/build.js --min -i echarts.custom.js -o lib/echarts.custom.min.js
-```
-
-这样,`myProject/lib/echarts.custom.min.js` 就生成了。我们可以创建 `myProject/pie.html` 来使用它:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
- <meta charset="utf-8">
- <title>myProject</title>
- <!-- 引入 lib/echarts.custom.min.js -->
- <script src="lib/echarts.custom.min.js"></script>
-</head>
-<body>
- <div id="main" style="width: 600px;height:400px;"></div>
- <script>
- // 绘制图表。
- echarts.init(document.getElementById('main')).setOption({
- series: {
- type: 'pie',
- data: [
- {name: 'A', value: 1212},
- {name: 'B', value: 2323},
- {name: 'C', value: 1919}
- ]
- }
- });
- </script>
-</body>
-</html>
-```
-
-然后在浏览器里打开 `myProject/pie.html`,就可以看到一个饼图:
-
-
-
-
-## 允许被引用的模块
-
-在自定义构建中,允许被引用的模块,全声明在 [`myProject/node_module/echarts/echarts.all.js`](https://github.com/apache/incubator-echarts/blob/master/echarts.all.js) 和 [`myProject/node_module/echarts/src/export.js`](https://github.com/apache/incubator-echarts/blob/master/src/export.js) 中。echarts 和 zrender 源代码中的其他模块,都是 echarts 的内部模块,**不应该去引用**。因为在后续 echarts 版本升级中,内部模块的接口和功能可能变化,甚至模块本身也可能被移除。
-
-
-## 引用 `echarts/lib/**` 还是 `echarts/src/**`
-
-+ 项目中如果直接引用 echarts 里的一些模块并自行构建,应该使用 `echarts/lib/**` 路径,而不可使用 `echarts/src/**`。
-+ 当使用构建脚本 `echarts/build/build.js` 打包 bundle,那么两者可以选其一使用(不可混用),使用 `echarts/src/**` 可以获得稍微小一些的文件体积。
-
-> 原因是:目前,`echarts/src/**` 中是采用 ES Module 的源代码,`echarts/lib/**` 中是 `echarts/src/**` 编译成为 CommonJS 后的产物(编译成 CommonJS 是为了向后兼容一些不支持 ES Module 的老版本 NodeJS 和 webpack)。
-> 因为历史上,各个 echarts 扩展、各个用户项目,一直是使用的包路径是 `echarts/lib/**`,所以这个路径不应该改变,否则,可能导致混合使用 `echarts/src/**` 和 `echarts/lib/**` 得到两个不同的 echarts 名空间,造成问题。而使用 `echarts/build/build.js` 打包 bundle 时没有涉及这个问题,`echarts/src/**` 中的 ES Module 便于静态分析从而得到稍微小些的文件体积。
-
-
-## 直接使用 rollup 自定义构建
-
-上文中介绍了如何使用 echarts 提供的脚本 `echarts/build/build.js` 自定义构建。与此并列的另一种选择是,我们直接使用构建工具(如 [rollup](https://rollupjs.org/)、[webpack](https://webpack.js.org/)、[browserify](http://browserify.org/))自定义构建,并且把 echarts 代码和项目代码在构建成一体。在一些项目中可能需要这么做。下面我们仅仅介绍如何使用 [rollup](https://rollupjs.org/) 来构建。[webpack](https://webpack.js.org/) 和 [browserify](http://browserify.org/) 与此类同,不赘述。
-
-首先我们在 `myProject` 目录下使用 npm 安装 [rollup](https://rollupjs.org/):
-
-```shell
-npm install rollup --save-dev
-npm install rollup-plugin-node-resolve --save-dev
-npm install rollup-plugin-uglify --save-dev
-```
-
-接下来创建项目 JS 文件 `myProject/line.js` 来绘制图表,内容为:
-
-```js
-// 引入 echarts 主模块。
-import * as echarts from 'echarts/lib/echarts';
-// 引入折线图。
-import 'echarts/lib/chart/line';
-// 引入提示框组件、标题组件、工具箱组件。
-import 'echarts/lib/component/tooltip';
-import 'echarts/lib/component/title';
-import 'echarts/lib/component/toolbox';
-
-// 基于准备好的dom,初始化 echarts 实例并绘制图表。
-echarts.init(document.getElementById('main')).setOption({
- title: {text: 'Line Chart'},
- tooltip: {},
- toolbox: {
- feature: {
- dataView: {},
- saveAsImage: {
- pixelRatio: 2
- },
- restore: {}
- }
- },
- xAxis: {},
- yAxis: {},
- series: [{
- type: 'line',
- smooth: true,
- data: [[12, 5], [24, 20], [36, 36], [48, 10], [60, 10], [72, 20]]
- }]
-});
-```
-
-对于不支持 ES Module 的浏览器而言,刚才创建的 `myProject/line.js` 还不能直接被网页引用并在浏览器中运行,需要进行构建。使用 [rollup](https://rollupjs.org/) 构建前,需要创建它的配置文件 `myProject/rollup.config.js`,内容如下:
-
-```js
-// 这个插件用于在 `node_module` 文件夹(即 npm 用于管理模块的文件夹)中寻找模块。比如,代码中有
-// `import 'echarts/lib/chart/line';` 时,这个插件能够寻找到
-// `node_module/echarts/lib/chart/line.js` 这个模块文件。
-import nodeResolve from 'rollup-plugin-node-resolve';
-// 用于压缩构建出的代码。
-import uglify from 'rollup-plugin-uglify';
-// 用于多语言支持(如果不需要可忽略此 plugin)。
-// import ecLangPlugin from 'echarts/build/rollup-plugin-ec-lang';
-
-export default {
- name: 'myProject',
- // 入口代码文件,就是刚才所创建的文件。
- input: './line.js',
- plugins: [
- nodeResolve(),
- // ecLangPlugin({lang: 'en'}),
- // 消除代码中的 __DEV__ 代码段,从而不在控制台打印错误提示信息。
- uglify()
- ],
- output: {
- // 以 UMD 格式输出,从而能在各种浏览器中加载使用。
- format: 'umd',
- // 输出 source map 便于调试。
- sourcemap: true,
- // 输出文件的路径。
- file: 'lib/line.min.js'
- }
-};
-```
-
-然后在 `myProject` 目录下使用命令行,构建工程代码 `myProject/line.js`:
-
-```shell
-./node_modules/.bin/rollup -c
-```
-
-> 其中 `-c` 表示让 `rollup` 使用我们刚才创建的 `myProject/rollup.config.js` 文件作为配置文件。
-
-构建生成的 `myProject/lib/line.min.js` 文件包括了工程代码和 echarts 代码,并且仅仅包括我们所需要的图和组件,并且可以在浏览器中使用。我们可以用一个示例页面来测试一下,创建文件 `myProject/line.html`,内容如下:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
- <meta charset="utf-8">
- <title>myProject</title>
-</head>
-<body>
- <!-- 为 echarts 准备一个具备大小(宽高)的Dom。 -->
- <div id="main" style="width: 600px;height:400px;"></div>
- <!-- 引入刚才构建好的文件。 -->
- <script src="lib/line.min.js"></script>
-</body>
-</html>
-```
-
-在浏览器里打开 `myProject/line.html` 则会得到如下效果:
-
-
-
-
-## 多语言支持
-
-上面的例子中能看到,工具箱组件(toolbox)的提示文字是中文。本质上,echarts 图表显示出来的文字,都可以通过 `option` 来定制,改成任意语言。但是如果想“默认就是某种语言”,则需要通过构建来实现。
-
-在上面的例子中,可以在 `echarts/build/build.js` 的参数中指定语言:
-
-```shell
-node node_modules/echarts/build/build.js --min -i echarts.custom.js -o lib/echarts.custom.min.js --lang en
-```
-
-表示使用内置的英文。此外还可以是 `--lang fi`。
-
-```shell
-node node_modules/echarts/build/build.js --min -i echarts.custom.js -o lib/echarts.custom.min.js --lang my/langXX.js
-```
-
-表示在构建时使用 `myProject/my/langXX.js` 文件来替换 `myProject/node_modules/echarts/lib/lang.js` 文件。这样可以在 `myProject/my/langXX.js` 文件中自定义语言。注意这种方式中,必须指定 `-o` 或者 `--output`。
-
-另外,上面的 rollup 插件 `echarts/build/rollup-plugin-ec-lang` 也可以传入同样的参数,实现同样的功能。
diff --git a/zh/tutorial/minimal-import.md b/zh/tutorial/minimal-import.md
new file mode 100644
index 0000000..6b5238d
--- /dev/null
+++ b/zh/tutorial/minimal-import.md
@@ -0,0 +1,111 @@
+
+{{target: npm-webpack}}
+
+# 在打包环境中使用 Apache ECharts<sup>TM</sup>
+
+假如你的开发环境使用了`npm`或者`yarn`等包管理工具,并且使用 Webpack 等打包工具进行构建,本文将会介绍如何引入 Apache ECharts<sup>TM</sup> 并通过 treeshaking 只打包需要的模块。
+
+## NPM 安装 ECharts
+
+你可以使用如下命令通过 npm 安装 ECharts
+
+```shell
+npm install echarts --save
+```
+
+## 引入 ECharts
+
+```js
+import * as echarts from 'echarts';
+
+// 基于准备好的dom,初始化echarts实例
+var myChart = echarts.init(document.getElementById('main'));
+// 绘制图表
+myChart.setOption({
+ title: {
+ text: 'ECharts 入门示例'
+ },
+ tooltip: {},
+ xAxis: {
+ data: ['衬衫', '羊毛衫', '雪纺衫', '裤子', '高跟鞋', '袜子']
+ },
+ yAxis: {},
+ series: [{
+ name: '销量',
+ type: 'bar',
+ data: [5, 20, 36, 10, 10, 20]
+ }]
+});
+```
+
+## 按需引入 ECharts 图表和组件
+
+上面的代码会引入所有 ECharts 中所有的图表和组件,但是假如你不想引入所有组件,也可以使用 ECharts 提供的按需引入的接口来打包必须的组件。
+
+```js
+// 引入 echarts 核心模块,核心模块提供了 echarts 使用必须要的接口。
+import * as echarts from 'echarts/core';
+// 引入柱状图图表,图表后缀都为 Chart
+import {
+ BarChart
+} from 'echarts/charts';
+// 引入提示框,标题,直角坐标系组件,组件后缀都为 Component
+import {
+ TitleComponent,
+ TooltipComponent,
+ GridComponent
+} from 'echarts/components';
+// 引入 Canvas 渲染器,注意引入 CanvasRenderer 或者 SVGRenderer 是必须的一步
+import {
+ CanvasRenderer
+} from 'echarts/renderers';
+
+// 注册必须的组件
+echarts.use(
+ [TitleComponent, TooltipComponent, GridComponent, BarChart, CanvasRenderer]
+);
+
+// 接下来的使用就跟之前一样,初始化图表,设置配置项
+var myChart = echarts.init(document.getElementById('main'));
+myChart.setOption({
+ ...
+});
+```
+
+> 需要注意的是注意为了保证打包的体积是最小的,ECharts 按需引入的时候不再提供任何渲染器,所以需要选择引入`CanvasRenderer`或者`SVGRenderer`作为渲染器。这样的好处是假如你只需要使用 svg 渲染模式,打包的结果中就不会再包含无需使用的`CanvasRenderer`模块。
+
+我们在示例编辑页的“完整代码”标签提供了非常方便的生成按需引入代码的功能。这个功能会根据当前的配置项动态生成最小的按需引入的代码。你可以直接在你的项目中使用。
+
+## 在 TypeScript 中按需引入
+
+对于使用了 TypeScript 来开发 ECharts 的开发者,我们提供了类型接口来组合出最小的`EChartsOption`类型。这个更严格的类型可以有效帮助你检查出是否少加载了组件或者图表。
+
+```ts
+import * as echarts from 'echarts/core';
+import {
+ BarChart,
+ // 系列类型的定义后缀都为 SeriesOption
+ BarSeriesOption,
+ LineChart,
+ LineSeriesOption
+} from 'echarts/charts';
+import {
+ TitleComponent,
+ // 组件类型的定义后缀都为 ComponentOption
+ TitleComponentOption,
+ GridComponent,
+ GridComponentOption
+} from 'echarts/components';
+import {
+ CanvasRenderer
+} from 'echarts/renderers';
+
+// 通过 ComposeOption 来组合出一个只有必须组件和图表的 Option 类型
+type ECOption = echarts.ComposeOption<
+ BarSeriesOption | LineSeriesOption | TitleComponentOption | GridComponentOption
+>;
+
+var option: ECOption = {
+ ...
+}
+```
\ No newline at end of file
diff --git a/zh/tutorial/npm-webpack.md b/zh/tutorial/npm-webpack.md
deleted file mode 100644
index 804795f..0000000
--- a/zh/tutorial/npm-webpack.md
+++ /dev/null
@@ -1,81 +0,0 @@
-
-{{target: npm-webpack}}
-
-# 在 webpack 中使用 ECharts
-
-[Webpack](https://webpack.js.org//) 是目前比较流行的模块打包工具,你可以在使用 webpack 的项目中轻松的引入和打包 Apache ECharts (incubating)<sup>TM</sup>,这里假设你已经对 webpack 具有一定的了解并且在自己的项目中使用。
-
-## npm 安装 ECharts
-
-你可以使用如下命令通过 npm 安装 ECharts
-
-```shell
-npm install echarts --save
-```
-
-## 引入 ECharts
-
-通过 npm 上安装的 ECharts 和 zrender 会放在`node_modules`目录下。可以直接在项目代码中 `require('echarts')` 得到 ECharts。
-
-```js
-var echarts = require('echarts');
-
-// 基于准备好的dom,初始化echarts实例
-var myChart = echarts.init(document.getElementById('main'));
-// 绘制图表
-myChart.setOption({
- title: {
- text: 'ECharts 入门示例'
- },
- tooltip: {},
- xAxis: {
- data: ['衬衫', '羊毛衫', '雪纺衫', '裤子', '高跟鞋', '袜子']
- },
- yAxis: {},
- series: [{
- name: '销量',
- type: 'bar',
- data: [5, 20, 36, 10, 10, 20]
- }]
-});
-```
-
-## 按需引入 ECharts 图表和组件
-
-默认使用 `require('echarts')` 得到的是已经加载了所有图表和组件的 ECharts 包,因此体积会比较大,如果在项目中对体积要求比较苛刻,也可以只按需引入需要的模块。
-
-例如上面示例代码中只用到了柱状图,提示框和标题组件,因此在引入的时候也只需要引入这些模块,可以有效的将打包后的体积从 400 多 KB 减小到 170 多 KB。
-
-```js
-// 引入 ECharts 主模块
-var echarts = require('echarts/lib/echarts');
-// 引入柱状图
-require('echarts/lib/chart/bar');
-// 引入提示框和标题组件
-require('echarts/lib/component/tooltip');
-require('echarts/lib/component/title');
-
-// 基于准备好的dom,初始化echarts实例
-var myChart = echarts.init(document.getElementById('main'));
-// 绘制图表
-myChart.setOption({
- title: {
- text: 'ECharts 入门示例'
- },
- tooltip: {},
- xAxis: {
- data: ['衬衫', '羊毛衫', '雪纺衫', '裤子', '高跟鞋', '袜子']
- },
- yAxis: {},
- series: [{
- name: '销量',
- type: 'bar',
- data: [5, 20, 36, 10, 10, 20]
- }]
-});
-```
-
-可以按需引入的模块列表见 [https://github.com/apache/incubator-echarts/blob/master/index.js](https://github.com/apache/incubator-echarts/blob/master/index.js)
-
-
-对于流行的模块打包工具 [browserify](http://browserify.org/) 也是同样的用法,这里就不赘述了。而对于使用 [rollup](https://rollupjs.org/) 的自定义构建,参见 [自定义构建 ECharts](${websitePath}/zh/tutorial.html#%E8%87%AA%E5%AE%9A%E4%B9%89%E6%9E%84%E5%BB%BA%20ECharts)。
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org