We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
Advanced filters
API versionAll
DeviceAll
Atomic service APIsNot filter by this
ReferencesApplication FrameworkArkUIArkTS ComponentsButtons and SelectionButton

Button

Phone12+PC/2in113+Tablet12+TV19+Wearable18+
Last updated: 2026-09-04 06:52
Content overview
Expand

The Button component can be used to create different types of buttons.

NOTE

This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

Child Components

This component can contain only one child component.

APIs

Button

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Button(options: ButtonOptions)

Creates a button that can contain a single child component.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
options ButtonOptions Yes Button settings.

Button

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Button(label: ResourceStr, options?: ButtonOptions)

Creates a button based on text content. In this case, the component cannot contain child components.

By default, the text content is displayed in a one line.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
label ResourceStr Yes

Button text.

Note: If the text is longer than the width of the button, it is truncated.
options ButtonOptions No Button settings.

Button

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Button()

Creates an empty button.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

ButtonOptions

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Describes the button style.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Type Read Only Optional Description
type ButtonType No Yes

Button display style.

Default value: ButtonType.ROUNDED_RECTANGLE

API version 18 and later: The default value is ButtonType.ROUNDED_RECTANGLE. Versions earlier than API version 18: The default value is ButtonType.Capsule.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.
stateEffect boolean No Yes

Whether to enable the pressed state effect when the button is clicked.

true: The pressed state effect is enabled. false: The pressed state effect is disabled.

Default value: true

NOTE

When the pressed state effect is enabled and a custom pressed state style is configured, the resulting color displayed after pressing is a composite blend of the original background color and the newly defined pressed state color.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.
buttonStyle11+ ButtonStyleMode No Yes

Style and importance of the button. The system automatically adjusts the button background color and text color based on the enumerated value. You can also use the backgroundColor, fontColor, and role APIs to set the background color and text color. The actual displayed effect will be determined by the last setting.

Default value: ButtonStyleMode.EMPHASIZED

NOTE

The button primacy is as follows, from high to low: emphasized button, normal button, text button.

Widget capability: This API can be used in ArkTS widgets since API version 11.

Atomic service API: This API can be used in atomic services since API version 12.
controlSize11+ ControlSize No Yes

Button size.

Default value: ControlSize.NORMAL

Widget capability: This API can be used in ArkTS widgets since API version 11.

Atomic service API: This API can be used in atomic services since API version 12.
role12+ ButtonRole No Yes

Role of the button. The system automatically adjusts the button background color and text color based on the enumerated value. You can also use the backgroundColor, fontColor, and buttonStyle APIs to set the background color and text color. The actual displayed effect will be determined by the last setting.

Default value: ButtonRole.NORMAL

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 12.

Attributes

In addition to the universal attributes, the following attributes are supported.

type

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

type(value: ButtonType)

Sets the button type.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value ButtonType Yes

Button type.

API version 18 and later: The default value is ButtonType.ROUNDED_RECTANGLE.

fontSize

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontSize(value: Length)

Sets the font size for the button.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value Length Yes

Font size of the button.

Default value:

$r('sys.float.Body_L') when controlSize is set to ControlSize.NORMAL

$r('sys.float.Body_S') when controlSize is set to ControlSize.SMALL

Note: For the string type, percentage values are not supported.

fontColor

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontColor(value: ResourceColor)

Sets the font color for the button.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value ResourceColor Yes

Font color of the button.

Default value: $r('sys.color.font_on_primary'), which means white

fontWeight

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontWeight(value: number | FontWeight | string)

Sets the font weight for the button.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value number | FontWeight | string Yes

Font weight of the button. For the number type, the value ranges from 100 to 900, at an interval of 100. A larger value indicates a thicker font.

Default value: 500

For the string type, only strings that represent a number, for example, '400', and the following enumerated values of FontWeight are supported: 'bold', 'bolder', 'lighter', 'regular', and 'medium'.

If the value is abnormal or invalid, the font weight defaults to 400.

fontStyle8+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontStyle(value: FontStyle)

