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 World--> 29 <text>key1 {{key1}}</text> <!-- Display key1 Hello--> 30 <text>{{flag1 && flag2}}</text> <!-- Display false--> 31 <text>{{flag1 || flag2}}</text> <!-- Display true--> 32 <text>{{!flag1}}</text> <!-- Display false--> 33</div> 34``` 35 36Declare the variables used in the XML file for service widgets in the **data** field in the JSON file. 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> **NOTE** 51> - 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]}}**. 52> 53> - String concatenation, logical operations, and ternary expressions are supported. 54> - String concatenation: 55> - A variable can be followed by another variable, for example, **{{key1}}{{key2}}**. 56> - A variable can also be followed by a constant, for example, **"my name is {{name}}, i am from {{city}}." "key1 {{key1}}"**. 57> - Logical operations: 58> - AND: {{flag1 && flag2}} (The AND operation can only be performed on two Boolean variables.) 59> - OR: {{flag1 || flag2}} (The OR operation can only be performed on two Boolean variables.) 60> - NOT: {{! flag1}} (The NOT operation can only be performed on a Boolean variable.) 61> - Ternary expressions: 62> - {{flag? key1: key2}} (**flag** is a Boolean variable. **key1** and **key2** can be variables or constants.) 63> - Notes 64> - The default value is **false** when a Boolean-specific operation is performed on a non-Boolean variable. 65> - The preceding variable and operation parsing do not support nesting. 66 67## Event Binding 68 69Declare 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. 70 71- Redirection event properties 72 73 Define the **abilityName** and **params** fields to implement direct redirection to the target application. 74 75 | Selector | Example | Default Value | Description | 76 | ----------- | ------ | -------- | ---------------------------------------- | 77 | action | string | "router" | Event type.<br>- **"router"**: redirection event.<br>- **"message"**: message event.| 78 | abilityName | string | - | Name of the ability to redirect to. | 79 | params | Object | - | Additional parameter passed during the redirection. | 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- Message event properties 99 100 | Selector | Example | Default Value | Description | 101 | ------ | ------ | ------- | ------------ | 102 | action | string | message | Event type. | 103 | params | Object | - | Additional parameter passed during the redirection.| 104 105 106 ```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{ 155 "data": { 156 "array": [ 157 {"id": 1, "name": "jack", "age": 18}, 158 {"id": 2, "name": "tony", "age": 18} 159 ] 160 } 161} 162``` 163 164The **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: 165 166- for="array": **array** is an array object, whose element variable is **$item** by default. 167 168- for="v in array": **v** is a custom element variable, whose index is **$idx** by default. 169 170- 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. 171 172> **NOTE** 173> - Each element in the array must have the data attribute specified by **tid**. Otherwise, an exception may occur. 174> 175> - 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. 176> 177> - The **tid** field does not support expressions. 178> 179> - Nested **for** loops are not supported. 180> 181> - When you use the **for** loop, ensure that the objects contained in the array are of the same type. 182 183 184## Conditional Rendering 185 186There are two ways to implement conditional rendering: **if-elif-else** or **show**. 187 188The **if-elif-else** statements must be used in sibling nodes. Otherwise, the compilation fails. The following example uses both ways to implement conditional rendering: 189 190 191```html 192<!-- xxx.hml --> 193<div> 194 <text if="{{show}}"> Hello-TV </text> 195 <text elif="{{display}}"> Hello-Wearable </text> 196 <text else> Hello-World </text> 197</div> 198``` 199 200 201```json 202{ 203 "data": { 204 "show": false, 205 "display": true 206 } 207} 208``` 209 210If **show** is **true**, the node is rendered properly; if it is **false**, the display style will be **none**. 211 212 213```html 214<!-- xxx.hml --> 215<text show="{{visible}}"> Hello World </text> 216``` 217 218 219```json 220{ 221 "data": { 222 "visible": false 223 } 224} 225``` 226 227 228## Logic Control Block 229 230**\<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. 231 232 233```html 234<!-- xxx.hml --> 235<div> 236 <block if="{{show}}"> 237 <text>Hello</text> 238 <text>World</text> 239 </block> 240</div> 241``` 242 243 244```json 245{ 246 "data": { 247 "show": true 248 } 249} 250``` 251
