1# 自定义组件的基本用法
2
3自定义组件是用户根据业务需求，将已有的组件组合，封装成的新组件，可以在工程中多次调用，从而提高代码的可读性。自定义组件通过element引入到宿主页面，使用方法如下：
4
5```html
6<element name='comp' src='../common/component/comp.hml'></element>
7<div>
8  <comp prop1='xxxx' @child1="bindParentVmMethod"></comp>
9</div>
10```
11
12结合if-else使用自定义组件的示例，showComp1为true时显示自定义组件comp1，否则显示comp2：
13
14```html
15<element name='comp1' src='../common/component/comp1/comp1.hml'></element>
16<element name='comp2' src='../common/component/comp2/comp2.hml'></element>
17<div>
18  <comp1 if="{{showComp1}}" prop1='xxxx' @child1="bindParentVmMethodOne"></comp1>
19  <comp2 else prop1='xxxx' @child1="bindParentVmMethodTwo"></comp2>
20</div>
21```
22
23自定义组件的name属性指自定义组件名称(非必填)，组件名称对大小写不敏感，默认使用小写。src属性指自定义组件hml文件路径(必填)，若没有设置name属性，则默认使用hml文件名作为组件名。
24
25
26## 自定义事件
27
28父组件中绑定自定义子组件的事件使用(on|@)event-name="bindParentVmMethod"语法，子组件中通过this.$emit('eventName', { params: '传递参数' })触发事件并向上传递参数，父组件执行bindParentVmMethod方法并接收子组件传递的参数。
29
30>  **说明：**
31>
32>  子组件中使用驼峰命名法命名的事件，在父组件中绑定时需要使用短横线分隔命名形式，例如：\@children-event表示绑定子组件的childrenEvent事件。
33
34**示例1：无参数传递**
35
36子组件comp定义如下：
37
38```html
39<!-- comp.hml -->
40<div class="item">
41   <text class="text-style" onclick="childClicked">点击这里查看隐藏文本</text>
42   <text class="text-style" if="{{showObj}}">hello world</text>
43</div>
44```
45
46```css
47/* comp.css */
48.item {
49  width: 700px;
50  flex-direction: column;
51  height: 300px;
52  align-items: center;
53  margin-top: 100px;
54}
55.text-style {
56  font-weight: 500;
57  font-family: Courier;
58  font-size: 40px;
59}
60```
61
62```js
63// comp.js
64export default {
65  data: {
66    showObj: false,
67  },
68  childClicked () {
69    this.$emit('eventType1');
70    this.showObj = !this.showObj;
71  },
72}
73```
74
75引入子组件comp的父组件示例如下：
76
77```html
78<!-- xxx.hml -->
79<element name='comp' src='../common/component/comp.hml'></element>
80<div class="container">
81  <comp @event-type1="textClicked"></comp>
82</div>
83```
84
85```css
86/* xxx.css */
87.container {
88  background-color: #f8f8ff;
89  flex: 1;
90  flex-direction: column;
91  align-content: center;
92}
93```
94
95```js
96// xxx.js
97export default {
98  textClicked () {}
99}
100```
101
102**示例2：有参数传递**
103
104子组件comp定义如下：
105
106```html
107<!-- comp.hml -->
108<div class="item">
109   <text class="text-style" onclick="childClicked">点击这里查看隐藏文本</text>
110   <text class="text-style" if="{{ showObj }}">hello world</text>
111</div>
112```
113
114```js
115// comp.js
116export default {
117  childClicked () {
118    this.$emit('eventType1', { text: '收到子组件参数' });
119    this.showObj = !this.showObj;
120  },
121}
122```
123
124子组件向上传递参数text，父组件接收时通过e.detail来获取该参数：
125
126```html
127<!-- xxx.hml -->
128<element name='comp' src='../common/comp/comp.hml'></element>
129<div class="container">
130   <text>父组件：{{text}}</text>
131   <comp @event-type1="textClicked"></comp>
132</div>
133```
134
135```js
136// xxx.js
137export default {
138  data: {
139    text: '开始',
140  },
141  textClicked (e) {
142    this.text = e.detail.text;
143  },
144}
145```
146
147![EventParameters](figures/EventParameters.gif)
148
149
150## 自定义组件数据
151
152
153自定义组件的js文件中可以通过声明data、props、computed等字段完成数据的定义、传递与处理，其中props与computed的具体使用请参考[数据传递与处理](js-components-custom-props.md)章节。
154
155**表1** 自定义组件数据
156
157| 名称      | 类型            | 描述                                     |
158| -------- | --------------- | ---------------------------------------- |
159| data     | Object&nbsp;\|&nbsp;Function | 页面的数据模型，类型是对象或者函数，如果类型是函数，返回值必须是对象。属性名不能以$或_开头，不要使用保留字for,&nbsp;if,&nbsp;show,&nbsp;tid。<br/>data与private和public不能重合使用。 |
160| props    | Array&nbsp;\|&nbsp;Object    | props用于组件之间的数据通信，可以通过&lt;tag&nbsp;xxxx='value'&gt;方式传递给组件；props名称必须用小写，不能以$或_开头，不要使用保留字for,&nbsp;if,&nbsp;show,&nbsp;tid。目前props的数据类型不支持Function。 |
161| computed | Object          | 计算属性，用于在读取或设置参数时，进行预先处理，其结果会被缓存。计算属性名不能以$或_开头，不要使用保留字。 |