Sets the font style for the button.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value FontStyle Yes

Font style of the button.

Default value: FontStyle.Normal

stateEffect

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

stateEffect(value: boolean)

Specifies whether to enable the pressed state effect when the button is clicked.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value boolean Yes

Whether to enable the pressed state effect when the button is clicked.

true: The pressed state effect is enabled. false: The pressed state effect is disabled.

Default value: true
NOTE

When the polymorphic style is used to set the pressed state, set stateEffect to false to avoid conflicts between the built-in and custom pressed state effects.

fontFamily8+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontFamily(value: string | Resource)

Sets the font family.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value string | Resource Yes Font family. The 'HarmonyOS Sans' font and registered custom fonts are supported.

labelStyle10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

labelStyle(value: LabelStyle)

Sets the label style for the button.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value LabelStyle Yes Label style of the button.

buttonStyle11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

buttonStyle(value: ButtonStyleMode)

Sets the style and primacy for the button. The system automatically adjusts the button background color and text color based on the enumerated value. You can also use the backgroundColor, fontColor, and role APIs to set the background color and text color. The actual displayed effect will be determined by the last setting.

NOTE

This API can be called within attributeModifier since API version 12.

Widget capability: This API can be used in ArkTS widgets since API version 11.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value ButtonStyleMode Yes

Style and primacy of the button

Default value: ButtonStyleMode.EMPHASIZED

controlSize11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

controlSize(value: ControlSize)

Sets the size for the button.

NOTE

This API can be called within attributeModifier since API version 12.

Widget capability: This API can be used in ArkTS widgets since API version 11.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value ControlSize Yes

Size of the button.

Default value: ControlSize.NORMAL

role12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

role(value: ButtonRole)

Sets the role of the button. The system automatically adjusts the button background color and text color based on the enumerated value. You can also use the backgroundColor, fontColor, and buttonStyle APIs to set the background color and text color. The actual displayed effect will be determined by the last setting.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value ButtonRole Yes

Role of the button.

Default value: ButtonRole.NORMAL

contentModifier12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

contentModifier(modifier: ContentModifier<ButtonConfiguration>)

Creates a content modifier.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
modifier ContentModifier<ButtonConfiguration> Yes

Content modifier to apply to the button.

modifier: content modifier. You need a custom class to implement the ContentModifier API.

minFontScale18+

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

minFontScale(scale: number | Resource)

Sets the minimum font scale factor for text.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
scale number | Resource Yes

Minimum font scale factor for text.

Value range: [0, 1]

NOTE

A value less than 0 is handled as 0. A value greater than 1 is handled as 1. Abnormal values are ineffective by default.

maxFontScale18+

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

maxFontScale(scale: number | Resource)

Sets the maximum font scale factor for text.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
scale number | Resource Yes

Maximum font scale factor for text.

Value range: [1, +∞)

NOTE

A value less than 1 is handled as 1. Abnormal values are ineffective by default.

If this parameter is not configured, the maximum scale for a circular button is 1x, while the maximum scale for capsule-type buttons, standard buttons, and rounded rectangle buttons defaults to the system-defined value.

ButtonType

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Enumerates the button types.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Value Description
Normal 0

Normal button, with no rounded corners by default.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.
Capsule 1

Capsule-type button (the round corner is half of the height by default).

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.
Circle 2

Circular button.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.
ROUNDED_RECTANGLE15+ 8

Rounded rectangle button (default value: when controlSize is NORMAL, the corner radius is 20 vp; when controlSize is SMALL, the corner radius is 14 vp).

Widget capability: This API can be used in ArkTS widgets since API version 15.

Atomic service API: This API can be used in atomic services since API version 15.
NOTE
  • The corner radius of the rounded rectangle button is set using the universal attribute borderRadius.
  • 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.
  • 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.
  • The button text is set using fontSize, fontColor, fontStyle, fontFamily, and fontWeight.
  • Before setting the gradient color, you need to set backgroundColor to transparent.
  • When borderRadius is not set, the corner radius of the rounded rectangle button remains at the default value. In this case, the corner radius does not change with the button height and is subject to the controlSize property. When controlSize is NORMAL, the corner radius is 20 vp; when controlSize is SMALL, the corner radius is 14 vp.
  • When border is set for the button, a default borderRadius value is automatically applied. When both border and borderRadius attributes are used, borderRadius must be specified after border to prevent the border radius from being overridden by the default radius value in the border style.

