kylinH5框架之项目组件理解

谁借莪１个温暖的怀抱￠ 2021-08-29 14:05 423阅读 0赞

**目录**

组件介绍

组件声明结构

组件接口

script

dependency

template

style

状态注入

接口声明

--------------------

## 组件介绍 ##

**Component** 扩充自 `Vue` 的组件, 提供了 `Vue` 组件对等的输入参数能力。在代码书写时提供类 `class` 的装饰器 `Decorator` 风格。

import { Component, Watch } from '@ali/kylin-framework';

一个组件可以包含数据、JSX 渲染函数、模板、挂载元素、方法、生命周期等 `Vue` 的 `options` 选项的对等配置。

### 组件声明结构 ###

组件声明包括以下几部分, 分别使用 `@Component` 和 `@Watch` 两种不同装饰器进行包装：

*  class 类声明, 使用装饰器 `@Component`。
 *  类成员声明, 不使用装饰器。
 *  类成员方法声明, 一般不装饰器, 除非该方法需要 `watch` 另外一个已声明的变量。

举例子

<template>
      <div>
        hello {
       {name}}
        <Child></Child>
      </div>
    </template>
    <style>
      /* put style here */
    </style>
    <component default="Child" src="./child.vue" />
    <script>
      import { Component } from '@ali/kylin-framework';
      @Component
      class Hello {
        data = {
          name: 'world'
        }
      }
      export default Hello;
    </script>

## 组件接口 ##

跟 vue 基本一致，组件定义写在 `.vue` 文件内，以下是一个简单的例子:

<template>
      <div>
        <AButton @click="onClick">点击</AButton>
      </div>
    </template>
    <style lang="less" rel="stylesheet/less">
        /* less */
    </style>
    <dependency component="{ AButton }" src="@alipay/antui-vue" lazy/>
    <script type="text/javascript">
      import { Component } from '@ali/kylin-framework';
      @Component
      export default class IndexView {
        props = {}
        data = {c:666}
        get comput() { return this.data.c * 2 }
        onClick() {}
        mounted() {}
      }
    </script>

上述例子中，**有`<template>`、`<style>`、`<script>、<dependency>`   4 个顶级标签**

其中 `<template>`、 `<style>` 与 `vue` 中定义一致。下文将对这 4 个标签的具体作用分别进行阐述。

### script ###

**1.class 结构**

定义一个 Component ，使用类 class 的装饰器 Decorator 风格。

其中装饰器有 `@Component` 和 `@Watch` 2 种，通过以下方式引入。

import { Component, Watch } from '@ali/kylin-framework';
    @Component
    export default class Hello {
    }

**2.方法类型**

**`@Component`**

**组件以 class 形式声明，必须对该 class 进行装饰器修饰。**

在 class 内部，不需要被手动处理`成员变量`，`babel` 插件在构建过程中自动进行处理。

而 `成员函数` 一般不需要装饰器挂载，除非是使用 `@Watch` 的场景,其中 `@Component` 会处理的属性如下表所示。

<table> 
 <thead> 
  <tr> 
   <th>成员类型</th> 
   <th>名称</th> 
   <th>功能</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><span style="color:#f33b45;"><strong>get/set </strong></span>property</td> 
   <td>*</td> 
   <td>用以转换成&nbsp;<code>Vue</code>&nbsp;的&nbsp;<span style="color:#f33b45;"><code>computed</code>&nbsp;计算属性</span>，可以直接通过&nbsp;<span style="color:#f33b45;"><code>this[varName]</code>&nbsp;调用</span>。</td> 
  </tr> 
  <tr> 
   <td>method</td> 
   <td>生命周期</td> 
   <td><strong><span style="color:#f33b45;">生命周期方法，与&nbsp;<code>Vue</code>&nbsp;对等。</span></strong></td> 
  </tr> 
  <tr> 
   <td>method</td> 
   <td>*</td> 
   <td>普通成员方法, 用以转换成<span style="color:#ffbb66;">&nbsp;<code>Vue</code>&nbsp;的&nbsp;<code>methods</code>&nbsp;</span>方法列表。</td> 
  </tr> 
 </tbody> 
