# TextField 聚焦时出现蓝色背景（Focus State Layer）

**问题标签**: `TextField`, `InputDecoration`, `ThemeData`, `focusColor`, `focus`, `背景色`
**问题类型**: `UI 样式异常`
**严重程度**: 中
**节省时间**: 多轮尝试 → 1 步修复

---

## 问题描述

TextField 点击聚焦后，输入框背景出现蓝色半透明叠加色（State Layer），与设计稿完全不符，视觉效果很突兀。

## 问题根因

Flutter Material Design 默认会在 `ThemeData.focusColor` 设置带透明度的蓝色：

```dart
// Flutter 框架默认值
ThemeData(
  focusColor: Color(0x1F2196F3), // 蓝色 12% 透明度 → 即 12% 不透明蓝色叠加层
)
```

当 TextField 聚焦时，这个颜色作为 **State Layer** 叠加在 `fillColor` 上方，产生明显的蓝色背景。

**陷阱**：只在 `InputDecorationTheme` 中设置 `focusColor: Colors.transparent` 并不够——`ThemeData` 级别的 `focusColor` 仍然生效，在某些情况下依然会显示。

## 错误尝试（导致反复）

| 尝试 | 结果 |
|------|------|
| 只设置 `InputDecorationTheme.focusColor: transparent` | 部分场景仍有蓝色 |
| 设置 `TextField.decoration.fillColor: transparent` | 填充色改了，但 focus 叠加色仍在 |
| 单独设置某个 TextField 的样式 | 新增 TextField 又出现问题，不是全局修复 |

## 正确方案

必须在 `ThemeData` 和 `InputDecorationTheme` **两处同时**设置：

```dart
ThemeData(
  // 全局消除 focus/hover/ripple State Layer
  focusColor: Colors.transparent,
  hoverColor: Colors.transparent,
  splashColor: Colors.transparent,
  highlightColor: Colors.transparent,

  inputDecorationTheme: InputDecorationTheme(
    filled: true,
    fillColor: Colors.transparent,
    focusColor: Colors.transparent,   // 针对 TextField 的双重保护
    hoverColor: Colors.transparent,
    // 消除聚焦时的边框
    border: InputBorder.none,
    enabledBorder: InputBorder.none,
    focusedBorder: InputBorder.none,
    errorBorder: InputBorder.none,
    focusedErrorBorder: InputBorder.none,
  ),
)
```

## 各属性作用说明

| 属性 | 控制范围 | 默认值 |
|------|----------|--------|
| `ThemeData.focusColor` | 全局所有 Widget 的 focus 状态叠加色 | `Color(0x1F2196F3)` |
| `ThemeData.hoverColor` | 全局所有 Widget 的 hover 状态叠加色 | `Color(0x0A000000)` |
| `ThemeData.splashColor` | InkWell 水波纹颜色 | 蓝色变体 |
| `ThemeData.highlightColor` | 长按高亮颜色 | 半透明 |
| `InputDecorationTheme.focusColor` | TextField 专属 focus 层（二次覆盖） | 跟随 ThemeData |
| `InputDecorationTheme.fillColor` | TextField 填充背景色 | 跟随主题 |

## 关键原则

1. **ThemeData 和 InputDecorationTheme 都必须设置**，只改一处不够
2. 如果项目有多套主题（亮色/暗色），**每套主题都需要单独设置**
3. 在明确需要 focus 效果的按钮上（如 `ElevatedButton`），可单独通过 `ButtonStyle` 恢复，不影响全局配置