---

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

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

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

目录

• 1. 为什么优先选择组合而非继承？
• 2. 示例目标：ServiceStatusCard
• 3. 组件实现：ServiceStatusCard
  • 3.1 基础结构与命名规范
  • 3.2 状态枚举定义
  • 3.3 完整 build 方法实现
• 4. 参数设计最佳实践
• 5. OpenHarmony 多分辨率适配策略
• 6. 使用示例
• 7. 总结

---

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 多分辨率设备。
class ServiceStatusCard extends StatelessWidget {
  const ServiceStatusCard({
    super.key,
    required this.title,
    required this.iconData,
    this.description,
    this.status = ServiceStatus.running,
    this.onTap,
  });

  final String title;
  final IconData iconData;
  final String? description;
  final ServiceStatus status;
  final VoidCallback? onTap;

  @override
  Widget build(BuildContext context) {
    // 实现见下文
  }
}

命名规范：

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

---

3.2 状态枚举定义

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

enum ServiceStatus {
  running,
  stopped,
  error,
}

Color _getStatusColor(ServiceStatus status, BuildContext context) {
  final isDark = Theme.of(context).brightness == Brightness.dark;
  switch (status) {
    case ServiceStatus.running:
      return Colors.green;
    case ServiceStatus.stopped:
      return isDark ? Colors.grey[500]! : Colors.grey[700]!;
    case ServiceStatus.error:
      return Colors.red;
  }
}

---

3.3 完整 build 方法实现

@override
Widget build(BuildContext context) {
  final statusColor = _getStatusColor(status, context);
  final cardChild = Row(
    children: [
      Icon(iconData, size: 24, color: Theme.of(context).iconTheme.color),
      const SizedBox(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) {
    return Card(
      margin: const EdgeInsets.symmetric(vertical: 4, horizontal: 8),
      clipBehavior: Clip.hardEdge,
      child: InkWell(
        onTap: onTap,
        child: Padding(
          padding: const EdgeInsets.all(16),
          child: cardChild,
        ),
      ),
    );
  } else {
    return Card(
      margin: const EdgeInsets.symmetric(vertical: 4, horizontal: 8),
      clipBehavior: Clip.hardEdge,
      child: Padding(
        padding: const EdgeInsets.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(),
)

---

7. 总结

通过组合基础 Widget 构建自定义组件，是 Flutter 开发中最高效、最安全的复用方式。关键在于：

• 明确组件职责：单一功能，高内聚
• 合理设计 API：必填/可选参数、类型安全、默认值
• 编写文档注释：提升团队协作效率
• 利用 Theme 与逻辑像素：天然适配 OpenHarmony 多设备

此方法不仅适用于卡片，还可扩展至按钮组、输入框、标签栏等任何复合 UI 单元，是构建可维护 OpenHarmony 应用的基础能力。

---

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