</table>

分别举例：

**getter/setter属性**

@Component 
    export default class Hello {
      get computName() {
        // to sth
      }
    }

上述 `getter` 声明，等价于如下 vue 配置

HelloOption = {
      computed: {
        computName: {
          get: computName() {
            // to sth
          }
        }
      }
    }

**同理，`setter` 也会被提取，如果同时存在 `getter` 和 `setter` 则会被一起提取。**

**生命周期函数**

@Component 
    export default class Hello {
      created() {}
      mounted() {}
    }

上述 `created` 和 `mounted` 生命周期函数，会被提取为数组。

TestOption = {
      created: [function created(){}],
      mounted: [function mounted(){}],
    }

支持的生命周期方法名如下，**`beforeCreate`、`created`、`beforeMount`、`mounted`、`beforeUpdate`、`updated`、 `beforeDestroy`、`destroyed`。**

**Watch**

该装饰器的出现，只是因为 `watch` 需要有以下几个要素：

*  被监听的变量名
 *  监听选项
 *  触发函数

**用法**

完整的 `@Watch` 接口如下表所示。

function Watch( key: string [, option: Object = {} ] ): PropertyDecorator

<table> 
 <tbody> 
  <tr> 
   <th colspan="2">参数名</th> 
   <th>类型</th> 
   <th>用途</th> 
  </tr> 
  <tr> 
   <td colspan="2">key</td> 
   <td>string</td> 
   <td>监听的<span style="color:#f33b45;">参数名</span>，来自&nbsp;<code>computed</code>、<code>data</code>、<code>props</code>三者之一。</td> 
  </tr> 
  <tr> 
   <td>option</td> 
   <td>deep</td> 
   <td>boolean</td> 
   <td>若监听的是<span style="color:#f33b45;">复杂对象，其内层数据变更是否触发</span>，默认为&nbsp;<code>false</code>。</td> 
  </tr> 
  <tr> 
   <td>immediate</td> 
   <td>boolean</td> 
   <td><span style="color:#f33b45;">立即以表达式的当前值触发回调</span>，默认为&nbsp;<code>false</code></td> 
  </tr> 
 </tbody> 
</table>

**示例**

*  对于 `@Watch` 装饰的成员函数，支持对成员函数配置多个变量的监听，如下同时对 `a` 和 `c` 的变化进行了监听，如果任何一个发生变化，会触发 `OnChangeA` 成员方法。
 *  如下，`OnChangeA` 本质是成员方法，所以他也会和其他成员方法一起被提取到`methods`块中，那么必须保证没有与其他方法重名。
 *  如果对Watch有额外配置项，请按 `@Watch('a', {deep: false})`的方法传入。配置项请参考 [watch配置项][watch]。

@Component
    class WTest {
      data = {
        a: {
          b: 2
        },
        c: 3
      }
      @Watch('c')
      @Watch('a', {deep: true}) 
      OnChangeA(newVal, oldVal) {
      }
    }

**注意**: 以上对 `data.a` 的监听，会转换成如下形式，需要注意的是，如果没开启 `deep: true` 选项，当 `data.a.b` 发生变动的时候，不会触发该 `OnChangeA` 监听。

**3.属性类型**

构建工具会自动对成员变量应用了 `@Component.Property` 装饰器，不需要用户手动填写，

最终的合并策略取决于被装饰的 `成员变量` 的标识符名称，框架内置了以下几种。如果不在下表中，会透传至 `VueComponent` 的 `options` 对象中。

