harmony 鸿蒙ProgressButtonV2

2025-06-12
浏览 (2)

ProgressButtonV2

The ProgressButtonV2 component is a download button with a progress indicator that shows the download progress.

This component is implemented based on state management V2. Compared with state management V1, V2 offers a higher level of observation and management over data objects beyond the component level. You can now more easily manage download button data and states with greater flexibility, leading to faster UI updates.

NOTE

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

Modules to Import

import { ColorMetrics, LengthMetrics, ProgressButtonV2,  ProgressButtonV2Color } from '@kit.ArkUI'

ProgressButtonV2

ProgressButtonV2({progress: number, content: ResourceStr, progressButtonWidth?: LengthMetrics, onClicked: ClickCallback, isEnabled: boolean, colorOptions?: ProgressButtonColorOptions, progressButtonRadius?: LengthMetrics})

The ProgressButton component is a download button with a progress indicator that shows the download progress.

Decorator: \@ComponentV2

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Decorator	Description
progress	number	Yes	\@Require \@Param	Current download progress. The value ranges from 0 to 100. Values less than 0 are adjusted to 0, and values greater than 100 are capped at 100. Default value: 0
content	ResourceStr	Yes	\@Require \@Param	Button text.
progressButtonWidth	LengthMetrics	No	\@Param \@Once	Width of the button. Default value: 44vp
onClicked	ClickCallback	Yes	\@Param	Callback invoked when the button is clicked.
isEnabled	boolean	Yes	\@Param	Whether the button can be clicked. true: The button can be clicked. false: The button cannot be clicked.
colorOptions	ProgressButtonV2Color	No	\@Param	Color options for the button. Default value: undefined
progressButtonRadius¹⁸⁺	LengthMetrics	No	\@Param	Corner radius of the button. It cannot be set in percentage. Value range: [0, height/2] Default value: height/2 If an invalid value is set, the default value is used.

Attributes

The universal attributes are not supported.

ClickCallback

type ClickCallback = () => void

Callback invoked when the button is clicked.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

ProgressButtonV2Color

Defines the color options for the download button.

Decorator type: @ObservedV2

Properties

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Decorator	Description
progressColor	ColorMetrics	No	\@Trace	Color of the progress indicator. Default value: undefined
borderColor	ColorMetrics	No	\@Trace	Border color of the button. Default value: undefined
textColor	ColorMetrics	No	\@Trace	Text color of the button. Default value: undefined
backgroundColor	ColorMetrics	No	\@Trace	Background color of the button. Default value: undefined

constructor

constructor(options: ProgressButtonV2ColorOptions);

A constructor used to create a ProgressButtonV2Color object.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
options	ProgressButtonV2ColorOptions	Yes	Color settings.

ProgressButtonV2ColorOptions

Provides options for customizing the color of the download button.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
progressColor	ColorMetrics	No	Color of the progress indicator. Default value: undefined
borderColor	ColorMetrics	No	Border color of the button. Default value: undefined
textColor	ColorMetrics	No	Text color of the button. Default value: undefined
backgroundColor	ColorMetrics	No	Background color of the button. Default value: undefined

Events

The universal events are not supported.

Example

This example demonstrates how to create a simple download button with a progress indicator that shows the loading status of a text file.

import { ColorMetrics, LengthMetrics, ProgressButtonV2, ProgressButtonV2Color } from '@kit.ArkUI'

@Entry
@ComponentV2
struct Index {
  @Local progressIndex: number = 0;
  @Local textState: string = 'Download';
  @Local ButtonWidth: LengthMetrics = LengthMetrics.vp(200);
  @Local isRunning: boolean = false;
  @Local enableState: boolean = true;

  build() {
    Column() {
      Scroll() {
        Column({ space: 20 }) {
          ProgressButtonV2({
            progress: this.progressIndex,
            progressButtonWidth: this.ButtonWidth,
            content: this.textState,
            isEnabled: this.enableState,
            onClicked: () => {
              if (this.textState && !this.isRunning && this.progressIndex < 100) {
                this.textState = 'Continue';
              }
              this.isRunning = !this.isRunning;
              let timer = setInterval(() => {
                if (this.isRunning) {
                  if (this.progressIndex === 100) {

                  } else {
                    this.progressIndex++
                    if (this.progressIndex === 100) {
                      this.textState = 'Completed';
                      this.enableState = false;
                    }
                  }
                } else {
                  clearInterval(timer);
                }
              }, 20);
            }
          })
        }.alignItems(HorizontalAlign.Center).width('100%').margin({ top: 20 });
      }
    }
  }
}