Flutter for OpenHarmony：通过组合现有 Widget 构建自定义组件-编程阁

Flutter for OpenHarmony：通过组合现有 Widget 构建自定义组件

在 Flutter for OpenHarmony 开发中，绝大多数 UI 定制需求并不需要继承RenderObject或使用CustomPaint进行底层绘制。组合（Composition）是 Flutter 推荐的核心复用机制——通过将基础 Widget（如Container、Text、Icon、Row等）嵌套组合，即可构建语义明确、高度可复用的自定义组件。

本文以一个典型的“服务状态卡片”为例，演示如何封装一个支持图标、标题、描述、状态颜色的通用组件，并重点说明命名规范、参数设计、文档注释及多设备适配策略。

1. 为什么优先选择组合而非继承？

Flutter 的 Widget 设计哲学强调“组合优于继承”。原因包括：

开发效率高：无需理解渲染管线或布局协议
维护成本低：依赖稳定的基础 Widget，避免底层变更风险
天然支持响应式：组合内部可自由使用StatelessWidget/StatefulWidget
OpenHarmony 兼容性好：所有基础 Widget 在 OpenHarmony SDK 中已充分验证

对于 90% 以上的业务 UI 组件（按钮、卡片、列表项、表单控件等），组合是更合理的选择。

2. 示例目标：ServiceStatusCard

我们希望封装一个如下图所示的卡片组件：

左侧：状态图标（可配置）
中部：标题 + 描述文本
右侧：状态指示点（颜色表示运行/停止/异常）
整体：圆角、内边距、点击反馈（可选）

该组件需支持以下自定义能力：

图标类型与颜色
标题与描述文本
状态类型（对应不同颜色）
是否可点击
主题适配（深色/浅色模式）

[图片：service_status_card_design.png]
（图：ServiceStatusCard 视觉设计稿，展示三种状态：运行、停止、异常）

3. 组件实现：ServiceStatusCard

3.1 基础结构与命名规范

创建文件lib/components/service_status_card.dart，定义StatelessWidget：

/// 一个用于展示服务状态的可复用卡片组件。////// 支持自定义图标、标题、描述、状态颜色，并适配 OpenHarmony 多分辨率设备。classServiceStatusCardextendsStatelessWidget{constServiceStatusCard({super.key,requiredthis.title,requiredthis.iconData,this.description,this.status=ServiceStatus.running,this.onTap,});finalStringtitle;finalIconDataiconData;finalString?description;finalServiceStatusstatus;finalVoidCallback?onTap;@overrideWidgetbuild(BuildContextcontext){// 实现见下文}}

命名规范：
组件名采用PascalCase（ServiceStatusCard）
文件名使用snake_case（service_status_card.dart）
参数名使用camelCase（iconData,onTap）

3.2 状态枚举定义

在同文件或独立文件中定义状态类型：

enumServiceStatus{running,stopped,error,}Color_getStatusColor(ServiceStatusstatus,BuildContextcontext){finalisDark=Theme.of(context).brightness==Brightness.dark;switch(status){caseServiceStatus.running:returnColors.green;caseServiceStatus.stopped:returnisDark?Colors.grey[500]!:Colors.grey[700]!;caseServiceStatus.error:returnColors.red;}}

3.3 完整 build 方法实现

@overrideWidgetbuild(BuildContextcontext){finalstatusColor=_getStatusColor(status,context);finalcardChild=Row(children:[Icon(iconData,size:24,color:Theme.of(context).iconTheme.color),constSizedBox(width:12),Expanded(child:Column(crossAxisAlignment:CrossAxisAlignment.start,children:[Text(title,style:Theme.of(context).textTheme.titleMedium?.copyWith(fontWeight:FontWeight.bold,),maxLines:1,overflow:TextOverflow.ellipsis,),if(description!=null)Text(description!,style:Theme.of(context).textTheme.bodySmall,maxLines:1,overflow:TextOverflow.ellipsis,),],),),Container(width:12,height:12,decoration:BoxDecoration(color:statusColor,shape:BoxShape.circle,),),],);// 若提供 onTap，则包裹 InkWell 提供水波纹反馈if(onTap!=null){returnCard(margin:constEdgeInsets.symmetric(vertical:4,horizontal:8),clipBehavior:Clip.hardEdge,child:InkWell(onTap:onTap,child:Padding(padding:constEdgeInsets.all(16),child:cardChild,),),);}else{returnCard(margin:constEdgeInsets.symmetric(vertical:4,horizontal:8),clipBehavior:Clip.hardEdge,child:Padding(padding:constEdgeInsets.all(16),child:cardChild,),);}}

关键设计点：
使用Expanded防止长文本溢出
通过Theme.of(context)适配系统主题
条件渲染description（避免空 Widget）
统一使用Card保证视觉一致性

4. 参数设计最佳实践

4.1 必填 vs 可选参数

必填参数：使用required（如title,iconData）
可选参数：提供合理默认值（如status = ServiceStatus.running）

4.2 类型安全

使用enum代替字符串表示状态（避免拼写错误）
使用VoidCallback?而非Function?（明确无参回调）

4.3 文档注释

为类和公共参数添加 Dartdoc（///）
说明组件用途、参数含义及默认行为

5. OpenHarmony 多分辨率适配策略

5.1 使用逻辑像素（dp）

所有尺寸（SizedBox、padding、width）均使用逻辑像素，由 Flutter 引擎自动映射到物理像素。OpenHarmony 设备（手机、平板、手表）会自动缩放。

5.2 避免硬编码字体大小

使用Theme.of(context).textTheme获取系统推荐字号，确保在不同设备上可读性一致。

5.3 测试建议

在 DevEco Studio 中使用以下模拟器验证：

手机（1080×2340）
平板（2560×1600）
智能手表（454×454）

实测表明：上述ServiceStatusCard在三种设备上均保持合理间距与文本截断，无需额外适配代码。

[图片：service_status_card_multi_device.png]
（图：同一组件在 OpenHarmony 手机、平板、手表模拟器上的实际渲染效果对比）

6. 使用示例

在页面中调用：

ServiceStatusCard(title:'设备管理服务',iconData:Icons.devices,description:'负责蓝牙与 Wi-Fi 设备连接',status:ServiceStatus.running,onTap:(){// 跳转详情页},)

可轻松构建列表：

ListView(children:services.map((s)=>ServiceStatusCard(title:s.name,iconData:s.icon,description:s.desc,status:s.status,onTap:()=>_navigateToDetail(s.id),)).toList(),)