1# Button 2 3The **\<Button>** component can be used to create different types of buttons. 4 5> **NOTE** 6> 7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12This component can contain only one child component. 13 14 15## APIs 16 17### Button 18 19Button(options: ButtonOptions) 20 21Creates a button that can contain a single child component. 22 23**Widget capability**: Since API version 9, this API is supported in ArkTS widgets. 24 25**System capability**: SystemCapability.ArkUI.ArkUI.Full 26 27**Parameters** 28 29| Name | Type | Mandatory| Description | 30| ------- | --------------------------------------- | ---- | -------------------- | 31| options | [ButtonOptions](#buttonoptions) | Yes | Button settings.| 32 33### Button 34 35Button(label: ResourceStr, options?: ButtonOptions) 36 37Creates a button component based on text content. In this case, the component cannot contain child components. 38 39**Widget capability**: Since API version 9, this API is supported in ArkTS widgets. 40 41**System capability**: SystemCapability.ArkUI.ArkUI.Full 42 43**Parameters** 44 45| Name | Type | Mandatory| Description | 46| ------- | --------------------------------------- | ---- | -------------------- | 47| label | [ResourceStr](ts-types.md#resourcestr) | Yes | Button text. | 48| options | [ButtonOptions](#buttonoptions) | No | Button settings.| 49 50## ButtonOptions 51 52| Name | Type | Mandatory| Description | 53| ------------------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 54| type | [ButtonType](#buttontype) | No | Button type.<br>Default value: **ButtonType.Capsule** | 55| stateEffect | boolean | No | Whether to enable the pressed effect on the click of the button. The value **false** means to disable the pressed effect.<br>Default value: **true**<br>**NOTE**<br>When the pressed effect is enabled on the click of the button and the state style is set, the background color is applied based on the state style.| 56| buttonStyle<sup>11+</sup> | [ButtonStyleMode](#buttonstylemode11) | No | Style and primacy of the button.<br>Default value: **ButtonStyleMode.EMPHASIZED**<br>**NOTE**<br>The button primacy is as follows: emphasized button (high emphasis) > normal button (medium emphasis) > text button (low emphasis).| 57| controlSize<sup>11+</sup> | [ControlSize](#controlsize11) | No | Size of the button.<br>Default value: **ControlSize.NORMAL** | 58 59## Attributes 60 61In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 62 63| Name | Type | Description | 64| ----------- | ----------- | --------------------------------- | 65| type | [ButtonType](#buttontype) | Button type.<br>Default value: **ButtonType.Capsule**<br>Since API version 9, this API is supported in ArkTS widgets.| 66| fontSize | [Length](ts-types.md#length) | Font size of the button.<br>Default value: **'16fp'**| 67| fontColor | [ResourceColor](ts-types.md#resourcecolor) | Font color of the button.<br>Default value: **'\#ffffff'**| 68| fontWeight | [FontWeight](ts-appendix-enums.md#fontweight) \| number \| string | Font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. A larger value indicates a thicker font.<br>Default value: **400** \| FontWeight.Normal | 69| fontStyle | [FontStyle](ts-appendix-enums.md#fontstyle) | Font style of the button.<br>Default value: **FontStyle.Normal**| 70| stateEffect | boolean | Whether to enable the pressed effect on the click of the button. The value **false** means to disable the pressed effect.<br>Default value: **true**<br>Since API version 9, this API is supported in ArkTS widgets.| 71| labelStyle<sup>10+</sup> | [LabelStyle](#labelstyle10) | Label style of the button.| 72| buttonStyle<sup>11+</sup> | [ButtonStyleMode](#buttonstylemode11) | Style and primacy of the button.<br>Default value: **ButtonStyleMode.EMPHASIZED**| 73| controlSize<sup>11+</sup> | [ControlSize](#controlsize11) | Size of the button.<br>Default value: **ControlSize.NORMAL**| 74 75## ButtonType 76 77Since API version 9, this API is supported in ArkTS widgets. 78 79| Name | Description | 80| ------- | ------------------ | 81| Capsule | Capsule-type button (the round corner is half of the height by default).| 82| Circle | Circle button. | 83| Normal | Normal button (without rounded corners by default). | 84 85> **NOTE** 86> - The rounded corner of a button is set by using [borderRadius](ts-universal-attributes-border.md#borderradius), rather than by using the **border** API. Only a rounded corner whose parameter is [Length](ts-types.md#length) is supported. 87> - For a button of the **Capsule** type, the **borderRadius** settings do not take effect, and the radius of its rounded corner is always half of the button height or width, whichever is smaller. 88> - For a button of the **Circle** type: (1) If both its width and height are set, **borderRadius** does not take effect, and the button radius is half of the width or height (whichever is smaller). (2) If either its width or height is set, **borderRadius** does not take effect, and the button radius is half of the set width or height. (3) If neither its width nor height is set, the button radius is as specified by **borderRadius**; if **borderRadius** is set to a negative value, the value **0** will be used. 89> - The button text is set using the [text style attributes](ts-universal-attributes-text-style.md#attributes). 90> - Before setting the [gradient color](ts-universal-attributes-gradient-color.md), you need to set [backgroundColor](ts-universal-attributes-background.md#backgroundcolor) to transparent. 91 92## LabelStyle<sup>10+</sup> 93 94| Name | Type | Mandatory| Description | 95| -------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 96| overflow | [TextOverflow](ts-appendix-enums.md#textoverflow) | No | Display mode when the label text is too long. Text is clipped at the transition between words. To clip text in the middle of a word, add zero-width spaces between characters.<br>Default value: **TextOverflow.Ellipsis**| 97| maxLines | number | No | Maximum number of lines in the label text. By default, text is automatically folded. If this attribute is specified, the text will not exceed the specified number of lines. If there is extra text, you can use **overflow** to specify how it is displayed.<br>Default value: **1**| 98| minFontSize | number \| [ResourceStr](ts-types.md#resourcestr) | No | Minimum font size of the label text. For the setting to take effect, this attribute must be used together with **maxFontSize**, **maxLines**, or layout constraint settings.| 99| maxFontSize | number \| [ResourceStr](ts-types.md#resourcestr) | No | Maximum font size of the label text. For the setting to take effect, this attribute must be used together with **minFontSize**, **maxLines**, or layout constraint settings.| 100| heightAdaptivePolicy | [TextHeightAdaptivePolicy](ts-appendix-enums.md#textheightadaptivepolicy10) | No | How the adaptive height is determined for the label text. | 101| font | [Font](ts-types.md#font) | No | Font of the label text.<br>Default value: See [Font](ts-types.md#font). | 102 103## ButtonStyleMode<sup>11+</sup> 104 105Since API version 11, this API is supported in ArkTS widgets. 106 107| Name | Description | 108| ------- | ------------------ | 109| EMPHASIZED | Emphasized button (used to direct the user to the most important task).| 110| NORMAL | Normal button (used to direct the user to a common task). | 111| TEXTUAL | Text button (displayed as simple text without any background color). | 112 113## ControlSize<sup>11+</sup> 114 115Since API version 11, this API is supported in ArkTS widgets. 116 117| Name | Description | 118| ------- | ------------------ | 119| SMALL | Small button.| 120| NORMAL | Normal button. | 121 122## Events 123 124The [universal events](ts-universal-events-click.md) are supported. 125## Example 126 127### Example 1 128 129```ts 130// xxx.ets 131@Entry 132@Component 133struct ButtonExample { 134 build() { 135 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { 136 Text('Normal button').fontSize(9).fontColor(0xCCCCCC) 137 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 138 Button('OK', { type: ButtonType.Normal, stateEffect: true }) 139 .borderRadius(8) 140 .backgroundColor(0x317aff) 141 .width(90) 142 .onClick(() => { 143 console.log('ButtonType.Normal') 144 }) 145 Button({ type: ButtonType.Normal, stateEffect: true }) { 146 Row() { 147 LoadingProgress().width(20).height(20).margin({ left: 12 }).color(0xFFFFFF) 148 Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 }) 149 }.alignItems(VerticalAlign.Center) 150 }.borderRadius(8).backgroundColor(0x317aff).width(90).height(40) 151 152 Button('Disable', { type: ButtonType.Normal, stateEffect: false }).opacity(0.4) 153 .borderRadius(8).backgroundColor(0x317aff).width(90) 154 } 155 156 Text('Capsule button').fontSize(9).fontColor(0xCCCCCC) 157 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 158 Button('OK', { type: ButtonType.Capsule, stateEffect: true }).backgroundColor(0x317aff).width(90) 159 Button({ type: ButtonType.Capsule, stateEffect: true }) { 160 Row() { 161 LoadingProgress().width(20).height(20).margin({ left: 12 }).color(0xFFFFFF) 162 Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 }) 163 }.alignItems(VerticalAlign.Center).width(90).height(40) 164 }.backgroundColor(0x317aff) 165 166 Button('Disable', { type: ButtonType.Capsule, stateEffect: false }).opacity(0.4) 167 .backgroundColor(0x317aff).width(90) 168 } 169 170 Text('Circle button').fontSize(9).fontColor(0xCCCCCC) 171 Flex({ alignItems: ItemAlign.Center, wrap: FlexWrap.Wrap }) { 172 Button({ type: ButtonType.Circle, stateEffect: true }) { 173 LoadingProgress().width(20).height(20).color(0xFFFFFF) 174 }.width(55).height(55).backgroundColor(0x317aff) 175 176 Button({ type: ButtonType.Circle, stateEffect: true }) { 177 LoadingProgress().width(20).height(20).color(0xFFFFFF) 178 }.width(55).height(55).margin({ left: 20 }).backgroundColor(0xF55A42) 179 } 180 }.height(400).padding({ left: 35, right: 35, top: 35 }) 181 } 182} 183``` 184 185 186 187### Example 2 188 189```ts 190// xxx.ets 191@Entry 192@Component 193struct SwipeGestureExample { 194 @State count: number = 0 195 196 build() { 197 Column() { 198 Text(`${this.count}`) 199 .fontSize(30) 200 .onClick(() => { 201 this.count++ 202 }) 203 if (this.count <= 0) { 204 Button('count is negative').fontSize(30).height(50) 205 } else if (this.count % 2 === 0) { 206 Button('count is even').fontSize(30).height(50) 207 } else { 208 Button('count is odd').fontSize(30).height(50) 209 } 210 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 211 } 212} 213``` 214 215 216 217### Example 3 218 219```ts 220// xxx.ets 221@Entry 222@Component 223struct buttonTestDemo { 224 @State txt: string = 'overflowTextOverlengthTextOverflow.Clip'; 225 @State widthShortSize: number = 200; 226 227 build() { 228 Row() { 229 Column() { 230 Button(this.txt) 231 .width(this.widthShortSize) 232 .height(100) 233 .labelStyle({ overflow: TextOverflow.Clip, 234 maxLines: 1, 235 minFontSize: 20, 236 maxFontSize: 20, 237 font: { 238 size: 20, 239 weight: FontWeight.Bolder, 240 family: 'cursive', 241 style: FontStyle.Italic 242 } 243 }) 244 .fontSize(40) 245 } 246 .width('100%') 247 } 248 .height('100%') 249 } 250} 251``` 252 253 254 255### Example 4 256```ts 257// xxx.ets 258@Entry 259@Component 260struct ButtonExample { 261 build() { 262 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { 263 Text('Normal size button').fontSize(9).fontColor(0xCCCCCC) 264 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 265 Button('Emphasized', { buttonStyle: ButtonStyleMode.EMPHASIZED }); 266 Button('Normal', { buttonStyle: ButtonStyleMode.NORMAL }); 267 Button('Textual', { buttonStyle: ButtonStyleMode.TEXTUAL }); 268 } 269 270 Text('Small size button').fontSize(9).fontColor(0xCCCCCC) 271 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 272 Button('Emphasized', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.EMPHASIZED }); 273 Button('Normal', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.NORMAL }); 274 Button('Textual', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.TEXTUAL }); 275 } 276 277 Text('Small size button').fontSize(9).fontColor(0xCCCCCC) 278 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 279 Button('Emphasized').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.EMPHASIZED); 280 Button('Normal').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.NORMAL); 281 Button('Textual').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.TEXTUAL); 282 } 283 284 }.height(400).padding({ left: 35, right: 35, top: 35 }) 285 } 286} 287``` 288 289