LabelStyle10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Label text and font style of the button.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Type Read Only Optional Description
overflow TextOverflow No Yes

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.

Default value: TextOverflow.Ellipsis

Atomic service API: This API can be used in atomic services since API version 11.
maxLines number No Yes

Maximum number of lines in the label text. 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.

Default value: 1

NOTE

If this parameter is set to a value less than or equal to 0, the default value is used.

Atomic service API: This API can be used in atomic services since API version 11.
minFontSize number | ResourceStr No Yes

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.

NOTE

If the value of minFontSize is less than or equal to 0, the adaptive font size does not take effect.

Atomic service API: This API can be used in atomic services since API version 11.
maxFontSize number | ResourceStr No Yes

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.

Atomic service API: This API can be used in atomic services since API version 11.
heightAdaptivePolicy TextHeightAdaptivePolicy No Yes

How the adaptive height is determined for the label text.

Default value: TextHeightAdaptivePolicy.MAX_LINES_FIRST

Atomic service API: This API can be used in atomic services since API version 11.
font Font No Yes

Font of the label text.

Default value:

{

size:'16.0fp',

weight:FontWeight.Medium,

style:FontStyle.Normal,

family:'HarmonyOS Sans'

}

Atomic service API: This API can be used in atomic services since API version 11.
textAlign23+ TextAlign No Yes

Horizontal alignment of the label text. This attribute does not take effect when the Text component of the child node is used to set the label. The actual text alignment mode is determined by the textAlign attribute of the Text component of the child node.

The default value is TextAlign.Center for wearables and TextAlign.Start for other devices.

Atomic service API: This API can be used in atomic services since API version 23.

ButtonStyleMode11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Enumerates the button importance levels.

Widget capability: This API can be used in ArkTS widgets since API version 11.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Value Description
NORMAL 0 Normal button (used to direct the user to a common task).
EMPHASIZED 1 Emphasized button (used to direct the user to the most important task).
TEXTUAL 2 Text button (displayed as simple text without any background color).

ControlSize11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Button size.

Widget capability: This API can be used in ArkTS widgets since API version 11.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Value Description
SMALL "small" Small button.
NORMAL "normal" Normal button.

ButtonRole12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Role of the button.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Value Description
NORMAL 0 Normal button.
ERROR 1 Warning button.

ButtonConfiguration12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

You need a custom class to implement the ContentModifier API. Inherits from CommonConfiguration.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Type Read Only Optional Description
label string No No

Text label of the button.

Note: If the text is longer than the width of the button, it is truncated.
pressed boolean No No

Whether the button is pressed.

true: pressed; false: not pressed.

Default value: false

NOTE

This setting applies to the original button size, not to any new component constructed using the builder.
triggerClick ButtonTriggerClickCallback No No Click event of the new component constructed using the builder.

ButtonTriggerClickCallback12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

type ButtonTriggerClickCallback = (xPos: number, yPos: number) => void

Defines the callback type used in ButtonConfiguration.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
xPos number Yes

X-coordinate of the click point.

Unit: vp
yPos number Yes

Y-coordinate of the click point.

Unit: vp

Events

The universal events are supported.

Example

Example 1: Setting the Button Display Style

