mta-mcp 1.0.0

package/troubleshooting/flutter/component-/351/200/232/347/224/250/345/214/226/346/217/220/345/217/226.md

@@ -0,0 +1,269 @@
+# 通用组件提取与文本自适应对齐
+
+> **问题标签**: `component`, `refactor`, `text-align`, `adaptive`, `center`, `left`  
+> **框架**: Flutter  
+> **严重程度**: 中等（影响代码可维护性和 UI 一致性）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "这两个卡片样式很像"
+- "单行居中、多行左对齐"
+- "重复代码太多"
+- "不同状态显示不同样式"
+
+### 问题特征
+- [ ] 多个相似组件（如 Warning Card、Error Card）硬编码实现
+- [ ] 相同的布局结构重复多次
+- [ ] 文本对齐方式需要根据内容长度动态调整
+- [ ] 颜色/图标等仅通过状态切换
+
+---
+
+## 🎯 核心原理
+
+### 问题 1：硬编码重复组件
+
+**错误做法**：为每种状态创建独立的 Widget 方法
+
+```dart
+// ❌ 硬编码 - 重复代码
+Widget _buildWarningCard() { ... }
+Widget _buildErrorCard() { ... }
+Widget _buildSuccessCard() { ... }
+```
+
+**正确做法**：提取通用组件，通过参数配置样式
+
+```dart
+// ✅ 通用组件
+TipCard(
+  type: TipCardType.warning, // 或 error, success, info
+  title: '标题',
+  content: '内容',
+  buttonText: '按钮',
+  onButtonPressed: () {},
+)
+```
+
+### 问题 2：文本单行居中、多行左对齐
+
+**需求**：
+- 短文本（单行）：水平居中显示
+- 长文本（多行）：左对齐显示
+
+**解决方案**：使用 `LayoutBuilder` + `TextPainter` 动态计算
+
+```dart
+Widget _buildAdaptiveText(String content, TextStyle style) {
+  return LayoutBuilder(
+    builder: (context, constraints) {
+      // 计算文本是否超出一行
+      final textPainter = TextPainter(
+        text: TextSpan(text: content, style: style),
+        maxLines: 1,
+        textDirection: TextDirection.ltr,
+      );
+      textPainter.layout(maxWidth: constraints.maxWidth);
+
+      // 判断是否溢出
+      final isMultiLine = textPainter.didExceedMaxLines ||
+          textPainter.width >= constraints.maxWidth * 0.95;
+
+      return Container(
+        width: double.infinity,
+        alignment: isMultiLine ? Alignment.centerLeft : Alignment.center,
+        child: Text(
+          content,
+          style: style,
+          textAlign: isMultiLine ? TextAlign.left : TextAlign.center,
+          maxLines: 2,
+          overflow: TextOverflow.ellipsis,
+        ),
+      );
+    },
+  );
+}
+```
+
+---
+
+## ✅ 完整解决方案
+
+### 1. 定义配置类
+
+```dart
+/// TipCard 类型枚举
+enum TipCardType { warning, error, success, info }
+
+/// 配置类 - 所有颜色来自 Sketch
+class TipCardConfig {
+  final Color backgroundColor;
+  final Color borderColor;
+  final Color titleColor;
+  final Color contentColor;
+  final Color buttonShadowColor;
+  final String iconPath;
+
+  const TipCardConfig({...});
+
+  /// Warning: #fff8e7ff, border #ffe4b5ff
+  static const warning = TipCardConfig(
+    backgroundColor: Color(0xFFFFF8E7),
+    borderColor: Color(0xFFFFE4B5),
+    titleColor: Color(0xFFFF9800),
+    contentColor: Color(0xFFB45309),
+    buttonShadowColor: Color(0x40FF9800),
+    iconPath: 'assets/icons/warning_icon.svg',
+  );
+
+  /// Error: #f4433614 (8%透明), border #ffcacaff
+  static const error = TipCardConfig(
+    backgroundColor: Color(0x14F44336),
+    borderColor: Color(0xFFFFCACA),
+    titleColor: Color(0xFFF44336),
+    contentColor: Color(0xFFCA4F57),
+    buttonShadowColor: Color(0x40D0121B),
+    iconPath: 'assets/icons/error_icon.svg',
+  );
+
+  static TipCardConfig fromType(TipCardType type) {
+    switch (type) {
+      case TipCardType.warning: return warning;
+      case TipCardType.error: return error;
+      // ...
+    }
+  }
+}
+```
+
+### 2. 创建通用组件
+
+```dart
+class TipCard extends StatelessWidget {
+  final TipCardType type;
+  final String title;
+  final String content;
+  final String buttonText;
+  final VoidCallback? onButtonPressed;
+
+  const TipCard({
+    super.key,
+    required this.type,
+    required this.title,
+    required this.content,
+    required this.buttonText,
+    this.onButtonPressed,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final config = TipCardConfig.fromType(type);
+
+    return Container(
+      padding: const EdgeInsets.fromLTRB(23, 17, 23, 10),
+      decoration: BoxDecoration(
+        color: config.backgroundColor,
+        borderRadius: BorderRadius.circular(16),
+        border: Border.all(color: config.borderColor, width: 1),
+      ),
+      child: Column(
+        children: [
+          _buildTitleRow(config),
+          const SizedBox(height: 8),
+          _buildAdaptiveContent(config), // 自适应对齐
+          const SizedBox(height: 10),
+          _buildButton(config),
+        ],
+      ),
+    );
+  }
+}
+```
+
+### 3. 使用组件
+
+```dart
+// 替换硬编码实现
+Widget _buildWarningCard(ProfileController controller) {
+  return Obx(() {
+    final status = controller.kycStatus.value;
+
+    if (status == KycStatus.expiring) {
+      return TipCard(
+        type: TipCardType.warning,
+        title: '证件即将过期',
+        content: '您的身份证件将于30天后过期，请及时更新。',
+        buttonText: '立即更新',
+        onButtonPressed: controller.updateIdDocument,
+      );
+    } else if (status == KycStatus.rejected) {
+      return TipCard(
+        type: TipCardType.error,
+        title: '验证失败',
+        content: '证件照片不清晰，请重新上传。', // 短文本会居中
+        buttonText: '重新验证',
+        onButtonPressed: controller.resubmitVerification,
+      );
+    }
+
+    return const SizedBox.shrink();
+  });
+}
+```
+
+---
+
+## 🔑 关键公式
+
+### TextPainter 溢出检测
+
+```dart
+final isMultiLine = textPainter.didExceedMaxLines ||
+    textPainter.width >= constraints.maxWidth * 0.95;
+```
+
+- `didExceedMaxLines`：文本是否超出 maxLines
+- `width >= maxWidth * 0.95`：文本宽度接近容器宽度（留 5% 余量）
+
+### 配置类设计模式
+
+```dart
+// 枚举 + 静态配置 + fromType 工厂方法
+enum Type { a, b, c }
+
+class Config {
+  static const a = Config(...);
+  static const b = Config(...);
+  
+  static Config fromType(Type type) => switch (type) {
+    Type.a => a,
+    Type.b => b,
+    // ...
+  };
+}
+```
+
+---
+
+## ⚠️ 预防措施
+
+1. **识别相似组件**：当发现 2+ 个组件结构相同、仅样式不同时，立即提取
+2. **颜色来自设计稿**：使用 Sketch MCP 工具获取精确颜色值
+3. **文本对齐需求确认**：明确单行/多行的对齐规则
+4. **配置集中管理**：将所有变体配置放在一个类中
+
+---
+
+## 🔗 相关问题
+
+- [sketch-背景层高度.md](./sketch-背景层高度.md) - 获取精确尺寸
+- [sketch-完整提取.md](./sketch-完整提取.md) - 一次性提取样式
+
+---
+
+**创建日期**: 2026-01-20  
+**最后更新**: 2026-01-20  
+**来源**: Profile 页面 TipCard 组件重构实战

package/troubleshooting/flutter/input-/345/255/227/346/256/265/347/274/272/345/244/261.md

@@ -0,0 +1,240 @@
+# 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 轮对话