1# HML语法参考 2 3 4HML（OpenHarmony Markup Language）是一套类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 class="item-container"> 27 <text>{{content}}</text> <!-- 输出：Hello World！--> 28 <text>{{key1}} {{key2}}</text> <!-- 输出：Hello World--> 29 <text>key1 {{key1}}</text> <!-- 输出：key1 Hello--> 30 <text>{{flag1 && flag2}}</text> <!-- 输出：false--> 31 <text>{{flag1 || flag2}}</text> <!-- 输出：true--> 32 <text>{{!flag1}}</text> <!-- 输出：false--> 33</div> 34``` 35 36卡片hml文件中的变量需要在json文件的data字段下进行声明： 37 38```json 39{ 40 "data": { 41 "content": "Hello World!", 42 "key1": "Hello", 43 "key2": "World", 44 "flag1": true, 45 "flag2": false 46 } 47} 48``` 49 50> **说明：** 51> - key值支持对象操作符和数组操作符，如{{key.value}}、{{key[0]}}。 52> 53> - 支持字符串拼接、逻辑运算和三元表达式。 54> - 字符串拼接： 55> - 支持变量跟变量：{{key1}}{{key2}}等 56> - 支持常量跟变量： "my name is {{name}}， i am from {{city}}." "key1 {{key1}}" 57> - 逻辑运算： 58> - 与：{{flag1 && flag2}}（仅支持两个boolean变量间的与逻辑运算） 59> - 或：{{flag1 || flag2}} （仅支持两个boolean变量间的或逻辑运算） 60> - 非：{{!flag1}} （仅支持boolean变量的非逻辑运算） 61> - 三元表达式 62> - {{flag? key1:key2}}（flag为boolean变量，key1和key2可以是变量，也可以是常量） 63> - 注意事项 64> - 非boolean类型值进行bool运算默认为false 65> - 以上所有变量解析跟运算解析均不支持嵌套 66 67## 事件绑定 68 69卡片的事件需要在json文件的actions字段下进行声明。卡片仅支持click通用事件，事件的定义只能是直接命令式，事件定义必须包含action字段，用以说明事件类型。卡片支持两种事件类型：跳转事件(router)和消息事件(message)。跳转事件可以跳转到卡片提供方的OpenHarmony应用，消息事件可以将开发者自定义信息传递给卡片提供方。事件参数支持变量，变量以"{{}}"修饰。跳转事件中若定义了params字段，则在被拉起应用的onStart的intent中，可用"params"作为key将跳转事件定义的params字段的值取到。 70 71- 跳转事件格式 72 73 通过定义ability名称和携带的参数字段params直接跳转，可用"params"作为key提取到跳转事件定义的params字段值。 74 75 | 选择器 | 样例 | 默认值 | 样例描述 | 76 | ----------- | ------ | -------- | ---------------------------------------- | 77 | action | string | "router" | 事件类型。<br/>- "router"：用于应用跳转。<br/>- "message"：自定义点击事件。 | 78 | abilityName | string | - | 跳转ability名。 | 79 | params | Object | - | 跳转应用携带的额外参数。 | 80 81 82 ```json 83 { 84 "data": { 85 "mainAbility": "xxx.xxx.xxx" 86 }, 87 "actions": { 88 "routerEvent": { 89 "action": "router", 90 "abilityName": "{{mainAbility}}", 91 "params":{} 92 } 93 } 94 } 95 ``` 96 97- 消息事件格式 98 99 | 选择器 | 样例 | 默认值 | 样例描述 | 100 | ------ | ------ | ------- | ------------ | 101 | action | string | message | 表示事件类型。 | 102 | params | Object | - | 跳转应用携带的额外参数。 | 103 104 105 ```json 106 { 107 "actions": { 108 "activeEvent": { 109 "action": "message", 110 "params": {} 111 } 112 } 113 } 114 ``` 115 116- 绑定路由事件和消息事件 117 118 ```html 119 <!-- xxx.hml --> 120 <div> 121 <!-- 正常格式 --> 122 <div onclick="activeEvent"></div> 123 <!-- 缩写 --> 124 <div @click="activeEvent"></div> 125 </div> 126 ``` 127 128 129## 列表渲染 130 131 132```html 133<!-- xxx.hml --> 134<div class="array-container"> 135 <!-- div列表渲染 --> 136 <!-- 默认$item代表数组中的元素, $idx代表数组中的元素索引 --> 137 <div for="{{array}}" tid="id"> 138 <text>{{$item.name}}</text> 139 </div> 140 <!-- 自定义元素变量名称 --> 141 <div for="{{value in array}}" tid="id"> 142 <text>{{value.name}}</text> 143 </div> 144 <!-- 自定义元素变量、索引名称 --> 145 <div for="{{(index, value) in array}}" tid="id"> 146 <text>{{value.name}}</text> 147 </div> 148</div> 149``` 150 151 152```json 153{ 154 "data": { 155 "array": [ 156 {"id": 1, "name": "jack", "age": 18}, 157 {"id": 2, "name": "tony", "age": 18} 158 ] 159 } 160} 161``` 162 163tid属性主要用来加速for循环的重渲染，旨在列表中的数据有变更时，提高重新渲染的效率。tid属性是用来指定数组中每个元素的唯一标识，如果未指定，数组中每个元素的索引为该元素的唯一id。例如上述tid="id"表示数组中的每个元素的id属性为该元素的唯一标识。for循环支持的写法如下： 164 165- for="array"：其中array为数组对象，array的元素变量默认为$item。 166 167- for="v in array"：其中v为自定义的元素变量，元素索引默认为$idx。 168 169- for="(i, v) in array"：其中元素索引为i，元素变量为v，遍历数组对象array。 170 171> **说明：** 172> - 数组中的每个元素必须存在tid指定的数据属性，否则运行时可能会导致异常。 173> 174> - 数组中被tid指定的属性要保证唯一性，如果不是则会造成性能损耗。比如，示例中只有id和name可以作为tid字段，因为它们属于唯一字段。 175> 176> - tid不支持表达式。 177> 178> - 不支持for嵌套使用。 179> 180> - for对应的变量数组，当前要求数组中的object是相同类型，不支持多种object类型混合写在一个数组中。 181 182 183## 条件渲染 184 185条件渲染分为2种：if/elif/else和show。 186 187当使用if/elif/else写法时，节点必须是兄弟节点，否则编译无法通过。实例如下： 188 189 190```html 191<!-- xxx.hml --> 192<div> 193 <text if="{{show}}"> Hello-TV </text> 194 <text elif="{{display}}"> Hello-Wearable </text> 195 <text else> Hello-World </text> 196</div> 197``` 198 199 200```json 201{ 202 "data": { 203 "show": false, 204 "display": true 205 } 206} 207``` 208 209当show为真时，节点正常渲染；当show为假时，节点不渲染，效果等同display样式为none。 210 211 212```html 213<!-- xxx.hml --> 214<text show="{{visible}}"> Hello World </text> 215``` 216 217 218```json 219{ 220 "data": { 221 "visible": false 222 } 223} 224``` 225 226 227## 逻辑控制块 228 229<block>控制块使得循环渲染和条件渲染变得更加灵活；block在构建时不会被当作真实的节点编译。block标签只支持if属性。 230 231 232```html 233<!-- xxx.hml --> 234<div> 235 <block if="{{show}}"> 236 <text>Hello</text> 237 <text>World</text> 238 </block> 239</div> 240``` 241 242 243```json 244{ 245 "data": { 246 "show": true 247 } 248} 249``` 250
