mta-mcp 1.0.0

package/troubleshooting/flutter/sketch-/350/203/214/346/231/257/345/261/202/351/253/230/345/272/246.md

@@ -0,0 +1,264 @@
+# Sketch Frame 与 Background 层高度差异问题
+
+> **问题标签**: `sketch`, `frame`, `background`, `height`, `_background`, `_bg`  
+> **框架**: Flutter  
+> **严重程度**: 高（导致布局错位和多轮返工）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "间距不对"
+- "高度算错了"
+- "内边距有问题"
+- "最后一个 item 高度不对"
+- "卡片高度不匹配"
+
+### 问题特征
+- [ ] 计算的间距与设计稿视觉效果不符
+- [ ] 使用 Frame 高度计算，但结果总是差几像素
+- [ ] Menu/List 的第一个或最后一个 item 高度异常
+- [ ] 多个卡片之间的 gap 计算错误
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：Sketch 的 Frame（组/画板）高度与其内部 `_background` 或 `_bg` 层高度可能不同。
+
+### Sketch 层级结构示例
+
+```
+Menu Card (Frame)         ← height: 336px ❌ 错误值
+├── Menu Card_background  ← height: 350px ✅ 正确值
+├── Menu Item 1
+├── Divider 1
+├── Menu Item 2
+...
+
+Warning Card (Frame)      ← height: 100px ❌ 错误值
+├── Warning Card_bg       ← height: 127px ✅ 正确值
+├── Warning Text
+├── Button
+```
+
+| 元素 | Frame 高度 | _background 高度 | 差异 |
+|------|------------|------------------|------|
+| Menu Card | 336px | 350px | +14px |
+| Warning Card | 100px | 127px | +27px |
+
+### 为什么会这样？
+
+1. **Auto Layout**: Frame 可能使用 Hug Contents 或固定高度
+2. **阴影/装饰**: _background 层包含了内边距、阴影区域
+3. **Padding 内含**: 背景层可能比 Frame 更大以提供视觉边距
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 使用 Frame 高度计算 gap | 背景层实际更大 | 3-5 轮对话 |
+| 反复调整 padding | 不知道正确的参考值 | 4-6 轮对话 |
+| 假设最后 item 与其他相同 | 底部 padding 通常不同 | 2-3 轮对话 |
+| 只测量 divider 位置 | 忽略了背景层边界 | 2-3 轮对话 |
+
+**总计浪费**: 10-15 轮对话
+
+---
+
+## ✅ 正确解决方案
+
+### 解决步骤
+
+#### 1. 必须同时测量 Frame 和 _background 层
+
+```javascript
+// Sketch 测量脚本 - 比较 Frame 与背景层高度
+const sketch = require('sketch');
+const doc = sketch.getSelectedDocument();
+const page = doc.selectedPage;
+const target = sketch.find('[name="Profile Page"]', page)[0]; // 替换为目标
+
+function measureBackgroundLayers(container) {
+  const results = {};
+  
+  sketch.find('*', container).forEach(layer => {
+    const name = layer.name;
+    
+    // 查找 Frame 和对应的 _background/_bg 层
+    if (name.includes('Card') || name.includes('Panel')) {
+      results[name] = {
+        type: layer.type,
+        frameHeight: layer.frame.height,
+        y: layer.frame.y
+      };
+    }
+    
+    // 单独记录 _background 和 _bg 层
+    if (name.includes('_background') || name.includes('_bg')) {
+      results[name] = {
+        type: layer.type,
+        height: layer.frame.height,
+        y: layer.frame.y
+      };
+    }
+  });
+  
+  console.log(JSON.stringify(results, null, 2));
+}
+
+measureBackgroundLayers(target);
+```
+
+#### 2. 使用 _background 层高度计算布局
+
+```dart
+// ❌ 错误: 使用 Frame 高度
+const warningCardHeight = 100; // Frame 高度
+const menuCardY = 274;
+const gap = menuCardY - (warningCardY + warningCardHeight);
+// gap = 274 - (130 + 100) = 44px ❌
+
+// ✅ 正确: 使用 _background 层高度
+const warningCardHeight = 127; // _bg 层高度
+const gap = menuCardY - (warningCardY + warningCardHeight);
+// gap = 274 - (130 + 127) = 17px ✅
+```
+
+#### 3. 区分列表首尾 item 的 padding
+
+Menu/List 类组件中，首尾 item 通常与背景边缘有特殊间距：
+
+```javascript
+// 测量 divider 位置和背景层边界
+const dividers = sketch.find('[name*="Divider"]', menuCard);
+const background = sketch.find('[name*="_background"]', menuCard)[0];
+
+dividers.forEach(d => {
+  console.log(`${d.name}: y=${d.frame.y}`);
+});
+console.log(`Background height: ${background.frame.height}`);
+
+// 计算每个区域高度
+// Item 1: 0 → divider1.y
+// Item 2-N-1: divider[i-1].y → divider[i].y  
+// Item N: divider[N-1].y + 1 → background.height
+```
+
+#### 4. Flutter 实现：区分首尾 item
+
+```dart
+Widget _buildMenuItem(int index, MenuItem item) {
+  // Sketch 精确测量 (Menu Card_background = 350px):
+  // - Item 1: 区域63px = top:20 + icon:36 + bottom:6 + divider:1
+  // - Item 2-5: 区域56px = top:12 + icon:36 + bottom:7 + divider:1
+  // - Item 6: 区域63px = top:12 + icon:36 + bottom:15 (无divider)
+  
+  return Padding(
+    padding: EdgeInsets.fromLTRB(
+      16,
+      index == 0 ? 20 : 12,           // 首 item top 更大
+      16,
+      index == 0 ? 6 : (index == 5 ? 15 : 7), // 尾 item bottom 更大
+    ),
+    child: Row(...),
+  );
+}
+```
+
+---
+
+## 🔑 关键公式
+
+### 卡片间距计算
+
+```
+实际 gap = 下一卡片.y - (当前卡片.y + 当前卡片._background.height)
+```
+
+### 列表 item 区域计算
+
+```
+区域[0] = divider[0].y                           // 首 item
+区域[i] = divider[i].y - divider[i-1].y          // 中间 items (含 divider)
+区域[N] = background.height - divider[N-1].y - 1 // 尾 item (无 divider)
+```
+
+### Icon 垂直 padding 计算
+
+```
+top_padding = icon.y - region_start
+bottom_padding = region_end - (icon.y + icon.height) - divider_height
+```
+
+---
+
+## ⚠️ 预防措施
+
+### 提取 Sketch 时的检查清单
+
+- [ ] 是否同时读取了 Frame 高度和 _background/_bg 层高度？
+- [ ] 两者是否相同？如果不同，使用哪个？
+- [ ] 卡片之间的 gap 是否基于视觉边界（_background）计算？
+- [ ] 列表的首尾 item 是否有特殊的 padding？
+
+### 命名约定识别
+
+| 后缀 | 含义 | 使用场景 |
+|------|------|----------|
+| `_background` | 完整背景层 | 用于计算实际高度 |
+| `_bg` | 简化背景层 | 同上 |
+| `_shadow` | 阴影层 | 可能影响视觉边界 |
+| `_border` | 边框层 | 不影响高度计算 |
+
+---
+
+## 📊 真实案例
+
+### 案例: Profile 页面卡片间距
+
+**问题**: Warning Card 到 Menu Card 的间距应该是 17px，但计算得到 44px
+
+**错误分析**:
+```
+Menu Card.y = 274
+Warning Card.y = 130
+Warning Card Frame.height = 100  ← 使用了错误的值
+
+gap = 274 - (130 + 100) = 44px ❌
+```
+
+**正确分析**:
+```
+Menu Card.y = 274
+Warning Card.y = 130  
+Warning Card_bg.height = 127  ← 使用 _bg 层高度
+
+gap = 274 - (130 + 127) = 17px ✅
+```
+
+**修复代码**:
+```dart
+// 修改前
+SizedBox(height: 44),
+
+// 修改后
+SizedBox(height: 17),
+```
+
+---
+
+## 🔗 相关问题
+
+- [layout-尺寸不匹配.md](./layout-尺寸不匹配.md) - 通用布局问题
+- [sketch-完整提取.md](./sketch-完整提取.md) - 完整提取脚本
+- [sketch-图标尺寸.md](./sketch-图标尺寸.md) - SVG 尺寸问题
+
+---
+
+**创建日期**: 2026-01-19  
+**最后更新**: 2026-01-19  
+**来源**: Profile 页面 Menu Card 布局调试实战

