企业官网建设流程全解析

你知道在 Open UI5 应用里，鼠标右键点一个按钮，弹出的属性面板里那些可配置的属性列表、可绑定的字段、可拖拽的聚合关系，到底是从哪儿来的吗？

我最早以为这是控件内部写死的，直到有一天要让自己写的自定义控件出现在设计工具的属性面板里，才顺着源码一路摸到了DesignTime.js这条线。翻完这个文件我才意识到：Open UI5 从来都不只是“运行时”那一套渲染引擎，它还有一条几乎不被业务开发者注意的“设计时”主链路，而DesignTime.js正好是这条链路的调度中枢。这篇源码解析，我就用第 31 篇来聊聊这个文件，拆清楚它到底在做什么、它靠什么数据工作，以及我们在写自定义控件时怎么跟它配合。适合对 UI5 框架内部机制好奇的开发者，也适合正在做可视化编辑、低代码搭建、模板生成这类工具的同学参考。

1. 在看代码之前：先把“设计时”和“运行时”两条主线分开

源码解析最怕的就是一头扎进代码里，连这个文件要解决什么问题都没搞清。我们先把概念对齐。

一个控件跑在页面上，负责渲染 DOM、响应事件、维护数据绑定，这套逻辑属于运行时（runtime）。比如你给sap.m.Input设了个value，它显示出来、用户输入后触发change事件，这些都是运行时的工作。

另一条线是：如果有一个可视化工具想把控件画在画布上、想让用户在右侧属性面板里改属性、想判断某个聚合能不能拖一个新控件进去，工具本身对控件一无所知，它必须有一份“说明书”——控件有哪些属性、哪些属性允许改、哪些聚合允许增删、哪些事件能配置。这套机制就是设计时（design time）。

DesignTime.js在 Open UI5 的命名空间里属于设计时基础设施，它做的事情概括起来就三件：把分散在各个控件包里的 designtime 元数据加载进来，合并出一份统一的视图，然后向编辑器、模板助手、变体管理这类工具提供查询入口。

有个细节值得先说：Open UI5 在正常运行一个应用时，不会主动去加载任何 designtime 文件。设计时元数据是“按需加载”的，只有当你打开可视化编辑器、或者调用了相关 API 时，DesignTime.js才被拉起来，再由它去逐个加载控件对应的 designtime 配置。这个设计我后来想明白了一部分：不能为了少数工具场景牺牲绝大多数应用首屏加载性能。

所以，如果你想给自己的自定义控件加上设计时支持，你实际上要做的有两件事：第一，为控件写一份 designtime 元数据文件；第二，通过模块命名空间让DesignTime.js能找得到它。第二件事很多人会漏掉，后面实操部分我会专门演示。

2. 拆读 DesignTime.js 的源码骨架：注册、加载、查询三条主线

我拿到这类框架源码文件，一般不会从头到尾逐行读，先找“主线”。DesignTime.js的主线很清楚：注册入口、加载器、查询接口。下面是我基于常见开源版本源码整理的逻辑骨架，行号在不同版本会有偏移，但结构主线基本稳定。

2.1 先抓到文件对外暴露的注册与初始化入口

文件开头通常是一串模块依赖，不要被这串依赖吓到，我们只需要辨认三类：

• 模块加载与命名空间基础服务，负责异步加载 designtime 文件；
• 控件metadata的访问接口，用于获取控件的类信息、属性、聚合、事件声明；
• 设计时事件与 overlay 相关的辅助对象。

真正的主线从初始化方法开始。在常见版本中，DesignTime.js会暴露一个类似registerDesigntime的注册方法，这个方法接收控件渲染类名与对应的 designtime 配置路径。调用方一般是一个个控件包里的.designtime.js文件，它们在加载时会主动注册自己。

核心逻辑大致长这样（非精确源码，是主线逻辑的还原）：

// 伪码形式的逻辑还原，用于说明主线 function registerDesigntime(controlName, designtimeModulePath) { if (!registry[controlName]) { registry[controlName] = designtimeModulePath; } } async function getDesigntime(controlName) { let dt = registry[controlName]; if (dt && !loadedCache[controlName]) { const module = await loadModule(dt); const metadata = module.default || module; loadedCache[controlName] = normalizeDesigntime(metadata); } return loadedCache[controlName]; }

