1# HML语法参考 2 3HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组件，事件构建出页面的内容。页面具备数据绑定、事件绑定、列表渲染、条件渲染和逻辑控制等高级能力。 4 5 6## 页面结构 7 8``` 9<!-- xxx.hml --> 10<div class="item-container"> 11 <text class="item-title">Image Show</text> 12 <div class="item-content"> 13 <image src="/common/xxx.png" class="image"></image> 14 </div> 15</div> 16``` 17 18 19## 数据绑定 20 21``` 22<!-- xxx.hml --> 23<div onclick="changeText"> 24 <text> {{content[1]}} </text> 25</div> 26``` 27``` 28/*xxx.css*/ 29.container{ 30 margin: 200px; 31} 32``` 33``` 34// xxx.js 35export default { 36 data: { 37 content: ['Hello World!', 'Welcome to my world!'] 38 }, 39 changeText: function() { 40 this.content.splice(1, 1, this.content[0]); 41 } 42} 43``` 44 45>  **说明：** 46> - 针对数组内的数据修改，请使用splice方法生效数据绑定变更。 47> 48> - hml文件中的js表达式不支持ES6语法。 49 50 51 52## 普通事件绑定 53 54事件通过'on'或者'\@'绑定在组件上，当组件触发事件时会执行JS文件中对应的事件处理函数。 55 56事件支持的写法有： 57 58- "funcName"：funcName为事件回调函数名（在JS文件中定义相应的函数实现）。 59 60- "funcName(a,b)"：函数参数例如a，b可以是常量，或者是在JS文件中的data中定义的变量（前面不用写this.）。 61 62- 示例 63 ``` 64 <!-- xxx.hml --> 65 <div class="container"> 66 <text class="title">{{count}}</text> 67 <div class="box"> 68 <input type="button" class="btn" value="increase" onclick="increase" /> 69 <input type="button" class="btn" value="decrease" @click="decrease" /> 70 <!-- 传递额外参数 --> 71 <input type="button" class="btn" value="double" @click="multiply(2)" /> 72 <input type="button" class="btn" value="decuple" @click="multiply(10)" /> 73 <input type="button" class="btn" value="square" @click="multiply(count)" /> 74 </div> 75 </div> 76 ``` 77 78 ``` 79 // xxx.js 80 export default { 81 data: { 82 count: 0 83 }, 84 increase() { 85 this.count++; 86 }, 87 decrease() { 88 this.count--; 89 }, 90 multiply(multiplier) { 91 this.count = multiplier * this.count; 92 } 93 }; 94 ``` 95 96 ``` 97 /* xxx.css */ 98 .container { 99 display: flex; 100 flex-direction: column; 101 justify-content: center; 102 align-items: center; 103 left: 0px; 104 top: 0px; 105 width: 454px; 106 height: 454px; 107 } 108 .title { 109 font-size: 30px; 110 text-align: center; 111 width: 200px; 112 height: 100px; 113 } 114 .box { 115 width: 454px; 116 height: 200px; 117 justify-content: center; 118 align-items: center; 119 flex-wrap: wrap; 120 } 121 .btn { 122 width: 200px; 123 border-radius: 0; 124 margin-top: 10px; 125 margin-left: 10px; 126 } 127 ``` 128 129 130 131## 冒泡事件绑定<sup>5+</sup> 132 133冒泡事件绑定包括： 134 135- 绑定冒泡事件：on:{event}.bubble。on:{event}等价于on:{event}.bubble。 136 137- 绑定并阻止冒泡事件向上冒泡：grab:{event}.bubble。grab:{event}等价于grab:{event}.bubble。 138 >  **说明：** 139 > 详细冒泡事件说明参见[通用事件](../reference/arkui-js/js-components-common-events.md)章节。 140 141- 示例 142 ``` 143 <!-- xxx.hml --> 144 <div> 145 <!-- 使用事件冒泡模式绑定事件回调函数。5+ -->; 146 <div on:touchstart.bubble="touchstartfunc"></div> 147 <div on:touchstart="touchstartfunc"></div> 148 <!-- 绑定事件回调函数，但阻止事件向上传递。5+ --> 149 <div grab:touchstart.bubble="touchstartfunc"></div> 150 <div grab:touchstart="touchstartfunc"></div> 151 <!-- 使用事件冒泡模式绑定事件回调函数。6+ --> 152 <div on:click.bubble="clickfunc"></div> 153 <div on:click="clickfunc"></div> 154 <!-- 绑定事件回调函数，但阻止事件向上传递。6+ --> 155 <div grab:click.bubble="clickfunc"></div> 156 <div grab:click="clickfunc"></div> 157 </div> 158 ``` 159 160 ``` 161 // xxx.js 162 export default { 163 clickfunc: function(e) { 164 console.log(e); 165 }, 166 touchstartfuc: function(e) { 167 console.log(e); 168 }, 169 } 170 ``` 171 172>  **说明：** 173> 采用旧写法(onclick)的事件绑定在最小API版本6以下时采用不冒泡处理，在最小API版本为6及6以上时采用冒泡处理。 174 175## 捕获事件绑定<sup>5+</sup> 176 177Touch触摸类事件支持捕获，捕获阶段位于冒泡阶段之前，捕获事件先到达父组件然后达到子组件。 178 179捕获事件绑定包括： 180 181- 绑定捕获事件：on:{event}.capture。 182 183- 绑定并阻止事件向下传递：grab:{event}.capture。 184 185- 示例 186 ``` 187 <!-- xxx.hml --> 188 <div> 189 <!-- 使用事件捕获模式绑定事件回调函数。5+ --> 190 <div on:touchstart.capture="touchstartfunc"></div> 191 <!-- 绑定事件回调函数，但阻止事件向下传递。5+ --> 192 <div grab:touchstart.capture="touchstartfunc"></div> 193 </div> 194 ``` 195 196 ``` 197 // xxx.js 198 export default { 199 touchstartfuc: function(e) { 200 console.log(e); 201 }, 202 } 203 ``` 204 205 206## 列表渲染 207 208``` 209<!-- xxx.hml --> 210<div class="array-container" style="flex-direction: column;margin: 200px;"> 211 <!-- div列表渲染 --> 212 <!-- 默认$item代表数组中的元素, $idx代表数组中的元素索引 --> 213 <div for="{{array}}" tid="id" onclick="changeText"> 214 <text>{{$idx}}.{{$item.name}}</text> 215 </div> 216 <!-- 自定义元素变量名称 --> 217 <div for="{{value in array}}" tid="id" onclick="changeText"> 218 <text>{{$idx}}.{{value.name}}</text> 219 </div> 220 <!-- 自定义元素变量、索引名称 --> 221 <div for="{{(index, value) in array}}" tid="id" onclick="changeText"> 222 <text>{{index}}.{{value.name}}</text> 223 </div> 224</div> 225 226``` 227 228``` 229// xxx.js 230export default { 231 data: { 232 array: [ 233 {id: 1, name: 'jack', age: 18}, 234 {id: 2, name: 'tony', age: 18}, 235 ], 236 }, 237 changeText: function() { 238 if (this.array[1].name === "tony"){ 239 this.array.splice(1, 1, {id:2, name: 'Isabella', age: 18}); 240 } else { 241 this.array.splice(2, 1, {id:3, name: 'Bary', age: 18}); 242 } 243 }, 244} 245``` 246 247tid属性主要用来加速for循环的重渲染，旨在列表中的数据有变更时，提高重新渲染的效率。tid属性是用来指定数组中每个元素的唯一标识，如果未指定，数组中每个元素的索引为该元素的唯一id。例如上述tid="id"表示数组中的每个元素的id属性为该元素的唯一标识。for循环支持的写法如下： 248 249- for="array"：其中array为数组对象，array的元素变量默认为$item。 250 251- for="v in array"：其中v为自定义的元素变量，元素索引默认为$idx。 252 253- for="(i, v) in array"：其中元素索引为i，元素变量为v，遍历数组对象array。 254 255>  **说明：** 256> - 数组中的每个元素必须存在tid指定的数据属性，否则运行时可能会导致异常。 257> 258> - 数组中被tid指定的属性要保证唯一性，如果不是则会造成性能损耗。比如，示例中只有id和name可以作为tid字段，因为它们属于唯一字段。 259> 260> - tid不支持表达式。 261 262 263 264## 条件渲染 265 266条件渲染分为2种：if/elif/else和show。两种写法的区别在于：第一种写法里if为false时，组件不会在vdom中构建，也不会渲染，而第二种写法里show为false时虽然也不渲染，但会在vdom中构建；另外，当使用if/elif/else写法时，节点必须是兄弟节点，否则编译无法通过。实例如下： 267 268``` 269<!-- xxx.hml --> 270<div class="container"> 271 <button class="btn" type="capsule" value="toggleShow" onclick="toggleShow"></button> 272 <button class="btn" type="capsule" value="toggleDisplay" onclick="toggleDisplay"></button> 273 <text if="{{visible}}"> Hello-world1 </text> 274 <text elif="{{display}}"> Hello-world2 </text> 275 <text else> Hello-World </text> 276</div> 277``` 278 279``` 280/* xxx.css */ 281.container{ 282 flex-direction: column; 283 align-items: center; 284} 285.btn{ 286 width: 280px; 287 font-size: 26px; 288 margin: 10px 0; 289} 290``` 291 292``` 293// xxx.js 294export default { 295 data: { 296 visible: false, 297 display: true, 298 }, 299 toggleShow: function() { 300 this.visible = !this.visible; 301 }, 302 toggleDisplay: function() { 303 this.display = !this.display; 304 } 305} 306``` 307 308 309 310优化渲染优化：show方法。当show为true时，节点正常渲染；当为false时，仅仅设置display样式为none。 311 312``` 313<!-- xxx.hml --> 314<div class="container"> 315 <button class="btn" type="capsule" value="toggle" onclick="toggle"></button> 316 <text show="{{visible}}" > Hello World </text> 317</div> 318``` 319 320``` 321/* xxx.css */ 322.container{ 323 flex-direction: column; 324 align-items: center; 325} 326.btn{ 327 width: 280px; 328 font-size: 26px; 329 margin: 10px 0; 330} 331``` 332 333``` 334// xxx.js 335export default { 336 data: { 337 visible: false, 338 }, 339 toggle: function() { 340 this.visible = !this.visible; 341 }, 342} 343``` 344 345>  **说明：** 346> 禁止在同一个元素上同时设置for和if属性。 347 348 349 350## 逻辑控制块 351 352<block>控制块使得循环渲染和条件渲染变得更加灵活；block在构建时不会被当作真实的节点编译。注意block标签只支持for和if属性。 353 354``` 355<!-- xxx.hml --> 356<list> 357 <block for="glasses"> 358 <list-item type="glasses"> 359 <text>{{$item.name}}</text> 360 </list-item> 361 <block for="$item.kinds"> 362 <list-item type="kind"> 363 <text>{{$item.color}}</text> 364 </list-item> 365 </block> 366 </block> 367</list> 368``` 369 370``` 371// xxx.js 372export default { 373 data: { 374 glasses: [ 375 {name:'sunglasses', kinds:[{name:'XXX',color:'XXX'},{name:'XXX',color:'XXX'}]}, 376 {name:'nearsightedness mirror', kinds:[{name:'XXX',color:'XXX'}]}, 377 ], 378 }, 379} 380``` 381 382 383 384## 模板引用 385 386HML可以通过element引用模板文件，详细介绍可参考[自定义组件](../reference/arkui-js/js-components-custom-basic-usage.md)章节。 387 388``` 389<!-- template.hml --> 390<div class="item"> 391 <text>Name: {{name}}</text> 392 <text>Age: {{age}}</text> 393</div> 394``` 395 396``` 397<!-- index.hml --> 398<element name='comp' src='../../common/template.hml'></element> 399<div> 400 <comp name="Tony" age="18"></comp> 401</div> 402``` 403
