1# HML语法参考
2
3
4HML是一套类HTML的标记语言，通过组件，事件构建出页面的内容。页面具备数据绑定、事件绑定、列表渲染、条件渲染等高级能力。
5
6
7## 页面结构
8
9
10```html
11<!-- xxx.hml -->
12<div class="item-container">
13  <text class="item-title">Image Show</text>
14  <div class="item-content">
15    <image src="/common/xxx.png" class="image"></image>
16  </div>
17</div>
18```
19
20
21## 数据绑定
22
23
24```html
25<!-- xxx.hml -->
26<div onclick="changeText">
27  <text> {{content[1]}} </text>
28</div>
29```
30
31
32```js
33// xxx.js
34export default {
35  data: {
36    content: ['Hello World!', 'Welcome to my world!']
37  },
38  changeText: function() {
39    this.content.splice(1, 1, this.content[0]);
40  }
41}
42```
43
44>  **说明：**
45>  - 针对数组内的数据修改，请使用splice方法生效数据绑定变更。
46>
47>  - hml中的js表达式不支持ES6语法。
48
49
50## 事件绑定
51
52事件绑定的回调函数接收一个事件对象参数，可以通过访问该事件对象获取事件信息。
53
54
55```html
56<!-- xxx.hml -->
57<div>
58  <!-- 通过'@'绑定事件 -->
59  <div @click="clickfunc"></div>
60  <!-- 通过'on'绑定事件  -->
61  <div onclick="clickfunc"></div>
62  <!-- 通过'on'绑定事件，不推荐使用5+ -->
63  <div onclick="clickfunc"></div>
64  <!-- 使用事件冒泡模式绑定事件回调函数。5+ -->
65  <div on:click.bubble="clickfunc"></div>
66  <!-- on:{event}等价于on:{event}.bubble。5+ -->
67  <div on:click="clickfunc"></div>
68  <!-- 绑定事件回调函数，但阻止事件向上传递。5+ -->
69  <div grab:click.bubble="clickfunc"></div>
70  <!-- grab:{event}等价于grab:{event}.bubble。5+ -->
71  <div grab:click="clickfunc"></div>
72</div>
73```
74
75
76```js
77// xxx.js
78export default {
79  data: {
80    obj: '',
81  },
82  clickfunc: function(e) {
83    this.obj = 'Hello World';
84    console.log(e);
85  },
86}
87```
88
89>  **说明：**
90>
91>  事件冒泡机制从API Version 5开始支持。升级SDK后，运行存量JS应用，采用旧写法（onclick）的事件绑定还是按事件不冒泡进行处理。但如果使用新版本SDK重新打包JS应用，将旧写法按事件冒泡进行处理。为了避免业务逻辑错误，建议将旧写法（如onclick）改成新写法（grab:click）。
92
93**示例：**
94
95```html
96<!-- xxx.hml -->
97<div class="container">
98  <text class="title">{{count}}</text>
99  <div class="box">
100    <input type="button" class="btn" value="increase" onclick="increase" />
101    <input type="button" class="btn" value="decrease" @click="decrease" />
102    <!-- 传递额外参数 -->
103    <input type="button" class="btn" value="double" @click="multiply(2)" />
104    <input type="button" class="btn" value="decuple" @click="multiply(10)" />
105    <input type="button" class="btn" value="square" @click="multiply(count)" />
106  </div>
107</div>
108```
109
110
111```js
112// xxx.js
113export default {
114  data: {
115    count: 0
116  },
117  increase() {
118    this.count++;
119  },
120  decrease() {
121    this.count--;
122  },
123  multiply(multiplier) {
124    this.count = multiplier * this.count;
125  }
126};
127```
128
129
130```css
131/* xxx.css */
132.container {
133    display: flex;
134    flex-direction: column;
135    justify-content: center;
136    align-items: center;
137    left: 0px;
138    top: 0px;
139    width: 454px;
140    height: 454px;
141}
142.title {
143    font-size: 30px;
144    text-align: center;
145    width: 200px;
146    height: 100px;
147}
148.box {
149    width: 454px;
150    height: 200px;
151    justify-content: center;
152    align-items: center;
153    flex-wrap: wrap;
154}
155.btn {
156    width: 200px;
157    border-radius: 0;
158    margin-top: 10px;
159    margin-left: 10px;
160}
161```
162
163
164## 列表渲染
165
166
167```html
168<!-- xxx.hml -->
169<div class="array-container">
170    <!-- div列表渲染 -->
171    <!-- 默认$item代表数组中的元素, $idx代表数组中的元素索引 -->
172    <div class="item-container" for="{{array}}" tid="id" onclick="changeText">
173        <text>{{$idx}}.{{$item.name}}</text>
174    </div>
175    <!-- 自定义元素变量名称 -->
176    <div class="item-container" for="{{value in array}}" tid="id" onclick="changeText">
177        <text>{{$idx}}.{{value.name}}</text>
178    </div>
179    <!-- 自定义元素变量、索引名称 -->
180    <div class="item-container" for="{{(index, value) in array}}" tid="id" onclick="changeText">
181        <text>{{index}}.{{value.name}}</text>
182    </div>
183</div>
184```
185
186
187```js
188// xxx.js
189export default {
190  data: {
191    array: [
192      {id: 1, name: 'jack', age: 18},
193      {id: 2, name: 'tony', age: 18},
194    ],
195  },
196  changeText: function() {
197    if (this.array[1].name === "tony"){
198      this.array.splice(1, 1, {id:2, name: 'Isabella', age: 18});
199    } else {
200      this.array.splice(2, 1, {id:3, name: 'Bary', age: 18});
201    }
202  },
203}
204```
205
206
207```css
208.array-container {
209    width: 100%;
210    height: 100%;
211    justify-content: center;
212    align-items: center;
213    flex-direction: column;
214}
215
216.item-container {
217    margin-top: 10px;
218    width: 200px;
219    height: 50px;
220    flex-direction: column;
221}
222```
223
224
225tid属性主要用来加速for循环的重渲染，旨在列表中的数据有变更时，提高重新渲染的效率。tid属性是用来指定数组中每个元素的唯一标识，如果未指定，数组中每个元素的索引为该元素的唯一id。例如上述tid="id"表示数组中的每个元素的id属性为该元素的唯一标识。for循环支持的写法如下：
226
227- for="array"：其中array为数组对象，array的元素变量默认为$item。
228
229- for="v in array"：其中v为自定义的元素变量，元素索引默认为$idx。
230
231- for="(i, v) in array"：其中元素索引为i，元素变量为v，遍历数组对象array。
232
233>  **说明：**
234>
235> - 数组中的每个元素必须存在tid指定的数据属性，否则运行时可能会导致异常。
236>
237> - 数组中被tid指定的属性要保证唯一性，如果不是则会造成性能损耗。比如，示例中只有id和name可以作为tid字段，因为它们属于唯一字段。
238>
239> - tid不支持表达式。
240
241
242## 条件渲染
243
244条件渲染分为2种：if/elif/else和show。两种写法的区别在于：第一种写法里if为false时，组件不会在vdom中构建，也不会渲染，而第二种写法里show为false时虽然也不渲染，但会在vdom中构建；另外，当使用if/elif/else写法时，节点必须是兄弟节点，否则编译无法通过。实例如下：
245
246
247```html
248<!-- xxx.hml -->
249<div class="container">
250  <button class="btn" type="capsule" value="toggleShow" onclick="toggleShow"></button>
251  <button class="btn" type="capsule" value="toggleDisplay" onclick="toggleDisplay"></button>
252  <text if="{{show}}"> Hello-One </text>
253  <text elif="{{display}}"> Hello-Two </text>
254  <text else> Hello-World </text>
255</div>
256```
257
258
259```css
260/* xxx.css */
261.container{
262  flex-direction: column;
263  align-items: center;
264}
265.btn{
266  width: 280px;
267  font-size: 26px;
268  margin: 10px 0;
269}
270```
271
272
273```js
274// xxx.js
275export default {
276  data: {
277    show: false,
278    display: true,
279  },
280  toggleShow: function() {
281    this.show = !this.show;
282  },
283  toggleDisplay: function() {
284    this.display = !this.display;
285  }
286}
287```
288
289优化渲染优化：show方法。当show为真时，节点正常渲染；当为假时，仅仅设置display样式为none。
290
291
292```html
293<!-- xxx.hml -->
294<div class="container">
295  <button class="btn" type="capsule" value="toggle" onclick="toggle"></button>
296  <text show="{{visible}}" > Hello World </text>
297</div>
298```
299
300
301```css
302/* xxx.css */
303.container{
304  flex-direction: column;
305  align-items: center;
306}
307.btn{
308  width: 280px;
309  font-size: 26px;
310  margin: 10px 0;
311}
312```
313
314
315```js
316// xxx.js
317export default {
318  data: {
319    visible: false,
320  },
321  toggle: function() {
322    this.visible = !this.visible;
323  },
324}
325```
326
327>  **说明：**
328>
329>  禁止在同一个元素上同时设置for和if属性。
330