组件

cml 项目一切皆组件。组件(Component)是视图的基本组成单元。

框架为开发者提供了一系列基础组件，开发者可以通过组合这些基础组件进行快速开发。

如：

<template>
  <view>
    <view>view 基础组件</view>
    <text>text 基础组件</text>
  </view>
</template>

同时，cml 支持简洁的组件化编程。

自定义组件

开发者可以将页面内的功能模块抽象成自定义组件，以便在不同的页面中重复使用。自定义组件在使用时与基础组件非常相似。

如何创建自定义组件

小程序创建自定义组件

代码示例：

Component({
  properties: {
    // 这里定义了innerText属性，属性值可以在组件使用时指定
    innerText: {
      type: String,
      value: "default value"
    }
  },
  data: {
    // 这里是一些组件内部数据
    someData: {}
  },
  methods: {
    // 这里是一个自定义方法
    customMethod() {}
  }
});

cml 创建自定义组件

示例代码

<script>
  class MyComponent {
    props = {
      // 这里定义了innerText属性，属性值可以在组件使用时指定
      innerText: {
        type: String,
        value: "default value"
      }
    };
    data = {
      // 这里是一些组件内部数据
      someData: {}
    };
    methods = {
      // 这里是一个自定义方法
      customMethod() {}
    };
    computed = {};
    watch = {};
  }
  export default new MyComponent();
</script>

如何使用自定义组件

使用已注册的自定义组件前，首先要进行引用声明。此时需要提供每个自定义组件的标签名和对应的自定义组件文件路径。

小程序使用自定义组件

代码示例：

在 page.json 中进行引用声明

{
  "usingComponents": {
    "component-tag-name": "path/to/the/custom/component"
  }
}

在 page.wxml 中使用

<view>
  <!-- 以下是对一个自定义组件的引用 -->
  <component-tag-name inner-text="Some text"></component-tag-name>
</view>

cml 使用自定义组件

代码示例：

在 page.cml中<script cml-type='json' />进行引用声明

<script cml-type="json">
  {
    "base": {
        "usingComponents": {
          "component-tag-name": "path/to/the/custom/component"
        }
    }
  }
</script>

在 page.cml中<template />使用

<template>
  <view>
    <!-- 以下是对一个自定义组件的引用 -->
    <component-tag-name inner-text="Some text"></component-tag-name>
  </view>
</template>

如何实现父子组件事件通信

事件系统是组件间通信的主要方式之一。自定义组件可以触发任意的事件，引用组件的页面可以监听这些事件。

小程序组件通信

代码示例：

<!-- 页面 page.wxml -->
<view>
  <my-component bindcustomevent="onMyEvent"></my-component>
</view>

// 页面 page.js
Page({
  methods: {
    onMyEvent(e) {
      console.log(e.detail); // 自定义组件触发事件时提供的detail对象
    }
  }
});

<!-- 组件 my-component.wxml -->
<view>
  <button bindtap="onTap">点击这个按钮将触发“myevent”事件</button>
</view>

// 组件 my-component.js
Component({
  methods: {
    onTap() {
      this.triggerEvent("customevent", {}); // 触发 自定义组件事件
    }
  }
});

cml 组件通信

代码示例：

<!-- 页面 page.cml -->
<template>
  <view>
    <my-component c-bind:customevent="onMyEvent"></my-component>
  </view>
</template>
<script>
  class Index {
    methods = {
      // 这里是一个自定义方法
      onMyEvent(e) {
        console.log(e.detail); // 自定义组件触发事件时提供的detail对象
      }
    };
  }
  export default new Index();
</script>
<script cml-type="json">
  {
    "base": {
        "usingComponents": {
          "my-component": "path/to/the/custom/component"
        }
    }
  }
</script>

<!-- 页面 path/to/the/custom/component.cml -->
<template>
  <view>
    <button c-bind:tap="onTap">点击这个按钮将触发“myevent”事件</button>
  </view>
</template>
<script>
  class MyComponent {
    methods = {
      // 这里是一个自定义方法
      onTap() {
        this.$cmlEmit("customevent", {}); // 触发 自定义组件事件
      }
    };
  }
  export default new MyComponent();
</script>
<script cml-type="json">
  {
  }
</script>

组件使用总结

和小程序一样，cml框架 提供了大量内置组件和扩展组件，抹平多端差异，便于开发者通过组合这些组件，创建出强大的应用程序。

扩展组件需要额外引入。如：

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

在执行 cml build 构建打包时，cml 框架 会按需打包引用的内置组件和扩展组件，为代码瘦身。

内置组件和扩展组件 都是支持跨多端的，对于一些没有提供的某个端的组件，可以通过组件多态来实现。

如果希望使用小程序端的原生组件，那么可以在原生标签前加上 origin-*，cml框架会渲染原生组件参考

注意：origin-* 只能在灰度区文件中使用！！

如在 map.wx.cml 文件中使用原生地图组件 <map/>：

<!-- map.wx.cml -->
<template>
  <origin-map
    id="map"
    longitude="113.324520"
    latitude="23.099994"
    controls="{{controls}}"
    bindcontroltap="controltap"
    style="width: 100%; height: 300px;"
  ></origin-map>
</template>