mta-mcp 2.13.0 → 2.14.0

package/troubleshooting/flutter/layout-/345/260/272/345/257/270/344/270/215/345/214/271/351/205/215.md

@@ -0,0 +1,214 @@
+# Flutter 布局尺寸不匹配问题
+
+> **问题标签**: `layout`, `sizing`, `design-spec`, `position`, `padding`  
+> **问题类型**: 布局偏差  
+> **框架**: Flutter  
+> **严重程度**: 中等
+
+---
+
+## 🔍 问题识别
+
+### 自动检测特征
+
+```dart
+// 代码模式匹配 - 使用自动布局
+Row(
+  mainAxisAlignment: MainAxisAlignment.spaceBetween,
+  children: [...]
+)
+// 或
+Expanded(child: ...)
+// 或缺少明确的尺寸
+```
+
+### 用户描述关键词
+- "位置跟设计稿不一样"
+- "间距不对"
+- "元素偏移了"
+- "尺寸不匹配"
+- "布局差不多但不精确"
+
+### 问题特征
+- [ ] 输入框内元素间距与设计稿不符
+- [ ] 国旗/图标/分隔线位置偏移
+- [ ] 容器宽高与设计稿不一致
+- [ ] 边框粗细或圆角不对
+- [ ] 使用了 `MainAxisAlignment` 自动分布
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 调整 padding/margin 值 | 依赖猜测，无法精确 | 2-3 轮对话 |
+| 使用 `MainAxisAlignment.spaceBetween` | 间距不可控 | 1-2 轮对话 |
+| 依赖 `Expanded` 自动填充 | 宽度与设计稿不符 | 1-2 轮对话 |
+| 忽略设计稿像素值 | 总是"差不多"但不精确 | 持续问题 |
+
+**总计浪费**: 4-7 轮对话
+
+---
+
+## ✅ 正确解决方案
+
+### 核心原理
+
+**问题根源**：未从设计稿提取精确坐标，依赖 Flutter 的自动布局系统。
+
+Flutter 的 `Row`、`MainAxisAlignment`、`Expanded` 等会自动分配空间，但这种"自动"无法保证与设计稿完全一致。
+
+### 解决步骤
+
+#### 1. 从设计稿提取精确坐标
+
+使用 Sketch MCP 工具或设计软件获取每个元素的精确位置：
+
+```
+设计稿规格示例 (国家代码选择器):
+- 容器: 290x54, 圆角16
+- 国旗 emoji: x=12, fontSize=20
+- +61 文字: x=40, fontSize=15, fontWeight=600
+- 下拉箭头: x=76, size=16x16
+- 分隔线: x=98, 1x34
+- 输入区起点: x=110
+```
+
+#### 2. 使用固定宽度而非弹性布局
+
+```dart
+// ❌ 错误：依赖自动布局
+Row(
+  mainAxisAlignment: MainAxisAlignment.spaceBetween,
+  children: [国旗, 区号, 箭头, 分隔线, 输入框],
+)
+
+// ✅ 正确：固定宽度容器
+Row(
+  children: [
+    Container(
+      width: 98, // 精确到分隔线位置 (设计稿 x=98)
+      padding: const EdgeInsets.only(left: 12), // 国旗起点 x=12
+      child: Row(
+        children: [
+          const Text('🇦🇺', style: TextStyle(fontSize: 20)),
+          const SizedBox(width: 5), // 间距精确计算：40 - 12 - 20 = 8（约5）
+          const Text(
+            '+61',
+            style: TextStyle(
+              fontSize: 15,
+              fontWeight: FontWeight.w600,
+              color: Color(0xFF1C2B45),
+            ),
+          ),
+          const SizedBox(width: 4), // 间距：76 - 40 - 文字宽度
+          const Icon(Icons.keyboard_arrow_down, size: 16, color: Color(0x44CCCCCC)),
+        ],
+      ),
+    ),
+    Container(
+      width: 1, 
+      height: 34, 
+      color: const Color(0x331C2B45)
+    ), // 分隔线
+    Expanded(child: TextField(...)), // 输入区从 x=110 开始
+  ],
+)
+```
+
+#### 3. 精确设置边框和圆角
+
+```dart
+decoration: BoxDecoration(
+  borderRadius: BorderRadius.circular(16), // 设计稿圆角值
+  border: Border.all(
+    color: const Color(0x99FFFFFF), // 设计稿边框颜色
+    width: 1, // 设计稿边框粗细
+  ),
+),
+```
+
+---
+
+## 📋 精确还原检查清单
+
+### 必须从设计稿读取的值
+
+- [ ] **容器尺寸**: width, height
+- [ ] **圆角**: borderRadius 值
+- [ ] **边框**: color, width
+- [ ] **内边距**: padding (top, right, bottom, left)
+- [ ] **元素坐标**: 每个子元素的 x, y 位置
+- [ ] **间距**: SizedBox 的精确数值
+- [ ] **字体**: fontSize, fontWeight, color
+- [ ] **图标**: size, color
+
+### 计算间距的方法
+
+```
+元素B的左边距 = 元素B的x坐标 - 元素A的x坐标 - 元素A的宽度
+
+示例：
+国旗x=12, width=20
+区号x=40
+间距 = 40 - 12 - 20 = 8px
+```
+
+---
+
+## 💡 预防措施
+
+### 1. 不要依赖自动布局
+
+```dart
+// ❌ 避免
+mainAxisAlignment: MainAxisAlignment.spaceBetween
+mainAxisAlignment: MainAxisAlignment.spaceEvenly
+Expanded(flex: 1)
+
+// ✅ 推荐
+Container(width: 精确值)
+SizedBox(width: 精确值)
+Positioned(left: 精确值, top: 精确值)
+```
+
+### 2. 使用 Sketch MCP 工具
+
+在 Copilot Chat 中直接查询设计稿：
+
+```
+@copilot 从 Sketch 获取"国家代码选择器"的布局坐标
+```
+
+### 3. 创建布局配置类
+
+```dart
+class LoginInputConfig {
+  // 国家代码选择器
+  static const countryWidth = 98.0;
+  static const flagX = 12.0;
+  static const codeX = 40.0;
+  static const arrowX = 76.0;
+  static const dividerX = 98.0;
+  
+  // 输入框
+  static const inputHeight = 54.0;
+  static const borderRadius = 16.0;
+  static const borderWidth = 1.0;
+}
+```
+
+---
+
+## 🔗 相关案例
+
+- [shadow-透出问题](./shadow-透出问题.md) - 新拟态容器的完整实现
+- [input-字段缺失](./input-字段缺失.md) - 自定义输入组件配置
+
+---
+
+**来源**: my_flutter 项目实战经验  
+**创建日期**: 2025-12-31  
+**最后验证**: 2026-01-16  
+**节省时间**: 4-7 轮对话