<table> 
 <thead> 
  <tr> 
   <th>成员类型</th> 
   <th>名称</th> 
   <th>功能</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>property</td> 
   <td><span style="color:#f33b45;"><strong>props</strong></span></td> 
   <td><span style="color:#f33b45;">vue的props属性</span></td> 
  </tr> 
  <tr> 
   <td>property</td> 
   <td><strong><span style="color:#f33b45;">data</span></strong></td> 
   <td><span style="color:#f33b45;">vue的data属性，<strong>会被转换成函数形式, 支持 this</strong>，请勿直接写&nbsp;<code>data(){}</code>&nbsp;函数</span></td> 
  </tr> 
  <tr> 
   <td>property</td> 
   <td>*</td> 
   <td>其他未知属性，直接复制到&nbsp;<code>Vue</code>&nbsp;的&nbsp;<code>options</code>&nbsp;中的对应属性上</td> 
  </tr> 
 </tbody> 
</table>

**props**

@Component 
    export default class Hello {
      props = {
        name: {
          type: String,
          default: 'haha'
        },
        num: Number
      }
    }

上述 `props` 成员变量定义，会被直接转换成到 `options` 中对应的 `props`。具体完整定义结构请参见 Vue 文档 [API-props][]。

HelloOption = {
      props: {
        name: {
          type: String,
          default: 'haha'
        },
        num: Number
      }
    }

**data**

@Component 
    export default class Hello {
      props = {
        name: {
          type: Number,
          default: 1
        },
      }
      data = {
        hello: this.props.name + 2
      }
    }

上述 `data` 成员变量定义，**会被转换成 data 函数形式**，您无需手动编写 data 函数。

TestOption = {
      props: {
        name: {
          type: Number,
          default: 1
        }, 
      },
      data: function data() {
        return {
          hello: this.props.name + 2
        }
      }
    }

### dependency ###

上述 `<script>` 定义中，没有说明组件依赖的使用方式，**在 `.vue` 文件中，推荐使用以下写法来标记组件依赖，即 `<dependency>` 标签**，下面示例中即引用了 `./child.vue` 组件。

标签属性

**default 导入**

针对 `ES6 Module` 的 `default` 导出或者 `commonjs Module` 对象的导出，可使用如下方式引入。

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><span style="color:#f33b45;">component</span></td> 
   <td>string</td> 
   <td>必填</td> 
   <td><span style="color:#f33b45;">引入到&nbsp;<code>options.components</code>&nbsp;的标识符名。</span></td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">src</span></td> 
   <td>string</td> 
   <td>必填</td> 
   <td><span style="color:#f33b45;">组件来源，同require(<code>src</code>)。</span></td> 
  </tr> 
  <tr> 
   <td>lazy</td> 
   <td>boolean</td> 
   <td>false</td> 
   <td>是否对该组件启用懒加载（当且仅当被&nbsp;<code>Vue</code>&nbsp;使用到时再进行&nbsp;<code>require</code>&nbsp;加载模块）。</td> 
  </tr> 
  <tr> 
   <td>style</td> 
   <td>string</td> 
   <td>undefined</td> 
   <td>默认不启用，如果设置了字符串，会根据&nbsp;<code>${src}/${style}</code>&nbsp;的路径来加载组件对应样式文件。</td> 
  </tr> 
 </tbody> 
</table>

如下示例:

**member 导入**

针对 `ES6 Module` 的命名导出，可使用如下方式引入：

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>component</td> 
   <td>string</td> 
   <td>必填</td> 
   <td>引入到&nbsp;<code>options.components</code>&nbsp;的多个命名标识符, 必须以花括号&nbsp;<code>{ </code>，<code>}</code>&nbsp;包括，否则会识别为&nbsp;<code>default 引入</code>。</td> 
  </tr> 
  <tr> 
   <td>src</td> 
   <td>string</td> 
   <td>必填</td> 
   <td>组件来源，同 require(<code>src</code>)。</td> 
  </tr> 
  <tr> 
   <td>lazy</td> 
   <td>boolean</td> 
   <td>false</td> 
   <td>是否对该组组件启用懒加载（当且仅当被&nbsp;<code>Vue</code>&nbsp;使用到时再进行&nbsp;<code>require</code>&nbsp;加载模块）。</td> 
  </tr> 
 </tbody> 
</table>

如下示例:

