# 字段类型与物料组件开发指南 **最后更新**: 2026-04-03 --- ## 目录 - [1. 这篇文档解决什么问题](#1-这篇文档解决什么问题) - [2. 开发前先判断你属于哪一类](#2-开发前先判断你属于哪一类) - [2.1 字段类型 + 对应物料组件](#21-字段类型--对应物料组件) - [2.2 纯物料组件](#22-纯物料组件) - [2.3 纯字段类型](#23-纯字段类型) - [2.4 三类场景一眼看懂](#24-三类场景一眼看懂) - [3. 当前仓库的真实分层与入口](#3-当前仓库的真实分层与入口) - [3.1 共享契约层 packages/types](#31-共享契约层-packagestypes) - [3.2 建模层 apps/lcdp](#32-建模层-appslcdp) - [3.3 业务组件层 packages/business-components](#33-业务组件层-packagesbusiness-components) - [3.4 页面设计器层 packages/form-designer](#34-页面设计器层-packagesform-designer) - [3.5 移动端镜像层 packages/form-designer/src/widget-mobile](#35-移动端镜像层-packagesform-designersrcwidget-mobile) - [3.6 form-create / lowcode-create / registry 的关系](#36-form-create--lowcode-create--registry-的关系) - [4. 场景A：字段类型 + 物料组件](#4-场景a字段类型--物料组件) - [4.1 必改文件总览](#41-必改文件总览) - [4.2 第一步：补共享契约层](#42-第一步补共享契约层) - [4.3 第二步：补建模层](#43-第二步补建模层) - [4.4 第三步：补业务组件层](#44-第三步补业务组件层) - [4.5 第四步：补 PC 设计器链路](#45-第四步补-pc-设计器链路) - [4.6 第五步：按需补移动端](#46-第五步按需补移动端) - [4.7 这一类通常可以不关注什么](#47-这一类通常可以不关注什么) - [5. 场景B：纯物料组件](#5-场景b纯物料组件) - [5.1 这类组件是什么](#51-这类组件是什么) - [5.2 纯物料的最小开发链路](#52-纯物料的最小开发链路) - [5.3 纯物料可以跳过哪些层](#53-纯物料可以跳过哪些层) - [5.4 三种常见纯物料子类](#54-三种常见纯物料子类) - [5.5 纯物料开发 checklist](#55-纯物料开发-checklist) - [6. 场景C：纯字段类型](#6-场景c纯字段类型) - [6.1 这类场景是什么](#61-这类场景是什么) - [6.2 纯字段的开发链路](#62-纯字段的开发链路) - [6.3 纯字段通常可以跳过什么](#63-纯字段通常可以跳过什么) - [7. 共同规则与边界](#7-共同规则与边界) - [7.1 什么时候需要双注册设置项组件](#71-什么时候需要双注册设置项组件) - [7.2 什么时候要改 FilterTypeEnum / filter/constants](#72-什么时候要改-filtertypeenum--filterconstants) - [7.3 什么时候要改 FieldViewMap](#73-什么时候要改-fieldviewmap) - [7.4 什么时候要改 user-script 事件配置](#74-什么时候要改-user-script-事件配置) - [7.5 什么时候要补移动端](#75-什么时候要补移动端) - [7.6 当前仓库里哪些历史口径不要再照搬](#76-当前仓库里哪些历史口径不要再照搬) - [8. 当前仓库的 live source 样板](#8-当前仓库的-live-source-样板) - [8.1 字段 + 物料：mobile-number](#81-字段--物料金mobile-number) - [8.2 纯物料：CommonBtn](#82-纯物料commonbtn) - [8.3 纯物料：GroupPanel / CommonTxt](#83-纯物料grouppanel--commontxt) - [8.4 纯字段：BinaryObject](#84-纯字段binaryobject) - [9. 最小验证建议](#9-最小验证建议) - [10. 常见误区](#10-常见误区) - [11. 文档变更记录](#11-文档变更记录) --- ## 1. 这篇文档解决什么问题 这篇文档是给团队成员看的，不是只给 AI 看“结论”。 它要解决的核心问题有两个： 1. 当前仓库里，“新增字段类型”和“新增纯物料组件”不是一套完全相同的开发链路。 2. 旧文档里很多路径和事实已经漂移，比如 `packages/types` 这层共享契约、`form-designer` 的 registry 注册链、`business-components` 的实际导出结构，都需要按当前源码重新理解。 如果你现在做的是： - 一个既有业务字段定义、又有页面物料渲染的字段 - 一个纯页面物料组件，例如按钮、分组面板、通用文本、列表、Tabs、FlexLayout - 一个只存在于业务模型、没有页面物料的字段 都可以从这篇文档里找到对应的开发入口。 **阅读建议**： - 如果你做的是“纯物料组件”，先看第 2 章判断场景，然后直接跳到第 5 章。 - 如果你做的是“字段类型 + 物料组件”，重点看第 4 章。 - 如果你做的是“纯字段类型”，重点看第 6 章。 --- ## 2. 开发前先判断你属于哪一类 ### 2.1 字段类型 + 对应物料组件 这是最常见、也是改动面最大的场景。 典型特征： - 业务模型里要新增一种字段类型 - 页面设计器里也要能拖入对应控件 - 列表、单据体、过滤器、运行时回显等也可能要支持 典型例子： - 金额 - 币种 - 手机号码 - 业务组织 / 人员 / 基础数据引用类字段 ### 2.2 纯物料组件 这类组件没有业务模型字段类型，不对应 `FieldType`。 它更像“页面设计器里的纯 UI / 纯交互 / 纯容器能力”。 典型例子： - `CommonBtn` - `CommonTxt` - `GroupPanel` - `Tabs` - `FlexLayout` - `Toolbar` - `ListVxe` - `ListVxeColumn` - `ListVxeAction` 这类场景最重要的结论是： **通常不需要改建模层，也通常不需要补 `business-components/src/enum/settings/` 这一类字段扩展属性。** ### 2.3 纯字段类型 这类字段只存在于业务模型，不进入页面设计器物料体系。 典型特征： - 业务模型里要支持该字段类型 - 但页面设计器不会拖拽出一个对应控件 - 也不会出现在 `Material.ts` / `RegisterWidget.ts` 这条链路 典型例子： - `BinaryObject` - 一些仅服务高开或后端协议的字段类型 ### 2.4 三类场景一眼看懂 | 场景 | 必看层 | 常见必改文件 | 通常可以跳过 | | ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | 字段类型 + 物料组件 | `packages/types`、`apps/lcdp`、`packages/business-components`、`packages/form-designer` | `FieldType`、`WidgetType`、`settings-helper`、`widget-helper`、`filter/constants`、`FieldViewMap` | 几乎没有，只有 user-script / mobile 视需求而定 | | 纯物料组件 | `packages/types`、`packages/form-designer` | `WidgetType`、`Material.ts`、`RegisterWidget.ts`、`RegisterWidgetHelper.ts`、`widget-helper`、`widget` | `apps/lcdp` 建模层、`FieldType`、`modeling.json`、大部分字段枚举/常量 | | 纯字段类型 | `packages/types`、`apps/lcdp`，必要时 `packages/business-components` | `FieldType`、建模 `Schema.ts`、`modeling.json` | `Material.ts`、`RegisterWidget.ts`、`RegisterWidgetHelper.ts`、大多数 widget 文件 | --- ## 3. 当前仓库的真实分层与入口 ### 3.1 共享契约层 `packages/types` 这是当前仓库和旧文档相比，最大的认知变化之一。 很多“枚举 / 类型 / 注册协议”的真相，已经在 `packages/types`，不是在业务包或设计器包本地定义。 当前常见真相入口： - `packages/types/business-components/enum/common/Enum.ts` - `FieldType` - `packages/types/business-components/enum/settings//Enum.ts` - 字段扩展属性 key - `packages/types/business-components/components/common/form/types/index.ts` - `ComponentType` - `packages/types/widget-pc/WidgetType.ts` - PC 侧 `WidgetType` - `packages/types/form-designer/SettingType.ts` - `SettingTypeEnum` - `packages/types/form-designer/components/filter/constants.ts` - `FilterTypeEnum` - `packages/types/form-designer/config/register/*.ts` - registry 配置协议 **结论**： - 新增字段类型时，不要只改 `apps/lcdp` - 新增物料组件时，也不要只改 `packages/form-designer/src/types/WidgetType.ts` - 先看 `packages/types`，再看各运行时包的再导出和消费点 ### 3.2 建模层 `apps/lcdp` 建模层主要负责业务模型字段的定义、实体建模 UI、业务属性配置。 关键入口： - `apps/lcdp/src/feature/modeling/components/model-details/entity-model/config/FieldType.ts` - `apps/lcdp/src/feature/modeling/components/model-details/entity-model/helper//Schema.ts` - `apps/lcdp/src/locales/model/modeling.json` - `apps/lcdp/src/components/common/form/RegistersFormComp.ts` 建模层只在以下场景一定要动： - 新增字段类型 - 变更业务模型字段属性配置项 - 新增建模侧专用设置组件 如果你做的是纯物料组件，这一层通常可以直接跳过。 ### 3.3 业务组件层 `packages/business-components` 这层主要负责： - 字段扩展属性的再导出 - 值解析 / 格式化 / 校验工具 - 通用服务、接口、公共设置组件 常见入口： - `packages/business-components/src/enum/index.ts` - `packages/business-components/src/enum/settings//` - `packages/business-components/src/utils/*.ts` - `packages/business-components/src/service/*.ts` - `packages/business-components/src/api/*.ts` - `packages/business-components/src/components/common/form/index.ts` **当前要特别注意**： - 不要再按旧文档去找 `packages/business-components/src/index.ts` - 当前这个包的对外导出已经拆散到多个子入口，不存在单个 `src/index.ts` 作为总维护入口 ### 3.4 页面设计器层 `packages/form-designer` 这是页面物料真正落地的主战场。 PC 侧常见入口： - `packages/form-designer/src/config/Material.ts` - `packages/form-designer/src/config/RegisterWidget.ts` - `packages/form-designer/src/config/RegisterWidgetHelper.ts` - `packages/form-designer/src/config/RegisterSettings.ts` - `packages/form-designer/src/config/settings-helper/*.ts` - `packages/form-designer/src/config/widget-helper/*.ts` - `packages/form-designer/src/config/widget/*.vue` - `packages/form-designer/src/components/filter/constants.ts` - `packages/form-designer/src/config/widget/table/FieldViewMap.ts` - `packages/form-designer/src/locales/model/Info.json` ### 3.5 移动端镜像层 `packages/form-designer/src/widget-mobile` 如果页面需要移动端渲染，除了 PC 侧，还要看移动端镜像配置。 常见入口： - `packages/form-designer/src/widget-mobile/config/index.ts` - `packages/form-designer/src/widget-mobile/config/RegisterWidget.ts` - `packages/form-designer/src/widget-mobile/config/RegisterWidgetHelper.ts` - `packages/form-designer/src/widget-mobile/config/Material.ts` - `packages/form-designer/src/widget-mobile/config/widget/*.vue` - `packages/form-designer/src/widget-mobile/config/widget-helper/*.ts` ### 3.6 `form-create` / `lowcode-create` / registry 的关系 旧文档里容易让人误解成“页面模型就是一套 `form-create` 注册”。 当前真实情况是： | 能力 | 当前真相 | | ----------------------------- | -------------------------------------------------- | | 建模侧表单组件 | `@busi-comp/components/common/form` | | 页面右侧属性面板设置项 | `@lingshu/form-create` | | 页面画布 / 运行时 widget 注册 | `@lingshu/lowcode-create` | | PC 端配置装配 | `packages/form-designer/src/config/RegisterWeb.ts` | | 实际注册执行 | `packages/form-designer/src/config/register/*.ts` | PC 端注册链路： ```mermaid flowchart LR A[Material.ts / RegisterWidget.ts / RegisterSettings.ts / RegisterWidgetHelper.ts] B[RegisterWeb.ts] C[setConfigAll PagePlatform.PC] D[register/registry.ts] E[register/material.ts] F[register/widget.ts] G[register/setting.ts] H[register/helper.ts] A --> B --> C --> D D --> E D --> F D --> G D --> H ``` 移动端装配链路： ```mermaid flowchart LR A[widget-mobile/config/*] B[widget-mobile/config/index.ts] C[setConfigAll PagePlatform.MOBILE] D[register/registry.ts] A --> B --> C --> D ``` **重要说明**： - 根目录 `package.json` 里虽然还保留了 `form-create:dev`、`lowcode-create:dev` 一类历史脚本 - 但在当前仓库日常字段 / 物料开发里，它们应被视为历史兼容脚本，不是主工作区入口 --- ## 4. 场景A：字段类型 + 物料组件 ### 4.1 必改文件总览 | 层次 | 常见文件 | 作用 | | --------------------- | --------------------------------------------------- | --------------------------------------------------------------- | | `packages/types` | `business-components/enum/common/Enum.ts` | 新增 `FieldType` | | `packages/types` | `business-components/enum/settings//Enum.ts` | 新增字段扩展属性 key | | `packages/types` | `widget-pc/WidgetType.ts` | 新增 `WidgetType` | | `packages/types` | `form-designer/SettingType.ts` | 新增设置项组件类型，只有自定义设置组件时才需要 | | `packages/types` | `form-designer/components/filter/constants.ts` | 新增 `FilterTypeEnum`，若字段进入过滤器 / 列表 / 单据体只读体系 | | `apps/lcdp` | `.../config/FieldType.ts` | 建模层字段到 Schema 的映射 | | `apps/lcdp` | `.../helper//Schema.ts` | 建模层业务属性配置 | | `apps/lcdp` | `src/locales/model/modeling.json` | 建模国际化 | | `apps/lcdp` | `src/components/common/form/RegistersFormComp.ts` | 建模侧自定义设置项组件注册 | | `business-components` | `src/enum/settings//` | 再导出字段扩展属性和默认配置 | | `business-components` | `src/utils/*.ts` | 格式化、解析、校验 | | `business-components` | `src/service/*.ts` / `src/api/*.ts` | 远程取数、服务接口 | | `form-designer` | `src/config/Material.ts` | 左侧物料面板 | | `form-designer` | `src/config/RegisterWidget.ts` | widget 实例映射 | | `form-designer` | `src/config/RegisterWidgetHelper.ts` | helper 注册 | | `form-designer` | `src/config/settings-helper/*.ts` | 右侧属性面板 schema | | `form-designer` | `src/config/RegisterSettings.ts` | 页面模型设置项组件注册 | | `form-designer` | `src/config/widget-helper/*.ts` | 构造 widget / settings / schema controller | | `form-designer` | `src/config/widget/*.vue` | 运行时渲染组件 | | `form-designer` | `src/components/filter/constants.ts` | 过滤器组件映射、回显文本 | | `form-designer` | `src/config/widget/table/FieldViewMap.ts` | 列表 / 单据体详情只读渲染 | | `form-designer` | `src/locales/model/Info.json` | 页面设计器国际化 | ### 4.2 第一步：补共享契约层 推荐顺序： 1. 在 `packages/types/business-components/enum/common/Enum.ts` 增加 `FieldType` 2. 在 `packages/types/business-components/enum/settings//Enum.ts` 增加扩展属性 key 3. 在 `packages/types/widget-pc/WidgetType.ts` 增加 `WidgetType` 4. 只有在自定义设置项组件时，再改 `packages/types/form-designer/SettingType.ts` 5. 如果字段要进入过滤器 / 列表 / 单据体详情体系，再改 `packages/types/form-designer/components/filter/constants.ts` 补完后，再去看各运行时包里的再导出与消费点。 ### 4.3 第二步：补建模层 常见改动： - `FieldType.ts` - 把 `FieldType` 映射到建模 Schema 构造函数 - `helper//Schema.ts` - 写字段业务属性 - `modeling.json` - 补建模国际化 - `RegistersFormComp.ts` - 只有你用了自定义设置项组件时才需要 建模层一般要回答这几个问题： - 这个字段有哪些业务属性 - 这些属性用什么设置项组件来编辑 - 是否需要默认值、格式、范围、联动、校验等 ### 4.4 第三步：补业务组件层 这一层通常承担“值语义”和“公共能力”。 常见改动： - `src/enum/settings//Constants.ts` - `src/enum/settings//index.ts` - `src/enum/index.ts` - `src/utils/Utils.ts` - `src/service/*.ts` - `src/api/*.ts` 要注意： - 字段扩展属性的**真相**在 `packages/types` - `packages/business-components` 这层更多是再导出、默认配置、运行时工具和服务 - 不要再按旧文档去补不存在的 `src/index.ts` ### 4.5 第四步：补 PC 设计器链路 这一层是字段真正进入页面设计器的关键。 通常至少要补： 1. `packages/form-designer/src/config/Material.ts` - 让物料出现在左侧面板 2. `packages/form-designer/src/config/RegisterWidget.ts` - 让 widget 能被渲染 3. `packages/form-designer/src/config/RegisterWidgetHelper.ts` - 让 helper 能参与构造和配置 4. `packages/form-designer/src/config/settings-helper/.ts` - 定义右侧属性面板 5. `packages/form-designer/src/config/RegisterSettings.ts` - 只有自定义设置项组件时才需要 6. `packages/form-designer/src/config/widget-helper/Helper.ts` - 一般至少实现： - `buildMaterialConfig` - `buildSettings` - `buildWidget` 7. `packages/form-designer/src/config/widget/.vue` - 真正的运行时渲染 8. `packages/form-designer/src/locales/model/Info.json` 如果字段会出现在过滤器、列表、单据体详情： - `packages/form-designer/src/components/filter/constants.ts` - `packages/form-designer/src/config/widget/table/FieldViewMap.ts` ### 4.6 第五步：按需补移动端 如果页面 clientType 需要移动端，通常还要镜像： - `packages/form-designer/src/widget-mobile/config/widget/.vue` - `packages/form-designer/src/widget-mobile/config/widget-helper/Helper.ts` 必要时再看： - `packages/form-designer/src/widget-mobile/config/RegisterWidget.ts` - `packages/form-designer/src/widget-mobile/config/RegisterWidgetHelper.ts` - `packages/form-designer/src/widget-mobile/config/Material.ts` ### 4.7 这一类通常可以不关注什么 这一类是最全链路场景，通常没有太多可以完全跳过的层。 但以下部分仍然是**按需**： - `user-script` 事件配置 - 移动端镜像 - `FieldViewMap` - `filter/constants` 如果字段不进入对应运行面，就不用硬补。 --- ## 5. 场景B：纯物料组件 ### 5.1 这类组件是什么 纯物料组件的核心特征是： - 它是页面设计器里的一个 widget - 但它不对应业务模型字段类型 - 因此不会走 `FieldType -> 建模 Schema -> 字段扩展属性` 这条链 常见例子： - 通用展示类：`CommonTxt`、`CommonImg`、`CommonLink` - 通用交互类：`CommonBtn` - 容器类：`GroupPanel`、`Tabs`、`TabPane`、`FlexLayout`、`Toolbar` - 列表类：`ListVxe`、`ListVxeColumn`、`ListVxeAction` ### 5.2 纯物料的最小开发链路 对大多数纯物料来说，最小链路是： 1. `packages/types/widget-pc/WidgetType.ts` - 新增 `WidgetType` 2. `packages/form-designer/src/config/Material.ts` - 注册左侧物料 3. `packages/form-designer/src/config/RegisterWidget.ts` - 注册组件实例 4. `packages/form-designer/src/config/RegisterWidgetHelper.ts` - 注册 helper 5. `packages/form-designer/src/config/widget-helper/.ts` - 写 helper 6. `packages/form-designer/src/config/widget/.vue` - 写组件 7. `packages/form-designer/src/locales/model/Info.json` - 补物料名称、属性面板文案 如果需要自定义右侧设置项组件，再额外补： - `packages/types/form-designer/SettingType.ts` - `packages/form-designer/src/config/RegisterSettings.ts` - `packages/form-designer/src/config/settings-helper/*.ts` ### 5.3 纯物料可以跳过哪些层 如果你新增的是普通纯物料组件，下面这些通常可以直接跳过： | 层 / 文件 | 是否通常可跳过 | 原因 | | ---------------------------------------------------------------- | -------------- | ----------------------------------- | | `packages/types/business-components/enum/common/Enum.ts` | 是 | 不涉及 `FieldType` | | `apps/lcdp/.../config/FieldType.ts` | 是 | 纯物料不属于业务模型字段 | | `apps/lcdp/.../helper//Schema.ts` | 是 | 没有建模层字段属性 | | `apps/lcdp/src/locales/model/modeling.json` | 是 | 没有建模文案 | | `apps/lcdp/src/components/common/form/RegistersFormComp.ts` | 是 | 纯物料不出现在建模侧设置表单 | | `packages/business-components/src/enum/settings//` | 是 | 没有字段扩展属性 | | `packages/form-designer/src/components/filter/constants.ts` | 通常是 | 除非这个物料本身就是过滤器相关组件 | | `packages/form-designer/src/config/widget/table/FieldViewMap.ts` | 通常是 | 除非这个物料参与列表/单据体只读渲染 | **一句话版**： 如果你做的是 `CommonBtn`、`CommonTxt`、`GroupPanel`、`Tabs`、`FlexLayout` 这类纯物料，先看： - 第 3 章 - 第 5 章 - 第 7 章 - 第 8.2 / 8.3 章 - 第 9 章 可以先跳过： - 第 4 章里的建模层和字段扩展属性相关内容 - `apps/lcdp` 建模链路 - `business-components/src/enum/settings/` 这条字段链 ### 5.4 三种常见纯物料子类 | 子类 | 例子 | 一般关注点 | | ------------------- | -------------------------------------------------------- | ----------------------------------------------------------------- | | 通用展示 / 交互物料 | `CommonTxt`、`CommonBtn`、`CommonImg`、`CommonLink` | `WidgetType`、`Material`、`RegisterWidget`、`Helper`、`Info.json` | | 容器 / 布局物料 | `GroupPanel`、`Tabs`、`TabPane`、`FlexLayout`、`Toolbar` | 容器 children、slot、拖拽规则、`hasSlotDropBox`、布局属性 | | 运行型复杂物料 | `ListVxe`、`Filter`、`CommonTree`、`FeatureDomain` | 除 widget/helper 外，还会碰 store、service、事件配置、运行时协议 | 其中第三类虽然仍是“纯物料”，但复杂度明显高于 `CommonTxt` / `GroupPanel` / `CommonBtn`。 ### 5.5 纯物料开发 checklist #### 普通纯物料 ``` 1. packages/types ✓ WidgetType ✗ FieldType ✗ 字段扩展属性 Enum 2. form-designer PC ✓ Material.ts ✓ RegisterWidget.ts ✓ RegisterWidgetHelper.ts ✓ widget-helper/.ts ✓ widget/.vue ✓ Info.json ✓ settings-helper/*.ts（如果有右侧属性面板配置） ✓ RegisterSettings.ts（只有自定义设置项组件时） 3. form-designer mobile（按需） ✓ widget-mobile/config/widget/*.vue ✓ widget-mobile/config/widget-helper/*.ts 4. 通常可跳过 ✗ apps/lcdp 建模层 ✗ business-components 字段枚举/常量/建模设置项 ✗ FieldViewMap ✗ filter/constants ``` #### 复杂纯物料 如果你做的是 `ListVxe`、`Filter`、`CommonTree` 这类运行型纯物料，还要额外检查： - `stores/` - `service/` - `settings-helper/Business.ts` 或专属 settings-helper - `user-script` 事件 / hook 配置 - 子物料或 slot 规则 --- ## 6. 场景C：纯字段类型 ### 6.1 这类场景是什么 纯字段类型的定义是： - 有 `FieldType` - 业务模型里要能配置和保存 - 但页面设计器不会出现一个对应物料组件 典型例子： - `BinaryObject` ### 6.2 纯字段的开发链路 通常至少要做： 1. `packages/types/business-components/enum/common/Enum.ts` - 增加 `FieldType` 2. `apps/lcdp/.../config/FieldType.ts` - 建模映射 3. `apps/lcdp/.../helper//Schema.ts` - 建模属性配置 4. `apps/lcdp/src/locales/model/modeling.json` - 建模国际化 5. 必要时补 `packages/business-components` 的工具 / 服务 ### 6.3 纯字段通常可以跳过什么 通常可以跳过： - `packages/types/widget-pc/WidgetType.ts` - `packages/form-designer/src/config/Material.ts` - `packages/form-designer/src/config/RegisterWidget.ts` - `packages/form-designer/src/config/RegisterWidgetHelper.ts` - `packages/form-designer/src/config/widget/*.vue` - `packages/form-designer/src/components/filter/constants.ts` - `packages/form-designer/src/config/widget/table/FieldViewMap.ts` - `packages/form-designer/src/widget-mobile/**` --- ## 7. 共同规则与边界 ### 7.1 什么时候需要双注册设置项组件 分两种情况： #### 字段类型 + 物料组件 如果这个字段有自定义设置项组件，并且： - 建模层也要用 - 页面设计器右侧属性面板也要用 那么要双注册： 1. `apps/lcdp/src/components/common/form/RegistersFormComp.ts` 2. `packages/types/form-designer/SettingType.ts` + `packages/form-designer/src/config/RegisterSettings.ts` #### 纯物料组件 纯物料没有建模层，所以通常只需要页面设计器侧注册： 1. `packages/types/form-designer/SettingType.ts` 2. `packages/form-designer/src/config/RegisterSettings.ts` ### 7.2 什么时候要改 `FilterTypeEnum` / `filter/constants` 只有当字段或组件进入“过滤器输入 / 条件回显”体系时才要改。 典型场景： - 字段类型要支持过滤器条件输入 - 过滤条件值需要格式化为可读文本 主要文件： - `packages/types/form-designer/components/filter/constants.ts` - `packages/form-designer/src/components/filter/constants.ts` ### 7.3 什么时候要改 `FieldViewMap` 只有当字段要进入以下任一场景时，才要改： - 列表只读展示 - 单据体详情展示 - 单据体非编辑态展示 主要文件： - `packages/form-designer/src/config/widget/table/FieldViewMap.ts` 纯物料组件通常不改这里，除非它本身就是列表单元格 / 详情渲染消费者的一部分。 ### 7.4 什么时候要改 user-script 事件配置 大多数普通表单字段和纯展示物料都不需要主动加事件配置。 通常只有以下情况才需要： - 按钮 - 列表 - 树 - 容器类切换组件 - 上传类组件 - 其他需要额外暴露 hook 的交互组件 ### 7.5 什么时候要补移动端 命中以下任一情况就要补： - 页面 `clientType` 需要移动端 - 该物料明确要在移动端表单 / 列表 / 卡片视图里使用 - 该字段在移动端运行时必须能编辑 / 回显 ### 7.6 当前仓库里哪些历史口径不要再照搬 以下口径在当前仓库里已经不准确： 1. “新增字段只需要三层” - 现在至少要先看 `packages/types` 2. “页面模型就是改 `RegisterWidget.ts` / `RegisterSettings.ts` 就够了” - 现在还要理解 `RegisterWeb.ts -> config/register/*` 这条执行链 3. “业务组件入口是 `packages/business-components/src/index.ts`” - 当前没有这个本地总入口 4. “`form-create` / `lowcode-create` 是本仓当前活跃开发目标” - 当前它们是外部依赖引擎，不是字段/物料日常开发的主入口 --- ## 8. 当前仓库的 live source 样板 ### 8.1 字段 + 物料：mobile-number 推荐作为“字段类型 + 物料组件”的首选样板。 对应链路： - 共享契约 - `packages/types/business-components/enum/common/Enum.ts` - `packages/types/business-components/enum/settings/mobile-number/Enum.ts` - `packages/types/widget-pc/WidgetType.ts` - `packages/types/form-designer/components/filter/constants.ts` - 建模层 - `apps/lcdp/src/feature/modeling/components/model-details/entity-model/config/FieldType.ts` - `apps/lcdp/src/feature/modeling/components/model-details/entity-model/helper/mobile-number/Schema.ts` - `apps/lcdp/src/components/common/form/RegistersFormComp.ts` - `apps/lcdp/src/locales/model/modeling.json` - business-components - `packages/business-components/src/enum/settings/mobile-number/Constants.ts` - `packages/business-components/src/enum/settings/mobile-number/index.ts` - `packages/business-components/src/utils/MobileNumberUtils.ts` - form-designer PC - `packages/form-designer/src/config/settings-helper/MobileNumber.ts` - `packages/form-designer/src/config/widget-helper/FormItemMobileNumberHelper.ts` - `packages/form-designer/src/config/widget/CustomMobileNumber.vue` - `packages/form-designer/src/components/filter/constants.ts` - `packages/form-designer/src/config/widget/table/FieldViewMap.ts` - `packages/form-designer/src/locales/model/Info.json` - form-designer mobile - `packages/form-designer/src/widget-mobile/config/widget/CustomMobileNumber.vue` - `packages/form-designer/src/widget-mobile/config/widget-helper/FormItemMobileNumberHelper.ts` ### 8.2 纯物料：CommonBtn 推荐作为“交互型纯物料”的样板。 主要看： - `packages/types/widget-pc/WidgetType.ts` - `packages/form-designer/src/config/widget-helper/common-btn/index.tsx` - `packages/form-designer/src/config/RegisterWidget.ts` - `packages/form-designer/src/config/RegisterWidgetHelper.ts` - `packages/form-designer/src/locales/model/Info.json` 它的特点是： - 没有 `FieldType` - 不走建模层 - 但会涉及 settings-helper、页面跳转、弹窗、事件 hook 等复杂交互 ### 8.3 纯物料：GroupPanel / CommonTxt 推荐作为“容器型 / 展示型纯物料”的样板。 主要看： - `packages/form-designer/src/config/widget-helper/GroupPanelHelper.ts` - `packages/form-designer/src/config/widget-helper/CommonTxtHelper.ts` 它们的特点是： - 只在 `packages/types` + `packages/form-designer` 内闭环 - 不需要建模层 - 不需要 `business-components/src/enum/settings/` 那条字段链 ### 8.4 纯字段：BinaryObject 推荐作为“只有字段类型、没有物料组件”的样板概念。 可以先看： - `packages/types/business-components/enum/common/Enum.ts` - `apps/lcdp/src/feature/modeling/components/model-details/entity-model/config/FieldType.ts` `FieldType.ts` 当前对 `BinaryObject` 的处理就是返回空的建模属性数组，这能帮助理解“纯字段”与“字段 + 物料”不是同一类工作。 --- ## 9. 最小验证建议 | 场景 | 最小验证 | | ----------- | ----------------------------------------------------------------------------------------------------------------------- | | 字段 + 物料 | `pnpm form-designer:dev` + `/designer/:pageId`；必要时 `pnpm start:lcdp:dev` + `/form/:pageId`、`/list/:pageId`、建模页 | | 纯物料 | `pnpm form-designer:dev` + `/designer/:pageId`；如果是运行型物料，再补 `/form/:pageId` 或 `/list/:pageId` | | 纯字段 | `pnpm start:lcdp:dev` + 建模页；必要时验证该字段对应的保存 / 接口协议 | --- ## 10. 常见误区 ### 误区 1：新增纯物料也要先改 `apps/lcdp` 通常不需要。 如果你新增的是 `CommonBtn` / `GroupPanel` / `CommonTxt` 这类纯物料，优先看 `packages/types` + `packages/form-designer`。 ### 误区 2：新增字段只改建模层就够了 不够。 只要它还要进入页面设计器、过滤器、列表或运行时，就还要继续补 `business-components` 和 `form-designer`。 ### 误区 3：只改 `packages/form-designer/src/types/WidgetType.ts` 不够。 真正的 `WidgetType` 真相在 `packages/types/widget-pc/WidgetType.ts`。 ### 误区 4：只改 `packages/form-designer/src/components/filter/constants.ts` 不够。 如果新增过滤器类型，还要先改 `packages/types/form-designer/components/filter/constants.ts`。 ### 误区 5：按旧文档补 `packages/business-components/src/index.ts` 当前仓库没有这个本地总入口，不要继续按这个口径开发。 --- ## 11. 文档变更记录 | 日期 | 版本 | 变更内容 | | ---------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------- | | 2025-12-17 | v1.0 | 初始版本 | | 2025-12-17 | v1.1 | 新增过滤器组件映射和字段视图映射章节；补充 FilterTypeEnum 和 FieldType 的关系说明；添加 Vue `h()` 函数说明 | | 2025-12-17 | v1.2 | 新增组件事件配置章节；说明自动继承机制和添加自定义事件的步骤 | | 2025-12-17 | v1.3 | 新增业务模型 vs 页面模型对比说明；新增设置项组件注册章节；说明 `ComponentType` 和 `SettingTypeEnum` 的注册位置和使用区别 | | 2026-04-03 | v2.0 | 按当前 live source 重写：补齐 `packages/types` 契约层，拆分“字段 + 物料 / 纯物料 / 纯字段”三类场景，并明确纯物料可跳过的层次与文件 |