手把手教你系列- 实现多态 echart

背景介绍

正常情况下大部分功能可以用CML语法即可实现；常常会有特殊情况：

  • 当我们想实现一个特别复杂功能时常常会用到成熟的第三方库
  • 当产品经理需要各端差异化实现需求
  • 类似“分享到朋友圈”功能在小程序、Web、Native天生有底层能力差异
    我们这里举例实现一个柱状图图表一般会想到很强大的开源可视化库 echart。

本文讲讲如何在CML项目中优雅的使用echart库,最终效果图如下：

多态组件扩展 - 图1

在CML项目中使用第三方库可以基于多态组件来开发。

多态组件扩展 - 图2多态协议的意义我就不做赘述了，直接说怎么使用。

项目初始化

新建一个项目 demo-poly

  1. cml init project

在项目中调用组件创建命令：

  1. cd demo-poly
  2. cml init component

  • 切换选择Polymorphic component

  • 输入echart

多态组件扩展 - 图3

此时项目中看到./src/components/echart文件夹

  1. ./src/components
  2. └── echart
  3.     ├── echart.interface
  4.     ├── echart.web.cml
  5.     ├── echart.weex.cml
  6.     └── echart.wx.cml

修改src/pages/index/index.cml文件里面的json配置，引用多态组件

  1.   "base": {
  2.     "usingComponents": {
  3.       "echart": "/components/echart/echart",
  4.       "demo-com": "/components/demo-com/demo-com"
  5.     }
  6.   }

修改src/pages/index/index.cml文件里面的组件template模板，调用echart组件

  1. <template>
  2.   <page title="chameleon">
  3.         <view class="scroller-wrap">
  4.           <demo-com title="{{title}}" image-src="{{chameleonSrc}}"></demo-com>
  5.           <echart class="echart" name="hi"></echart>
  6.         </view>
  7.   </page>
  8. </template>

修改style标签代码给<echart>标签添加宽高

  1. .scroller-wrap {
  2.   display: flex;
  3.   flex-direction: column;
  4.   align-items: center;
  5. }
  6. .echart{
  7.   display:flex;
  8.   flex-direction:row;
  9.   justify-content: center;
  10.   height: 500px;
  11.   width: 500px;
  12. }

在项目根目录下启动预览cml dev，有效果如下，展现2个组件分别是默认项目初始化放置的<demo-com>和我们刚刚添加的<echart>组件。echart作为多态组件，在web、weex、微信小程序分别展示的是不同文案。

web端效果如下：

多态组件扩展 - 图4

多态组件构成介绍

echart.interface：描述echart组件的输入和输出。

默认interface定义了一个组件，参数name的值是一个字符串，事件onshow的值是一个函数，函数的回调是一个Object结构为{value: 字符串}。

  1. <script cml-type="interface">
  2. /*
  3. 定义一个inteface用于描述组件的属性和事件
  4. 1、 如何区分组件属性和事件？
  5. 通过类型来区分，事件为函数类型，属性为非函数类型
  6. 2、 如何定义组件属性
  7. 给interface添加同名的属性即可，指定类型
  8. 3、 如何定义组件事件
  9. 以事件名称为key值给interface定义属性，该属性是一个函数类型，返回值为void，
  10. 定义函数的第一个参数为自定义事件传递的detail对象类型
  11. */
  13. //定义事件detail对象的参数
  14. type EventDetail = {
  15.   value: String 
  16. }
  17. interface EchartInterface {
  18.   name: String,
  19.   onshow(eventDetail: EventDetail): void;
  20. }
  21. </script>

其中的具体语法参见。这里我们先不用改。

echart.web.cml、echart.weex.cml、echart.wx.cml：文件是灰度区，它是唯一可以调用下层端组件的CML文件，分别是web、weex、wx三个端的调用入口。建议这一块代码尽量薄，只是用来调用下层端代码，不要编写过于重的代码。

  • 在灰度区的template模板中：可以调用下层组件，传入的属性也可以是各自下层端的语法，绑定的函数回调事件对象也是原始对象。也可以正常使用普通的cml模板语法

  • 在灰度区的script逻辑代码中：可以调用下层端的全局变量和任意方法，以及下层段的生命周期。也可以正常使用普通cml逻辑代码。

  • 在灰度区的style样式代码中：可以使用下层端css语法。也可以正常调用cmss语法。

实现微信echart

