# Flutter 组件字段缺失问题

> **问题标签**: `component`, `props`, `missing-field`, `custom-widget`  
> **问题类型**: 组件配置  
> **框架**: Flutter  
> **严重程度**: 低（编译错误，容易发现）

---

## 🔍 问题识别

### 自动检测特征

```dart
// 编译错误信息
The named parameter 'showBorder' isn't defined
The named parameter 'shadow' isn't defined
```

### 用户描述关键词
- "组件不支持这个属性"
- "字段未定义"
- "参数不存在"
- "自定义组件缺少配置"

### 问题特征
- [ ] 编译错误：`The named parameter 'xxx' isn't defined`
- [ ] 自定义组件无法接收某些属性
- [ ] IDE 提示参数不存在
- [ ] 想配置组件样式但没有对应的属性

---

## ❌ 常见错误排查路线（避免重复）

| 尝试方向 | 为什么无效 | 浪费时间 |
|----------|-----------|---------|
| 直接在使用处添加样式 | 破坏组件封装性 | 1 轮对话 |
| 修改组件内部硬编码 | 失去可配置性 | 1-2 轮对话 |
| 复制组件代码到页面 | 违反 DRY 原则 | 1 轮对话 |

**总计浪费**: 2-4 轮对话

---

## ✅ 正确解决方案

### 核心原理

**问题根源**：自定义组件（如 `FlexInput`）在设计时未预留足够的可配置字段。

### 解决步骤

#### 1. 检查组件定义

找到组件源文件（如 `lib/core/themes/flex_widgets.dart`）

#### 2. 补充缺失字段

```dart
class FlexInput extends StatelessWidget {
  const FlexInput({
    super.key,
    // ... 已有字段
    this.controller,
    this.hintText,
    this.inputType = TextInputType.text,
    
    // ← 新增字段
    this.showBorder = true,
    this.shadow,
    this.borderColor,
    this.borderWidth = 1.0,
  });

  // 已有属性
  final TextEditingController? controller;
  final String? hintText;
  final TextInputType inputType;
  
  // ← 新增属性
  final bool showBorder;
  final List<BoxShadow>? shadow;
  final Color? borderColor;
  final double borderWidth;

  @override
  Widget build(BuildContext context) {
    return Container(
      decoration: BoxDecoration(
        // ← 使用新增的属性
        border: showBorder 
          ? Border.all(
              color: borderColor ?? $c.border,
              width: borderWidth,
            ) 
          : null,
        boxShadow: shadow,
        // ... 其他样式
      ),
      child: TextField(
        controller: controller,
        decoration: InputDecoration(
          hintText: hintText,
          // ...
        ),
      ),
    );
  }
}
```

#### 3. 使用新字段

```dart
// 现在可以配置了
FlexInput(
  hintText: 'Enter phone',
  showBorder: false,        // ← 新增
  shadow: [                 // ← 新增
    BoxShadow(
      color: Color(0x0D000000),
      blurRadius: 3,
      offset: Offset(0, 1),
    ),
  ],
)
```

---

## 📋 组件设计最佳实践

### 必须预留的常用字段

#### 样式相关
```dart
// 边框
final bool showBorder;
final Color? borderColor;
final double borderWidth;
final BorderRadius? borderRadius;

// 阴影
final List<BoxShadow>? shadow;

// 背景
final Color? backgroundColor;
final Gradient? gradient;

// 尺寸
final double? width;
final double? height;
final EdgeInsets? padding;
final EdgeInsets? margin;
```

#### 交互相关
```dart
// 状态
final bool enabled;
final bool readOnly;

// 回调
final VoidCallback? onTap;
final ValueChanged<String>? onChanged;
final VoidCallback? onSubmitted;

// 验证
final String? Function(String?)? validator;
final bool showError;
```

### 组件设计检查清单

- [ ] 是否支持自定义颜色？
- [ ] 是否支持自定义尺寸？
- [ ] 是否支持显示/隐藏边框？
- [ ] 是否支持阴影配置？
- [ ] 是否支持禁用/只读状态？
- [ ] 回调函数是否足够？

---

## 💡 预防措施

### 1. 使用 Token 系统

```dart
// ✅ 推荐：使用 Token 作为默认值
final Color borderColor;

FlexInput({
  this.borderColor = $c.border, // Token 默认值
})

// ❌ 避免：硬编码
final Color borderColor = Color(0xFFDDDDDD);
```

### 2. 参考 Material/Cupertino 组件

Flutter 官方组件的属性设计很完善，可以参考：

```dart
// TextField 的部分属性
TextField(
  decoration: InputDecoration(
    border: ...,
    enabledBorder: ...,
    focusedBorder: ...,
    filled: ...,
    fillColor: ...,
  ),
  style: ...,
  enabled: ...,
  readOnly: ...,
)
```

### 3. 渐进式添加属性

**不要一开始就添加所有属性**，遵循 YAGNI 原则：
1. 先实现基础功能
2. 使用时发现缺少属性
3. 及时补充属性

---

## 🔗 相关案例

- [layout-尺寸不匹配](./layout-尺寸不匹配.md) - 组件的精确尺寸配置
- [shadow-透出问题](./shadow-透出问题.md) - CustomPainter 组件的属性设计

---

**来源**: my_flutter 项目实战经验  
**创建日期**: 2025-12-31  
**最后验证**: 2026-01-16  
**节省时间**: 2-4 轮对话