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