# CircularProgressBar

**Repository Path**: batee/circular-progress-bar

## Basic Information

- **Project Name**: CircularProgressBar
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-13
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ohos_circular_progress_bar

## 简介
> OpenHarmony 圆形进度条组件 - 一个功能强大且高度可定制的圆形进度条组件，支持渐变色、动画、不确定模式等多种特性。

## 功能特性

- **双进度条设计**：支持背景进度条和前景进度条独立配置
- **丰富的样式选项**：
  - 自定义进度条宽度
  - 支持纯色和双色渐变
  - 支持四种渐变方向（左到右、右到左、上到下、下到上）
  - 支持圆角边框
- **动画支持**：
  - 平滑的进度动画效果
  - 可配置动画时长、缓动函数和延迟
  - 支持不确定模式（Indeterminate Mode）自动旋转动画
- **灵活的进度控制**：
  - 支持顺时针和逆时针方向
  - 可设置起始角度和结束角度
  - 可自定义最大进度值
- **事件监听**：
  - 进度变化监听
  - 不确定模式切换监听
- **高性能渲染**：基于Canvas 2D绘制，确保流畅的动画效果

## 下载安装

```shell
ohpm install @ohos/circularprogressbar
```

OpenHarmony ohpm 环境配置等更多内容，请参考[如何安装 OpenHarmony ohpm 包](https://gitcode.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md)。

## 使用说明

### 基础用法

```typescript
import { CircularProgressBar } from '@ohos/circularprogressbar'

@Component
struct BasicExample {
  @State progress: number = 75;

  build() {
    Column() {
      CircularProgressBar({
        backgroundProgressBar: {
          width: 10,
          color: '#b6bbd8'
        },
        frontProgressBar: {
          width: 20,
          color: '#3f51b5',
          startAngle: -90,
          endAngle: 270,
          progress: this.progress,
          progressMax: 360,
          roundBorder: true
        }
      })
      .width('70%')
      .height('50%')
    }
  }
}
```

### 渐变色用法

```typescript
@Component
struct GradientExample {
  build() {
    Column() {
      CircularProgressBar({
        backgroundProgressBar: {
          width: 10,
          colorStart: '#b6bbd8',
          colorEnd: '#778899',
          colorDirection: ColorDirection.LEFT_TO_RIGHT
        },
        frontProgressBar: {
          width: 20,
          startAngle: -90,
          endAngle: 270,
          progressMax: 360,
          colorStart: '#3f51b5',
          colorEnd: '#ff4081',
          colorDirection: ColorDirection.TOP_TO_BOTTOM
        }
      })
      .width('70%')
      .height('50%')
    }
  }
}
```

### 不确定模式用法

```typescript
@Component
struct IndeterminateExample {
  @State indeterminateMode: boolean = false;

  build() {
    Column() {
      CircularProgressBar({
        backgroundProgressBar: {
          width: 10,
          color: '#b6bbd8'
        },
        frontProgressBar: {
          width: 20,
          color: '#3f51b5',
          indeterminateMode: this.indeterminateMode
        },
        setOnIndeterminateModeChangeListener: (isIndeterminate: boolean) => {
          console.info('Indeterminate mode: ' + isIndeterminate);
        }
      })
      .width('70%')
      .height('50%')

      Toggle({ type: ToggleType.Switch, isOn: this.indeterminateMode })
        .onChange((isOn: boolean) => {
          this.indeterminateMode = isOn;
        })
    }
  }
}
```

### 带动画的进度条

```typescript
@Component
struct AnimatedExample {
  @State progress: number = 0;

  build() {
    Column() {
      CircularProgressBar({
        backgroundProgressBar: {
          width: 10,
          color: '#b6bbd8'
        },
        frontProgressBar: {
          width: 20,
          color: '#3f51b5',
          progress: this.progress,
          progressMax: 100
        },
        setOnProgressChangeListener: (progress: number) => {
          console.info('Progress: ' + progress);
        },
        animationArgs: {
          progress: 100,
          duration: 2000,
          easing: 'ease'
        }
      })
      .width('70%')
      .height('50%')
    }
  }
}
```

## 接口说明

### CircularProgressBar

| 参数名 | 类型 | 必填 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- | :--- |
| backgroundProgressBar | BackgroundProgressBarImpl | 否 | - | 背景进度条配置对象 |
| frontProgressBar | FrontProgressBarImpl | 否 | - | 前景进度条配置对象 |
| setOnIndeterminateModeChangeListener | (isIndeterminate: boolean) => void | 否 | - | 不确定模式变化监听器 |
| setOnProgressChangeListener | (progress: number) => void | 否 | - | 进度变化监听器 |
| animationArgs | AnimationArgs | 否 | - | 动画参数配置对象 |

### BackgroundProgressBarImpl / FrontProgressBarImpl

| 参数名 | 类型 | 必填 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- | :--- |
| width | number | 否 | 10(背景) / 20(前景) | 进度条宽度 |
| color | string | 否 | Color.Gray | 纯色（优先使用） |
| colorStart | string | 否 | - | 渐变起始颜色 |
| colorEnd | string | 否 | - | 渐变结束颜色 |
| colorDirection | ColorDirection | 否 | LEFT_TO_RIGHT | 渐变方向 |

### FrontProgressBarImpl 额外参数

| 参数名 | 类型 | 必填 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- | :--- |
| startAngle | number | 否 | 0 | 起始角度 |
| endAngle | number | 否 | 0 | 结束角度 |
| progress | number | 否 | 0 | 当前进度 |
| progressMax | number | 否 | 100 | 最大进度值 |
| progressDirection | Direction | 否 | to_right | 进度方向（顺时针/逆时针） |
| roundBorder | boolean | 否 | false | 是否使用圆角边框 |
| indeterminateMode | boolean | 否 | false | 是否启用不确定模式 |

### AnimationArgs

| 参数名 | 类型 | 必填 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- | :--- |
| progress | number | 是 | - | 目标进度值 |
| duration | number | 否 | 1500 | 动画时长（毫秒） |
| easing | string | 否 | 'ease' | 缓动函数 |
| startDelay | number | 否 | 0 | 动画延迟（毫秒） |

### ColorDirection 枚举

| 值 | 描述 |
| :--- | :--- |
| LEFT_TO_RIGHT | 从左到右 |
| RIGHT_TO_LEFT | 从右到左 |
| TOP_TO_BOTTOM | 从上到下 |
| BOTTOM_TO_END | 从下到上 |

### Direction 枚举

| 值 | 描述 |
| :--- | :--- |
| to_right | 顺时针方向 |
| to_left | 逆时针方向 |

## 约束与限制
在下述版本验证通过：
- DevEco Studio: DevEco Studio 6.0.1 Release(6.0.1.251), SDK: API21(6.0.1.112)

## 目录结构
```text
│----─circular-progress-bar
│        ├─library       # 组件模块
│        │  └─src
│        │      ├─main
│        │         └─ets
│        │            └─components
│        │                ├─circularProgressBar.ets    # 圆形进度条主组件
│        │                ├─progressBar.ets            # 进度条基础配置
│        │                └─progressBarImpl.ets        # 进度条实现类
│        ├─entry         # 示例应用模块
│        ├─README.md     # 安装使用方法（中文）
│        └─README.en.md  # 安装使用方法（英文）
```

## 贡献代码

使用过程中发现任何问题都可以提交 [Issue](https://gitcode.com/OpenHarmony-ApplicationTPC/ohos_circular_progress_bar/issues)，当然，也非常欢迎提交 [PR](https://gitcode.com/OpenHarmony-ApplicationTPC/ohos_circular_progress_bar/pulls)。

## 开源协议

本项目遵循 [Apache-2.0](https://gitcode.com/OpenHarmony-ApplicationTPC/ohos_circular_progress_bar/blob/main/LICENSE)，请自由的享受和参与开源。