package/troubleshooting/flutter/shadow-/351/200/217/345/207/272/351/227/256/351/242/230.md

@@ -0,0 +1,172 @@
+# Flutter 阴影透出问题
+
+> **问题标签**: `shadow`, `neumorphism`, `transparency`, `boxshadow`  
+> **框架**: Flutter  
+> **严重程度**: 中等（视觉问题）
+
+---
+
+## 🔍 问题识别
+
+### 自动检测特征
+
+```dart
+// 代码模式匹配
+BoxShadow(
+  color: Color(0x??000000), // 包含黑色阴影
+  // ...
+)
+// + 半透明背景
+color: Color(0x??FFFFFF)
+```
+
+### 用户描述关键词
+- "阴影透出来了"
+- "容器比设计稿暗"
+- "失去通透感"
+- "新拟态效果不对"
+- "毛玻璃效果变灰"
+
+### 问题特征
+- [ ] 半透明容器颜色比设计稿更暗
+- [ ] 容器有 BoxShadow 阴影
+- [ ] 阴影包含深色（黑色/灰色）
+- [ ] 视觉上失去"玻璃感"或"通透感"
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 降低容器透明度 | 治标不治本，破坏设计稿规格 | 1-2 轮对话 |
+| 修改全局主题 fillColor | 问题不在主题层 | 2-3 轮对话 |
+| 调整阴影颜色/大小 | 只要阴影在下方就会透出 | 2-3 轮对话 |
+| 使用深色背景模拟 | Hack 方案，不同背景下失效 | 1-2 轮对话 |
+
+**总计浪费**: 6-10 轮对话
+
+---
+
+## ✅ 正确解决方案
+
+### 核心原理
+
+Flutter `BoxShadow` 绘制在容器**下方**，当容器背景半透明时，阴影颜色会透过容器显示出来。
+
+```
+┌─────────────────────────┐
+│      阴影层（黑色）       │  ← 最底层
+├─────────────────────────┤
+│   容器层（55%白色）       │  ← 半透明，下面的黑色透出来
+├─────────────────────────┤
+│      内容层              │
+└─────────────────────────┘
+
+结果: 55%白色 + 黑色阴影 = 偏暗的灰色
+```
+
+### 解决方法：空心阴影 (Hollow Shadow)
+
+使用 `CustomPainter` 绘制阴影，但裁剪掉中间的容器区域。
+
+```dart
+import 'dart:ui' as ui;
+
+class HollowShadowPainter extends CustomPainter {
+  final List<BoxShadow> shadows;
+  final double radius;
+
+  HollowShadowPainter({required this.shadows, required this.radius});
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    final RRect shape = RRect.fromRectAndRadius(
+      Rect.fromLTWH(0, 0, size.width, size.height),
+      Radius.circular(radius),
+    );
+
+    final Path shapePath = Path()..addRRect(shape);
+    final Path canvasPath = Path()
+      ..addRect(Rect.fromLTWH(-500, -500, size.width + 1000, size.height + 1000));
+
+    // 关键：挖空中间区域
+    final Path outerPath = Path.combine(
+      ui.PathOperation.difference,
+      canvasPath,
+      shapePath,
+    );
+
+    canvas.save();
+    canvas.clipPath(outerPath); // 只在外部绘制
+
+    for (final shadow in shadows) {
+      final Paint shadowPaint = Paint()
+        ..color = shadow.color
+        ..maskFilter = MaskFilter.blur(
+          BlurStyle.normal, 
+          shadow.blurRadius * 0.57735 + 0.5,
+        );
+      canvas.drawRRect(
+        shape.inflate(shadow.spreadRadius).shift(shadow.offset), 
+        shadowPaint,
+      );
+    }
+
+    canvas.restore();
+  }
+
+  @override
+  bool shouldRepaint(covariant HollowShadowPainter oldDelegate) {
+    return oldDelegate.shadows != shadows || oldDelegate.radius != radius;
+  }
+}
+```
+
+### 使用示例
+
+```dart
+Widget _buildNeumorphicContainer({required Widget child, double height = 54}) {
+  return CustomPaint(
+    painter: HollowShadowPainter(
+      radius: 16,
+      shadows: const [
+        BoxShadow(color: Color(0x0D000000), blurRadius: 3, offset: Offset(0, 1)),
+        BoxShadow(color: Color(0x14000000), blurRadius: 5, offset: Offset(2, 2)),
+        BoxShadow(color: Color(0xE6FFFFFF), blurRadius: 5, offset: Offset(-2, -2)),
+      ],
+    ),
+    child: Container(
+      height: height,
+      decoration: BoxDecoration(
+        color: const Color(0x8CFFFFFF), // 可以放心使用设计稿透明度
+        borderRadius: BorderRadius.circular(16),
+        border: Border.all(color: const Color(0x99FFFFFF), width: 1),
+      ),
+      child: child,
+    ),
+  );
+}
+```
+
+---
+
+## 📋 适用场景
+
+- ✅ 新拟态 (Neumorphism) 设计
+- ✅ 毛玻璃/磨砂玻璃效果
+- ✅ 任何需要半透明背景 + 阴影的场景
+- ✅ iOS 风格 UI
+
+---
+
+## 🔗 相关案例
+
+- [layout-尺寸不匹配.md](./layout-尺寸不匹配.md) - 新拟态容器尺寸调整
+- [input-字段缺失.md](./input-字段缺失.md) - CustomPainter 配合输入框使用
+
+---
+
+**来源**: my_flutter 项目实战经验  
+**创建日期**: 2025-12-31  
+**最后验证**: 2026-01-16