package/troubleshooting/flutter/svg-/346/234/252/345/261/205/344/270/255.md

@@ -0,0 +1,120 @@
+# Flutter SVG 未居中问题
+
+> **问题标签**: `svg`, `viewbox`, `center`, `alignment`, `icon`  
+> **框架**: Flutter  
+> **严重程度**: 低（布局问题）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "SVG 图标没有居中"
+- "图标位置偏了"
+- "需要用 Center 包裹"
+- "viewBox 不对"
+
+### 问题特征
+- [ ] SVG 显示位置与预期不符
+- [ ] 需要额外的 Center/Align 组件包裹
+- [ ] SVG viewBox 尺寸与使用尺寸不匹配
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：Sketch 导出 SVG 时，viewBox 可能是图形的最小边界框，而非设计稿中的容器尺寸。
+
+```xml
+<!-- ❌ 问题：viewBox 是最小边界框 -->
+<!-- 箭头图标实际尺寸是 6x3，但需要放在 12x12 的容器中 -->
+<svg viewBox="0 0 6 3">
+  <path d="..."/>
+</svg>
+```
+
+```dart
+// 放在 12x12 容器中，图标会被拉伸或需要额外居中处理
+SvgPicture.asset('arrow.svg', width: 12, height: 12);
+```
+
+---
+
+## ✅ 正确解决方案
+
+### 方案1：导出时保留完整 viewBox（推荐）
+
+在 Sketch 中导出 SVG 时，选择图标所在的外层容器（Group），而非内部的形状：
+
+```javascript
+// Sketch 脚本：导出完整容器的 SVG
+const sketch = require('sketch');
+const layer = sketch.find('[name="Icon Container"]')[0]; // 选择外层 Group
+const svg = sketch.export(layer, { formats: 'svg', output: false });
+```
+
+```xml
+<!-- ✅ 正确：viewBox 包含完整容器空间 -->
+<svg viewBox="0 0 12 12">
+  <!-- 箭头在容器中的正确位置 -->
+  <path transform="translate(3, 4.5)" d="..."/>
+</svg>
+```
+
+### 方案2：Flutter 中手动设置对齐
+
+```dart
+// 如果 SVG 无法重新导出，在 Flutter 中处理
+SizedBox(
+  width: 12,
+  height: 12,
+  child: Center(
+    child: SvgPicture.asset(
+      'arrow.svg',
+      width: 6,  // 使用 SVG 实际尺寸
+      height: 3,
+    ),
+  ),
+)
+```
+
+---
+
+## 📝 Sketch 图标导出检查清单
+
+1. **确认选择正确的图层**
+   - 选择外层 Group/Frame，而非内部 Shape
+   - 外层应该是设计稿中图标的"点击区域"尺寸
+
+2. **验证导出的 viewBox**
+   ```bash
+   # 检查 SVG 文件的 viewBox
+   head -3 assets/icons/arrow.svg
+   # 应该看到 viewBox="0 0 12 12" 而非 viewBox="0 0 6 3"
+   ```
+
+3. **检查 Flutter 中的使用**
+   ```dart
+   // 宽高应该与 viewBox 匹配
+   SvgPicture.asset('arrow.svg', width: 12, height: 12);
+   ```
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 用 Center 包裹 | 治标不治本，每个图标都要处理 | 1 轮对话/图标 |
+| 调整 alignment 属性 | SvgPicture 的 alignment 可能不生效 | 1-2 轮对话 |
+| 修改 SVG 的 transform | 需要计算精确偏移量 | 2-3 轮对话 |
+
+**最佳做法**：从源头修复，重新导出正确 viewBox 的 SVG
+
+---
+
+## 📁 适用场景
+
+- ✅ 小尺寸图标（箭头、点击指示器等）
+- ✅ 需要放在固定容器中的图标
+- ✅ TabBar、按钮中的图标

