一、引言与架构背景：为什么现代化研发协作工具需要专业的 Diff 差异比对系统？

在软件工程、DevOps 平台、API 管理中台、自动化配置审计以及设计系统（Design System）版本迭代中，**差异对比查看器（Diff Viewer）与代码审查系统（Code Review System）**是研发团队最不可或缺的基础设施。无论是 GitHub / GitLab 中的 Pull Request 审查、Figma 自带的 Dev Mode Component Diff（组件版本差异变动校验），还是企业级多环境配置文件比对，用户都需要一目了然地定位“到底新增了什么、删除了什么、修改了哪几个单词”。

然而，在 Figma 中搭建一个能够支撑企业级复杂度的 Diff 查看器组件库，对于很多设计团队来说都是一个巨大的架构挑战：

1. 拓扑布局割裂：用户在不同场景下需要无缝切换“左右并排视图（Split View）”与“单列统一内联视图（Unified View）”，传统设计方法常常为此画两套完全互不相通的写死画板；
2. 字符排版与行号基线错位：不同语言、中英混排、换行代码以及行号槽（Gutter）之间极易产生 1px 级别的垂直偏移，导致左右两栏代码行错位甚至上下抖动；
3. 差异高亮层级混乱：未能将“整行背景浅色染色（Line Background）”与“单词级别深色高亮（Word-level Highlight）”从语义 Tokens 层面解耦，直接导致视觉层级模糊、无障碍对比度（WCAG 2.2）不达标；
4. 长文本横向溢出与折叠代码块缺失：成百上千行代码如果全量平铺，会导致 Figma 画布内存暴涨并产生性能卡顿。

为了彻底解决上述痛点，本文将系统拆解 Diff Viewer 的双拓扑容器架构、三态语义 Tokens 标准、Auto Layout 像素级对齐法则与 Dev Mode 现代工程交付全流程。

+------------------------------------------------------------------------+
|               差异对比查看器（Diff Viewer）四层架构模型                      |
+------------------------------------------------------------------------+
| 1. 工具栏与控制中枢 (Diff Header & Control Bar)                         |
|    - 拓扑切换 (Split vs Unified Segmented Control)                     |
|    - 文件路径与增删统计 (+14 / -6 Badge) + 字符折叠开关 (Wrap Lines)    |
+------------------------------------------------------------------------+
| 2. 代码块上下文容器 (Hunk & Context Container)                          |
|    - 折叠块导航标头 (Hunk Header: @@ -12,8 +12,10 @@)                  |
|    - 上下文未变更代码展开手柄 (Expand Up/Down Action Trigger)          |
+------------------------------------------------------------------------+
| 3. 双拓扑行级流式排版 (Row Layout Topology)                            |
|    - 并排模式 (Split): 左右双栏绝对等宽 (50:50 Flex) + 双向行号映射      |
|    - 内联模式 (Unified): 单栏垂直流 (Old & New 紧凑交替排列)           |
+------------------------------------------------------------------------+
| 4. 原子单元格与字符高亮层 (Atomic Diff Cell & Highlight)               |
|    - 行号槽 (Gutter: Old Line No. / New Line No. / Diff Marker + -)    |
|    - 代码内容槽 (Monospace Text + Token 语法高亮)                      |
|    - 词级变更遮罩 (Word Highlight Mask: Insertion / Deletion)          |
+------------------------------------------------------------------------+

---

二、架构决策：并排视图（Split View）vs 内联视图（Unified View）对比矩阵

在动手搭建组件前，必须透彻理解两种核心拓扑的优劣势与适用业务场景：

维度指标	并排视图 (Split View / Side-by-Side)	内联视图 (Unified View / Inline)
视觉呈现结构	左右等分两栏，左侧为旧版本（Old），右侧为新版本（New）	单列垂直堆叠，删减行（-）与新增行（+）顺序混排
适用视口屏幕	宽屏桌面端（屏幕宽度 >= 1440px）	中窄屏桌面端、平板、移动端或嵌入式抽屉（< 1200px）
上下文对照性	极高（左右同一行水平平齐，直观比对改动细节）	中等（长段重构代码上下交替容易产生视觉跳跃）
空行占位机制	必需（当单侧纯新增/纯删除时，另一侧需插入占位空行）	无需（纯垂直流式排布，无需空行对齐）
行内修改标识	左右同位对比，左右两侧分别标记删除词与新增词	红绿双行紧贴，上方显示整行删除，下方显示整行新增
实现复杂度	较高（需处理左右双向等高同步与独立水平滚动）	较低（标准纵向 Auto Layout 流式容器）
组件复用度	依赖双列包装容器，内部原子行实例完全同构	依赖单列包装容器，行级原子状态机高度通用

---

三、语义化 Design Tokens 体系与行级/词级差异高亮规范

差异对比组件的核心在于“色彩语义传达的准确度与无障碍辨识度”。严禁直接使用任意红绿色，必须构建标准化的语义 Tokens 体系，并完美兼容浅色（Light）与深色（Dark）模式。