我们先修改./src/components/echart/echart.wx.cml实现微信的 echart 功能。Google搜索到了echarts-for-weixin，我们看该项目的使用文档，我们把该项目下的ec-canvas文件夹拷贝到./src/components/echart文件夹下

  1. ./src/components
  2. └── echart
  3.     ├── ec-canvas
  4.     │   ├── ec-canvas.js
  5.     │   ├── ec-canvas.json
  6.     │   ├── ec-canvas.wxml
  7.     │   ├── ec-canvas.wxss
  8.     │   ├── echarts.js
  9.     │   └── wx-canvas.js
  10.     ├── echart.interface
  11.     ├── echart.web.cml
  12.     ├── echart.weex.cml
  13.     └── echart.wx.cml

修改./src/components/echart/echart.wx.cml文件里面的json配置，引用微信组件

  1.   "base": {
  2.     "usingComponents": {
  3.       "ec-canvas": "./ec-canvas/ec-canvas"
  4.     }
  5.   }

修改cml模板，调用组件

  1. <template>
  2. <view class="container">
  3.   <ec-canvas class="mychart_dom_bar" canvas-id="mychartbar" ec="{{ ec }}"></ec-canvas>
  4. </view>
  5. </template>

新建./src/components/echart/bar.js，作为统一存放echart图表的配置代码，代码如下：

  1. export default function getdata () {
  2.   var option = {
  4.     tooltip: {},
  6.     xAxis: {
  7.         data: ["衬衫","羊毛衫","雪纺衫"]
  8.     },
  9.     yAxis: {},
  10.     series: [{
  11.         name: '销量',
  12.         type: 'bar',
  13.         data: [5, 20, 36]
  14.     }]
  15.   };
  16.   return option;
  17. }

修改./src/components/echart/echart.wx.cml文件里面的JS代码，编写传递给组件的参数

  1. import * as echarts from './ec-canvas/echarts';
  3. let chart = null;
  4. import getBar from './bar'
  5. function initChart(canvas, width, height) {
  6.   chart = echarts.init(canvas, null, {
  7.     width: width,
  8.     height: height
  9.   });
  10.   canvas.setChart(chart);
  11.   chart.setOption(getBar());
  12.   return chart;
  13. }
  16. class Echart implements EchartInterface {
  17.   props = {
  18.     name: {
  19.       type: String,
  20.       default: '默认值'
  21.     }
  22.   }
  24.   data = { 
  25.     ec: {
  26.       onInit: initChart
  27.     }
  28.   }
  30.   computed = {
  31.   }
  33.   watch = {
  34.   }
  36.   methods = {
  37.   }
  39.   beforeCreate() {
  40.   }
  42.   created() {
  43.   }
  45.   beforeMount() {
  46.   }
  48.   mounted() {
  49.     this.$cmlEmit('onshow',{
  50.       value: this.name
  51.     })
  52.   }
  54.   beforeDestroy() {
  55.   }
  57.   destroyed() {
  58.   }
  59. }
  61. export default new Echart();

修改./src/components/echart/echart.wx.cml文件里面的style代码，设置宽高

  1. .mychart_dom_bar,
  2. .container{
  3.   height: 750cpx;
  4.   width: 750cpx;
  5. }

此时能看到微信能展现图表了

多态组件扩展 - 图5

实现web端echart

web端使用vue框架，所以找到echart的vue版本 vue-echarts，按他说明文档，直接在chameleon项目根目录demo-poly(我创建的project名)下安装组件

  1. npm install echarts vue-echarts --save

打开src/components/echart/echart.web.cml修改json标签配置，引用组件

  1. {
  2.   "base": {
  3.     "usingComponents": {
  4.       "chart": "vue-echarts/components/ECharts"
  5.     }
  6.   }
  7. }

修改cml模板，调用组件

  1. <template>
  2.   <view class="container">
  3.       <chart class="mychart_dom_bar"
  4.         :options="bar"
  5.         :init-options="initOptions"
  6.         ref="bar"
  7.         theme="ovilia-green"
  8.         auto-resize
  9.       />
  10.   </view>
  11. </template>

修改script，设置传入chart组件的参数

  1. import 'echarts/lib/chart/bar'
  2. import getBar from './bar'
  3. class Echart implements EchartInterface {
  4.   props = {
  5.     name: {
  6.       type: String,
  7.       default: '默认值'
  8.     }
  9.   }
  11.   data = {
  12.       bar: getBar(),
  13.       initOptions: {
  14.         renderer: 'canvas'
  15.       }
  16.   }
  18.   computed = {
  19.   }
  21.   watch = {
  22.   }
  24.   methods = {
  25.   }
  27.   beforeCreate() {
  28.   }
  30.   created() {
  31.   }
  33.   beforeMount() {
  34.   }
  36.   mounted() {
  37.     this.$cmlEmit('onshow',{
  38.       value: this.name
  39.     })
  40.   }
  42.   beforeDestroy() {
  43.   }
  45.   destroyed() {
  46.   }
  47. }
  49. export default new Echart();

此时web端也能看到图表效果了

多态组件扩展 - 图6

实现native weex端echart

weex不支持canvas接口，所以无法在weex环境下运行，我们可以用weex的web组件

需要注意点就是 weex的 web组件是用于展示一个页面的

所以，我们需要新建一个页面用于展示 echarts 

  1. cml init page 
  4. 然后输入页面名称
  6. weex-echarts

然后在 ./src/pages/weex-echarts/weex-echarts.cml中写入图表这个页面的内容

  1. <template>
  2.   <page title="chameleon">
  3.       <scroller height="{{-1}}">
  4.         <view class="scroller-wrap">
  5.           <echart class="echart" name="hi"></echart>
  6.         </view>
  7.       </scroller>
  8.   </page>
  9. </template>
  11. <script>
  13. class Index  {
  14.   data = {
  15.   }
  16. }
  18. export default new Index();
  20. </script>
  21. <style>
  23. .scroller-wrap {
  24.   display: flex;
  25.   flex-direction: column;
  26.   align-items: center;
  27. }
  28. .echart{
  29.   display:flex;
  30.   flex-direction:row;
  31.   justify-content: center;
  32.   height: 500px;
  33.   width: 500px;
  34. }
  35. </style>
  36. <script cml-type="json">
  37. {
  38.   "base": {
  39.     "usingComponents": {
  40.       "echart": "/components/echart/echart",
  41.     }
  42.   },
  43.   "wx": {
  44.     "navigationBarTitleText": "index",
  45.     "backgroundTextStyle": "dark",
  46.     "backgroundColor": "#E2E2E2"
  47.   }
  48. }
  49. </script>

在./src/components/echart/echart.weex.cml里面修改

  1. <template>
  2.    <web :src="h5url"
  3.       @pagestart="onPageStart" @pagefinish="onPageFinish" @error="onError" @receivedtitle="onReceivedTitle"></web>
  4. </template>
  6. <script>
  8. class Echart implements EchartInterface {
  9.   props = {
  10.     name: {
  11.       type: String,
  12.       default: '默认值'
  13.     }
  14.   }
  15.   data = {
  16.     pagestart: '',
  17.       pagefinish: '',
  18.       title: '',
  19.       error: '',
  20.       canGoBack: false,
  21.       canGoForward: false,
  22.       //这是作者的本机IP,cml/h5/weex-echarts 这个页面只有echarts图表
  23.       h5url: 'http://172.22.137.224:8000/cml/h5/weex-echarts'
  24.   }
  25.   methods = {
  26.     onPageStart: function(e) {
  27.         this.pagestart = e.url;
  28.       },
  29.       onPageFinish: function(e) {
  30.         this.pagefinish = e.url;
  31.         this.canGoBack = e.canGoBack;
  32.         this.canGoForward = e.canGoForward;
  33.         if (e.title) {
  34.           this.title = e.title;
  35.         }
  36.       },
  37.       onError: function(e) {
  38.         this.error = url;
  39.       },
  40.       onReceivedTitle: function(e) {
  41.         this.title = e.title;
  42.       }
  43.   }
  44.   mounted() {
  45.     this.$cmlEmit('onshow',{
  46.       value: this.name
  47.     })
  48.   }
  49. }
  51. export default new Echart();
  52. </script>
  54. <style >
  55. .mychart_dom_bar{
  56.   height: 500cpx;
  57.   width: 750cpx;
  58. }
  59. .container{
  60.   height: 500cpx;
  61.   width: 750cpx;
  62. }
  63. </style>
  65. <script cml-type="json">
  66. {
  67.   "base": {
  68.     "usingComponents": {
  69.     }
  70.   }
  71. }
  72. </script>

此时weex端也能看到图表效果了

多态组件扩展 - 图7

最后

  • 同时如果有更多配置参数需要由调用方index.cml传入时，可以再echart.interface中定义更多输入输出的参数，保障各端一致。

  • 基于多态协议开发各端上实现差异较大的一类组件，调用上抹平了差异，同时我们可以各自维护，修改其中一端代码时，不会影响其他端的代码，做到充分隔离。

  • 后期我们可以把这 src/components/echart 单独发布成一个npm包，单拉出来维护