mta-mcp 2.17.0 → 3.0.0

package/troubleshooting/flutter/sketch-/345/261/236/346/200/247/346/234/252/344/275/277/347/224/250.md

@@ -1,139 +0,0 @@
-# 组件属性定义但未使用问题
-
-> **问题标签**: `property`, `unused`, `debug`, `widget`  
-> **框架**: Flutter  
-> **严重程度**: 高（功能无效）
-
----
-
-## 🔍 问题识别
-
-### 用户描述关键词
-- "设置了属性但没效果"
-- "参数不生效"
-- "改了值但 UI 没变化"
-- "属性没有被使用"
-
-### 问题特征
-- [ ] 在组件类中定义了新属性
-- [ ] 修改属性值后 UI 没有变化
-- [ ] 没有编译错误
-- [ ] 运行正常但功能不符合预期
-
----
-
-## 🎯 核心原理
-
-**根本原因**：在类中定义了属性，但在 `build` 方法中没有实际使用该属性。
-
-```dart
-// ❌ 错误示例：定义了 iconSize 但没使用
-class MyIcon extends StatelessWidget {
-  const MyIcon({
-    super.key,
-    this.iconSize = 24.0, // 定义了属性
-  });
-  
-  final double iconSize; // 有这个字段
-  
-  @override
-  Widget build(BuildContext context) {
-    return Icon(
-      Icons.star,
-      size: 24.0, // ← 直接写死了！没用 iconSize
-    );
-  }
-}
-```
-
----
-
-## ✅ 正确解决方案
-
-### 1. 验证属性被使用
-
-```bash
-# 搜索属性在文件中的使用情况
-grep -n "iconSize" lib/widgets/my_icon.dart
-
-# 期望输出：
-# 5: this.iconSize = 24.0,   ← 定义
-# 8: final double iconSize;  ← 字段
-# 14: size: iconSize,        ← 使用 ✅
-```
-
-### 2. 正确使用属性
-
-```dart
-// ✅ 正确示例
-class MyIcon extends StatelessWidget {
-  const MyIcon({
-    super.key,
-    this.iconSize = 24.0,
-  });
-  
-  final double iconSize;
-  
-  @override
-  Widget build(BuildContext context) {
-    return Icon(
-      Icons.star,
-      size: iconSize, // ← 使用属性
-    );
-  }
-}
-```
-
-### 3. 添加属性后的验证清单
-
-每次添加新属性后必须检查：
-
-- [ ] 属性在 constructor 中定义
-- [ ] 属性有对应的 final 字段
-- [ ] 属性在 build 方法中被引用
-- [ ] 修改属性值后 UI 确实变化
-
----
-
-## 📝 快速调试方法
-
-```dart
-// 临时添加打印语句验证
-@override
-Widget build(BuildContext context) {
-  print('🔍 iconSize: $iconSize'); // 确认值正确
-  return Icon(
-    Icons.star,
-    size: iconSize,
-  );
-}
-```
-
-```dart
-// 或使用断言
-@override
-Widget build(BuildContext context) {
-  assert(iconSize > 0, 'iconSize must be positive');
-  // ...
-}
-```
-
----
-
-## ❌ 常见错误排查路线（避免重复）
-
-| 尝试方向 | 为什么无效 | 浪费时间 |
-|----------|-----------|---------|
-| 调整属性默认值 | 如果没使用，改默认值也没用 | 1-2 轮对话 |
-| 添加更多属性 | 同样的问题会重复 | 2-3 轮对话 |
-| 检查父组件传值 | 如果子组件没用，传什么都一样 | 1-2 轮对话 |
-
-**最佳做法**：先 grep 确认属性被使用，再调试其他问题
-
----
-
-## 📁 适用场景
-
-- ✅ 自定义 Widget 开发
-- ✅ 组件可配置化
-- ✅ 任何涉及属性传递的场景

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

@@ -1,264 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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

@@ -1,117 +0,0 @@
-# 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 的场景