1. Diff 语义配色变量规范

Token 变量名称	Light 浅色模式	Dark 深色模式	语义角色与节点说明
diff.addition.line.bg	rgba(46, 160, 67, 0.15)	rgba(63, 185, 80, 0.15)	新增行整行底色（低饱和度，保证长篇阅读舒适）
diff.addition.word.bg	rgba(46, 160, 67, 0.40)	rgba(63, 185, 80, 0.40)	新增代码块中具体变更词汇的高亮背景
diff.addition.gutter.text	#1A7F37	#3FB950	新增行号与加号（+）的高对比度前景色
diff.deletion.line.bg	rgba(248, 81, 73, 0.15)	rgba(248, 81, 73, 0.15)	删除行整行底色
diff.deletion.word.bg	rgba(248, 81, 73, 0.40)	rgba(248, 81, 73, 0.40)	删除代码块中被移去词汇的高亮背景
diff.deletion.gutter.text	#CF222E	#F85149	删除行号与减号（-）的前景色
diff.gutter.bg	#F6F8FA	#0D1117	左侧行号栏独立中性底色，隔离视觉焦段
diff.hunk.bg	#DDF4FF	#042645	折叠代码段标头背景色（浅蓝调）
diff.hunk.text	#0969DA	#58A6FF	折叠代码段定位描述文本色

2. OpenType 代码排印与基线对齐

• 字体族：必须采用工业级等宽字体（Monospace），如 JetBrains Mono、Fira Code 或 SF Mono；
• 排印参数：字号 12px，行高（Line Height）严格锁定为固定的 20px（禁止使用百分比或 Normal），字间距（Letter Spacing）设为 0；
• Tabular Figures：行号文本必须启用 OpenType 等宽数字特性，确保 1、8、9 等所有数字宽度严格等于 1ch，防止十位数跨百位数时行号跳动。

---

四、Auto Layout 双拓扑组件解耦与像素级对齐实操步骤

步骤 1：构建行号槽原子组件 Diff-Gutter

1. 创建水平 Auto Layout 容器，高度固定为 20px；
2. 内部包含三个关键图层：
   • Old-Line-Num：宽度固定为 36px，文本右对齐，绑定次级文本色；
   • New-Line-Num：宽度固定为 36px，文本右对齐，在 Split 模式下根据当前栏位隐藏其中一个；
   • Sign-Symbol：宽度固定为 16px，居中对齐，展示 +、- 或空格（普通行）；
3. 右侧添加 1px 垂直分割线（color.border.subtle），作为行号与代码的分界线。

步骤 2：构建代码文本行原子组件 Diff-Content-Cell

1. 创建水平 Auto Layout 容器，高度固定为 20px，水平内边距左右 8px，Resizing 设为 Fill container；
2. 内嵌文本图层：设置为单行不换行（或根据需求开启 Truncate），垂直居中对齐；
3. 词级高亮封装：当某一行存在单词级差异时，在文本下方叠加带圆角的词级高亮矩形 Frame（水平 Auto Layout，绑定 diff.addition.word.bg，圆角 2px），利用绝对定位或内嵌插槽实现字符级对齐。

步骤 3：拼装差异单行组件 Diff-Line-Row

1. 将 Diff-Gutter 与 Diff-Content-Cell 水平组合在 Auto Layout 中，间距为 0；
2. 垂直高度统一为 20px，水平宽度设为 Fill container；
3. 通过 Component Properties 声明变体属性：
   • Type：Context（未改动普通行）/ Addition（新增行）/ Deletion（删除行）/ Empty（占位空行，用于 Split 左右对齐）；
   • 根据变体属性自动切换整行背景色与行号色彩。

+-----------------------------------------------------------------------------------+
| Component: Diff-Line-Row (Horizontal Auto Layout, Height: 20px, Fill container)   |
| +------------------------------------+ +----------------------------------------+ |
| | Diff-Gutter (Width: 88px, Fix)     | | Diff-Content-Cell (Fill container)     | |
| | [Old: 42] [New: 42] [Sign: +] [|]  | |   const [status, setStatus] = useState | |
| +------------------------------------+ +----------------------------------------+ |
+-----------------------------------------------------------------------------------+

步骤 4：构建双栏并排视图容器 Diff-Split-Container

1. 创建水平 Auto Layout 容器，间距为 0，宽度设为 Fill container；
2. 左右划分为两个主面板：Left-Pane (Old) 与 Right-Pane (New)，两者的宽度 Resizing 均设为 Fill container（实现严格的 50:50 等分）；
3. 中间放置 1px 垂直分割线；
4. 当某处为纯新增代码时，左侧面板对应行切换为 Empty 变体，呈现斜纹浅灰占位底色，右侧面板对应行呈现 Addition 变体，两者行高完全一致（均为 20px），确保后续代码继续严丝合缝地水平齐平。