默认对 `@alipay/antui-vue` 组件库支持 `babel-plugin-import` 按需加载。

### template ###

模板的内容结构与 vue 一致。

<template>
      <div>Hello World</div>
    </template>

### style ###

可以通过添加 `scoped` 属性标记来使得该样式只对当前组件生效。

## 状态注入 ##

对于 Kylin 组件， 如果需要使用到 `Store` 中的属性，使用计算属性把 `$store` 对象中的属性透传出来是一种不推荐的写法，如下所示：

@Component 
    class Hello {
      // 通过计算属性来关联store中的状态
      get hello() {
        return this.$store.state.hello
      }
    }

推荐使用下面的 `connect` 机制来透传 `$store` 数据：

*  [mapStateToProps][]
 *  [mapActionsToMethods][mapStateToProps]
 *  [mapMethods][mapStateToProps]

### 接口声明 ###

@Component({
      mapStateToProps: Object|Array,
      mapActionsToMethods: Object|Array,
      mapMethods: Array|Boolean,
      mapEvents: Array
    })
    class Hello {
    }

mapStateToProps

把 `state` 中的特定键值映射到当前组件的 `props` 中，其接收参数等价于 `Vuex` 提供的 [`mapState` 辅助函数][mapState]。

有以下 3 种方式可实现上述功能：

**函数方式**

**说明**：把 `$store.state` 中名为 `bbb` 的数据，映射到名为 `aaa` 的 `props` 上。

{
      mapStateToProps: {
        aaa: (state, getters) => state.bbb
      }
    }

**字符串键值对方式**

**说明**：把 `$store.state` 中名为 `bbb` 的数据，映射到名为 `aaa` 的 `props` 上。

{
      mapStateToProps: {
        aaa: 'bbb'
      }
    }

**字符串数组方式**

**说明**：

*  把 `$store.state` 中名为 `aaa` 的数据，映射到名为 `aaa` 的 `props` 上。
 *  把 `$store.state` 中的名为 `bbb` 的数据，映射到名为 `bbb` 的`props` 上。

{
      mapStateToProps: ['aaa', 'bbb']
    }

mapActionsToMethods

与 `Vuex` 中 `mapActions` 入参一致，支持使用对象方式（名称映射）、数组方式（名称）把在全局 `$store` 下配置的 `actions` 注入到当前组件的 `methods` 中。

@Component({
      mapActionsToMethods: ['a', 'b']
    })
    class IndexView {
      async doSomeAction() {
        const ret = await this.a(123);
        // 等价于调用
        // const ret = await this.$store.dispatch('a', 123);
      }
    }

mapMethods

**通过在父子组件之间加一层中间层组件的方式来具体实现 `connect` 机制。**当父组件调用子组件中特定的 `method` 方法时，无法直接访问子组件（实际访问到的是中间层组件），需要通过以下配置实现访问。

@Component({
      mapMethods: true
    })
    export default class Child {
      a() {}
    }

<template>
      <div>
        this is parent
        <child ref="child"></child>
      </div>
    </template>
    <script>
      @Component
      export default class Parent {
        b() {
          // 此处可以访问
          this.$refs.child.a();
        }
      }
    </script>

吐槽：学这个麒麟框架真的像中了佐二助大招雷遁麒麟一样难受(╯﹏╰)

![format_png][]

[watch]: https://cn.vuejs.org/v2/api/index.html?spm=a2c4g.11186623.2.15.34af3b14kz1dpg#vm-watch
[API-props]: https://cn.vuejs.org/v2/api/?spm=a2c4g.11186623.2.16.34af3b14kz1dpg#props
[mapStateToProps]: https://help.aliyun.com/document_detail/72599.html?spm=a2c4g.11186623.6.1343.442c4c07RpqEV5#mapStateToProps
[mapState]: https://vuex.vuejs.org/zh-cn/state.html#mapstate-%E8%BE%85%E5%8A%A9%E5%87%BD%E6%95%B0
[format_png]: /images/20210813/707593e97ac1412aad2b10d110cc2043.png