mta-mcp 2.13.0 → 2.14.0

package/troubleshooting/flutter/clip-/351/230/264/345/275/261/350/243/201/345/211/252.md

@@ -0,0 +1,244 @@
+# Flutter clipBehavior 阴影裁剪问题
+
+> **问题标签**: `clip`, `shadow`, `layout`, `overflow`, `neumorphism`  
+> **问题类型**: 布局裁剪  
+> **框架**: Flutter  
+> **严重程度**: 中等（视觉问题）
+
+---
+
+## 🔍 问题识别
+
+### 自动检测特征
+
+```dart
+// 代码模式匹配 - 嵌套容器带阴影
+Container(
+  // 外层容器有 padding
+  padding: EdgeInsets.all(6),
+  child: Container(
+    decoration: BoxDecoration(
+      boxShadow: [...], // 内层有阴影
+    ),
+  ),
+)
+```
+
+### 用户描述关键词
+- "阴影模糊一片"
+- "阴影没有清晰边界"
+- "阴影被裁剪了"
+- "新拟态效果不清晰"
+- "选中项看不出凸起效果"
+
+### 问题特征
+- [ ] 新拟态选中项阴影看起来"模糊一片"
+- [ ] 阴影没有清晰的边界
+- [ ] 选中项与背景融为一体
+- [ ] 类似效果的其他组件显示正常
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 调整阴影参数 (blur/offset) | 问题不在阴影本身 | 2-3 轮对话 |
+| 嵌套两层 Container (外层阴影/内层渐变) | 阴影仍在裁剪区域内 | 2-3 轮对话 |
+| 添加白色边框产生锐利边缘 | 边框过于明显，产生分层感 | 1-2 轮对话 |
+| 使用叠加渐变模拟内阴影 | 效果不自然 | 1-2 轮对话 |
+| 只设置 Stack 的 clipBehavior | 外层 Container 仍会裁剪 | 1 轮对话 |
+
+**总计浪费**: 7-11 轮对话
+
+---
+
+## ✅ 正确解决方案
+
+### 核心原理
+
+**问题根源**：Flutter 的 `Container`、`Padding`、`ClipRRect` 等组件**默认会裁剪**超出边界的内容，包括 `BoxShadow` 阴影。
+
+```
+问题结构:
+Container (默认 clipBehavior: Clip.hardEdge)
+└── Padding (padding: 6)
+    └── Container
+        └── 带阴影的滑块  ← 阴影被最外层 Container 裁剪！
+```
+
+### 解决步骤
+
+#### 1. 设置 clipBehavior: Clip.none
+
+```dart
+Container(
+  clipBehavior: Clip.none, // ← 关键！允许内容溢出
+  decoration: BoxDecoration(
+    color: config.backgroundColor,
+    borderRadius: BorderRadius.circular(config.borderRadius),
+  ),
+  child: Stack(
+    clipBehavior: Clip.none, // ← Stack 也要设置
+    children: [
+      // ...
+    ],
+  ),
+)
+```
+
+#### 2. 重构布局结构
+
+**错误的结构**（会裁剪）：
+```dart
+Container(
+  padding: EdgeInsets.all(6), // padding 会导致裁剪
+  child: Stack(
+    children: [
+      Container(boxShadow: [...]), // 阴影被外层裁剪
+    ],
+  ),
+)
+```
+
+**正确的结构**（不裁剪）：
+```dart
+Container(
+  clipBehavior: Clip.none,
+  child: Stack(
+    clipBehavior: Clip.none,
+    children: [
+      Positioned( // 使用 Positioned 代替 padding
+        left: 6,
+        top: 6,
+        bottom: 6,
+        right: 6,
+        child: Container(boxShadow: [...]),
+      ),
+    ],
+  ),
+)
+```
+
+#### 3. 完整示例
+
+```dart
+@override
+Widget build(BuildContext context) {
+  final config = _getConfig();
+  final selectedIndex = items.indexWhere((item) => item.value == selectedValue);
+  final innerPadding = padding ?? const EdgeInsets.all(6);
+
+  return LayoutBuilder(
+    builder: (context, outerConstraints) {
+      final totalWidth = outerConstraints.maxWidth;
+      final innerWidth = totalWidth - innerPadding.horizontal;
+      final itemWidth = innerWidth / items.length;
+
+      return Container(
+        height: height,
+        clipBehavior: Clip.none, // 关键点1：允许溢出
+        decoration: BoxDecoration(
+          color: config.backgroundColor,
+          borderRadius: BorderRadius.circular(config.borderRadius),
+          boxShadow: config.shadow,
+        ),
+        child: Stack(
+          clipBehavior: Clip.none, // 关键点2：Stack 也允许溢出
+          children: [
+            // 滑动背景 - 使用 Positioned 精确定位
+            if (selectedIndex != -1)
+              Positioned(
+                left: innerPadding.left + (itemWidth * selectedIndex),
+                top: innerPadding.top,
+                bottom: innerPadding.bottom,
+                width: itemWidth,
+                child: AnimatedContainer(
+                  duration: $d.fast,
+                  curve: Curves.easeInOut,
+                  decoration: BoxDecoration(
+                    gradient: config.selectedGradient,
+                    borderRadius: BorderRadius.circular(12),
+                    boxShadow: config.selectedShadow, // 阴影在这里
+                  ),
+                ),
+              ),
+
+            // 文本层 - 使用 Padding 而非容器的 padding
+            Padding(
+              padding: innerPadding,
+              child: Row(
+                children: items.map((item) {
+                  return Expanded(
+                    child: GestureDetector(
+                      onTap: () => onChanged(item.value),
+                      child: Container(
+                        alignment: Alignment.center,
+                        child: Text(item.label, ...),
+                      ),
+                    ),
+                  );
+                }).toList(),
+              ),
+            ),
+          ],
+        ),
+      );
+    },
+  );
+}
+```
+
+---
+
+## 📋 关键改动点
+
+### 1. clipBehavior 设置
+- ✅ Container: `clipBehavior: Clip.none`
+- ✅ Stack: `clipBehavior: Clip.none`
+- ✅ 所有可能裁剪的父组件都要设置
+
+### 2. 布局方式
+- ❌ Container 的 padding 属性
+- ✅ Positioned 精确定位
+- ✅ Padding widget 包裹内容
+
+### 3. 使用 LayoutBuilder
+提前计算尺寸，避免布局错误：
+```dart
+LayoutBuilder(
+  builder: (context, constraints) {
+    final totalWidth = constraints.maxWidth;
+    final innerWidth = totalWidth - padding.horizontal;
+    final itemWidth = innerWidth / items.length;
+    // ...
+  },
+)
+```
+
+---
+
+## 💡 clipBehavior 值说明
+
+| 值 | 行为 | 性能 | 使用场景 |
+|----|------|------|---------|
+| `Clip.none` | 不裁剪，允许溢出 | 最好 | **需要显示阴影** |
+| `Clip.hardEdge` | 硬边裁剪（默认） | 好 | 一般容器 |
+| `Clip.antiAlias` | 抗锯齿裁剪 | 中 | 圆角需要平滑 |
+| `Clip.antiAliasWithSaveLayer` | 最高质量裁剪 | 差 | 尽量避免 |
+
+**推荐**：需要阴影时使用 `Clip.none`，其他情况保持默认。
+
+---
+
+## 🔗 相关案例
+
+- [shadow-透出问题](./shadow-透出问题.md) - 另一个阴影相关问题
+- [layout-尺寸不匹配](./layout-尺寸不匹配.md) - 使用 Positioned 精确布局
+
+---
+
+**来源**: my_flutter 项目实战经验  
+**创建日期**: 2025-12-31  
+**最后验证**: 2026-01-16  
+**节省时间**: 7-11 轮对话

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 轮对话

