UX1 自定义组件工程与加载契约

目录示意

my-component/
├── package.json
├── vite.config.ts
├── tsconfig.json
├── public/
│   ├── data.json
│   └── icon.svg
└── src/
    ├── types.ts
    ├── edit.tsx
    ├── use.tsx
    ├── option.tsx
    ├── optionSchema.ts
    └── components/        # 按需放组件内部实现和自定义属性控件

目标项目已有模板时，以模板为准；不要只为匹配上面的示意图移动现有文件。

文件职责

当前辅助工具包中的 ux-material-contract 要求提供 Edit、Use、Option 三个默认导出，并分别构建为 edit.js、use.js、option.js。目标项目使用不同版本模板时，以该模板的契约为准。

data.json 是契约起点

下面按当前辅助工具包中的 ux-material-contract 给出一个可解析示例；它不是可直接复制到所有组件的完整模板，实际字段和取值还应从目标工程的同类组件确认：

{
  "name": "@example/summary-card",
  "label": {
    "zh-cn": "摘要卡片",
    "en": "Summary Card"
  },
  "version": "1.0.0",
  "description": {
    "zh-cn": "展示一项摘要数据",
    "en": "Displays one summary value"
  },
  "icon": "./icon.svg",
  "webType": "dataEntry",
  "config": {
    "title": {
      "zh-cn": "标题",
      "en": "Title"
    },
    "hidden": false
  },
  "configCss": {
    "style": {
      "width": "100%"
    }
  },
  "events": [
    {
      "id": "onClick",
      "name": "点击"
    }
  ]
}

注意：

• 文件必须是严格 JSON，不能写注释、函数、单引号或尾随逗号。

• config 与 configCss 是新拖入实例的默认值；修改默认值不会自动覆盖页面上已有实例。

• 当前辅助工具包契约支持示例中的 webType: "dataEntry"；旧培训材料还列出 form、table、area、layout。具体组件使用哪个值，以目标项目当前模板为准。

• 业务配置通常绑定到 :config.* 或 :configCss.*；需要初始值时，再在 data.json 的 config 或 configCss 中配置，并与组件实际读取路径保持一致。

• events[].id 必须与 Use 接收并触发的事件回调名一致。

• 组件名、版本与 package.json、dist/data.json 是否需要逐项对应，由当前构建模板校验；不要沿用旧项目规则代替当前模板。

三个运行入口

平台为什么要求这些产物

平台会读取 data.json 并按当前模板约定加载相应入口。当前辅助工具包要求三入口默认导出，并构建为 SystemJS；遇到组件不出现或白屏时，优先检查：

• data.json 的名称或版本与加载路径不一致。

• 对应 JS 文件缺失，或没有默认导出。

• 构建格式不是当前工具包要求的 SystemJS。

• JS 引用了目标运行时没有提供的外部模块。

构建和打包检查见开发包、调试包与上传包。精确类型和导入入口以 Agent 开发辅助工具包及目标项目当前版本为准。

事件、方法和依赖

• 事件：在 data.json.events 声明，在 Use 中调用同名回调；属性面板可用 EventAction 为事件配置动作。

• 方法：需要让页面动作调用组件能力时，在元数据中声明方法，并在运行态注册对应实现。参数能力以目标版本契约为准。

• 元素依赖：组件配置引用其它页面元素时，应实现目标工程规定的依赖提取能力，使被引用元素更新后可以同步。

• 保存校验：组件存在保存前置条件时，可通过 Edit.checkOption 返回错误；校验范围不限于输入组件，签名和返回结构以当前模板类型为准。