这里最值得琢磨的是：注册的只是路径，而不是具体配置对象。为什么？因为特定控件的 designtime 配置可能很大，而且大多数场景根本用不到，只有真正请求到某个控件时才去加载、解析、缓存。这种“延迟加载 + 缓存”的组合，是 UI5 一堆基础设施文件的通用思路，读源码时记下这个模式，后面看别的文件会顺畅很多。

2.2 理解 getDesigntime 的返回形态

getDesigntime(controlName)是DesignTime.js最核心的对外接口。它的返回值通常不是单个控件的一份 JS 对象，而是一个经过整理的、按控件名聚合的 designtime 元数据集合。

在可视化工具里，当一个控件被选中时，工具会调用类似下面的逻辑：

const dt = await DesignTime.getDesigntime("my.controls.RatingInput");

拿到元数据后，属性面板才能列出可配置项。所以如果你发现“工具里看不到我的控件属性”，第一反应不是去调 CSS，而是去查getDesigntime()返回了什么。

我在实际调试中还发现一个容易被忽略的点：getDesigntime()返回的数据往往还会带一层“合并逻辑”，例如把控件继承链上的元数据合并到一起，父类定义了width、height可改，子类自己定义了icon可改，最终返回的配置可能是两者合并后的结果。这种继承合并逻辑对使用者来说很顺手——你给子控件写 designtime 时不需要把父类的配置再抄一遍，框架帮你兜底。

2.3 顺带一提：文件命名里的规律

如果看源码目录结构，你会发现很多控件包里有类似Button.designtime.js、Input.designtime.js这样的文件。它们在命名上遵循<控件名>.designtime.js的约定，而DesignTime.js是整个机制的总入口。理解这一层之后，我们再去看某个具体控件的 designtime 文件时，就不会迷路：总入口负责“调度”，具体 designtime 文件负责“描述”。

提示：不同 Open UI5 版本对 designtime 文件的路径约定可能有变化，有些版本倾向于把 designtime 配置放到/designtime子目录下，有些版本则放在控件包根目录。判断规则很简单：去 node_modules 对应的框架包里搜*.designtime.js，看目录结构就一目了然。

3. 核心数据结构：一份 designtime 元数据到底长什么样

DesignTime.js本身不算难懂，难懂的是它处理的数据对象。这一节我们重点看控件 designtime 元数据的常见结构，这是后面写自定义配置的基础。

3.1 元数据的整体骨架

我见过的大多数控件 designtime 文件，返回对象都围绕这么几个维度组织：

拿一个简化版的自定义按钮举例，它的 designtime 配置大概长这样：

// my/controls/PrettyButton.designtime.js sap.ui.define([], function () { "use strict"; return { name: { singular: "PrettyButton", plural: "PrettyButtons" }, properties: { text: { changeable: true, bindable: true }, icon: { changeable: true, bindable: true } }, aggregations: { content: { droppable: true, maxItems: 3 } }, events: { press: { bindable: true } }, actions: { remove: { changeable: true }, clone: { changeable: true } } }; });

3.2 字段级别的含义，逐个说明白

properties下有常见的修饰字段。changeable表示这个属性是否允许在设计工具里被修改；bindable表示是否允许把它绑定到某个数据模型的路径。这两个字段经常被混为一谈，实际上区别很明显：changeable控制“能不能在属性面板里直接改值”，bindable控制“能不能给它配一条绑定的数据路径”。比如一个控件里有ariaLabel这种辅助属性，你可以允许它被绑定，但不一定允许用户随便改字面值。

aggregations的droppable表示是否允许把别的控件拖进这个聚合。maxItems可以限制聚合内控件数量。如果你的自定义控件里有一个聚合，它只允许放 0 到 1 个子控件，那maxItems: 1会让设计工具自动在拖入第二个时给出拦截提示。这个细节在实际搭建低代码表单场景时很常用。

actions里常常有remove、clone、move、rename这些控件级操作。注意，这些字段大多数也是对象，因为要对操作做更细的控制。比如remove.changeable是布尔值，但有些控件可能希望在特定业务场景下不允许删除，那么可以在 designtime 里配置校验逻辑，返回 false 或者禁止条件。具体配置方式取决于你用的 Open UI5 版本，但主体思路一致。

