1# Custom Component Basic Usage 2 3 4> **NOTE** 5> 6> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 7 8 9Custom components are existing components encapsulated based on service requirements. A custom component can be invoked multiple times in a project to improve the code readability. You can introduce a custom component to the host page through **element** as shown in the following code snippet: 10 11```html 12<element name='comp' src='../../common/component/comp.hml'></element> 13<div> 14 <comp prop1='xxxx' @child1="bindParentVmMethod"></comp> 15</div> 16``` 17 18- The **name** attribute indicates the custom component name (optional), which is case-insensitive and is in lowercase by default. The **src** attribute indicates the **.hml** file path (mandatory) of the custom component. If **name** is not set, the **.hml** file name is used as the component name by default. 19 20- Event binding: Use **(on|\@)*child1*** in the custom component to bind a child component event. In the child component, use **{action:"*proxy*", method: "*eventName*"}** to trigger the bound event and pass the parameter value. In the parent component, call **bindParentVmMethod** and receive the parameter passed from the child component. 21 22## Labels of Custom Component Configuration File 23 24| Name| Type| Description| 25| -------- | -------- | -------- | 26| data | Object | Data model of the page. The name cannot start with a dollar sign ($) or underscore (_). Do not use reserved words (**for**, **if**, **show**, and **tid**).| 27| props | Array/Object | Used for communication between components. This attribute can be transferred to components via **\<tag xxxx='value'>**. A **props** name must be in lowercase and cannot start with a dollar sign ($) or underscore (_). Do not use reserved words (**for**, **if**, **show**, and **tid**). Currently, **props** does not support functions. | 28 29 30## Adding a Custom Event 31 32Custom components support custom events, whose **action** is **proxy** and name is specified by **method**. A service widget page that uses a custom component can register an event callback corresponding to the custom event name. When the custom event in the custom component is triggered, the registered callback will be invoked. 33 34> **NOTE** 35> 36> The event name cannot contain uppercase letters. 37 38Example of a custom child component: 39 40```html 41<!-- comp.hml --> 42<div class="container"> 43 <div class="row-3" if="true"> 44 <button onclick="buttonClicked" value="click"></button> 45 </div> 46</div> 47``` 48 49```css 50/* comp.css */ 51.container { 52 flex-direction:column; 53 background-color: green; 54 width: 100%; 55 height: 100%; 56} 57 58.row-3 { 59 width: 100%; 60 height: 50px; 61 background-color: orange; 62 font-size:15px; 63} 64``` 65 66```json 67{ 68 "data": { 69 }, 70 "actions": { 71 "buttonClicked": { 72 "action": "proxy", 73 "method":"event_1" 74 } 75 } 76} 77``` 78Example of a parent component: 79 80```html 81<!-- xxx.hml --> 82<element name='comp' src='../../common/customComponent/customComponent.hml'></element> 83 84<div class="container"> 85 <comp @event_1="click"></comp> 86 <button value="parentClick" @click="buttonClick"></button> 87</div> 88``` 89 90```css 91/* xxx.css */ 92.container { 93 background-color: red; 94 height: 500px; 95 width: 500px; 96} 97``` 98 99```json 100{ 101 "data": { 102 }, 103 "actions": { 104 "click": { 105 "action": "message", 106 "params": { 107 "message": "click event" 108 } 109 }, 110 "buttonClick": { 111 "action": "message", 112 "params": { 113 "message": "click event 2" 114 } 115 } 116 } 117} 118``` 119 120 121## props 122 123You can use **props** to declare custom attributes of a custom component. The attributes can be used by a parent component to pass parameters to a child component. 124 125### Default Value 126 127You can set the default value for a child component attribute via **default**. The default value is used if the parent component does not have **default** set. In this case, the **props** attribute must be in object format instead of an array. 128 129```html 130<!-- comp.hml --> 131<div class="container"> 132 <div class="row-1"> 133 <div class="box-1"> 134 <text>xiaoziti</text> 135 </div> 136 <div class="box-2"> 137 <text>{{text}}</text> 138 </div> 139 <div class="box-3"> 140 <text>{{textdata[0]}}</text> 141 </div> 142 </div> 143 <div class="row-2" if="true"> 144 <button value="{{progress}}"></button> 145 </div> 146 <div class="row-3" if="true"> 147 <button onclick="buttonClicked" value="click"></button> 148 </div> 149</div> 150``` 151 152```json 153{ 154 "data": { 155 "progress": { 156 "default": "80" 157 } 158 }, 159 "props": { 160 "textdata": { 161 "default": ["a","b"] 162 }, 163 "progress": { 164 "default": 60 165 }, 166 "text": { 167 "default": "ha" 168 } 169 }, 170 "actions": { 171 "buttonClicked": { 172 "action": "proxy", 173 "method": "event_1" 174 } 175 } 176} 177``` 178 179Example of the parent component that references the **comp** child component: 180 181```html 182<!-- xxx.hml --> 183<element name='comp' src='../../common/customComponent/customComponent.hml'></element> 184 185<div class="container"> 186 <comp progress="{{clicknow}}" textdata="{{texts}}" if="false" @event_1="click"></comp> 187</div> 188``` 189 190### Unidirectional Value Transfer 191 192Data can be transferred only from the parent component to child components. You are not allowed to change the value passed to the child component. However, you can receive the value passed by **props** as a default value in **data**, and then change the **data** value. 193 194For details, see [props](../arkui-js/js-components-custom-props.md). 195