# 【Demo】品牌换肤（两级主题模型）

> 源文件：`lib/pages/demo/theme_demo.dart` ｜ 分类：基础布局
> 一句话：换品牌 = 一级换整套色板 + 二级换页面细节，一套代码全 App 变色。

---

## 一、这个 Demo 解决什么问题

教育 App 常有"多品牌运营"需求：不同机构定制不同主色、页面配色、甚至标题文案。
本 Demo 演示项目核心的**两级主题模型**：

```
一级 = 品牌：seedColor 生成整套 Material 色板（全 App 共享）
二级 = 页面细节（PageTheme）：按页面层级（home/detail/result）
       区分背景色 / 头部色 / 强调色 / 专属 banner / 标题文案
```

页面只声明"我是哪个层级"，细节从品牌对象按层级查出来：
**换品牌 → 一级色板全换 + 二级细节全换（一套代码）**。

---

## 二、怎么运行 / 演示内容

```dart
runApp(const MaterialApp(home: ThemeDemoPage()));
```

- 顶部 ChoiceChip 切换品牌（从注册表 `brandThemes` 自动生成按钮，新增品牌自动出现）；
- "一级"区：显示 seed 色与生成的 primary 对比 + 跟随主题的按钮/进度条；
- "二级"区：home/detail/result 三个层级各渲染一个页面骨架预览（背景/头部/强调色/文案全跟随品牌）。

---

## 三、核心知识点（新手向）

### 1. 主题的两层结构（模型已解耦，见 `core/theme/`）
| 层 | 内容 | 存放 |
|---|---|---|
| 模型 + 注册表 | `BrandTheme` / `PageTheme` / `PageLevel` + `brandThemes` | `core/theme/brand_theme.dart` |
| 每品牌配置 | 只有具体色值/文案 | `core/theme/brands/xxx_theme.dart` |

新增一个品牌 = 新建一个配置文件 + 注册表加一行，**业务代码零改动**。

### 2. 一级：colorSchemeSeed 的原理
```dart
ThemeData(colorSchemeSeed: _brand.seedColor)
```
传一个种子色，Material 自动生成整套 ColorScheme（primary/secondary/tertiary...），
**没写死颜色的 Material 组件全部自动跟随**（FilledButton/Checkbox/Switch/进度条/聚焦输入框）。
验证页见 [seed_palette_demo.md](seed_palette_demo.md)。

> ⚠ colorSchemeSeed 生成的 primary 不是精确色值（Material 会调和），
> 要求精确用 `ColorScheme.fromSeed(...)` 后手动覆盖 primary。

### 3. 二级：PageTheme 按层级查询
```dart
// 页面只声明层级（本 demo 直接取，真实项目从路由/参数拿）
final page = _brand.pages[PageLevel.home]!;
// 使用：背景 page.bg、头部 page.headerBg、强调 page.accent、banner page.banner
```
- banner 存资源路径（如 `assets/img/banner_sky.png`），页面 `Image.asset(page.banner!)` 即可跟随换图；
- 本 demo 没准备两套图片，用"强调色渐变块"模拟 banner 占位（代码里标注了替换点）。

### 4. 局部主题覆盖（不依赖全局 MaterialApp 的切换法）
```dart
return Theme(
  data: ThemeData(colorSchemeSeed: _brand.seedColor),
  child: Scaffold( ... ), // 页面内组件都从局部主题取色
);
```
> 真实项目把 `_brand` 换成 Riverpod Provider + MaterialApp 的 theme，切换点移到根层。

---

## 四、关键代码剖析

```dart
// 品牌切换（注册表驱动，新增品牌自动出现）
Wrap(
  spacing: 8,
  children: [
    for (final b in brandThemes)
      ChoiceChip(
        label: Text(b.name),
        selected: _brand.name == b.name,
        onSelected: (_) => setState(() => _brand = b),
      ),
  ],
)

// 二级细节消费示例（页面骨架预览）
Container(
  color: page.bg,                 // ← 二级：背景
  child: Column(children: [
    Container(
      color: page.headerBg,        // ← 二级：头部色
      child: Text(page.title),     // ← 二级：标题文案
    ),
    // banner 占位：真实项目替换成 Image.asset(page.banner!)
    Container(decoration: BoxDecoration(gradient: LinearGradient(colors: [page.accent, page.headerBg]))),
    FilledButton(
      style: FilledButton.styleFrom(backgroundColor: page.accent), // ← 二级：强调色
      child: const Text('本页主按钮'),
    ),
  ]),
)
```

---

## 五、踩坑记录

1. **colorSchemeSeed 生成的 primary 不精确** —— 需要精确色值时手动覆盖；
2. **局部 `Theme(data:)` 必须包在 Scaffold 外面**，AppBar 才能取到（包在 body 里 AppBar 取不到）；
3. **PNG 位图不跟主题着色** —— 能用矢量（IconData）就别放多份图；
4. 深色模式要单独配 `darkTheme` + `themeMode`，不是简单换个 seed；
5. `.w/.h/.sp` 的组件不能 const（`const_eval_extension_method`）。

---

## 六、扩展思考

- 持久化：品牌选择存 shared_preferences，启动时读出来传给 MaterialApp 的 theme；
- 动态切换动画：`AnimatedTheme` 包 MaterialApp，换主题有过渡动画；
- 与 [seed_palette_demo.md](seed_palette_demo.md) 对照：一个验证"seed 生效"，一个演示"两级模型的消费"；
- 更重的多主题需求可引入 `flex_color_scheme` 包，本项目的轻量模型够用且无依赖。