admin/wukuang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
34914088c610ef3c042220be629107783e43c741
wukuang/字段类型与物料组件开发指南.md
T
董海洋 34914088c6 Initial commit: 上传整个code目录
2026-05-23 14:05:22 +08:00

829 lines
35 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 字段类型与物料组件开发指南
**最后更新**: 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 View Git Blame Copy Permalink