1# HML 2 3 4The OpenHarmony Markup Language (HML) is an HTML-like language that allows you to build pages based on components and events. HML pages provide advanced capabilities such as data binding, event binding, loop rendering, conditional rendering, and logic control. 5 6 7## Page Structure 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## Data Binding 22 23 24```html 25<!-- xxx.hml --> 26<div class="item-container"> 27 <text>{{content}}</text> <!-- Display Hello World!--> 28 <text>{{key1}} {{key2}}</text> <!-- Display Hello World6+--> 29 <text>key1 {{key1}}</text> <!-- Display key1 Hello6+--> 30 <text>{{flag1 && flag2}}</text> <!-- Display false6+--> 31 <text>{{flag1 || flag2}}</text> <!-- Display true6+--> 32 <text>{{!flag1}}</text> <!-- Display false6+--> 33</div> 34``` 35 36 37```json 38{ 39 "data": { 40 "content": "Hello World!", 41 "key1": "Hello", 42 "key2": "World", 43 "flag1": true, 44 "flag2": false 45 } 46} 47``` 48 49> **NOTE** 50> - When using data binding, you can use the object operator or array operator on a key to access the bound data, for example, **{{key.value}}** and **{{key[0]}}**. 51> 52> - String concatenation, logical operations, and ternary expressions are supported since API version 6. 53> - String concatenation: 54> - A variable can be followed by another variable, for example, **{{key1}}{{key2}}**. 55> - A variable can also be followed by a constant, for example, **"my name is {{name}}, i am from {{city}}." "key1 {{key1}}"**. 56> - Logical operations: 57> - AND: {{flag1 && flag2}} (The AND operation can only be performed on two Boolean variables.) 58> - OR: {{flag1 || flag2}} (The OR operation can only be performed on two Boolean variables.) 59> - NOT: {{! flag1}} (The NOT operation can only be performed on a Boolean variable.) 60> - Ternary expressions: 61> - {{flag? key1: key2}} (**flag** is a Boolean variable. **key1** and **key2** can be variables or constants.) 62> - Notes 63> - The default value is **false** when a Boolean-specific operation is performed on a non-Boolean variable. 64> - The preceding variable and operation parsing do not support nesting. 65 66## Event Binding 67 68Declare the events for service widgets in the **actions** field in the JSON file. Service widgets support the common click event only. The event must be declared explicitly. The event definition must contain the **action** field to describe the event type. Service widgets support redirection events (**router**) and message events (**message**). A redirection event is used for switching to the OpenHarmony application (the widget provider). A message event can transfer custom information to the service widget provider. Event parameters can be variables, which are defined using **{{}}**. If the **params** field is defined in the redirection event, you can pass **params** to the **onStart** method (as **intent**) of the started application to access the value. 69 70- Redirection event properties 71 72 Define the **abilityName** and **params** fields to implement direct redirection to the target application. 73 74 | Selector | Example | Default Value | Description | 75 | ----------- | ------ | -------- | ---------------------------------------- | 76 | action | string | "router" | Event type.<br>- **"router"**: redirection event.<br>- **"message"**: message event.| 77 | abilityName | string | - | Name of the ability to redirect to. | 78 | params | Object | - | Additional parameter passed during the redirection. | 79 80 81 ```json 82 // xxx.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- Message event properties 98 99 | Selector | Example | Default Value | Description | 100 | ------ | ------ | ------- | ------------ | 101 | action | string | message | Event type. | 102 | params | Object | - | Additional parameter passed during the redirection.| 103 104 105 ```json 106 // xxx.json 107 { 108 "actions": { 109 "activeEvent": { 110 "action": "message", 111 "params": {} 112 } 113 } 114 } 115 ``` 116 117- The following example shows two styles for binding the redirection event and message event: 118 119 ```html 120 <!-- xxx.hml --> 121 <div> 122 <!-- Regular format --> 123 <div onclick="activeEvent"></div> 124 <!-- Abbreviation --> 125 <div @click="activeEvent"></div> 126 </div> 127 ``` 128 129 130## Loop Rendering 131 132 133```html 134<!-- xxx.hml --> 135<div class="array-container"> 136 <!-- div loop rendering --> 137 <!-- By default, $item indicates the element in the array, and $idx indicates the index of the element in the array. --> 138 <div for="{{array}}" tid="id"> 139 <text>{{$item.name}}</text> 140 </div> 141 <!-- Define the name for an element variable. --> 142 <div for="{{value in array}}" tid="id"> 143 <text>{{value.name}}</text> 144 </div> 145 <!-- Define an element variable and its index name. --> 146 <div for="{{(index, value) in array}}" tid="id"> 147 <text>{{value.name}}</text> 148 </div> 149</div> 150``` 151 152 153```json 154// xxx.json 155{ 156 "data": { 157 "array": [ 158 {"id": 1, "name": "jack", "age": 18}, 159 {"id": 2, "name": "tony", "age": 18} 160 ] 161 } 162} 163``` 164 165The **tid** attribute accelerates the **for** loop and improves the re-rendering efficiency when data in a loop changes. The **tid** attribute specifies the unique ID of each element in the array. If it is not specified, the index of each element in the array is used as the ID. For example, **tid="id"** indicates that the **id** attribute of each element is its unique ID. The **for** loop supports the following statements: 166 167- for="array": **array** is an array object, whose element variable is **$item** by default. 168 169- for="v in array": **v** is a custom element variable, whose index is **$idx** by default. 170 171- for="(i, v) in array": **i** indicates the element index, and **v** indicates the element variable. All elements of the array object will be looped through. 172 173> **NOTE** 174> - Each element in the array must have the data attribute specified by **tid**. Otherwise, an exception may occur. 175> 176> - The attribute specified by **tid** in the array must be unique. Otherwise, performance loss occurs. In the above example, only **id** and **name** can be used as **tid** because they are unique fields. 177> 178> - The **tid** field does not support expressions. 179> 180> - Nested **for** loops are not supported. 181> 182> - When you use the **for** loop, ensure that the objects contained in the array are of the same type. 183 184 185## Conditional Rendering 186 187There are two ways to implement conditional rendering: **if-elif-else** or **show**. 188 189The **if-elif-else** statements must be used in sibling nodes. Otherwise, the compilation fails. The following example uses both ways to implement conditional rendering: 190 191 192```html 193<!-- xxx.hml --> 194<div> 195 <text if="{{show}}"> Hello-TV </text> 196 <text elif="{{display}}"> Hello-Wearable </text> 197 <text else> Hello-World </text> 198</div> 199``` 200 201 202```json 203// xxx.json 204{ 205 "data": { 206 "show": false, 207 "display": true 208 } 209} 210``` 211 212If **show** is **true**, the node is rendered properly; if it is **false**, the display style will be **none**. 213 214 215```html 216<!-- xxx.hml --> 217<text show="{{visible}}"> Hello World </text> 218``` 219 220 221```json 222// xxx.json 223{ 224 "data": { 225 "visible": false 226 } 227} 228``` 229 230 231## Logic Control Block 232 233**\<block>** makes loop rendering and conditional rendering more flexible. A **\<block>** will not be compiled as a real component. The **\<block>** supports the **if** attribute only. 234 235 236```html 237<!-- xxx.hml --> 238<div> 239 <block if="{{show}}"> 240 <text>Hello</text> 241 <text>World</text> 242 </block> 243</div> 244``` 245 246 247```json 248// xxx.json 249{ 250 "data": { 251 "show": true 252 } 253} 254``` 255