This example demonstrates two methods to create buttons, either with child components or using text content.

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ButtonExample {
  5.   build() {
  6.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
  7.       Text('Normal button').fontSize(9).fontColor(0xCCCCCC)
  8.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  9.         Button('OK', { type: ButtonType.Normal, stateEffect: true })
  10.           .borderRadius(8)
  11.           .backgroundColor(0x317aff)
  12.           .width(90)
  13.           .onClick(() => {
  14.             console.info('ButtonType.Normal');
  15.           })
  16.         Button({ type: ButtonType.Normal, stateEffect: true }) {
  17.           Row() {
  18.             LoadingProgress().width(20).height(20).margin({ left: 12 }).color(0xFFFFFF)
  19.             Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 })
  20.           }.alignItems(VerticalAlign.Center)
  21.         }.borderRadius(8).backgroundColor(0x317aff).width(90).height(40)
  22. 

  23.         Button('Disable', { type: ButtonType.Normal, stateEffect: false }).opacity(0.4)
  24.           .borderRadius(8).backgroundColor(0x317aff).width(90)
  25.       }
  26. 

  27.       Text('Capsule button').fontSize(9).fontColor(0xCCCCCC)
  28.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  29.         Button('OK', { type: ButtonType.Capsule, stateEffect: true }).backgroundColor(0x317aff).width(90)
  30.         Button({ type: ButtonType.Capsule, stateEffect: true }) {
  31.           Row() {
  32.             LoadingProgress().width(20).height(20).margin({ left: 12 }).color(0xFFFFFF)
  33.             Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 })
  34.           }.alignItems(VerticalAlign.Center).width(90).height(40)
  35.         }.backgroundColor(0x317aff)
  36. 

  37.         Button('Disable', { type: ButtonType.Capsule, stateEffect: false }).opacity(0.4)
  38.           .backgroundColor(0x317aff).width(90)
  39.       }
  40. 

  41.       Text('Circle button').fontSize(9).fontColor(0xCCCCCC)
  42.       Flex({ alignItems: ItemAlign.Center, wrap: FlexWrap.Wrap }) {
  43.         Button({ type: ButtonType.Circle, stateEffect: true }) {
  44.           LoadingProgress().width(20).height(20).color(0xFFFFFF)
  45.         }.width(55).height(55).backgroundColor(0x317aff)
  46. 

  47.         Button({ type: ButtonType.Circle, stateEffect: true }) {
  48.           LoadingProgress().width(20).height(20).color(0xFFFFFF)
  49.         }.width(55).height(55).margin({ left: 20 }).backgroundColor(0xF55A42)
  50.       }
  51.     }.height(400).padding({ left: 35, right: 35, top: 35 })
  52.   }
  53. }

Example 2: Adding Render Control to a Button

This example uses if/else statements to control the display text of the button.

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct SwipeGestureExample {
  5.   @State count: number = 0;
  6. 

  7.   build() {
  8.     Column() {
  9.       Text(`${this.count}`)
  10.         .fontSize(30)
  11.         .onClick(() => {
  12.           this.count++;
  13.         })
  14.       if (this.count <= 0) {
  15.         Button('count is negative').fontSize(30).height(50)
  16.       } else if (this.count % 2 === 0) {
  17.         Button('count is even').fontSize(30).height(50)
  18.       } else {
  19.         Button('count is odd').fontSize(30).height(50)
  20.       }
  21.     }.height('100%').width('100%').justifyContent(FlexAlign.Center)
  22.   }
  23. }

Example 3: Setting the Button Text Style

This example customizes the display style of button text by configuring labelStyle.

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ButtonTestDemo {
  5.   @State txt: string = 'overflowTextOverLengthTextOverflow.Clip';
  6.   @State widthShortSize: number = 205;
  7. 

  8.   build() {
  9.     Row() {
  10.       Column() {
  11.         Button(this.txt)
  12.           .type(ButtonType.Capsule)
  13.           .width(this.widthShortSize)
  14.           .height(100)
  15.           .backgroundColor(0x317aff)
  16.           .labelStyle({ overflow: TextOverflow.Clip,
  17.             maxLines: 1,
  18.             minFontSize: 20,
  19.             maxFontSize: 20,
  20.             font: {
  21.               size: 20,
  22.               weight: FontWeight.Bolder,
  23.               family: 'cursive',
  24.               style: FontStyle.Italic
  25.             }
  26.           })
  27.           .fontSize(40)
  28.       }
  29.       .width('100%')
  30.     }
  31.     .height('100%')
  32.   }
  33. }

