# 迁移 Weex 项目到 CML

# 迁移原则:

以小逻辑块为单位,对照老代码,以 cml 语法重写,报错可修正

这样可避免以下问题:

1、大块逻辑迁移会导致报错无法追查

2、直接 copy 会导致语法隐藏 bug 不可控(虽然 ide 没有问题,但真机调试出问题)

请尽量按照 cml 语法或者类 vue 语法重写迁移,避免语法纠错浪费时间

# 项目初始化

cml init project

初始化后,CML 项目如下:

依具体情况配置构建平台和配置平台基础样式。

可修改 chameleon.config.js 的 platforms 和 baseStyle 字段,如下:

假设有下面 👇 结构的 Weex 项目 weex-toolkit生成。

components下包含各个组件代码,router.js下是路由配置,config是 Weex 项目的 webpack 构建的基本配置

# 工程层面的迁移

# 迁移 —— webpack 配置

CML 的工程配置具体参考

# CML 命令行工具,提供了 dev build 两种构建模式,可以对应到 Weex 项目中的dev build
Weex 项目 CML 项目
npm run dev cml dev
npm run build cml build
# CML 内置了对于 webpack 和项目的构建,参考这里修改 CML 内置 webpack 构建

# 迁移 —— store

Weex 使用 Vuex 参考 Weex 官网

CML 中的 store 使用参考

CML 项目中的 store 和 Weex 项目中的 store 文件下是对应的。

假设 vue 项目中某个组件

import { mapState } from 'vuex';
export default {
  computed: mapState(['count']),
};

那么在 CML 项目中

import store from '../path/to/store';

class Index {
  computed = store.mapState(['count']);
}
export default new Index();

# 迁移 —— router

# router-view出口的对应关系

假如 Weex 项目中入口文件 src/index.vue

<template>
  <div id="app">
    <router-view />
  </div>
</template>

那么对应着 CML 项目中的src/app/app.cml,这里的<app>会渲染成<router-view>对应的某个路由;

<template>
  <app store="{{store}}" router-config="{{routerConfig}}"></app>
</template>
# 路由配置的对应关系

weex项目中的路由 src/router.js

import Vue from 'vue';
import Router from 'vue-router';
import HelloWorld from '@/components/HelloWorld';

Vue.use(Router);

export default new Router({
  routes: [
    {
      path: '/helloworld',
      name: 'HelloWorld',
      component: HelloWorld,
    },
  ],
});

cml项目src/router.config.json

{
  "mode": "history",
  "domain": "https://www.chameleon.com",
  "routes":[
    {
      "url": "/helloworld",
      "path": "/pages/HelloWorld/HelloWorld",
      "name": "helloworld",
      "mock": "index.php"
    }
  ]
}

其中:

url字段 对应 vue 中的path字段;

path字段对应 vue 中 import Comp from '/path/to/Comp'中的组件路径

chameleon 会自动引入 component 字段配置的组件,不需要再配置 component 字段;

总结

1 注意 CML 项目中不支持路由嵌套,如果有路由嵌套的情况需要考虑转化成组件去实现

2 在迁移路由的时候,要一个一个路由对应着去迁移

3 vue 项目中的一级路由的组件都通过 cml init page 去初始化这个组件

# 迁移页面/组件

假如 Weex 项目中 src/components/HelloWorld.vue组件内有个子组件 comp;

首先我们修改下这两个组件,使其有一些简单的新增 todolist 的功能

HelloWorld.vue

<template>
  <div class="demo-com">
    <div class="title">this is helloworld</div>
    <comp @parentClick="handleParentClick"></comp>
  </div>
</template>

<script>
import lodash from 'lodash';
import comp from './comp.vue';
export default {
  name: 'HelloWorld',
  data() {
    return {};
  },
  methods: {
    handleParentClick(...args) {
      console.log('parentClick', ...args);
    },
  },
  components: {
    comp,
  },
};
</script>

<!-- Add "scoped" attribute to limit CSS to this component only -->
<style scoped>
.demo-com {
  display: flex;
  flex-direction: column;
  align-items: center;
  height: 400px;
  justify-content: center;
}
.title {
  align-self: center;
  color: #61c7fc;
  font-size: 72px;
  margin-bottom: 20px;
}
</style>

注意:如果第三方仓库中的某些 API 依赖该平台的全局变量,那么这些 API 只能在该平台使用,在其他平台是无效的;

comp.vue

<template>
  <div>
    <input type="text" v-model="todo" />
    <div v-for="(item, index) in todos">
      {{ item }}
    </div>
    <div @click="addTodo">addTodo</div>
    <div @click="handleClick">触发父组件事件</div>
  </div>
</template>

