figma-ios-to-code-conventions

Figma → 代码：约定与跳过规则

从 figma-ios-preload-data 数据包（design.json / index.json）还原业务界面 时，除用户另有说明外，遵守下列规则。后续可在本文 「规则列表」 中追加条目（保持编号递增）。

规则列表

1. 忽略 Home Indicator（系统底部横条）

必须跳过的节点（不要生成任何代码）：

• 节点类型：INSTANCE、COMPONENT、FRAME 或任何其他类型
• 节点名称匹配（任一即跳过）：
  • 完全匹配：Home Indicator、home indicator
  • 包含关键词：Home Indicator/（如 系统控件/home indicator/dark）
  • 包含关键词：iPhone X/Home Indicator
  • Component ID: 1:31 或类似系统组件 ID

识别特征：

• 通常位于页面底部（y ≈ 页面高度 - 34）
• 尺寸：width ≈ 页面宽度, height ≈ 34pt
• 外观：白色或黑色的圆角横条（宽约 134pt，高约 5pt）

匹配规则（强制）：

// 跳过 Home Indicator 的判断逻辑
function shouldSkipNode(node) {
  const name = node.name.toLowerCase();
  
  // 规则 1: 名称包含 "home indicator"
  if (name.includes('home indicator')) {
    return true;
  }
  
  // 规则 2: 名称包含 "home-indicator"（短横线）
  if (name.includes('home-indicator')) {
    return true;
  }
  
  // 规则 3: 特定 component ID（视具体文件而定）
  if (node.id === '1:31' || node.id === '1:326') {
    return true;
  }
  
  return false;
}

Swift 代码生成时：

• ❌ 禁止：创建 homeIndicatorView、homeIndicatorLayer 等属性
• ❌ 禁止：为 Home Indicator 添加 addSubview、约束、样式
• ❌ 禁止：下载 Home Indicator 相关的图片资源
• ✅ 正确：完全跳过该节点及其子树，就像它不存在一样

原因：

• iOS 系统会自动在设备上绘制 Home Indicator（iPhone X 及以上）
• Figma 中的 Home Indicator 只是设计稿示意，不是真实 UI
• 在代码中实现会导致：
  • 重复渲染（系统已经有了）
  • 与系统手势区域冲突
  • 在 iPhone 8 及以下设备显示错误的横条

做法：

1. 遍历 design.json 节点树（或 index.json 的扁平列表）时，检查节点名称
2. 如果匹配 Home Indicator，完全跳过该节点及其子树
3. 不要将其坐标用于计算其他元素的布局（除了判断安全区域）
4. 注释中可说明"已跳过 Figma 中的 Home Indicator（系统控件）"

2. 忽略状态栏（Status Bar）

必须跳过的节点（不要生成任何代码）：

• 节点名称匹配（任一即跳过）：
  • 完全匹配：Status Bar、status bar、状态栏
  • 包含关键词：系统控件/status bar、iPhone Status Bar
  • 包含关键词：状态栏/

识别特征：

• 位于页面顶部（y = 0 或接近 0）
• 高度：20pt（iPhone 8 及以下）或 44pt（iPhone X 及以上）
• 包含时间、信号、电池等元素

原因：

• iOS 系统自动绘制状态栏
• 应用只能通过 statusBarStyle 控制状态栏样式（浅色/深色）
• 在 Info.plist 中配置 UIStatusBarStyle

做法：

• 完全跳过该节点及其子树
• 布局顶部元素时使用 safeAreaLayoutGuide.snp.top