【2025版 OpenHarmony】GitCode 口袋工具 v1.0.3：Flutter + HarmonyOS 深色模式全面启用

🌙 版本亮点 ：引入统一 AppTheme，实现 HarmonyOS/Windows 等平台自动夜间模式，UI 配色全面语义化，暗光环境下也能舒适浏览。

📅 版本信息

• 版本号：v1.0.3
• 发布日期：2025 年
• 核心更新：深浅色双主题、UI 配色体系重构、无障碍对比度提升

---

GitCode 地址 https://gitcode.com/byyixuan/gitcode_pocket_tool/tree/v1.0.3

✨ 为什么要做 1.0.3

此前 UI 里存在大量硬编码 Colors.*，在暗色环境下对比度不足、提示色不统一。本次版本聚焦"主题体系重构 + 代码语义化"，一口气解决：

• ✅ 统一全局主题入口，支持 ThemeMode.system 自动切换
• ✅ 页面/组件改造为只依赖 ColorScheme 语义色
• ✅ 错误提示、空状态、卡片等场景全面适配暗色视觉
• ✅ 通过 flutter analyze，零警告上线

---

如何打开深色模式

下滑打开：

点击加号：

添加深色模式：

展示如下

🧱 主题体系重构

1. 新增 AppTheme，集中管理主题

lib/core/app_theme.dart 是本次版本的核心，它封装了浅色/深色的 ThemeData，包含导航栏、卡片、输入框、Chip 等子主题。后续如需定制新的组件，只需在这里统一配置。

import 'package:flutter/material.dart';

/// 统一管理浅色（Light）与深色（Dark）主题的工具类。
/// 通过 Material 3 的 ColorScheme.fromSeed 自动生成协调配色，
/// 并为常用组件（AppBar、Card、Input 等）定制统一的视觉风格。
/// 特别适用于需要适配系统夜间模式的场景（如 HarmonyOS）。
class AppTheme {
  // 私有构造函数：防止外部实例化此类（仅作为静态工具类使用）
  AppTheme._();

  /// 主题的"种子颜色"（Seed Color）。
  /// Material 3 会基于此颜色自动生成整套配色方案（primary、onPrimary、surface 等）。
  /// 这里使用 Indigo（靛蓝）作为主色调，可根据需求替换。
  static const Color _seedColor = Colors.indigo;

  /// 返回浅色主题（Brightness.light）
  static ThemeData light() => _theme(Brightness.light);

  /// 返回深色主题（Brightness.dark）
  static ThemeData dark() => _theme(Brightness.dark);

  /// 内部私有方法：根据指定的亮度（亮/暗）生成完整的 ThemeData 主题配置。
  ///
  /// [brightness]：指定主题是亮色还是暗色。
  static ThemeData _theme(Brightness brightness) {
    // 基于种子色和亮度，自动生成一套符合 Material 3 规范的配色方案
    final colorScheme = ColorScheme.fromSeed(
      seedColor: _seedColor,
      brightness: brightness, // 决定生成的是浅色还是深色配色
    );

    // 判断当前是否为深色模式，用于后续微调某些颜色的透明度
    final isDark = brightness == Brightness.dark;

    // 构建完整的 ThemeData 对象
    return ThemeData(
      // 使用自动生成的配色方案
      colorScheme: colorScheme,

      // 启用 Material Design 3（Material You）风格
      useMaterial3: true,

      // 设置视觉密度为标准（不压缩 UI 元素间距）
      visualDensity: VisualDensity.standard,

      // 明确指定主题亮度（影响滚动条、弹窗等系统组件）
      brightness: brightness,

      // Scaffold 背景色使用 surface（Material 3 中代表"纸张"表面的颜色）
      scaffoldBackgroundColor: colorScheme.surface,

      // 配置 AppBar（顶部导航栏）样式
      appBarTheme: AppBarTheme(
        backgroundColor: colorScheme.surface,           // 背景使用 surface 色
        foregroundColor: colorScheme.onSurface,         // 文字/图标使用 onSurface 色
        centerTitle: true,                              // 标题居中
        elevation: 0,                                   // 无阴影（M3 推荐用颜色区分层级而非阴影）
      ),

      // 配置底部导航栏（NavigationBar）样式
      navigationBarTheme: NavigationBarThemeData(
        backgroundColor: colorScheme.surfaceContainerHigh, // 使用高一级容器色，略深于 surface
        indicatorColor: colorScheme.primary.withOpacity(
          isDark ? 0.35 : 0.2, // 深色模式下指示器更不透明，保证可见性
        ),
        labelBehavior: NavigationDestinationLabelBehavior.alwaysShow, // 始终显示标签文字
      ),

      // 配置 Card（卡片）样式
      cardTheme: CardTheme(
        color: colorScheme.surfaceContainerLowest, // 最浅的容器色，用于卡片背景
        elevation: 0, // 无阴影（靠颜色层次表达层级）
        shape: RoundedRectangleBorder(
          borderRadius: BorderRadius.circular(20), // 圆角 20，现代感强
        ),
      ),

      // 配置输入框（TextField 等）的装饰样式
      inputDecorationTheme: InputDecorationTheme(
        // 默认边框样式（未聚焦）
        border: OutlineInputBorder(
          borderRadius: BorderRadius.circular(16),
          borderSide: BorderSide(color: colorScheme.outlineVariant),
        ),
        // 启用状态下的边框（同默认）
        enabledBorder: OutlineInputBorder(
          borderRadius: BorderRadius.circular(16),
          borderSide: BorderSide(color: colorScheme.outlineVariant),
        ),
        // 聚焦状态下的边框（高亮主色）
        focusedBorder: OutlineInputBorder(
          borderRadius: BorderRadius.circular(16),
          borderSide: BorderSide(color: colorScheme.primary, width: 1.4),
        ),
        filled: true, // 启用填充背景
        fillColor: colorScheme.surfaceContainerLowest, // 填充色使用最浅容器色
        // 标签文字颜色（如 "用户名"）
        labelStyle: TextStyle(color: colorScheme.onSurfaceVariant),
        // 提示文字颜色（如 "请输入..."），稍透明
        hintStyle: TextStyle(color: colorScheme.onSurfaceVariant.withOpacity(0.7)),
        // 前缀图标颜色（如 🔍）
        prefixIconColor: colorScheme.onSurfaceVariant,
      ),

      // 配置 Chip（标签/徽章）样式
      chipTheme: ChipThemeData(
        backgroundColor: colorScheme.surfaceContainerHigh, // 背景色
        selectedColor: colorScheme.primary.withOpacity(0.2), // 选中时的半透主色背景
        shape: RoundedRectangleBorder(
          borderRadius: BorderRadius.circular(24), // 更大圆角，柔和
        ),
        labelStyle: TextStyle(color: colorScheme.onSurface), // 文字颜色
      ),

      // 配置 Divider（分割线）样式
      dividerTheme: DividerThemeData(
        color: colorScheme.outlineVariant.withOpacity(0.7), // 使用 outlineVariant 并降低透明度
        thickness: 1, // 线条粗细
      ),
    );
  }
}

