UX1 自定义组件开发

这页是“前端 JS 自定义开发”中的 UX1 自定义组件主流程，用于判断需求是否属于 UX1 组件，并说明从准备工程、开发调试到导入验收的完整过程。

适合这类需求：在 UX 页面新增卡片、按钮或图表；修改组件样式和交互；增加属性配置、数据源或页面事件。修改电子表格时请看电子表格自定义 JS。

先判断：复用还是开发

直接复用：组件不需要改动时，从来源空间取得已有组件包，直接导入目标空间，不必重新构建。
新建或修改：先取得可修改的组件开发工程，完成开发、检查和调试，再生成上传包。已有组件只有上传包、没有源码工程时，不能把上传包当成开发工程直接修改。

分清工具包和三类产物

名称	主要内容	在流程中的用途
Agent 开发辅助工具包	Skills、公开契约、页面代理和使用说明	告诉 Agent 如何开发和验证；不包含业务组件源码
开发包（组件开发工程）	`package.json`、`src/`、`public/`、构建配置和测试	日常修改、检查和构建；不能直接导入目标空间
调试产物（`dist/`）	当前开发辅助工具包契约包含 `data.json`、`edit.js`、`use.js`、`option.js` 和按需图标	供本地预览和按需页面联调；通常不再单独压缩
上传包（`package.zip`）	当前单组件模板由 `pack` 脚本生成，根目录包含 `package.json` 和 `dist/`	导入目标空间；旧工程以自身模板和脚本为准

开发辅助工具包与组件开发工程不是同一个“包”。本文推荐调试和打包基于同一次已验证的 dist/：如果源码有变化，就重新构建、重新验证，再重新生成上传包；如果 pack 脚本会重新构建，还要验证它最终使用的产物。详细边界和检查方法见开发包、调试包与上传包。

完整开发流程

Copy

准备辅助工具包和组件开发工程
  → 确认需求、现有约定和验收标准
  → 实现 Edit / Use / Option 与组件元数据
  → 类型检查、测试和规范检查
  → 构建 dist
  → 本地预览；按需进行真实页面联调
  → 执行现有 pack 脚本生成上传包
  → 导入目标空间
  → 在画布、属性面板和使用态验收

1. 准备输入

下载并解压开发辅助工具包。
提供现有组件开发工程；新组件优先从目标项目正在使用的模板或同类组件开始。
提供测试页面、需求说明和完成标准。需要真实页面联调时，再提供页面链接和临时凭据。
先读取目标工程的 package.json、构建配置和现有脚本，不凭旧示例猜测目录、依赖或命令。

2. 开发组件

维护 data.json 和配置类型，实现三个运行入口：

Edit：设计画布中的编辑态，保证组件可显示、选中和保存。
Use：页面使用态，处理数据、交互、空状态、异常状态和事件。
Option：右侧属性面板，让组件配置与 Edit、Use 使用同一份字段契约。

工程目录、元数据和加载规则见组件工程与加载契约；涉及属性控件、Tab 或显隐联动时查看属性面板与联动。

3. 检查并构建 `dist/`

按目标工程已有脚本完成类型检查、测试和代码规范检查，再执行构建。当前开发辅助工具包契约要求 dist/ 包含合法的 data.json、带默认导出的 edit.js、use.js、option.js，三个入口为 SystemJS 产物，组件声明的图标和资源也必须齐全。应优先运行工程自带的产物检查脚本；旧工程模板版本不同时，以其现有脚本和加载约定为准。

4. 调试同一份 `dist/`

先用本地预览检查组件是否能加载，再检查编辑态、属性面板和使用态。只有依赖真实页面上下文、真实数据或页面事件时，才进入页面联调，让页面临时读取当前 dist/。

联调发现问题后回到源码修改并重新构建，不直接改 dist/，也不为联调另做一份压缩包。

5. 生成上传包

本地验证通过后，执行目标工程 package.json 的 scripts 中已有的 pack 命令。当前单组件模板会生成 package.zip，ZIP 根目录包含 package.json 和 dist/；实际结果仍以目标工程当前脚本为准，不手工套用到不同模板。本文推荐让它使用本次已验证的 dist/；如果脚本会重新构建，则对最终产物补做验证。同时确认上传包没有意外混入代理配置、临时凭据、日志或其它敏感信息。

6. 导入与验收

将打包脚本生成的上传包导入目标空间并选择分类，然后在 UX 页面拖入组件。平台入口和页面操作可参考 DeepUX 的自定义组件说明。

至少完成以下验收：

编辑态可以显示、选中、配置和保存。
属性面板的默认值、修改、显隐和联动符合预期。
使用态的数据、交互、空状态和异常状态正常。
组件事件和页面动作可以触发，多个实例互不影响。
目标空间实际加载的版本与本次验证和打包的版本一致。

发给 Agent

Copy

工具包路径：<解压后的目录>
要改的位置：<UX1 项目目录；不知道可以让 Agent 查找>
UX1 页面：<测试页面链接>
临时 Cookie：<需要登录时填写>
需求：<组件显示什么、可以怎样配置、用户操作后发生什么>
完成标准：<页面效果和不能受影响的功能>

请自动选择 UX1 Skill，先读取目标工程现有约定，再完成开发、检查、
构建和可见浏览器验证。最后分别说明组件源码目录、dist 目录、
上传包路径或生成条件、验证结果和待确认项。
推荐上传包基于本次已验证的同一份 dist；如 pack 会重新构建，需验证最终产物。

Agent 会处理组件显示、属性配置、数据和事件，并汇报修改文件、各类产物与验证结果。未提供目标工程时，让 Agent 先查找现有工程和脚本，不要凭空假设目录或打包命令。

继续查看：开发包、调试包与上传包 · 组件工程与加载契约 · 属性面板与联动 · 常用公开 API · 可复制任务示例

上一篇：视频演示

下一篇：开发包、调试包与上传包

本页目录