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

35 KiB
Raw Blame History

字段类型与物料组件开发指南

最后更新: 2026-04-03

目录

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 端注册链路：

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

移动端装配链路：

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