# 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 布局调试实战
