自学记录：用鸿蒙API 13 开发一个专业的进度条与二维码组件

这篇文章，我会结合自己的学习故事，讲解如何使用 API 13 的全新能力，打造一个进度条和二维码展示组件，并以实际开发项目作为成果展示。

我的学习路线：从文档到实践

如果正在看的同学如果你不了解鸿蒙，那么我简单说一下，鸿蒙目前需要使用ArkUI配合ArkTS进行开发。它们不仅支持声明式开发，还通过 DSL (领域专用语言) 的设计，使代码更高效、模块化。于是，我们从以下几点展开学习：

1. 了解进度条与二维码组件的能力\
   官方文档详细描述了 Progress 和 QRCode 的全新属性和用法，包括支持自定义样式、动态更新和多种事件监听。
2. 设计项目需求\
   我决定开发一个包含进度条和二维码展示的小工具：一个“下载助手”，显示下载进度，并在下载完成后生成下载链接对应的二维码。

---

第一步：配置开发环境

开始开发前，我花了一些时间配置开发环境。通过 HarmonyOS DevEco Studio，我快速创建了一个 ArkTS 项目。

# 确保使用的是最新环境
npm install -g @hmscore/harmonyos-cli
harmonyos-cli create my-harmony-app

进入项目后，我根据需求调整了 config.json 配置文件，确保项目运行在 API 13 环境下。

---

第二步：打造动态进度条

进度条是项目中的第一个核心组件。学习过程中，我发现 Progress 的新 API 十分强大，支持灵活的属性绑定和事件监听。

实现代码：

@Entry
@Component
struct DownloadProgress {
  private progressValue: number = 0;

  build() {
    Column({ space: 16 }) {
      Text('下载助手').fontSize(24).fontWeight(FontWeight.Bold).margin({ bottom: 16 });

      Progress({ value: this.progressValue })
        .width('100%')
        .height(10)
        .backgroundColor('#F0F0F0')
        .progressColor('#00BCD4')
        .onChange((value: number) => {
          console.info(`当前进度: ${value}%`);
        });

      Button('开始下载')
        .onClick(() => this.startDownload());
    }.padding(16);
  }

  private startDownload() {
    let interval = setInterval(() => {
      this.progressValue += 10;
      if (this.progressValue >= 100) {
        clearInterval(interval);
        this.progressValue = 100;
        console.info('下载完成！');
      }
    }, 1000);
  }
}

解读：

• Progress 组件通过 value 属性动态控制进度值。
• 使用 onChange 方法监听进度变化，这在实际开发中非常实用。

遇到的坑：

起初，我试图直接更新 value 属性，却发现进度条没有响应。后来才了解到，数据绑定需要通过 @State 或直接绑定变量才生效。

---

第三步：生成二维码

下载完成后，我希望展示一个二维码，方便用户扫描链接。我发现 QRCode 组件支持自定义大小、颜色和容错级别，非常适合这种需求。

实现代码：

@Entry
@Component
struct QRCodeDisplay {
  private downloadUrl: string = 'https://example.com/myfile.zip';

  build() {
    Column({ space: 16 }) {
      Text('扫描二维码下载文件')
        .fontSize(20)
        .margin({ bottom: 12 });

      QRCode({ value: this.downloadUrl })
        .width(200)
        .height(200)
        .color('#000000')
        .backgroundColor('#FFFFFF')
        .errorCorrectionLevel('H'); // 高容错级别

      Button('复制链接')
        .onClick(() => this.copyToClipboard(this.downloadUrl));
    }.padding(16);
  }

  private copyToClipboard(text: string) {
    // 模拟剪贴板复制逻辑
    console.info(`链接已复制: ${text}`);
  }
}

解读：

• QRCode 的 value 属性绑定了下载链接，随时可以动态修改内容。
• 通过 errorCorrectionLevel 设置二维码的容错率，确保即使部分二维码受损也能正常读取。

遇到的坑：

在开发过程中，二维码生成组件的 value 必须是非空字符串，否则组件不会渲染。

---

第四步：整合进度条和二维码

最终，我将两个组件整合在一个页面中，构建了完整的“下载助手”。

完整代码：

@Entry
@Component
struct DownloadAssistant {
  private progressValue: number = 0;
  private isDownloadComplete: boolean = false;

  build() {
    Column({ space: 16 }) {
      Text('下载助手').fontSize(24).fontWeight(FontWeight.Bold).margin({ bottom: 16 });

      if (!this.isDownloadComplete) {
        Progress({ value: this.progressValue })
          .width('100%')
          .height(10)
          .backgroundColor('#F0F0F0')
          .progressColor('#00BCD4');

        Button('开始下载')
          .onClick(() => this.startDownload());
      } else {
        QRCode({ value: 'https://example.com/myfile.zip' })
          .width(200)
          .height(200)
          .color('#000000')
          .backgroundColor('#FFFFFF')
          .errorCorrectionLevel('H');
      }
    }.padding(16);
  }

  private startDownload() {
    let interval = setInterval(() => {
      this.progressValue += 10;
      if (this.progressValue >= 100) {
        clearInterval(interval);
        this.progressValue = 100;
        this.isDownloadComplete = true;
      }
    }, 1000);
  }
}

---

结语：学习与反思

这次开发让我深刻体会到 HarmonyOS Next API 13 的强大和灵活性。ArkTS 与 ArkUI 的组合，既简洁又高效，能让开发者快速上手，同时充分利用鸿蒙生态的能力。整个项目虽然简单，但涵盖了动态组件、数据绑定、事件监听等核心开发技能。如果你也在学习 HarmonyOS，不妨尝试基于此案例进行拓展，打造属于自己的鸿蒙应用！

当然如果你也在这一领域研究，不妨关注我，我们一起进步～！