Example 4: Setting Importance of Different Sized Buttons

This example demonstrates how to set the importance of buttons of different sizes by configuring controlSize and buttonStyle.

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ButtonExample {
  5.   build() {
  6.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
  7.       Text('Normal size button').fontSize(9).fontColor(0xCCCCCC)
  8.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  9.         Button('Emphasized', { buttonStyle: ButtonStyleMode.EMPHASIZED });
  10.         Button('Normal', { buttonStyle: ButtonStyleMode.NORMAL });
  11.         Button('Textual', { buttonStyle: ButtonStyleMode.TEXTUAL });
  12.       }
  13. 

  14.       Text('Small size button').fontSize(9).fontColor(0xCCCCCC)
  15.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  16.         Button('Emphasized', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.EMPHASIZED });
  17.         Button('Normal', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.NORMAL });
  18.         Button('Textual', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.TEXTUAL });
  19.       }
  20. 

  21.       Text('Small size button').fontSize(9).fontColor(0xCCCCCC)
  22.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  23.         Button('Emphasized').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.EMPHASIZED);
  24.         Button('Normal').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.NORMAL);
  25.         Button('Textual').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.TEXTUAL);
  26.       }
  27. 

  28.     }.height(400).padding({ left: 35, right: 35, top: 35 })
  29.   }
  30. }

Example 5: Setting the Button Role

This example demonstrates how to set the role of the button by configuring role.

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ButtonExample {
  5.   build() {
  6.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
  7.       Text('Role is Normal button').fontSize(9).fontColor(0xCCCCCC)
  8.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  9.         Button('Emphasized', { buttonStyle: ButtonStyleMode.EMPHASIZED, role: ButtonRole.NORMAL });
  10.         Button('Normal', { buttonStyle: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL });
  11.         Button('Textual', { buttonStyle: ButtonStyleMode.TEXTUAL, role: ButtonRole.NORMAL });
  12.       }
  13.       Text('Role is Error button').fontSize(9).fontColor(0xCCCCCC)
  14.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  15.         Button('Emphasized', { buttonStyle: ButtonStyleMode.EMPHASIZED, role: ButtonRole.ERROR});
  16.         Button('Normal', { buttonStyle: ButtonStyleMode.NORMAL, role: ButtonRole.ERROR });
  17.         Button('Textual', { buttonStyle: ButtonStyleMode.TEXTUAL, role: ButtonRole.ERROR });
  18.       }
  19.     }.height(200).padding({ left: 15, right: 15, top: 35 })
  20.   }
  21. }

Example 6: Implementing a Custom Button

This example implements a custom button in the shape of a circle. The circle is red when pressed, accompanied by the text "Pressed" in the title. It is black when not pressed, accompanied by the text "Not pressed" in the title.