<script>
export default {
  name: 'HelloWorld',
  data() {
    return {
      todo: 'todo1',
      todos: [],
    };
  },
  methods: {
    addTodo() {
      this.todos.push(this.todo);
    },
    handleClick() {
      console.log('click');
      this.$emit('parentClick', {
        value: 1,
      });
    },
  },
};
</script>

<!-- Add "scoped" attribute to limit CSS to this component only -->
<style scoped></style>

# 新建页面/组件

cml init page

输入 HelloWorld

利用命令行命令,在src/pages中生成对应的页面

<template>
  <view><text>HelloCML</text></view>
</template>

<script>
class HelloWorld {
  //...
}

export default new HelloWorld();
</script>

<style></style>

<script cml-type="json">
{
  "base": {
    "usingComponents": {}
  },
  "wx": {
    "navigationBarTitleText": "index",
    "backgroundTextStyle": "dark",
    "backgroundColor": "#E2E2E2"
  },
  "alipay": {
    "defaultTitle": "index",
    "pullRefresh": false,
    "allowsBounceVertical": "YES",
    "titleBarColor": "#ffffff"
  },
  "baidu": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "white",
    "navigationBarTitleText": "index",
    "backgroundColor": "#ffffff",
    "backgroundTextStyle": "dark",
    "enablePullDownRefresh": false,
    "onReachBottomDistance": 50
  }
}
</script>
cml init component
选择 Normal component
输入 comp

生成的组件如下

<template>
  <view><text>HelloCML</text></view>
</template>

<script>
class Comp {
  //...
}

export default new Comp();
</script>
<style></style>
<script cml-type="json">
{
  "base": {
    "usingComponents": {}
  }
}
</script>

# 迁移组件引用

假设 Weex 项目src/components/HelloWorld.vue中引用了其他组件 import comp from './comp.vue';

对应到 CML 项目 组件需要在 usingComponents 引用,不需要在配置 components字段

修改src/pages/HelloWorld/HelloWorld.cml 页面配置,如下:

<script cml-type="json">
{
  "base": {
    "usingComponents": {
      "comp":"/components/comp/comp"
    }
  }
}
</script>

总结:

1 router.js中对应的组件需要通过 cml init page生成,然后在 router.config.js中配置对应路由

2 组件内部引用的子组件要通过cml init component生成,然后通过 usingComponents字段去引用

3 组件内引用的其他 js 库,比如import lodash from 'lodash'仍然通过import的形式引用

# 页面&&组件迁移细节

# template 模板迁移

这里以 CML 的 Vue 语法为例:CML 类 Vue 基础语法

# 数据绑定、条件渲染、循环、事件绑定的迁移

假设,原有 vue 项目代码,如下:

<div class="scroller-wrap">
  数据绑定
  <div>{{}}</div>
  条件渲染
  <div v-if="condition1">v-if</div>
  <div v-else-if="condition2">v-else-if</div>
  <div v-else>v-else</div>
  循环
  <div v-for="(item ,index) in array"></div>
  事件绑定
  <div id="tapTest" @click="handleClick">Click me!</div>
</div>

那么,使用 CML 的类 Vue 语法后:整体基本上不用变,只需要将标签改成 CML 的内置标签即可。

<view class="scroller-wrap">
  数据绑定
  <view>{{}}</view>
  条件渲染
  <view v-if="condition">v-if</view>
  <view v-else-if="condition1">v-else-if</view>
  <view v-else>v-else</view>
  循环
  <view v-for="(item ,index) in array"></view>
  事件绑定
  <view id="tapTest" @click="handleClick">Click me!</view>
</view>

# CML 对于语法的扩展支持

# 指令的扩展 c-show、c-model、c-show参考
# component is 动态组件的扩展参考
# 事件绑定支持内联事件传参数参考

# Weex 的内置组件迁移

以下表格列出 Weex 的内置组件迁移到 CML 项目中的对应情况,不能在视图层用 Weex 端特有的组件,需要通过以下标签进行替换

除非是通过多态组件调用的下层组件才可以使用。

对于 Weex 内置的组件,CML 提供了大部分与之对应的可以跨端的组件。

Weex 内置组件 CML 备注
<div> <view> 支持跨多端
<text> <text> 支持跨多端
<image> <image> 支持跨多端
<list> <list> 支持跨多端
<cell> <cell> 支持跨多端
<loading> <c-loading> 支持跨多端
<scroller> <scroller> 支持跨多端
<slider> <carousel> 对于轮播图组件,chameleon 内置了carousel组件,如果想要用原生的slider,需要在多态组件中通过 origin-slider使用
<textarea> <textarea> 支持跨多端
<input> <input> 支持跨多端
<video> <video> 支持跨多端

chameleon 不支持的 Weex 内置组件

Weex 内置组件 在 CML 中的替换方式
<a> 可以通过给一个 text 标签绑定事件,通过 chameleon-api 提供的接口打开页面
<waterfall> 该组件不支持跨多端,仅可在多态组件中使用
<web> 该组件不支持跨端,仅可在多态组件中使用
<richtext> 该组件不支持跨端,仅可在多态组件中使用

