admin/wukuang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
34914088c610ef3c042220be629107783e43c741
wukuang/字段类型与物料组件开发指南.md
T

829 lines
35 KiB
Markdown
Raw Normal View History

Initial commit: 上传整个code目录
2026-05-23 14:05:22 +08:00
# 字段类型与物料组件开发指南
**最后更新**: 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/<field>` 这一类字段扩展属性。**
### 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/<field>/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/<field>/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/<field>/`
- `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/<field>/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/<field>/Schema.ts` | 建模层业务属性配置 |
| `apps/lcdp` | `src/locales/model/modeling.json` | 建模国际化 |
| `apps/lcdp` | `src/components/common/form/RegistersFormComp.ts` | 建模侧自定义设置项组件注册 |
| `business-components` | `src/enum/settings/<field>/` | 再导出字段扩展属性和默认配置 |
| `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/<field>/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/<field>/Schema.ts`
- 写字段业务属性
- `modeling.json`
- 补建模国际化
- `RegistersFormComp.ts`
- 只有你用了自定义设置项组件时才需要
建模层一般要回答这几个问题：
- 这个字段有哪些业务属性
- 这些属性用什么设置项组件来编辑
- 是否需要默认值、格式、范围、联动、校验等
### 4.4 第三步：补业务组件层
这一层通常承担“值语义”和“公共能力”。
常见改动：
- `src/enum/settings/<field>/Constants.ts`
- `src/enum/settings/<field>/index.ts`
- `src/enum/index.ts`
- `src/utils/<Field>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/<Field>.ts`
- 定义右侧属性面板
5. `packages/form-designer/src/config/RegisterSettings.ts`
- 只有自定义设置项组件时才需要
6. `packages/form-designer/src/config/widget-helper/<Field>Helper.ts`
- 一般至少实现：
- `buildMaterialConfig`
- `buildSettings`
- `buildWidget`
7. `packages/form-designer/src/config/widget/<Field>.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/<Field>.vue`
- `packages/form-designer/src/widget-mobile/config/widget-helper/<Field>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/<Helper>.ts`
- 写 helper
6. `packages/form-designer/src/config/widget/<Comp>.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/<field>/Schema.ts` | 是 | 没有建模层字段属性 |
| `apps/lcdp/src/locales/model/modeling.json` | 是 | 没有建模文案 |
| `apps/lcdp/src/components/common/form/RegistersFormComp.ts` | 是 | 纯物料不出现在建模侧设置表单 |
| `packages/business-components/src/enum/settings/<field>/` | 是 | 没有字段扩展属性 |
| `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/<field>` 这条字段链
### 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/<Helper>.ts
✓ widget/<Comp>.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/<field>/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/<field>` 那条字段链
### 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` 契约层，拆分“字段 + 物料 / 纯物料 / 纯字段”三类场景，并明确纯物料可跳过的层次与文件 |
Reference in New Issue Copy Permalink