2. MaterialApp 跟随系统模式

lib/main.dart 现在只需引用 AppTheme，即可同时拥有亮/暗主题，并通过 ThemeMode.system 跟随 HarmonyOS/Windows 的系统设置：

return MaterialApp(
  title: 'GitCode 口袋工具',
  theme: AppTheme.light(),
  darkTheme: AppTheme.dark(),
  themeMode: ThemeMode.system,
  home: const MainNavigationPage(),
);

---

🎨 UI 语义色改造详情

我们逐页梳理了配色，删除硬编码 Colors.grey/Colors.red 等写法，全部改为从 Theme.of(context).colorScheme 读取语义色，保证亮/暗模式下视觉统一。

1. 首页 & 组件色彩

• IntroPage：描述文案、提示文案统一使用 onSurfaceVariant
• Chip、Icon、Divider 等继承自 AppTheme 设定的 ChipTheme、DividerTheme

2. 搜索页提示组件

_InfoBanner 现在根据状态动态取 primaryContainer、secondaryContainer、errorContainer：

return _InfoBanner(
  icon: Icons.error_outline,
  background: scheme.errorContainer,
  textColor: scheme.onErrorContainer,
  message: _errorMessage!,
);

3. 用户/仓库列表与详情页

• 列表页空状态、错误提示采用 scheme.error / onErrorContainer
• UserCard、RepositoryCard 使用 onSurfaceVariant 作为次要文本色，保证暗色下可读
• RepositoryDetailPage、UserDetailPage 的卡片文案、重试按钮等全部切换到语义色

4. 个人页外观统一

ProfilePage 的头像描边、阴影、卡片边框改为 withValues(alpha: x)，同时将背景从弃用的 surfaceVariant 升级为 surfaceContainerHighest。

---

🧪 验证与工具

• flutter analyze：处理完 withOpacity、surfaceVariant 的弃用告警后再次运行，确保 0 issue
• HarmonyOS 真机 + Windows 桌面：切换系统主题，确认导航栏、对话框、空状态等随系统同步

---

🔍 关键改动一览

文件	主要工作
lib/core/app_theme.dart	新建主题工厂，输出浅色/深色 ThemeData
lib/main.dart	接入双主题，开启 ThemeMode.system
pages/* & widgets/*	清理 Colors.* 与 withOpacity，统一使用 ColorScheme
README.md	更新版本信息、功能列表、更新日志到 v1.0.3

---

🔧 升级指南

1. git pull 获取最新代码
2. flutter pub get 安装依赖
3. 直接在 HarmonyOS/Windows 环境运行（无需额外配置），即可体验自动夜间模式
4. 若需自定义配色，只需在 AppTheme 中调整 seedColor 或子主题

---

🧭 下一站

• 收藏/历史功能
• 多语言国际化
• 数据缓存与离线模式
• 自定义主题配色面板

---