package/troubleshooting/flutter/svg-/351/242/234/350/211/262/345/274/202/345/270/270.md

@@ -0,0 +1,117 @@
+# Flutter SVG 颜色异常问题
+
+> **问题标签**: `svg`, `color`, `colorfilter`, `transparency`, `icon`  
+> **框架**: Flutter  
+> **严重程度**: 中等（视觉问题）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "SVG 颜色比设计稿浅"
+- "图标颜色不对"
+- "透明度丢失"
+- "图标颜色变淡了"
+
+### 问题特征
+- [ ] 使用 flutter_svg 加载 SVG 图标
+- [ ] 使用了 ColorFilter.mode
+- [ ] SVG 原本有透明度（如 #1C2B45B3）
+- [ ] 实际显示颜色比设计稿浅
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：`ColorFilter.mode(color, BlendMode.srcIn)` 会完全覆盖 SVG 的原有颜色和透明度。
+
+```dart
+// Sketch 设计稿：#1C2B45B3（70% 透明度的深蓝色）
+// SVG 文件中：fill="#1C2B45" fill-opacity="0.7"
+
+// ❌ 使用 ColorFilter 后：
+SvgPicture.asset(
+  'icon.svg',
+  colorFilter: ColorFilter.mode(
+    Color(0xFF1C2B45), // 只有颜色，没有透明度
+    BlendMode.srcIn,   // 完全覆盖原有样式
+  ),
+)
+// 结果：显示为 100% 的深蓝色，比设计稿深/浅
+```
+
+---
+
+## ✅ 正确解决方案
+
+### 方案1：保留 SVG 原有样式（推荐）
+
+```dart
+// ✅ 不使用 colorFilter，保留 SVG 原有颜色和透明度
+SvgPicture.asset(
+  'assets/icons/dropdown_arrow.svg',
+  width: 12,
+  height: 12,
+  // 不传 colorFilter
+)
+```
+
+### 方案2：需要动态颜色时，包含透明度
+
+```dart
+// ✅ 如果必须使用 colorFilter，颜色要包含 alpha
+SvgPicture.asset(
+  'icon.svg',
+  colorFilter: customColor != null
+      ? ColorFilter.mode(
+          customColor.withValues(alpha: 0.7), // 保留透明度
+          BlendMode.srcIn,
+        )
+      : null, // 无自定义颜色时保留原样式
+)
+```
+
+### 方案3：SVG 导出时保留透明度信息
+
+```xml
+<!-- Sketch 导出 SVG 时确保保留 fill-opacity -->
+<path fill="#1C2B45" fill-opacity="0.7" d="..."/>
+```
+
+---
+
+## 📝 Sketch 颜色透明度转换
+
+Sketch 颜色格式：`#RRGGBBAA`（最后两位是透明度）
+
+| Sketch | Flutter | 说明 |
+|--------|---------|------|
+| #1C2B45B3 | Color(0xB31C2B45) | 70% 透明度 |
+| #00000080 | Color(0x80000000) | 50% 透明度 |
+| #FFFFFF26 | Color(0x26FFFFFF) | 15% 透明度 |
+
+**常用透明度对照表**：
+- 100% = FF
+- 70% = B3
+- 50% = 80
+- 30% = 4D
+- 15% = 26
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 调整 SVG 本身的颜色 | ColorFilter 会覆盖 | 1-2 轮对话 |
+| 修改 BlendMode | srcIn 是正确的混合模式 | 1-2 轮对话 |
+| 用 Opacity widget 包裹 | 影响整个图标，不是颜色透明度 | 1 轮对话 |
+
+---
+
+## 📁 适用场景
+
+- ✅ 设计稿中有透明度的图标
+- ✅ TabBar 图标
+- ✅ 任何使用 flutter_svg 的场景