package/troubleshooting/flutter/sketch-/345/233/276/346/240/207/345/260/272/345/257/270.md

@@ -0,0 +1,135 @@
+# Sketch 图标尺寸提取问题
+
+> **问题标签**: `sketch`, `icon`, `size`, `group`, `shape`  
+> **框架**: Flutter  
+> **严重程度**: 中等（还原精度）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "图标尺寸与设计稿不符"
+- "设置了尺寸但没效果"
+- "Group 和 Shape 尺寸不一样"
+- "提取的尺寸是外层容器的"
+
+### 问题特征
+- [ ] 从 Sketch 提取了图标尺寸
+- [ ] 实际显示比预期大或小
+- [ ] Sketch 中图标有 Group 包裹
+- [ ] Group 尺寸与内部 Shape 尺寸不同
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：Sketch 中图标通常有两层结构，外层 Group 用于布局定位，内层 Shape 才是实际视觉尺寸。
+
+```
+Sketch 图标结构:
+├─ Group "Tab Icon" (22x22)       ← 外层容器，用于布局
+│  └─ Shape "Icon_path" (14.67x14.67)  ← 内部实际图形
+```
+
+如果提取外层 Group 的尺寸，图标会比设计稿看起来大。
+
+---
+
+## ✅ 正确解决方案
+
+### 使用脚本提取内部 Shape 尺寸
+
+```javascript
+// Sketch 脚本：提取图标的内部实际尺寸
+const sketch = require('sketch');
+const document = sketch.getSelectedDocument();
+const page = document.selectedPage;
+
+function extractIconInternalSize(frameName) {
+  const frame = sketch.find(`[name="${frameName}"]`, page)[0];
+  if (!frame) return console.log('Frame not found');
+  
+  function traverse(layer, parentY = 0) {
+    const f = layer.frame;
+    const absY = parentY + f.y;
+    
+    if (layer.type === 'Group' && layer.name.includes('Icon')) {
+      console.log(`\n📦 ${layer.name} (外层 Group): ${f.width}x${f.height}`);
+      layer.layers?.forEach(child => {
+        if (child.type === 'Shape' || child.type === 'ShapePath') {
+          const cf = child.frame;
+          console.log(`  └─ ${child.name} (内部图形): ${cf.width.toFixed(1)}x${cf.height.toFixed(1)} ← 使用这个`);
+        }
+      });
+    }
+    if (layer.layers) layer.layers.forEach(child => traverse(child, absY));
+  }
+  traverse(frame);
+}
+
+extractIconInternalSize('Frame Name');
+```
+
+### 输出示例
+
+```
+📦 Tab Recipient Icon (外层 Group): 22x22
+  └─ Tab Recipient Icon_path_0 (内部图形): 14.7x14.7 ← 使用这个尺寸
+```
+
+### Flutter 中使用正确尺寸
+
+```dart
+// ✅ 使用内部图形的实际尺寸
+SvgPicture.asset(
+  'assets/icons/recipient.svg',
+  width: 15.0,  // 14.7 取整
+  height: 15.0,
+)
+
+// ❌ 错误：使用外层 Group 尺寸
+SvgPicture.asset(
+  'assets/icons/recipient.svg',
+  width: 22.0,  // 这是 Group 尺寸，图标会偏大
+  height: 22.0,
+)
+```
+
+---
+
+## 📝 验证检查清单
+
+1. **确认提取的是 Shape 尺寸**
+   - 不是 Group、Frame、Artboard 的尺寸
+   - 查看脚本输出中带 ← 标记的行
+
+2. **视觉对比验证**
+   - 在模拟器/设备上与设计稿截图对比
+   - 图标边缘应与设计稿完全重合
+
+3. **属性使用验证**
+   ```bash
+   # 搜索确认尺寸属性被使用
+   grep -n "iconSize" lib/widgets/my_widget.dart
+   ```
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 调整 Flutter 中的尺寸 | 如果基准就错了，调来调去 | 3-5 轮对话 |
+| 添加 transform scale | Hack 方案，难以精确 | 2-3 轮对话 |
+| 重新导出 SVG | 如果不知道问题在哪，重复错误 | 2-3 轮对话 |
+
+**最佳做法**：先用脚本确认正确尺寸，再修改代码
+
+---
+
+## 📁 适用场景
+
+- ✅ TabBar 图标
+- ✅ 按钮内图标
+- ✅ 任何从 Sketch 导出的图标