3.3 为什么需要这套数据结构

你可能会有个疑问：控件自己的metadata里不是已经声明了 properties、aggregations、events 吗？为什么 designtime 还要再写一遍？这两个声明并不是重复劳动，它们的视角完全不同。

metadata是从“控件怎么运行”的角度定义的，它告诉框架：我有哪些属性、聚合、事件，这些是控件本身完整性所必需的。designtime 是从“工具怎么操作”的角度定义的，它告诉设计工具：这些属性能不能被设计器修改、能不能绑定、聚合能不能拖拽。一个业务属性在运行时当然存在，但你未必希望做设计工具的人随便修改它，比如控件内部权重值，你在属性面板里暴露这个字段不但没有意义，还可能搞出数据不一致。designtime 的作用就是把这层“是否开放、开放到什么程度”的控制做出来。

我认识不少做过可视化搭建系统的开发，最后都倒在同一个问题上：控件写了一大堆，设计器里什么都能改，等于什么都不能改——因为缺少一层白名单机制。DesignTime.js里维护的正是这层白名单。

4. 实战：给自定义控件补一份 designtime 支持的全过程

前面理论铺了这么多，现在进入真正能“抄作业”的环节。假设我们已经写了一个简单的自定义控件my.controls.PrettyButton，它继承自sap.ui.core.Control，里面有一个text属性、一个press事件、一个content聚合。我们现在要让它能被设计工具识别和操作。

4.1 第一步：确认控件的常规声明没有缺东西

在写 designtime 之前，控件本体必须能正常工作。所以先检查 metadata 声明：

sap.ui.define([ "sap/ui/core/Control" ], function (Control) { "use strict"; return Control.extend("my.controls.PrettyButton", { metadata: { properties: { text: { type: "string" }, icon: { type: "string" } }, aggregations: { content: { singularName: "content" } }, events: { press: {} } } }); });

这一步当然不是为设计时做的，但它的字段会决定 designtime 里能引用哪些名字。如果控件 metadata 里没有声明text属性，designtime 里写了text也没用，工具拿不到对应的运行时信息。

4.2 第二步：编写 designtime 文件

在控件所在目录下创建PrettyButton.designtime.js，内容如下：

sap.ui.define([], function () { "use strict"; return { name: { singular: "Pretty Button", plural: "Pretty Buttons" }, properties: { text: { changeable: true, bindable: true }, icon: { changeable: true, bindable: true } }, aggregations: { content: { droppable: true, maxItems: 2 } }, events: { press: { bindable: true } }, actions: { remove: { changeable: true }, clone: { changeable: true } } }; });

这里特别说明一下droppable: true和maxItems: 2：如果你的content聚合允许多个子控件，你可以写大一些；如果希望它在设计器里表现得像“只能放一个内容区”，那就设成maxItems: 1。具体数字没有统一标准，完全取决于你希望设计工具呈现出什么样的交互边界。

4.3 第三步：把 designtime 文件暴露到模块系统中

写完文件之后，光放在那儿是不够的。DesignTime.js并不是按目录自动扫描的——它必须知道从哪个模块路径加载这份配置。有两种常见做法：

一种是在manifest.json的sap.ui5段里增加dependencies或设计时相关的配置项，显式声明这个控件的 designtime 模块路径；另一种是直接在你封装控件的公共入口文件里调用注册逻辑，把控件名和 designtime 模块路径交给DesignTime注册器。

实际上，很多控件提供方会在 designtime 文件内部就完成注册，或者由框架在加载控件包时，按命名约定自动尝试加载<控件名>.designtime.js。如果你的应用里发现 designtime 没有生效，优先检查框架版本约定，再检查文件命名和路径大小写是否与约定完全一致。

这里有个极容易踩的坑：文件名大小写和路径分隔符。PrettyButton.designtime.js与prettybutton.designtime.js在某些环境里是不同的模块路径，框架按约定去加载时可能直接报 404，但错误信息经常被上层工具吞掉，只在开发环境的网络面板里留一条红色请求。我排查过好几次，最后都是大小写问题。

4.4 第四步：验证设计时能力是否真正生效

验证不能用肉眼，给你两个可操作的方法。

方法一：在浏览器控制台里，等应用和设计工具都启动后，手动调用框架的getDesigntime查询接口：

// 这里是伪码风格示意，实际 API 取决于具体版本与命名空间 const dt = await DesignTime.getDesigntime("my.controls.PrettyButton"); console.log(dt);

如果返回对象里有properties.text、aggregations.content等字段，说明你的 designtime 文件已经成功注册并解析了。如果返回 undefined 或者空对象，说明DesignTime.js没有找到这个模块，回到上一步检查路径。

方法二：在设计工具里选中PrettyButton，右侧属性面板如果列出的属性范围与你 designtime 配置的字段一致，就说明链路通了。不一致的时候，注意区分是“整个控件没识别出来”还是“识别出来了但属性列表不对”。前者多半是模块加载问题，后者多半是 designtime 字段写错。

把整个链路走通之后，你会更加明白DesignTime.js这层调度存在的意义：它把“描述控件可操作性”这件事完全从控件运行时逻辑里解耦出来了。我们日常开发时根本不需要关心它，但要做工具链扩展时，它就是绕不开的那扇门。

5. 设计时相关的常见问题怎么排查

最后这部分分享几条我在项目里实打实遇到过的坑。设计时功能本身不常用，一旦出了问题，网上能搜到的有效信息很少，很多时候得靠自己的排查思路。

5.1 症状定位表

这张表不能覆盖所有场景，但绝大多数设计时问题都逃不过这几类。

5.2 一条从现象到根因的完整排查链路

举一个我实际处理过的例子：一个自定义表单容器在低代码工具里拖不进去任何子控件，也没有任何报错。最开始我以为是自己控件聚合声明有问题，反复检查了六七遍 metadata，没有问题，运行时能正常往里 add 子控件。

后面我把重心放到 designtime 上，先走了一遍完整链路：

1. 打开浏览器开发者工具，刷新应用，网络面板里搜.designtime.，确认FormContainer.designtime.js是否被请求。 结果是：这个文件根本没被请求。

2. 文件没被请求，说明DesignTime.js的加载器没有触发对应模块加载。继续检查控件的 manifest.json 和模块暴露方式，发现我的控件包是在某个公共入口文件里一次性 define 的，而 designtime 文件依赖的命名空间路径与控件库公开的命名空间路径不一致。 这一层如果路径不一致，框架按命名约定去拼接模块名时，得到的是一个不存在的路径，自然不发起请求。

3. 修正路径，重新构建，刷新后再看网络面板，请求发出去了，但返回 404。 继续查文件目录，发现本地文件名是formContainer.designtime.js，而约定要求控件名首字母大写FormContainer.designtime.js。对于模块加载器来说，这是两个不同的模块路径。

4. 改完文件名，请求正常返回 200。打开设计器，聚合拖拽恢复正常。

整个过程最费时间的不是改代码，而是第一想到的是“检查逻辑”，而不是“检查文件到底有没有被加载”。如果你以后遇到类似现象，我建议第一步永远是看网络面板，看 designtime 文件有没有被拉起来。这一步能在两分钟内完成，能砍掉 80% 的盲目排查。

5.3 我的两个实用调试技巧

第一个技巧：临时改一个控件的 designtime 文件，在里面直接console.log控件名，观察加载器是否执行到这一段。虽然看起来原始，但比断点排查更快，尤其是多个控件同时加载时，你能很快分清哪些控件走了开发时配置，哪些没有。

第二个技巧：利用DesignTime.js查询接口的返回结果做验证，把返回的字段与你在 designtime 里写的字段做一次“交差核对”。很多时候你以为自己写的是properties: { text: ... }，实际文件里因为 JSON 嵌套错误或者注释残留，解析出来的却是properties: { }。直接在控制台打印一次，谜底立刻揭晓。

我在实际开发里还发现，做这类框架源码解读时，最好的学习方式不是背 API，而是带着一个问题去源码里找答案。比如“为什么我的自定义控件不出现在属性面板里”就是一个比“DesignTime.js 有哪些方法”好得多的学习问题。

如果你也想走一遍完整链路，建议按这个顺序去读代码：先看一个真实控件的.designtime.js文件知道“配什么”，再回头读DesignTime.js知道“怎么加载”，最后动手给一个小自定义控件补配置，跑通一次就全通了。整个过程不需要太高深的前端功底，但需要耐心和一套系统的排查方法。