package/troubleshooting/flutter/tabbar-/345/212/250/347/224/273/345/220/214/346/255/245.md

@@ -0,0 +1,107 @@
+# Flutter TabBar 动画同步问题
+
+> **问题标签**: `tabbar`, `animation`, `neumorphism`, `color`, `sync`  
+> **框架**: Flutter  
+> **严重程度**: 中等（视觉体验）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "颜色变化太快"
+- "动画不同步"
+- "背景块还没移动图标就变色了"
+- "选中/未选中切换不流畅"
+
+### 问题特征
+- [ ] TabBar 有背景滑块动画
+- [ ] 图标/文字颜色需要随选中状态变化
+- [ ] 背景块使用 AnimatedPositioned/AnimatedContainer
+- [ ] 颜色使用 setState 直接切换
+
+---
+
+## 🎯 核心原理
+
+**根本原因**：背景块使用了动画（如 AnimatedPositioned），但颜色切换使用 `setState` 立即更新，导致颜色变化比背景块移动快。
+
+```dart
+// ❌ 错误：颜色立即变化
+setState(() {
+  selectedIndex = newIndex; // 颜色立即切换
+});
+// 同时 AnimatedPositioned 的背景块需要 300ms 移动
+// 结果：图标已经变白，背景还没移到位
+```
+
+---
+
+## ✅ 正确解决方案
+
+**使用 TweenAnimationBuilder 同步所有动画**
+
+```dart
+const animDuration = Duration(milliseconds: 300);
+const animCurve = Curves.easeInOut;
+
+// 背景块动画
+AnimatedPositioned(
+  duration: animDuration,
+  curve: animCurve,
+  left: targetLeft,
+  child: greenBackground,
+)
+
+// 颜色动画（同步）
+TweenAnimationBuilder<Color?>(
+  duration: animDuration,
+  curve: animCurve,
+  tween: ColorTween(
+    begin: isSelected ? unselectedColor : selectedColor,
+    end: isSelected ? selectedColor : unselectedColor,
+  ),
+  builder: (_, color, child) => Icon(
+    icon,
+    color: color,
+    size: iconSize,
+  ),
+)
+
+// 布局动画（同步）
+AnimatedContainer(
+  duration: animDuration,
+  curve: animCurve,
+  height: isSelected ? 44.0 : 22.0,
+  child: icon,
+)
+```
+
+### 关键要点
+1. **统一动画参数**：所有动画使用相同的 `duration` 和 `curve`
+2. **颜色也要动画**：使用 `TweenAnimationBuilder<Color?>` 而非直接 setState
+3. **布局也要动画**：如果选中/未选中的布局不同，也要使用 AnimatedContainer
+
+---
+
+## ❌ 常见错误排查路线（避免重复）
+
+| 尝试方向 | 为什么无效 | 浪费时间 |
+|----------|-----------|---------|
+| 调整动画时长 | 不解决同步问题 | 1-2 轮对话 |
+| 使用 AnimatedSwitcher | 会导致整个组件重建 | 2-3 轮对话 |
+| 添加延迟切换颜色 | Hack 方案，难以精确匹配 | 2-3 轮对话 |
+
+---
+
+## 📁 适用场景
+
+- ✅ 底部导航栏 TabBar
+- ✅ 分段控制器 SegmentedControl
+- ✅ 任何需要"选中滑块 + 颜色变化"的组件
+
+---
+
+## 🔗 相关案例
+
+- [clip-阴影裁剪](./clip-阴影裁剪.md) - 滑块阴影被裁剪问题