Collapse
Word wrap
Dark theme
Copy code
  1. class MyButtonStyle implements ContentModifier<ButtonConfiguration> {
  2.   x: number = 0;
  3.   y: number = 0;
  4.   selectedColor: Color = Color.Black;
  5. 

  6.   constructor(x: number, y: number, colorType: Color) {
  7.     this.x = x;
  8.     this.y = y;
  9.     this.selectedColor = colorType;
  10.   }
  11. 

  12.   applyContent(): WrappedBuilder<[ButtonConfiguration]> {
  13.     return wrapBuilder(buildButton1);
  14.   }
  15. }
  16. 

  17. @Builder
  18. function buildButton1(config: ButtonConfiguration) {
  19.   Column({ space: 30 }) {
  20.     Text(config.enabled ? "enabled true" : "enabled false")
  21.     Text('Circle state' + (config.pressed? "(Pressed)" : "(Not pressed)"))
  22.     Text('X-coordinate of the click point:' + (config.enabled ? (config.contentModifier as MyButtonStyle).x : "0"))
  23.     Text('Y-coordinate of the click point:' + (config.enabled ? (config.contentModifier as MyButtonStyle).y : "0"))
  24.     Circle({ width: 50, height: 50 })
  25.       .fill(config.pressed ? (config.contentModifier as MyButtonStyle).selectedColor : Color.Black)
  26.       .gesture(
  27.         TapGesture({ count: 1 }).onAction((event: GestureEvent) => {
  28.           config.triggerClick(event.fingerList[0].localX, event.fingerList[0].localY)
  29.         })).opacity(config.enabled ? 1 : 0.1)
  30.   }
  31. }
  32. 

  33. @Entry
  34. @Component
  35. struct ButtonExample {
  36.   @State buttonEnabled: boolean = true;
  37.   @State positionX: number = 0;
  38.   @State positionY: number = 0;
  39.   @State state: boolean[] = [true, false];
  40.   @State index: number = 0;
  41. 

  42.   build() {
  43.     Column() {
  44.       Button('OK')
  45.         .contentModifier(new MyButtonStyle(this.positionX, this.positionY, Color.Red))
  46.         .onClick((event) => {
  47.           console.info('change' + JSON.stringify(event));
  48.           this.positionX = event.displayX;
  49.           this.positionY = event.displayY;
  50.         }).enabled(this.buttonEnabled)
  51.       Row() {
  52.         Toggle({ type: ToggleType.Switch, isOn: true }).onChange((value: boolean) => {
  53.           if (value) {
  54.             this.buttonEnabled = true;
  55.           } else {
  56.             this.buttonEnabled = false;
  57.           }
  58.         }).margin({ left: -80 })
  59.       }
  60.     }.height('100%').width('100%').justifyContent(FlexAlign.Center)
  61.   }
  62. }

Example 7: Setting Rounded Rectangle Buttons

This example creates rounded rectangle buttons by configuring ButtonType.ROUNDED_RECTANGLE.

Collapse
Word wrap
Dark theme
Copy code
  1. @Entry
  2. @Component
  3. struct ButtonExample {
  4.   build() {
  5.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
  6.       Text('Rounded rectangle button with rounded corners by default.').fontSize(9).fontColor(0xCCCCCC)
  7.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  8.         Button('Rounded rectangle')
  9.           .type(ButtonType.ROUNDED_RECTANGLE)
  10.           .backgroundColor(0x317aff)
  11.           .controlSize(ControlSize.NORMAL)
  12.           .width(180)
  13.       }
  14.       Text('Rounded rectangle button configured with a borderRadius of 5.').fontSize(9).fontColor(0xCCCCCC)
  15.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  16.         Button('Rounded rectangle')
  17.           .type(ButtonType.ROUNDED_RECTANGLE)
  18.           .backgroundColor(0x317aff)
  19.           .controlSize(ControlSize.NORMAL)
  20.           .width(180)
  21.           .borderRadius(5)
  22.       }
  23.       Text('Rounded rectangle button configured extra long text.').fontSize(9).fontColor(0xCCCCCC)
  24.       Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  25.         Button('Rounded rectangle Rounded rectangle Rounded rectangle Rounded rectangle')
  26.           .type(ButtonType.ROUNDED_RECTANGLE)
  27.           .backgroundColor(0x317aff)
  28.           .width(180)
  29.           .labelStyle({overflow:TextOverflow.Ellipsis, maxLines:3, minFontSize: 0})
  30.       }
  31.     }.height(400).padding({ left: 35, right: 35, top: 35 })
  32.   }
  33. }

Example 8 (Setting the Horizontal Alignment Mode of the Label Text)

This example shows how to set the text alignment mode by configuring textAlign of LabelStyle.

The textAlign API is supported since API version 23.

Collapse
Word wrap
Dark theme
Copy code
  1. @Entry
  2. @Component
  3. struct Index {
  4.   build() {
  5.     Column(){
  6.       Button('helloWorld helloWorld helloWorld helloWorld helloWorld helloWorld')
  7.         .width(200)
  8.         .labelStyle({
  9.           textAlign: TextAlign.Center
  10.         })
  11.     }
  12.     .width('100%')
  13.     .alignItems(HorizontalAlign.Center)
  14.   }
  15. }

Buttons and Selection
Toggle
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice