编写 EDM（Email Direct Marketing）HTML 的痛苦，本质上是现代设计工具与二十年前渲染引擎之间的技术代差。

在 MasterGo 或 Figma 中，设计师习惯了自由的二维绝对定位或现代的 Flexbox 布局；但在邮件客户端（尤其是 Outlook）里，前端面对的依然是旧时代的 table 嵌套、全内联样式，以及对现代 CSS 属性的集体免疫。一个普通的营销页，视觉设计可能只需半小时，前端却需要花费数倍的时间去手工翻译代码。一旦间距或图片发生微调，又是一轮推倒重来。

为了终结这种低效的重复劳动，我开发了一款 MasterGo 插件。它的核心目标很纯粹：选中画布，直接输出一份全兼容的邮件 HTML。

这个项目最核心的价值，在于将一个繁琐的视觉翻译工作，收敛成了一个清晰的布局树重建算法问题。以下是该方案的具体实现拆解。

核心矛盾：绝对定位向受限流式布局的转换

设计工具导出的节点数据天然是扁平的二维绝对定位信息：

interface SceneNode {
    x: number;
    y: number;
    width: number;
    height: number;
    // ... 样式与层级树
}

而高效且兼容的 EDM HTML 需要的是一个高度受限的流式布局系统：

垂直方向：依靠文档流自然堆叠，通过间距节点或 margin 控制距离。
水平方向：全面放弃现代 flex 属性，退回到使用 table 的 tr 与 td 来实现确定性的多列并排。
样式表现：必须实现像素级的内联样式注入，避免样式被邮件客户端拦截。

因此，转换的核心问题被定义为：如何将二维空间中的绝对定位节点，重建为一棵可流式渲染的语义布局树（AST）。

转化流水线设计

为了保证逻辑的解耦与可扩展性，整个核心转换流程（位于 core 包中）被设计为一个纯函数式管道（Pipeline）：

export function json2html(jsonData: IBaseComponent): string {
    const pipeFunc = pipe(
        transTreeStructData,  // 1. 结构重建：识别上下层级与左右并列
        removeExcessEl,       // 2. 节点清洗：剔除无意义的视觉模板噪音
        generateStructData,   // 3. 样式推导：将坐标转换为流式布局样式
        generateHTMLCode      // 4. 代码降级：输出高兼容性的 Table HTML
    );
 
    return pipeFunc(deepClone(jsonData)) as string;
}

数据在管道中的演进过程如下所示：

核心算法：二维布局树的重建

整个流水线中最关键、也最复杂的步骤是 transTreeStructData。虽然设计稿本身包含图层树，但那种树结构往往只是视觉容器的分组，并不等同于 HTML 的 DOM 结构。

算法通过两遍扫描来重新推导节点间的真实布局关系：

第一遍扫描：Y 轴分割，构建垂直流

首先，将当前容器下的所有子节点按空间坐标进行多级排序：

arr = arr.sort((a, b) => {
    if (a.globalY !== b.globalY) {
        return a.globalY - b.globalY; // 规则 1：优先按 Y 轴从上到下排序
    }
    else if (a.height !== b.height) {
        return b.height - a.height;   // 规则 2：Y 轴相同时，高度大的节点优先处理
    }
    else {
        return a.globalX - b.globalX; // 规则 3：其余情况按 X 轴从left到right排序
    }
});

为什么高度大的节点优先处理？

在实际设计稿中，外层大容器与内层小组件的起始 Y 坐标经常重合。优先处理大节点，可以在后续线性扫描中更稳定地识别出“包含与被包含”的父子关系。

排序完成后，通过线性扫描进行空间归并：

若当前节点的 globalY 已经超出了上一个节点的垂直范围，则判定其为新的一行。
若当前节点的 globalY 和 height 被上一个节点的垂直范围完整包裹，则进一步校验 X 轴。若 X 轴同样处于包裹状态，则将其作为子节点挂载到上一个节点下方，形成嵌套结构。

第二遍扫描：X 轴分割，识别水平并列

在垂直结构确定后，需要解决同层级内多个元素的水平排列问题。

如果多个元素处于同一 Y 轴区间，算法会在抽象语法树（AST）中隐式创建一个虚拟的 flex 容器，将这些并排节点包裹起来。

if (isSameYAxisArea(v, newArr[newArr.length - 1])) {
    // 创建虚拟父级 flex 节点
    const newFlexEl = createParentFlexEl(newArr[newArr.length - 1], v);
 
    newArr[newArr.length - 1] = {
        ...newFlexEl,
        children: sortByXAxis([
            newArr[newArr.length - 1],
            modifyAreaAndXY(v, newFlexEl),
        ]),
    };
}

