Flutter for OpenHarmony：打造专属自定义组件

Flutter for OpenHarmony：打造专属自定义组件

在 Flutter for OpenHarmony 开发中，当内置组件无法满足特定 UI 或交互需求时，开发者需构建自定义组件。Flutter 提供两种主要路径：组合现有 Widget（适用于结构化 UI）和CustomPaint+Canvas绘制（适用于图形、动画或像素级控制）。本文以“圆形进度条”为例，完整演示如何从零实现一个高性能、可配置、可复用的自定义绘制组件，并将其封装为独立 Dart 包，同时分析其在 OpenHarmony 渲染引擎下的性能表现与优化策略。

目录

• 1. 自定义组件的两种实现路径
• 2. 需求分析：圆形进度条功能定义
• 3. 使用 CustomPaint 实现绘制逻辑
  • 3.1 创建 CircularProgressBarPainter
  • 3.2 实现 paint 方法
• 4. 封装为 StatelessWidget 组件
• 5. 支持动画与状态更新
• 6. 封装为独立 Dart 包
• 7. OpenHarmony 渲染性能分析与优化
• 8. 总结

1. 自定义组件的两种实现路径

本文选择CustomPaint路径，因为圆形进度条涉及弧线绘制、角度计算、抗锯齿等图形操作，组合方式难以高效实现。

2. 需求分析：圆形进度条功能定义

目标组件需支持以下特性：

• 可配置外圈（轨道）颜色与宽度
• 可配置进度条颜色与宽度
• 进度值范围：0.0 ~ 1.0
• 支持中心文本显示（如百分比）
• 可选是否带动画
• 适配不同尺寸（通过size自适应）

3. 使用 CustomPaint 实现绘制逻辑

3.1 创建 CircularProgressBarPainter

继承CustomPainter，接收绘制参数：