package/troubleshooting/flutter/input-/350/276/271/346/241/206/351/227/256/351/242/230.md

@@ -0,0 +1,236 @@
+# Flutter TextField 边框和背景问题
+
+> **问题标签**: `textfield`, `input`, `border`, `focus`, `theme`  
+> **问题类型**: 主题冲突  
+> **框架**: Flutter  
+> **严重程度**: 中等
+
+---
+
+## 🔍 问题识别
+
+### 自动检测特征
+
+```dart
+// 只设置了 border 但没设置其他状态
+TextField(
+  decoration: InputDecoration(
+    border: InputBorder.none, // 不够！
+  ),
+)
+```
+
+### 用户描述关键词
+- "TextField 聚焦时出现蓝色边框"
+- "输入框背景颜色变了"
+- "只设置了 border: InputBorder.none 但还有边框"
+- "新拟态输入框样式被覆盖"
+
+### 问题特征
+- [ ] TextField 聚焦时出现蓝色边框
+- [ ] TextField 聚焦时背景颜色变化
+- [ ] 只设置了 `border: InputBorder.none` 但边框仍存在
+- [ ] 新拟态输入框样式被全局主题覆盖
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 只设置 `border: InputBorder.none` | 不覆盖 focusedBorder 等状态 | 1-2 轮对话 |
+| 组件级覆盖但不完整 | 全局主题的其他状态仍生效 | 2-3 轮对话 |
+| 修改颜色为透明 | 边框仍存在，只是看不见 | 1 轮对话 |
+| 不知道是全局主题的问题 | 反复修改组件级样式 | 2-3 轮对话 |
+
+**总计浪费**: 6-9 轮对话
+
+---
+
+## ✅ 正确解决方案
+
+### 核心原理
+
+#### 原因1: Flutter InputDecoration 边框机制
+
+Flutter 的 `InputDecoration.border` 只是**默认值**，各状态有独立的边框属性：
+- `enabledBorder` - 启用状态
+- `focusedBorder` - 聚焦状态 ⚠️ **最常见问题**
+- `disabledBorder` - 禁用状态
+- `errorBorder` - 错误状态
+- `focusedErrorBorder` - 聚焦+错误状态
+
+**只设置 `border` 不会覆盖其他状态的边框！**
+
+#### 原因2: 全局主题干扰
+
+`ThemeData.inputDecorationTheme` 会注入默认样式：
+
+```dart
+// 全局主题中的问题配置
+inputDecorationTheme: InputDecorationTheme(
+  focusedBorder: OutlineInputBorder(
+    borderSide: BorderSide(color: Colors.blue, width: 2), // 蓝框来源！
+  ),
+  filled: true,  // 导致背景变色！
+),
+```
+
+### 解决步骤
+
+#### 方案1: 全局主题移除边框（推荐）
+
+修改 `lib/core/themes/app_theme.dart` 和 `theme_manager.dart`：
+
+```dart
+ThemeData(
+  // ... 其他配置
+  inputDecorationTheme: InputDecorationTheme(
+    filled: true,
+    fillColor: Colors.transparent,  // 透明填充
+    
+    // ← 关键：所有状态都设为无边框
+    border: InputBorder.none,
+    enabledBorder: InputBorder.none,
+    focusedBorder: InputBorder.none,
+    disabledBorder: InputBorder.none,
+    errorBorder: InputBorder.none,
+    focusedErrorBorder: InputBorder.none,
+    
+    // 其他样式...
+    isDense: true,
+    contentPadding: EdgeInsets.symmetric(horizontal: 12, vertical: 8),
+  ),
+)
+```
+
+#### 方案2: 组件级完整覆盖
+
+在 `TextField` 或自定义输入组件中：
+
+```dart
+TextField(
+  decoration: InputDecoration(
+    // 禁用填充背景
+    filled: false,
+    fillColor: Colors.transparent,
+    
+    // ← 关键：移除所有状态下的边框
+    border: InputBorder.none,
+    enabledBorder: InputBorder.none,
+    focusedBorder: InputBorder.none,      // 必须！
+    disabledBorder: InputBorder.none,
+    errorBorder: InputBorder.none,
+    focusedErrorBorder: InputBorder.none,
+    
+    // 紧凑布局
+    isDense: true,
+    contentPadding: EdgeInsets.zero,
+    
+    // 提示文本
+    hintText: '请输入',
+    hintStyle: TextStyle(color: Colors.grey),
+  ),
+)
+```
+
+---
+
+## 📋 完整修复示例
+
+### 全局主题配置
+
+```dart
+// lib/core/themes/app_theme.dart
+class AppTheme {
+  static ThemeData lightTheme = ThemeData(
+    // ... 其他配置
+    
+    inputDecorationTheme: const InputDecorationTheme(
+      // 禁用填充背景，避免 focus 时背景色变化
+      filled: false,
+      fillColor: Colors.transparent,
+      
+      // 移除所有状态下的边框
+      border: InputBorder.none,
+      enabledBorder: InputBorder.none,
+      focusedBorder: InputBorder.none,
+      disabledBorder: InputBorder.none,
+      errorBorder: InputBorder.none,
+      focusedErrorBorder: InputBorder.none,
+      
+      // 紧凑布局
+      isDense: true,
+      contentPadding: EdgeInsets.symmetric(horizontal: 12, vertical: 8),
+    ),
+  );
+}
+```
+
+### 自定义输入组件
+
+```dart
+class AppInputSection extends StatelessWidget {
+  Widget _buildTextField() {
+    return TextField(
+      controller: controller,
+      style: TextStyle(
+        fontSize: 32,
+        fontWeight: FontWeight.w800,
+        color: AppColors.textDark,
+      ),
+      decoration: InputDecoration(
+        // 双重保险：组件级也禁用
+        filled: false,
+        fillColor: Colors.transparent,
+        
+        // 完整覆盖所有边框状态
+        border: InputBorder.none,
+        enabledBorder: InputBorder.none,
+        focusedBorder: InputBorder.none,
+        disabledBorder: InputBorder.none,
+        errorBorder: InputBorder.none,
+        focusedErrorBorder: InputBorder.none,
+        
+        // 紧凑布局
+        isDense: true,
+        contentPadding: EdgeInsets.zero,
+        
+        // 提示文本
+        hintText: hint,
+        hintStyle: TextStyle(color: AppColors.textDarkTertiary),
+      ),
+      onChanged: onChanged,
+    );
+  }
+}
+```
+
+---
+
+## 💡 边框状态完整对照表
+
+| 状态 | 属性 | 何时生效 | 优先级 |
+|------|------|---------|--------|
+| 默认 | `border` | 其他状态未设置时 | 最低 |
+| 启用 | `enabledBorder` | 输入框可用但未聚焦 | 中 |
+| 聚焦 | `focusedBorder` | 输入框获得焦点 | **高** ⭐ |
+| 禁用 | `disabledBorder` | 输入框被禁用 | 中 |
+| 错误 | `errorBorder` | 验证失败 | 中 |
+| 聚焦错误 | `focusedErrorBorder` | 验证失败且聚焦 | 高 |
+
+**最常见的错位**：只设置 `border`，忽略了 `focusedBorder`！
+
+---
+
+## 🔗 相关案例
+
+- [shadow-透出问题](./shadow-透出问题.md) - 新拟态输入框的阴影实现
+- [layout-尺寸不匹配](./layout-尺寸不匹配.md) - 输入框精确布局
+
+---
+
+**来源**: my_flutter 项目实战经验  
+**创建日期**: 2025-12-31  
+**最后验证**: 2026-01-16  
+**节省时间**: 6-9 轮对话