根据以上教程,我们可以迁移HelloWorld.vuecomp.vue中的模板内容了

HelloWorld.cml

<template lang="vue">
  <view>
    <text>this is helloworld</text>
    <comp @parentClick="handleParentClick"></comp>
  </view>
</template>

comp.cml

<template lang='vue'>
  <view>
    <input type="text" v-model="todo" ></input>
    <div v-for="(item,index) in todos">
      {{item}}
    </div>
    <div @click="addTodo">addTodo</div>
    <view @click="handleClick"><text>触发父组件事件</text></view>
  </view>
</template>

# JS 内容迁移

# 生命周期迁移 :和 vue 保持一致

# 数据的迁移参考

# Weex 项目 API 的迁移

API 迁移包括 http 请求 路由跳转 本地存储等 参考:chameleon-api 的文档

# weex 内置模块的迁移

不能在逻辑层用 Weex 端特有的内置模块,需要通过以下chameleon-api提供的进行替换

除非是通过多态组件调用的下层组件才可以直接使用。

Weex CML 备注
animation chameleon-api 中的 createAnimation 参考
cliboard chameleon-api 中的 clipBoard 参考
dom chameleon-api 中的 getRect 参考
globalEvent 暂不支持
meta chameleon-api 中的 getSystemInfo 参考:可以通过这个 API 获取到视口的值然后给页面宽高赋值
modal chameleon-api 中的 showToast 参考
navigator chameleon-api 中的 路由导航 参考
picker 扩展组件中的 c-picker 参考
storage chameleon-api 中的数据存储 参考
stream chameleon-api 中的网络请求 参考
webview 暂不支持
websockets chameleon-api 中的 websockets 参考

# 事件的触发机制,映射如下:

vue 项目 cml
this.$emit(xxx,xxx) this.$cmlEmit(xxx,xxx)
# 事件对象参数

CML 对 web native wx 各个端的事件对象进行了统一代理参考

对于灰度区组件(多态组件)各个端的事件对象还是对应端的事件对象,CML 框架不会对灰度区origin-开头的标签和第三方组件标签上绑定的事件进行事件代理

CML 支持的类 Vue 语法,只有在文档中列出的语法才支持多端,其他没有列出的语法仅可以在 Web 端使用,跨端没有支持,比如 v-html class 的对象语法 数组语法等。

# 不支持的事件

longpress appear disappear 事件暂不支持

# 事件冒泡

chameleon 生成的 Weex 项目默认都是开启了支持事件冒泡的机制

同时扩展了阻止事件冒泡的语法;

vue 语法(仅仅支持 .stop)

<view @click.stop="handleClick"></view>

cml 语法

<view c-catch:click="handleClick"></view>

总结

1 由于 CML 是跨多端的框架,所以在 Weex 端特有的环境变量,比如weex.config等在 CML 中是不支持的

2 对于 Weex 的内置模块,比如 animation 等,在 chameleon-api 中基本上都有对应,参考上文 Weex 内置模块的迁移

根据以上教程,我们可以迁移HelloWorld.vuecomp.vue中的 js 内容了

HelloWorld.cml

<template lang="vue">
  <view>
    <text>this is helloworld</text>
    <comp @parentClick="handleParentClick"></comp>
  </view>
</template>

<script>
import lodash from 'lodash';
class HelloWorld {
  methods = {
    handleParentClick(...args) {
      console.log('parentClick', ...args);
    },
  };
}

export default new HelloWorld();
</script>

comp.cml

<script>
class Comp {
  data = {
    todo: 'todo1',
    todos: [],
  };

  methods = {
    addTodo() {
      this.todos.push(this.todo);
    },
    handleClick() {
      this.$cmlEmit('parentClick', {
        value: 1,
      });
    },
  };
}

export default new Comp();
</script>

# style 内容的迁移

weex 样式官方文档

# 页面布局的迁移

使用 flexbox进行样式布局

关于样式的使用教程参考

模板上的样式语法参考

Vue 样式语法规范参考

# 样式单位的迁移

如果样式想要适配多端,需要将单位改成cpx;

根据以上教程,我们可以迁移HelloWorld.vuecomp.vue中的 js 内容了

HelloWorld.cml

.demo-com { display: flex; flex-direction: column; align-items: center; height:400cpx;
justify-content: center; } .title { align-self: center; color: #61c7fc; font-size: 72cpx;
margin-bottom: 20cpx; }

#

以上,简单的介绍了 Weex 项目迁移到 CML 的步骤,如果还有任何疑问,欢迎随时在 CML 官方微信和官方 QQ 群里进行反馈,我们将随时解答你的困惑,再次感谢你对 CML 的支持~

​ Best wishes

​ CML 团队