package/troubleshooting/flutter/withopacity-/345/274/203/347/224/250.md

@@ -0,0 +1,81 @@
+# withOpacity 弃用警告
+
+> **问题标签**: `deprecation`, `color`, `opacity`, `flutter3`  
+> **框架**: Flutter  
+> **严重程度**: 低（警告）
+
+---
+
+## 🔍 问题识别
+
+### IDE 提示
+```
+'withOpacity' is deprecated and shouldn't be used.
+Use withValues to avoid precision loss.
+```
+
+### 问题特征
+- [ ] 使用了 `Color.withOpacity()`
+- [ ] IDE 显示删除线警告
+- [ ] Flutter 3.x 版本
+
+---
+
+## 🎯 核心原理
+
+**原因**：Flutter 3.x 弃用了 `withOpacity()` 方法，因为浮点数精度问题。推荐使用精度更高的 `withValues()`。
+
+---
+
+## ✅ 正确解决方案
+
+### 替换语法
+
+```dart
+// ❌ 弃用写法
+color: Colors.white.withOpacity(0.7)
+color: const Color(0xFF1C2B45).withOpacity(0.15)
+
+// ✅ 新写法
+color: Colors.white.withValues(alpha: 0.7)
+color: const Color(0xFF1C2B45).withValues(alpha: 0.15)
+```
+
+### 批量替换命令
+
+```bash
+# 查找所有使用
+grep -r "\.withOpacity(" lib/
+
+# macOS/Linux sed 替换
+find lib -name "*.dart" -exec sed -i '' 's/\.withOpacity(\([^)]*\))/.withValues(alpha: \1)/g' {} \;
+```
+
+### IDE 全局替换
+- 搜索：`.withOpacity(`
+- 替换：`.withValues(alpha: `
+- 注意：需要手动调整括号
+
+---
+
+## 📝 注意事项
+
+1. **const 表达式**：`withValues` 同样不能在 const 中使用
+   ```dart
+   // 两种都不行用于 const
+   const color = Colors.white.withOpacity(0.5); // ❌
+   const color = Colors.white.withValues(alpha: 0.5); // ❌
+   
+   // const 颜色需要直接指定 alpha
+   const color = Color(0x80FFFFFF); // ✅ 0x80 = 50% alpha
+   ```
+
+2. **alpha 范围**：0.0 - 1.0（与 withOpacity 相同）
+
+---
+
+## 📁 适用场景
+
+- ✅ Flutter 3.x 项目升级
+- ✅ 消除 IDE 警告
+- ✅ 代码规范化