步骤 5：构建折叠上下文标头 Hunk-Header-Row

1. 创建水平 Auto Layout 容器，高度 24px，背景绑定 diff.hunk.bg；
2. 左侧放置展开按钮手柄（Fold Expand Buttons: Up/Down/Both），右侧放置代码块位置元数据：@@ -12,7 +12,9 @@ export function useUserSession() {；
3. 文本采用等宽斜体代码排印，颜色绑定 diff.hunk.text。

---

五、Variables 变量模式与多态交互原型

在实际设计交付中，产品经理与前端工程师需要直观体验并排与单栏的切换效果，以及浅色与深色模式下的代码辨识度。

1. Variables 视图拓扑状态机

变量名称	类型	可选值	说明
diff.viewMode	String	"split" / "unified"	驱动组件在双栏与单栏之间无损切换
diff.showLineNumbers	Boolean	true / false	控制是否隐藏行号栏以适配超窄视口
diff.wrapLines	Boolean	true / false	控制代码是单行横向滚动还是自动换行

通过在顶层 Frame 设置 diff.viewMode = "split"，内部嵌套的 Split 容器自动显示、Unified 容器自动隐藏；切换为 "unified" 时反向生效，完全无需维护两套独立的断层设计稿。

2. Figma 高级交互原型连线设置

• 在顶部分段控制器（Segmented Control）的“并排”与“内联”按钮上配置：On click -> Set variable: diff.viewMode = "split" 或 "unified"；
• 在折叠标头 Hunk-Header 上配置点击事件：On click -> 触发 Smart Animate 展开隐藏的 10 行上下文普通代码，动画曲线设置为 Ease out (150ms)，真实模拟 IDE 与 GitHub 的丝滑展开体验。

---

六、Dev Mode 现代工程化落地：Monaco Editor 与 Diff2html 代码交付

在 Dev Mode 中，必须向研发团队交付符合业内标准的组件调用范式。以下为基于生产级 Monaco Editor Diff View 的标准 React 规范集成：

import React, { useRef, useEffect } from 'react';
import * as monaco from 'monaco-editor';

interface DiffViewerProps {
  originalCode: string;
  modifiedCode: string;
  language?: string;
  isSplitView?: boolean;
  theme?: 'vs-dark' | 'light';
}

export const MonacoDiffViewer: React.FC<DiffViewerProps> = ({
  originalCode,
  modifiedCode,
  language = 'typescript',
  isSplitView = true,
  theme = 'vs-dark',
}) => {
  const containerRef = useRef<HTMLDivElement>(null);
  const diffEditorRef = useRef<monaco.editor.IStandaloneDiffEditor | null>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    // 创建 Diff Editor 实例
    diffEditorRef.current = monaco.editor.createDiffEditor(containerRef.current, {
      renderSideBySide: isSplitView, // 对应 Figma diff.viewMode
      readOnly: true,
      automaticLayout: true,
      lineNumbers: 'on',
      fontSize: 12,
      lineHeight: 20,
      fontFamily: 'JetBrains Mono, Menlo, Monaco, monospace',
      theme: theme,
      renderOverviewRuler: false,
      scrollBeyondLastLine: false,
      diffWordWrap: 'off',
    });

    // 绑定左右模型
    const originalModel = monaco.editor.createModel(originalCode, language);
    const modifiedModel = monaco.editor.createModel(modifiedCode, language);

    diffEditorRef.current.setModel({
      original: originalModel,
      modified: modifiedModel,
    });

    return () => {
      diffEditorRef.current?.dispose();
      originalModel.dispose();
      modifiedModel.dispose();
    };
  }, [originalCode, modifiedCode, language, isSplitView, theme]);

  return (
    <div className="w-full h-[600px] border border-gray-200 dark:border-neutral-800 rounded-lg overflow-hidden shadow-sm">
      <div ref={containerRef} className="w-full h-full" />
    </div>
  );
};

---

七、总结与设计系统架构速查

专业级差异对比查看器是软件工程交付与协同设计系统的高阶试金石。通过推导双拓扑解耦模型、等高行号基准对齐机制、行级/词级多态染色 Tokens 体系，以及与 Monaco Editor 工业标准的深度对齐，设计团队能够交付一套零歧义、可无缝落地的生产级 Diff 架构资产。

扩展阅读与站内相关指南

• 深入探索设计系统 Tokens 标准化与命名？请查阅 Design Tokens 标准命名与对照手册 与 Figma 样式转变量平滑迁移指南；
• 了解复杂代码行基线错位与双栏滚动失步排查？请查阅 Figma 常见报错与疑难故障诊断手册；
• 探索多端响应式尺寸与断点规范？推荐阅读 UI 设计规范与设备尺寸速查表；
• 进阶研究复杂数据展示与代码交付？推荐阅读 Figma 描述列表与详情键值对系统组件架构实战 与 Figma 复杂数据表格系统组件架构实战。