1# Button 2 3按钮组件，可快速创建不同样式的按钮。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12可以包含单个子组件。 13 14 15## 接口 16 17### Button 18 19Button(options: ButtonOptions) 20 21创建可以包含单个子组件的按钮。 22 23**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 24 25**系统能力：** SystemCapability.ArkUI.ArkUI.Full 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------- | --------------------------------------- | ---- | -------------------- | 31| options | [ButtonOptions](#buttonoptions对象说明) | 是 | 配置按钮的显示样式。 | 32 33### Button 34 35Button(label: ResourceStr, options?: ButtonOptions) 36 37使用文本内容创建相应的按钮组件，此时Button无法包含子组件。 38 39**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 40 41**系统能力：** SystemCapability.ArkUI.ArkUI.Full 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| ------- | --------------------------------------- | ---- | -------------------- | 47| label | [ResourceStr](ts-types.md#resourcestr) | 是 | 按钮文本内容。 | 48| options | [ButtonOptions](#buttonoptions对象说明) | 否 | 配置按钮的显示样式。 | 49 50## ButtonOptions对象说明 51 52| 名称 | 类型 | 必填 | 描述 | 53| ------------------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 54| type | [ButtonType](#buttontype枚举说明) | 否 | 描述按钮显示样式。<br/>默认值：ButtonType.Capsule | 55| stateEffect | boolean | 否 | 按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。<br/>默认值：true<br/>**说明：** <br/>当开启按压态显示效果，开发者设置状态样式时，会基于状态样式设置完成后的背景色再进行颜色叠加。 | 56| buttonStyle<sup>11+</sup> | [ButtonStyleMode](#buttonstylemode11枚举说明) | 否 | 描述按钮的样式和重要程度。<br/>默认值：ButtonStyleMode.EMPHASIZED <br/>**说明：** <br/>按钮重要程度：强调按钮>普通按钮>文字按钮。 | 57| controlSize<sup>11+</sup> | [ControlSize](#controlsize11枚举说明) | 否 | 描述按钮的尺寸。<br/>默认值：ControlSize.NORMAL | 58 59## 属性 60 61除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 62 63| 名称 | 参数类型 | 描述 | 64| ----------- | ----------- | --------------------------------- | 65| type | [ButtonType](#buttontype枚举说明) | 设置Button样式。<br/>默认值：ButtonType.Capsule<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 66| value | [Length](ts-types.md#length) | 是 | 文本显示字号。<br/>默认值：若controlSize的值为：controlSize.NORMAL，取'16fp'，若controlSize的值为：controlSize.SMALL，取'12fp' | 67| fontColor | [ResourceColor](ts-types.md#resourcecolor) | 设置文本显示颜色。<br/>默认值：'\#ffffff' | 68| fontWeight | [FontWeight](ts-appendix-enums.md#fontweight) \| number \| string | 设置文本的字体粗细，number类型取值[100, 900]，取值间隔为100，取值越大，字体越粗。<br>默认值：400 \| FontWeight.Normal | 69| fontStyle | [FontStyle](ts-appendix-enums.md#fontstyle) | 设置文本的字体样式。<br>默认值：FontStyle.Normal。 | 70| fontFamily | [Resource](ts-types.md#resource) \| string | 字体列表。默认字体'HarmonyOS Sans'，当前支持'HarmonyOS Sans'字体和[注册自定义字体](../js-apis-font.md)。 | 71| stateEffect | boolean | 按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。<br/>默认值：true<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 72| labelStyle<sup>10+</sup> | [LabelStyle](#labelstyle10对象说明) | 设置Button组件label文本和字体的样式。 | 73| buttonStyle<sup>11+</sup> | [ButtonStyleMode](#buttonstylemode11枚举说明) | 设置Button组件的样式和重要程度。<br>默认值:ButtonStyleMode.EMPHASIZED。 | 74| controlSize<sup>11+</sup> | [ControlSize](#controlsize11枚举说明) | 设置Button组件的尺寸。<br>默认值:ControlSize.NORMAL。 | 75 76## ButtonType枚举说明 77 78从API version 9开始，该接口支持在ArkTS卡片中使用。 79 80| 名称 | 描述 | 81| ------- | ------------------ | 82| Capsule | 胶囊型按钮（圆角默认为高度的一半）。 | 83| Circle | 圆形按钮。 | 84| Normal | 普通按钮（默认不带圆角）。 | 85 86> **说明：** 87> - 按钮圆角通过[通用属性borderRadius](ts-universal-attributes-border.md#borderradius)设置（不支持通过border接口设置圆角），且只支持设置参数为[Length](ts-types.md#length)的圆角。 88> - 当按钮类型为Capsule时，borderRadius设置不生效，按钮圆角始终为宽、高中较小值的一半。 89> - 当按钮类型为Circle时，若同时设置了宽和高，则borderRadius不生效，且按钮半径为宽高中较小值的一半；若只设置宽、高中的一个，则borderRadius不生效，且按钮半径为所设宽或所设高值的一半；若不设置宽高，则borderRadius为按钮半径；若borderRadius的值为负，则borderRadius的值按照0处理。 90> - 按钮文本通过[通用文本样式](ts-universal-attributes-text-style.md#属性)进行设置。 91> - 设置[颜色渐变](ts-universal-attributes-gradient-color.md)需先设置[backgroundColor](ts-universal-attributes-background.md#backgroundcolor)为透明色。 92 93## LabelStyle<sup>10+</sup>对象说明 94 95| 名称 | 参数类型 | 必填 | 描述 | 96| -------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 97| overflow | [TextOverflow](ts-appendix-enums.md#textoverflow) | 否 | 设置Label文本超长时的显示方式。文本截断是按字截断。例如，英文以单词为最小单位进行截断，若需要以字母为单位进行截断，可在字母间添加零宽空格。<br>默认值：TextOverflow.Ellipsis | 98| maxLines | number | 否 | 设置Label文本的最大行数。默认情况下，文本是自动折行的，如果指定此参数，则文本最多不会超过指定的行。如果有多余的文本，可以通过overflow来指定截断方式。<br>默认值：1 | 99| minFontSize | number \| [ResourceStr](ts-types.md#resourcestr) | 否 | 设置Label文本最小显示字号。需配合maxFontSize以及maxLines或布局大小限制使用。 | 100| maxFontSize | number \| [ResourceStr](ts-types.md#resourcestr) | 否 | 设置Label文本最大显示字号。需配合minFontSize以及maxLines或布局大小限制使用。 | 101| heightAdaptivePolicy | [TextHeightAdaptivePolicy](ts-appendix-enums.md#textheightadaptivepolicy10) | 否 | 设置Label文本自适应高度的方式。<br>默认值：TextHeightAdaptivePolicy.MAX_LINES_FIRST。 | 102| font | [Font](ts-types.md#font) | 否 | 设置Label文本字体样式。<br>默认值：默认值参考[Font](ts-types.md#font)。 | 103 104## ButtonStyleMode<sup>11+</sup>枚举说明 105 106从API version 11开始，该接口支持在ArkTS卡片中使用。 107 108| 名称 | 描述 | 109| ------- | ------------------ | 110| EMPHASIZED | 强调按钮（用于强调当前操作）。 | 111| NORMAL | 普通按钮（一般界面操作）。 | 112| TEXTUAL | 文本按钮（纯文本，无背景颜色）。 | 113 114## ControlSize<sup>11+</sup>枚举说明 115 116从API version 11开始，该接口支持在ArkTS卡片中使用。 117 118| 名称 | 描述 | 119| ------- | ------------------ | 120| SMALL | 小尺寸按钮。 | 121| NORMAL | 正常尺寸按钮。 | 122 123## 事件 124 125支持[通用事件](ts-universal-events-click.md)。 126## 示例 127 128### 示例1 129 130```ts 131// xxx.ets 132@Entry 133@Component 134struct ButtonExample { 135 build() { 136 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { 137 Text('Normal button').fontSize(9).fontColor(0xCCCCCC) 138 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 139 Button('OK', { type: ButtonType.Normal, stateEffect: true }) 140 .borderRadius(8) 141 .backgroundColor(0x317aff) 142 .width(90) 143 .onClick(() => { 144 console.log('ButtonType.Normal') 145 }) 146 Button({ type: ButtonType.Normal, stateEffect: true }) { 147 Row() { 148 LoadingProgress().width(20).height(20).margin({ left: 12 }).color(0xFFFFFF) 149 Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 }) 150 }.alignItems(VerticalAlign.Center) 151 }.borderRadius(8).backgroundColor(0x317aff).width(90).height(40) 152 153 Button('Disable', { type: ButtonType.Normal, stateEffect: false }).opacity(0.4) 154 .borderRadius(8).backgroundColor(0x317aff).width(90) 155 } 156 157 Text('Capsule button').fontSize(9).fontColor(0xCCCCCC) 158 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 159 Button('OK', { type: ButtonType.Capsule, stateEffect: true }).backgroundColor(0x317aff).width(90) 160 Button({ type: ButtonType.Capsule, stateEffect: true }) { 161 Row() { 162 LoadingProgress().width(20).height(20).margin({ left: 12 }).color(0xFFFFFF) 163 Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 }) 164 }.alignItems(VerticalAlign.Center).width(90).height(40) 165 }.backgroundColor(0x317aff) 166 167 Button('Disable', { type: ButtonType.Capsule, stateEffect: false }).opacity(0.4) 168 .backgroundColor(0x317aff).width(90) 169 } 170 171 Text('Circle button').fontSize(9).fontColor(0xCCCCCC) 172 Flex({ alignItems: ItemAlign.Center, wrap: FlexWrap.Wrap }) { 173 Button({ type: ButtonType.Circle, stateEffect: true }) { 174 LoadingProgress().width(20).height(20).color(0xFFFFFF) 175 }.width(55).height(55).backgroundColor(0x317aff) 176 177 Button({ type: ButtonType.Circle, stateEffect: true }) { 178 LoadingProgress().width(20).height(20).color(0xFFFFFF) 179 }.width(55).height(55).margin({ left: 20 }).backgroundColor(0xF55A42) 180 } 181 }.height(400).padding({ left: 35, right: 35, top: 35 }) 182 } 183} 184``` 185 186 187 188### 示例2 189 190```ts 191// xxx.ets 192@Entry 193@Component 194struct SwipeGestureExample { 195 @State count: number = 0 196 197 build() { 198 Column() { 199 Text(`${this.count}`) 200 .fontSize(30) 201 .onClick(() => { 202 this.count++ 203 }) 204 if (this.count <= 0) { 205 Button('count is negative').fontSize(30).height(50) 206 } else if (this.count % 2 === 0) { 207 Button('count is even').fontSize(30).height(50) 208 } else { 209 Button('count is odd').fontSize(30).height(50) 210 } 211 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 212 } 213} 214``` 215 216 217 218### 示例3 219 220```ts 221// xxx.ets 222@Entry 223@Component 224struct buttonTestDemo { 225 @State txt: string = 'overflowTextOverlengthTextOverflow.Clip'; 226 @State widthShortSize: number = 200; 227 228 build() { 229 Row() { 230 Column() { 231 Button(this.txt) 232 .width(this.widthShortSize) 233 .height(100) 234 .labelStyle({ overflow: TextOverflow.Clip, 235 maxLines: 1, 236 minFontSize: 20, 237 maxFontSize: 20, 238 font: { 239 size: 20, 240 weight: FontWeight.Bolder, 241 family: 'cursive', 242 style: FontStyle.Italic 243 } 244 }) 245 .fontSize(40) 246 } 247 .width('100%') 248 } 249 .height('100%') 250 } 251} 252``` 253 254 255 256### 示例4 257```ts 258// xxx.ets 259@Entry 260@Component 261struct ButtonExample { 262 build() { 263 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { 264 Text('Normal size button').fontSize(9).fontColor(0xCCCCCC) 265 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 266 Button('Emphasized', { buttonStyle: ButtonStyleMode.EMPHASIZED }); 267 Button('Normal', { buttonStyle: ButtonStyleMode.NORMAL }); 268 Button('Textual', { buttonStyle: ButtonStyleMode.TEXTUAL }); 269 } 270 271 Text('Small size button').fontSize(9).fontColor(0xCCCCCC) 272 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 273 Button('Emphasized', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.EMPHASIZED }); 274 Button('Normal', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.NORMAL }); 275 Button('Textual', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.TEXTUAL }); 276 } 277 278 Text('Small size button').fontSize(9).fontColor(0xCCCCCC) 279 Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) { 280 Button('Emphasized').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.EMPHASIZED); 281 Button('Normal').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.NORMAL); 282 Button('Textual').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.TEXTUAL); 283 } 284 285 }.height(400).padding({ left: 35, right: 35, top: 35 }) 286 } 287} 288``` 289