classCircularProgressBarPainterextendsCustomPainter{finaldouble progress;finalColortrackColor;finalColorprogressColor;finaldouble trackWidth;finaldouble progressWidth;constCircularProgressBarPainter({requiredthis.progress,this.trackColor=Colors.grey,this.progressColor=Colors.blue,this.trackWidth=6.0,this.progressWidth=6.0,});@overridevoidpaint(Canvascanvas,Sizesize){// 绘制逻辑见下文}@overrideboolshouldRepaint(covariantCircularProgressBarPainteroldDelegate){returnoldDelegate.progress!=progress||oldDelegate.trackColor!=trackColor||oldDelegate.progressColor!=progressColor;}}

关键点：

• 所有绘制参数通过构造函数传入
• shouldRepaint决定是否重绘，避免无效刷新

3.2 实现 paint 方法

@overridevoidpaint(Canvascanvas,Sizesize){finalcenter=Offset(size.width/2,size.height/2);finalradius=math.min(size.width,size.height)/2-math.max(trackWidth,progressWidth);// 1. 绘制轨道（完整圆）finaltrackPaint=Paint()..color=trackColor..strokeWidth=trackWidth..style=PaintingStyle.stroke..strokeCap=StrokeCap.round;canvas.drawCircle(center,radius,trackPaint);// 2. 绘制进度弧if(progress>0){finalprogressPaint=Paint()..color=progressColor..strokeWidth=progressWidth..style=PaintingStyle.stroke..strokeCap=StrokeCap.round;finalsweepAngle=360*progress;// 转换为角度canvas.drawArc(Rect.fromCircle(center:center,radius:radius),degreesToRadians(-90),// 从顶部开始（-90°）degreesToRadians(sweepAngle),false,progressPaint,);}}// 辅助函数：角度转弧度doubledegreesToRadians(double degrees)=>degrees*(math.pi/180);

注意：

• 使用math.min确保半径不超出容器
• drawArc的起始角设为-90°（即 12 点钟方向）
• 启用StrokeCap.round使两端圆润

4. 封装为 StatelessWidget 组件

将CustomPaint包装为易用的 Widget：

classCircularProgressBarextendsStatelessWidget{finaldouble progress;finalColor?trackColor;finalColor?progressColor;finaldouble?trackWidth;finaldouble?progressWidth;finalWidget?centerChild;constCircularProgressBar({super.key,requiredthis.progress,this.trackColor,this.progressColor,this.trackWidth,this.progressWidth,this.centerChild,});@overrideWidgetbuild(BuildContextcontext){returnCustomPaint(painter:CircularProgressBarPainter(progress:progress.clamp(0.0,1.0),trackColor:trackColor??Theme.of(context).disabledColor,progressColor:progressColor??Theme.of(context).primaryColor,trackWidth:trackWidth??6.0,progressWidth:progressWidth??6.0,),child:Center(child:centerChild),);}}

设计亮点：

• 支持centerChild插槽，可嵌入任意 Widget（如Text、Icon）
• 自动从Theme获取默认颜色，适配深色/浅色模式
• 对progress做安全 clamp，防止越界

5. 支持动画与状态更新

结合AnimationController实现平滑进度过渡：

classAnimatedCircularProgressextendsStatefulWidget{finaldouble targetProgress;finalDurationduration;constAnimatedCircularProgress({super.key,requiredthis.targetProgress,this.duration=constDuration(milliseconds:500),});@overrideState<AnimatedCircularProgress>createState()=>_AnimatedCircularProgressState();}class_AnimatedCircularProgressStateextendsState<AnimatedCircularProgress>withSingleTickerProviderStateMixin{lateAnimationController_controller;lateAnimation<double>_animation;@overridevoidinitState(){super.initState();_controller=AnimationController(vsync:this,duration:widget.duration);_animation=Tween<double>(begin:0.0,end:widget.targetProgress).animate(_controller);_controller.forward();}@overridevoiddidUpdateWidget(covariantAnimatedCircularProgressoldWidget){super.didUpdateWidget(oldWidget);if(oldWidget.targetProgress!=widget.targetProgress){_controller.animateTo(widget.targetProgress);}}@overridevoiddispose(){_controller.dispose();super.dispose();}@overrideWidgetbuild(BuildContextcontext){returnAnimatedBuilder(animation:_animation,builder:(context,child){returnCircularProgressBar(progress:_animation.value,centerChild:Text('${(_animation.value*100).toInt()}%'),);},);}}

6. 封装为独立 Dart 包

为在多个 OpenHarmony 项目中复用，可将其发布为私有或公开 Dart 包。

步骤：

1. 创建新包项目：

   flutter create --template=package circular_progress_ohos

2. 将CircularProgressBar和CircularProgressBarPainter移至lib/src/
3. 在lib/circular_progress_ohos.dart中导出：

   export'src/circular_progress_bar.dart';

4. 更新pubspec.yaml元信息（name、description、version）
5. 发布到私有 Pub 服务器或 Git 仓库

在 OpenHarmony 项目中引用：

dependencies:circular_progress_ohos:git:url:https://your-git-repo/circular_progress_ohos.git

优势：版本管理、跨项目复用、团队共享。

7. OpenHarmony 渲染性能分析与优化

7.1 性能实测（OpenHarmony 4.0 手机）

7.2 优化建议

• 避免频繁重建CustomPainter：确保shouldRepaint逻辑精准
• 使用RepaintBoundary：若组件独立变化，可隔离重绘区域

  RepaintBoundary(child:CircularProgressBar(...),)

• 限制动画帧率：对非关键动画，可降至 30fps 节省资源
• 预计算常量：如degreesToRadians(-90)可缓存为静态常量

OpenHarmony 的 Flutter 引擎基于 Skia，与 Android/iOS 行为一致，上述优化策略通用有效。

8. 总结

通过CustomPaint实现自定义绘制组件，是 Flutter for OpenHarmony 中处理图形类 UI 的标准方案。关键在于：

• 精准控制绘制逻辑：合理使用CanvasAPI
• 高效重绘策略：通过shouldRepaint减少 GPU 负载
• 良好封装：提供清晰 API 与插槽（如centerChild）
• 性能意识：在 OpenHarmony 多设备上验证帧率与资源占用
• 工程化复用：封装为 Dart 包，提升团队开发效率

此模式可扩展至仪表盘、波形图、自定义图表等复杂可视化组件，是构建高保真 OpenHarmony 应用的核心能力之一。

欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net