深入解析：【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 或子主题

---

下一站

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

---