NocoBase 数据表选择器（Collection Select）字段：配置用法与源码实现深度解析

NocoBase 数据表选择器Collection Select字段配置用法与源码实现深度解析【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase数据表选择器Collection select是 NocoBase 数据建模中一类元数据型字段它选择的不是某张表里的业务记录而是数据表Collection本身的标识。本文以 NocoBase 官方文档《数据表选择器》为主体逐节展开其创建配置、字段特性、编辑与删除规则并结合当前仓库中CollectionSelect组件与字段接口源码解释选项来源、继承场景过滤、多选展示等行为的底层实现帮助你在插件配置、规则配置、元数据管理等场景中正确使用并排查该字段。1. 数据表选择器是什么在 NocoBase 中数据表选择器Collection select用于选择一个或多个数据表。它保存的是数据表标识Collection name而不是业务记录 ID。这一点是理解该字段的关键如果你的需求是在一张表里记录指向另一张表某条记录应该使用关系字段relation fields而不是数据表选择器如果你的需求是让配置项能够指向某张表例如某插件作用于哪些表、某条规则的数据范围是哪张表数据表选择器才是正确的选择。该字段天然面向配置即数据的场景字段所在的记录本身是一条配置而该字段存储的值是系统元数据表名。2. 适用场景数据表选择器适合这些业务场景插件配置中选择作用数据表规则配置中指定数据表范围元数据管理、模板配置需要引用 Collection 标识的功能配置。从源码结构看这个定位与字段接口的官方描述一致客户端字段接口CollectionSelectFieldInterface的 description 即为Providing certain collections as options for users, typically used in polymorphic or inheritance scenarios将某些数据表作为可选项提供给用户通常用于多态或继承场景见 collection.ts。3. 创建数据表选择器字段在数据表的「Configure fields」页面中点击「Add field」选择「数据表选择器」即可创建数据表选择器字段。创建表单包含以下配置项配置说明Field interface字段的界面类型。数据表选择器对应collectionSelect决定页面中如何录入和展示。Field display name字段在界面中显示的名称比如「作用数据表」「目标数据表」「数据范围」。建议使用业务人员能直接理解的名称。Field name字段标识名称用于 API、关系字段、权限、工作流等内部引用。创建后通常不再修改只支持字母、数字和下划线并且必须以字母开头。Field type字段在数据层的类型。数据表选择器通常保存数据表标识存储类型以实际配置为准。Default value默认值。新增记录时如果用户没有填写可以自动带出默认值。Validation rules校验规则。通常配置必填或选择范围。Description字段说明。适合写字段含义、填写要求、数据来源或维护人。注意字段名创建后会被页面区块、权限、工作流和 API 引用。创建前先确认命名避免后续修改带来配置调整成本。一个实操提示如果需要限制用户只能在若干张表中选择而不是全量列表可以为字段配置uiSchema.enum。源码中CollectionSelectFieldInterface.properties显式暴露了uiSchema.enum: collectionDataSource这一属性项即字段配置表单支持以数据源列表形式约束可选项见 collection.ts。4. 字段特性数据表选择器字段的默认行为如下特性说明默认 Field interfacecollectionSelect。默认 Field typestring。可选 Field typestring、json以实际配置为准。页面组件编辑模式使用数据表选择组件。筛选通常不作为业务筛选字段。排序通常不用于排序。校验支持必填等基础校验。结合源码可以对上述默认值做更精确的印证。在 CollectionSelectFieldInterface 中name collection、type string字段接口内部标识为collection数据层类型默认string与文档的默认 Field type 为 string一致availableTypes [string]从源码结构看当前客户端实现的可选数据层类型只有string一种文档中可选 string/json以实际配置为准的表述可理解为以具体版本与配置为准group advanced、order 5该字段被归入高级分组在 Add field 列表中的排序靠后sortable true接口声明支持排序能力但文档建议通常不用于排序实际业务中一般不依赖它hasDefaultValue false接口层面不内置默认值文档中的 Default value 属于通用字段配置能力默认 uiSchema 为{ type: string, x-component: CollectionSelect }即页面上实际渲染的组件是CollectionSelect。5. 选项从哪里来CollectionSelect 组件源码解析数据表选择器在表单中的编辑组件位于 CollectionSelect.tsx其核心逻辑是useCollectionOptions第 27-55 行选项生成规则如下默认取当前数据源的全部数据表通过useCollectionManager_deprecated()拿到collections列表enum 约束若字段声明了dataSource则只保留 enum 中列出的数据表实现在指定范围内选择继承场景特判isTableOid当组件属性isTableOid为true时选项不是全量表列表而是通过useSelfAndChildrenCollections(targetCollection)取自身 子表继承体系中的子集对应多态/继承场景中记录来源于哪张表的语义过滤隐藏表hidden为true的数据表不会出现在选项中选项结构label取collection.title || label经过国际化编译useCompilevalue取collection.name同时携带color: item.category?.color用于按分类着色展示可搜索组件固定开启showSearchfilterOption同时按 label 和 value 做不区分大小写的包含匹配第 62-67 行表名多时可通过输入表名或中文名快速定位。渲染层基于 antd 的Select并用 Formily 的connect包装第 57-81 行因此它天然支持mode: multiple、disabled等标准 Select 属性。仓库中还提供了三个 Demo分别演示基础用法、多选与只读展示可直接参考 demos/basic.tsx、demos/multiple.tsx、demos/read-pretty.tsx相关行为由 collection-select.test.tsx 等测试用例覆盖。6. 只读展示与多选 TagCollectionSelect通过 Formily 的mapReadPretty注册了只读详情模式渲染第 82-106 行只读模式下组件会按当前值反查选项单选时匹配props.value option.value多选时匹配mode multiple且值数组包含该选项每个匹配到的数据表渲染为一个带分类颜色的Tag即详情页中已选择的数据表以彩色标签形式展示。同时在字段接口层面collection.ts的schemaInitialize中字段宽度默认100%当字段出现在 Table表格区块或 Kanban看板区块中时自动开启ellipsis省略号展示。这与文档中详情区块展示已选择的数据表的特性描述对应。7. 进阶组件跨数据源选表CollectionSelect.tsx同文件内还导出了两个配套组件用于更复杂的选表需求第 109-238 行DataSourceSelect选择数据源data source本身选项来自dataSourceManager.getDataSources()value 为数据源的keyDataSourceCollectionCascader级联选择数据源 → 数据表选项按dataSourceFilter/collectionFilter过滤隐藏表存储值的规则是主数据源只存集合名value[1]非主数据源存数据源key:集合名的拼接串见 第 228-236 行只读模式下按数据源 / 数据表路径回显。如果你的功能需要让用户从外部数据源而不仅是主库中选择数据表可以基于这两个组件实现而不是仅依赖主库的CollectionSelect。8. v2 前端CollectionSelectorFieldModel当前仓库同时维护新一代前端client-v2。在 flow 引擎的字段模型中CollectionSelectorFieldModel.tsx 通过EditableItemModel.bindModelToInterface(CollectionSelectorFieldModel, [collection, tableoid])将collection与tableoid两个字段接口统一绑定到同一个选择器模型第 98-100 行。其选项装载流程注册的collectionSelectFlow与 v1 逻辑一致但更直白第 52-96 行若字段是isTableOid继承场景则取目标表的子集合并合并collectionField.collection配置项作为选项否则取主数据源getCollections()先过滤hidden表再按字段上配置的uiSchema.enum或enum限定范围最后映射为{ label, value, color }。这说明无论新旧前端enum 约束可选项 隐藏表过滤 继承场景取子表三条行为是一致的跨版本迁移字段配置时预期表现相同。9. tableoid继承场景下的虚拟字段与数据表选择器密切相关的系统字段是tableoidTable OID。在 tableoid.ts 中TableoidFieldInterface将默认字段定义为name: __collection、type: virtual这是一个虚拟字段不额外落库uiSchema 中x-component: CollectionSelect、x-component-props: { isTableOid: true }、x-read-pretty: true复用的正是数据表选择器组件且开启继承语义选项为自身子表、默认只读展示。该字段用于在继承多态场景中标记一条记录实际来源于哪张表。如果你在插件中处理继承型数据表理解tableoid与collection接口共用CollectionSelect组件这一点能帮助你正确解读元数据。10. 编辑字段配置创建后点击字段右侧的「Edit」可以编辑数据表选择器字段配置。编辑字段主要用于调整字段在 NocoBase 中的展示和使用方式比如修改显示名称、说明、默认值、校验规则或字段专属配置。如果字段来自主数据库中已经同步的表编辑时通常是在做字段映射——把数据库字段映射为 NocoBase 的 Field type 和 Field interface。配置允许编辑说明Field display name是修改字段在界面中的显示名称不改变字段标识名称。Field name否字段标识名称创建后通常不能在编辑表单中修改。Field interface条件支持主数据库字段或同步字段在字段映射时可以调整。调整后会影响页面输入、展示和校验方式。Field type条件支持主数据库字段或同步字段在字段映射时可以调整。调整前需要确认已有数据能否按新类型使用。Default value是调整新增记录时的默认值。Validation rules是调整字段校验规则。Description是补充字段含义、填写要求、数据来源或维护人。注意切换 Field type 或 Field interface 不等于简单改一个显示名称。它会影响字段的存储方式、输入组件、校验规则、筛选条件和工作流变量使用方式。已有数据较多时先确认数据格式是否匹配。从源码看这一警告是有据可依的字段接口中sortable、filterable.operators、default.uiSchema决定输入组件与展示方式都是接口的组成部分切换接口即整体替换了这些行为见 collection.ts 与 tableoid.ts 中两个接口的差异。11. 删除字段点击字段右侧的「Delete」可以删除数据表选择器字段。主数据库中还可以勾选多个字段后批量删除。删除主数据库中新建的数据表选择器字段时通常会同时删除数据库中的真实列及该列已有数据。删除从数据库同步或外部数据源映射出的字段时影响范围取决于对应数据源和字段来源。警告删除字段可能影响页面区块、表单、筛选、权限、工作流、API、导入导出和已有数据。删除前先确认字段是否仍被业务配置引用。12. 页面配置使用数据表选择器适合在配置类表单中使用场景用途表单区块选择一个或多个数据表。详情区块展示已选择的数据表。插件配置指定功能作用的数据表范围。工作流或规则作为元数据配置参与逻辑。实操建议在表单区块中使用多选时为字段配置mode: multiple详情页将以多个彩色 Tag 展示已选数据表在表格/看板区块中展示时会自动省略号截断避免表名过长撑破列宽配合uiSchema.enum收窄可选项可以做出模板作用范围规则生效表这类受限选择器。13. 延伸阅读字段 — 了解字段的作用、分类和映射逻辑普通表 — 在普通表中创建和管理字段、了解 Collection 的使用方式关系字段 — 选择某张表中的记录服务端插件侧的字段接口参考实现plugin-mock-collections/field-interfaces掌握数据表选择器后你就具备了在 NocoBase 中构建可指向任意数据表的配置型字段的能力创建时正确命名与选型配置 enum 约束选项范围编辑时谨慎切换接口/类型删除前评估引用面并能通过CollectionSelect、tableoid与 v2CollectionSelectorFieldModel的源码快速定位选项来源与展示行为的异常。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考