企业官网建设流程全解析

ESPHome Designer 是一个可视化的拖拽式显示设计编辑器，面向 ESPHome、OpenEpaperLink（OEPL）和 OpenDisplay 三类墨水屏/触摸屏设备，可运行在 Home Assistant 集成中，也可作为独立 Web 应用使用。它最大的卖点就是"一套设计，三种输出"：你在画布上拖拽完成的同一个布局，可以一键生成 ESPHome 的 C++ Lambda 代码、OEPL 的 JSON 服务调用，以及 OpenDisplay 的 JSON 动作报文——全程不需要手写一行显示代码。

支持的三大平台与输出格式

不同硬件平台对"往屏幕上画东西"这件事有不同的协议，ESPHome Designer 把它们统一成了三种输出：

也就是说，同一块画布既可以烧进带屏的 ESP32 主控板，也可以发给挂在网络里的无线墨水屏模块，一套设计资产即可复用到所有设备。

一键切换输出格式：设置 Rendering Mode

在编辑器的Device Settings（设备设置）弹窗中，有一个Rendering Mode下拉框，这是整个多平台输出的总开关。源码中的五个选项定义在 modals.html：

• Direct (Display Lambda)：标准 ESPHome C++ Lambda 输出
• LVGL (Recommended for LCD)：面向 LCD 屏幕的 LVGL YAML
• C/C++ Drawing Code：只输出纯净的 C/C++ 绘图回调体
• OpenEpaperLink JSON (Drawing Protocol)：生成 OEPL 报文
• OpenDisplay JSON (ODP)：生成 OpenDisplay 报文

切换模式后，底部代码面板会立即重新生成对应格式的内容。这个刷新逻辑由 main.js 中的refreshAdapter()完成——检测到模式变化就重建适配器并刷新代码框。

幕后架构：适配器模式让"三输"成为可能

ESPHome Designer 没有为每种输出各写一套生成逻辑，而是采用了经典的适配器模式，所有输出都遵循同一个接口。

统一的基类 BaseAdapter

所有输出适配器都继承自抽象基类 base_adapter.js，它规定了两个核心契约：

• generate(layout)：输入完整的布局状态，输出最终字符串（YAML、JSON 或 C++ 代码）
• generateWidget(widget, context)：负责单个组件到目标格式的转换

这让编辑器主流程（main.js）完全不需要关心当前目标是 ESPHome 还是 OEPL——它只调用adapter.generate(layout)。

适配器工厂：按模式自动装配

具体用哪个适配器，由工厂函数决定。adapter_factory.js 中的createAdapterForMode(mode)根据渲染模式返回对应实例：

C++ Lambda 输出：复用成熟的导出器

CAdapter 是架构上的一个巧妙设计：它直接继承自ESPHomeAdapter，复用 native_generator.js 里成熟的generateDisplayLambda()绘图代码生成器，只是剥掉了 ESPHome 的 YAML 外壳，只留下原生 C/C++ 回调体。动态 Home Assistant 值以id(...)占位符形式保留，方便粘贴进你自己的工程替换。

这对非 ESPHome 项目（比如自写 C++ 固件的墨水屏设备）特别友好——拿到的是一段紧凑、可直接参考的绘制起点。

OEPL JSON 输出：生成标准服务调用

OEPLAdapter 会把当前页面的组件逐一转换为 OEPL 元素，最终拼装成一个标准的 Home Assistant 服务调用：

• service: open_epaper_link.drawcustom
• 数据包含background（背景色）、rotate（按屏幕方向自动计算 0/90/180/270）、dither（抖动等级）、ttl（缓存时长）和payload（组件列表）

组件与实体 ID 都支持在设备设置中配置，未配置时使用占位符，方便直接接入自动化。

OpenDisplay 输出：生成 JSON 动作报文

OpenDisplayAdapter 则生成opendisplay.drawcustom动作，包含device_id目标、background、rotate、dither、ttl、refresh_type等参数，payload 中每个元素都对应画布上的一个组件，并带有注释 ID 便于定位调试。

关键设计：每个插件同时"会画"和"会导出"

你可能会问：几十种组件（传感器文本、图表、天气图标……）是怎么被翻译成三种互不相干的格式的呢？

答案是插件注册表机制。每个组件都是一个独立插件（见 features/ 下的 55+ 目录），每个插件可以同时实现多个导出函数：

• exportESPHome：ESPHome YAML 导出
• exportOEPL：OEPL JSON 元素导出
• exportOpenDisplay：ODP 元素导出

运行时，OEPL 适配器执行registry.get(widget.type)拿到插件，再调用它的exportOEPL(widget, context)（见 oepl_adapter.js#L108-L126）；ODP 适配器同理调用exportOpenDisplay。如果某组件尚不支持该格式，只会记录一次警告并跳过，不会中断整体生成。

这种"画一个、导三样"的插件契约，正是"一套设计三种输出"能够成立的核心。

反向导入：三种格式都能回到画布

除了导出，ESPHome Designer 还支持往返编辑（Round-trip）：把已有的 ESPHome 配置、OEPL YAML 数组或 ODP JSON 报文导入编辑器，重新变回可拖拽的画布组件。

解析器分布在 yaml_parsers/ 目录下，例如 oepl_parser.js 负责解析 OEPL 报文；导入主入口是 yaml_import.ts。这意味着：

1. 同事发来的 OEPL JSON → 导入 → 在画布上微调 → 再导出为 ESPHome Lambda
2. 旧的 ESPHome 手写 lambda 项目 → 导入 → 转为可视化布局 → 顺手改成 ODP 格式给另一台设备

💡 小提示：非常定制化的手写lambda:或script:代码可能无法完美还原预览，但原始 YAML 仍会被保留，不会丢失。

总结：为什么这个架构值得学习

• 一个入口：generate(layout)统一契约，UI 层对输出格式完全无感知
• 一个工厂：adapter_factory.js 按渲染模式装配适配器，切换格式零成本
• 一层复用：CAdapter继承ESPHomeAdapter，共享整个绘图代码生成器，避免重复造轮子
• 一套插件契约：每个组件插件自带多格式导出函数，新增组件即可自动获得多平台支持

对于想给 ESPHome 设备、无线电子价签和 HTTP 墨水屏做统一界面的开发者来说，这套"设计一次、输出多端"的架构不仅省去了反复手写的痛苦，也提供了一个相当干净的代码组织范本。