需要强调的是，这里的 flex 只是中间层抽象的语义节点，而非最终生成的 CSS 属性。它的作用是显式标记“这几个元素在视觉上属于同一行”，为后续渲染层降级为 table 结构提供依据。

工程实践中的边界与容差处理

真实的工程项目不是完美的算法题，设计稿往往带有像素级的误差。

1. 5px 空间容差机制

在理论上，一个水平居中的组件，其左右间距应该绝对相等。但设计师在手动拖拽组件时，经常会出现左间距 201px、右间距 204px 的微小偏差。如果进行严格的数学相等判断，系统会将其误判为普通靠左对齐，导致最终生成的 HTML 产生整体视觉偏移。

为了规避这一硬性问题，算法引入了实用的容差机制：

function isComponentXCenter(curNode: TComponent, parentNode: TComponent): boolean {
    const leftWidth = Math.abs(parentNode.globalX - curNode.globalX);
    const rightWidth = parentNode.globalX + parentNode.width - curNode.globalX - curNode.width;
 
    // 允许 5px 以内的像素误差
    return Math.abs(leftWidth - rightWidth) <= 5;
}

通过牺牲绝对的数学精确性，换取了对真实设计稿极强的工程稳定性。

2. 高度补偿节点（Bottom Padding Spacer）

在设计稿中，容器通常具有固定的高度（Height）。而在 HTML 流式布局中，容器高度是由内部内容撑开的。如果最底部的子节点与父容器边缘之间存在一段空白，若不处理，这段空白在流式渲染中就会丢失。

为了精确还原视觉效果，逻辑中增加了高度补偿机制。当检测到尾部剩余空间时，自动追加一个虚拟的占位节点：

function getBottomHeightEl(el: IContainer, childrenLastEl: TComponent): IContainer {
    const newHeight = el.globalY + el.height - childrenLastEl.globalY - childrenLastEl.height;
 
    return {
        type: 'container',
        name: 'auto-height-spacer',
        structure: [`height: ${newHeight}px`],
        style: {},
        x: 0,
        y: 0,
        globalX: el.globalX,
        globalY: childrenLastEl.globalY + childrenLastEl.height,
        width: 0,
        height: newHeight,
    };
}

渲染层降级：生成高兼容性 HTML

在最终的 generateHTMLCode 阶段，AST 中的抽象节点会被翻译成邮件客户端能够稳定解析的底层标签。由于 Outlook 等引擎对 div 的 margin 及 flex 支持极差，转换策略进行了彻底的降级：

AST 节点类型	最终输出的 HTML 结构	核心逻辑与兼容考量
`flex` 容器	`<table><tbody><tr>`	用表格行替代弹性盒子，确保绝对水平排列
`flex` 子项	`<td>`	继承宽度，利用 `td` 阻断垂直流
普通块级节点	`<div>` 或 `<table>`	用于垂直流式堆叠，配合内联 `margin-top` 或空行进行填充

当检测到 flex 抽象节点时，代码会进行如下构建：

// 转换核心抽象
case 'flex': {
    tag.push('<table border="0" cellpadding="0" cellspacing="0" width="100%">');
    tag.push('<tbody>');
    tag.push('<tr>');
    createFlexChildren(node, html);
    tag.push('</tr>');
    tag.push('</tbody>');
    tag.push('</table>');
    break;
}

研发效率与协作约定

在日常迭代中，工具的交互成本决定了它能否真正落地。许多效率工具由于配置面板过于繁琐，最终反而降低了效率。

本插件采用了图层命名约定（Naming Convention）来替代复杂的配置 UI。设计师只需在图层名称后追加特定的标签，即可控制代码的语义化输出：

Banner #image -> 强制识别为图片组件，自动提取资产
CTA Button #link -> 自动包装 <a> 标签，预留链接占位符
Product Group #containerLink -> 使得整块卡片具备全局点击行为

export const isImage = (nodeData: SceneNode): boolean => nodeData.name.toLowerCase().includes('#image');
export const isLink = (nodeData: SceneNode): boolean => nodeData.name.toLowerCase().includes('#link');

这种设计让研发与设计之间的契约直接留存在画板上，不仅消除了配置成本，也让设计稿本身成为了唯一的信任源（Single Source of Truth）。

总结

引入该插件后，团队在 EDM 交付流程上实现了显著的效率提升：

工时缩减：单个复杂营销页的还原时间由传统的 2~3 小时 骤降至 10~15 分钟。
低返工成本：面对频繁的视觉调整，只需在设计稿中一键重新导出，无需前端进入 table 源码中肉眼定位修改。

将无序的“体力活”抽象为结构化的算法，是解决前端研发链路中重复劳动的有效路径。定义好数据结构与边界，后面的代码生成自然水到渠成。

0 条评论

发表评论