diff --git a/README.md b/README.md index 013cdc6..7711f33 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,18 @@ > ECharts component for Vue.js. +> [🇨🇳 中文版](./README.zh_CN.md) + Built upon [ECharts](http://echarts.baidu.com/index.html) `v3.8.5`+ and depends on [Vue.js](https://vuejs.org/) `v2.2.6`+. ## Installation +### npm + +```bash +$ npm install vue-echarts +``` + ### Manual Just download `dist/vue-echarts.js` and include it in your HTML file: @@ -14,46 +22,27 @@ Just download `dist/vue-echarts.js` and include it in your HTML file: ``` -### npm - -```bash -$ npm install vue-echarts -``` - -### bower - -```bash -$ bower install vue-echarts -``` - -### manual - -Just download `dist/vue-echarts.js` and include it in your HTML file: - -```html - -``` - ## Usage -### ES Modules with NPM & vue-loader (Recommended) +### ES Modules with npm & vue-loader (Recommended) ```js import Vue from 'vue' -import ECharts from 'vue-echarts/components/ECharts.vue' +import ECharts from 'vue-echarts/components/ECharts' // import ECharts modules manually to reduce bundle size import 'echarts/lib/chart/bar' import 'echarts/lib/component/tooltip' // register component to use +Vue.component('chart', ECharts) ``` -## Heads up +## ⚠️ Heads up ### Importing the souce version -If you are using `vue-cli` to create your project and you want to use the untranspiled component (import `vue-echarts/components/ECharts` rather than import `vue-echarts` directly, to optimize bundle size, which is recommended), the `webpack` template may exclude `node_modules` from files to be transpiled by Babel. To fix this problem, try change `build/webpack.base.conf.js` like this: +If you are using vue-cli to create your project and you want to use the untranspiled component (import `vue-echarts/components/ECharts` rather than import vue-echarts directly, to optimize bundle size, which is recommended), Vue's webpack template may exclude `node_modules` from files to be transpiled by Babel. To fix this problem, try change `build/webpack.base.conf.js` like this: For webpack 1.x: @@ -84,7 +73,7 @@ For webpack 2+: If you are using bare webpack config, just do similar modifications make it work. -### CommonJS with NPM without ES Next support +### CommonJS with npm ```js var Vue = require('vue') @@ -94,14 +83,13 @@ var ECharts = require('vue-echarts') // or with vue-loader you can require the src directly // and import ECharts modules manually to reduce bundle size -var ECharts = require('vue-echarts/components/ECharts.vue') +var ECharts = require('vue-echarts/components/ECharts') require('echarts/lib/chart/bar') require('echarts/lib/component/tooltip') // register component to use ``` - ### AMD ```js @@ -120,7 +108,7 @@ require(['vue', 'vue-echarts'], function (Vue, ECharts) { ### Global variable -The component class is exposed as `window.VueECharts`. +The component is exposed as `window.VueECharts`. ```js // register component to use @@ -218,17 +206,17 @@ See more examples [here](https://github.com/Justineo/vue-echarts/tree/master/dem * `watchShallow` (default: `false`) - This prop is used to turn off the default deep watch for `options` prop. For charts with large amount of data, you may need to set this prop so that Vue only watches the `options` prop itself instead of watching all its properties inside. To trigger the rerender of the chart, you have to change the root reference to `option` prop itself, or you can manually manage data via the `mergeOptions` method. + This prop is used to turn off the default deep watch for `options` prop. For charts with large amount of data, you may need to set this prop so that Vue only watches the `options` prop itself instead of watching all its properties inside. To trigger the rerender of the chart, you have to change the root reference to `options` prop itself, or you can manually manage data via the `mergeOptions` method (chart data won't be synchronized with `options` prop when doing this). ### Computed * `width` **[readonly]** - Used to retrieve the current width of the chart instance. + Used to retrieve the current width of the ECharts instance. * `height` **[readonly]** - Used to retrieve the current height of the chart instance. + Used to retrieve the current height of the ECharts instance. * `computedOptions` **[readonly]** @@ -238,7 +226,7 @@ See more examples [here](https://github.com/Justineo/vue-echarts/tree/master/dem * `mergeOptions` (use `setOption` in ECharts under the hood) - *Provides a better method name to describe the actual behavior of `setOption.`* + *Provides a better method name to describe the actual behavior of `setOption`.* * `resize` * `dispatchAction` diff --git a/README.zh_CN.md b/README.zh_CN.md new file mode 100644 index 0000000..39388e6 --- /dev/null +++ b/README.zh_CN.md @@ -0,0 +1,301 @@ +# Vue-ECharts + +> ECharts 的 Vue.js 组件。 + +基于 [ECharts](http://echarts.baidu.com/index.html) `v3.8.5`+ 开发,依赖 [Vue.js](https://vuejs.org/) `v2.2.6`+。 + +## 安装 + +### npm + +```bash +$ npm install vue-echarts +``` + +### bower + +```bash +$ bower install vue-echarts +``` + +### 手动安装 + +直接下载 `dist/vue-echarts.js` 并在 HTML 文件中引入: + +```html + +``` + +## 使用方法 + +### 用 npm 与 vue-loader 基于 ES Module 引入(推荐用法) + +```js +import Vue from 'vue' +import ECharts from 'vue-echarts/components/ECharts.vue' + +// 手动引入 ECharts 各模块来减小打包体积 +import 'echarts/lib/chart/bar' +import 'echarts/lib/component/tooltip' + +// 注册组件后即可使用 +Vue.component('chart', ECharts) +``` + +## ⚠️ 注意事项 + +### 引入源码版本 + +如果你正在使用 vue-cli 来创建项目并且希望使用未经转译的组件(引入 `vue-echarts/components/ECharts` 而非直接引入 `vue-echarts`)来减小打包尺寸(是推荐用法),那么 Vue 的 `webpack` 模板可能会把 `node_modules` 中的文件排除在 Babel 转译范围以外。要解决此问题,需要按下述的方式修改 `build/webpack.base.conf.js`: + +对于 webpack 1.x: + +```diff + { + test: /\.js$/, + loader: 'babel', + include: [ +- path.join(projectRoot, 'src') ++ path.join(projectRoot, 'src'), ++ path.join(projectRoot, 'node_modules/vue-echarts') + ], +- exclude: /node_modules/ ++ exclude: /node_modules(?![\\/]vue-echarts[\\/])/ + }, +``` + +对于 webpack 2+: + +```diff + { + test: /\.js$/, + loader: 'babel-loader', +- include: [resolve('src'), resolve('test')] ++ include: [resolve('src'), resolve('test'), resolve('node_modules/vue-echarts')] + } +``` + +如果你正直接配置使用 webpack,那么也请做类似的修改使其能够正常工作。 + +### 在没有 ES Next 支持环境下用 npm 以 CommonJS 方式引入 + +```js +var Vue = require('vue') + +// 引入 UMD 模块 +var ECharts = require('vue-echarts') + +// 或者在使用 vue-loader 时可以直接引入源码版本,并且手动 +// 引入 ECharts 各个模块来减小打包尺寸 +var ECharts = require('vue-echarts/components/ECharts') +require('echarts/lib/chart/bar') +require('echarts/lib/component/tooltip') + +// 注册组件后即可使用 +Vue.component('chart', ECharts) +``` + +### AMD + +```js +require.config({ + paths: { + 'vue': 'path/to/vue', + 'vue-echarts': 'path/to/vue-ehcarts' + } +}) + +require(['vue', 'vue-echarts'], function (Vue, ECharts) { + // 注册组件后即可使用 + Vue.component('chart', ECharts) +}) +``` + +### 全局变量 + +组件将通过 `window.VueECharts` 变量暴露接口: + +```js +// 注册组件后即可使用 +Vue.component('chart', VueECharts) +``` + +## 调用组件 + +```vue + + + + + +``` + +查看[这里](https://github.com/Justineo/vue-echarts/tree/master/demo)了解更多例子。 + +### Props *(均为响应式)* + +* `initOptions` + + 用来初始化 ECharts 实例。 + +* `theme` + + 当前 ECharts 实例使用的主题。 + +* `options` + + ECharts 实例的数据。修改这个 prop 会触发 ECharts 实例的 `setOption` 方法。 + +* `group` + + 实例的分组,会自动绑定到 ECharts 组件的同名属性上。 + +* `auto-resize` (默认值:`false`) + + 这个 prop 用来指定 ECharts 实例在窗口尺寸变化时是否需要自动进行重绘。 + +* `watchShallow` (默认值:`false`) + + 这个 prop 可以用来关闭默认的对 `options` prop 的深度监听。对于有大量数据的图表,你可能会需要开启这个选项,来让 Vue 仅监听 `options` prop 本身的变化而忽略内部属性的变化。此时在需要重绘图表时,你需要重新设置 `options` prop 的直接引用,或者调用 `mergeOptions` 方法来手动管理图表内的数据(此时 `options` prop 的数据将不和图表内数据同步)。 + +### 计算属性 + +* `width` **[只读]** + + 用来获取 ECharts 实例的当前宽度。 + +* `height` **[只读]** + + 用来获取 ECharts 实例的当前高度。 + +* `computedOptions` **[只读]** + + 用来读取 ECharts 更新内部 `options` 后的实际数据。 + +### 方法 + +* `mergeOptions`(底层调用了 ECharts 实例的 `setOption` 方法) + + *提供了一个更贴切的名称来描述 `setOption` 方法的实际行为。* + +* `resize` +* `dispatchAction` +* `showLoading` +* `hideLoading` +* `convertToPixel` +* `convertFromPixel` +* `containPixel` +* `getDataURL` +* `getConnectedDataURL` +* `clear` +* `dispose` + +### 静态方法 + +* `connect` +* `disconnect` +* `registerMap` +* `registerTheme` + +### 事件 + +Vue-ECharts 支持如下事件: + +* `legendselectchanged` +* `legendselected` +* `legendunselected` +* `datazoom` +* `datarangeselected` +* `timelinechanged` +* `timelineplaychanged` +* `restore` +* `dataviewchanged` +* `magictypechanged` +* `geoselectchanged` +* `geoselected` +* `geounselected` +* `pieselectchanged` +* `pieselected` +* `pieunselected` +* `mapselectchanged` +* `mapselected` +* `mapunselected` +* `axisareaselected` +* `focusnodeadjacency` +* `unfocusnodeadjacency` +* `brush` +* `brushselected` +* 鼠标事件 + * `click` + * `dblclick` + * `mouseover` + * `mouseout` + * `mousedown` + * `mouseup` + * `globalout` + +更多详细信息请参考 [ECharts 的 API 文档](https://ecomfe.github.io/echarts-doc/public/cn/api.html)。 + +## 本地开发 + +```bash +$ npm i +$ npm run dev +``` + +打开 `http://localhost:8080/demo` 来查看 demo。