NocoBase 手机号（Phone）字段：创建、配置与源码实现解析

NocoBase 手机号Phone字段创建、配置与源码实现解析【免费下载链接】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本篇技术指南围绕 NocoBase 数据建模中的手机号Phone字段展开从「Configure fields」页面的创建与配置、字段特性、编辑/删除规则到页面区块中的实际用法并结合开源仓库中PhoneFieldInterface的源码实现讲清该字段的数据类型、可用校验项、筛选算子与默认组件的来龙去脉。读完后你不仅能按步骤建好一个符合业务规范的手机号字段还能从源码层面理解它的默认行为边界例如电话格式校验默认并未强制开启从而做出更可靠的字段设计决策。1. 什么是手机号字段在 NocoBase 中手机号Phone字段用于保存手机号或联系电话。它适合客户电话、联系人电话、员工手机号等联系方式场景比普通单行文本更能表达「电话类数据」的语义字段界面类型为phone编辑态使用带type: tel的输入框录入并在筛选、排序、校验等方面按文本类字段统一处理。如果业务需要保存多个电话或更复杂的联系信息建议改用多行文本或单独建立联系人表而不是把多个号码硬塞进一个手机号字段。2. 适用场景手机号字段适合的业务场景包括客户手机号、联系人电话员工手机号、备用电话门店联系电话、服务热线短信通知号码这类场景的共同特征是数据本质是「单条电话号码文本」需要可录入、可筛选、可参与工作流与通知。凡涉及多号码、分机号、备注等复合结构则不适合用单个 phone 字段承载。3. 源码实现PhoneFieldInterface 决定了字段的默认行为手机号字段的前端行为由字段界面类PhoneFieldInterface定义仓库中在 client 与 client-v2 两套前端中均有同名实现二者属性一致参见 phone.tsexport class PhoneFieldInterface extends CollectionFieldInterface { name phone; type object; group basic; order 3; title {{t(Phone)}}; sortable true; default { type: string, uiSchema: { type: string, x-component: Input, x-component-props: { type: tel, }, // x-validator: phone, }, }; availableTypes [string]; validationType string; availableValidationOptions [min, max, length, pattern]; hasDefaultValue true; properties { ...defaultProps, unique, }; filterable { operators: operators.string, }; titleUsable true; }从这份源码可以确认文档中「字段特性」表格每一条结论的实现依据特性源码依据默认 Field interface 为phonename phone通过 interfaces/index.ts 中的export * from ./phone注册到字段界面列表默认 Field type 为stringdefault.type string可选 Field type 仅stringavailableTypes [string]界面类型下拉中只会列出这一种存储类型编辑模式使用输入框并可配置电话格式校验uiSchema指定x-component: Input且x-component-props.type: tel让移动端键盘按电话键盘呈现支持文本类筛选filterable.operators operators.string即包含、等于、为空、不为空等文本算子支持表格排序sortable true支持长度、正则、必填等校验availableValidationOptions [min, max, length, pattern]且validationType string支持设置默认值hasDefaultValue true可作为列表标题字段titleUsable true可在列表/表格区块中将其设为标题列两点值得特别注意格式校验默认未强制开启。源码第 28 行// x-validator: phone,处于注释状态说明创建 phone 字段时默认并不会自动套用电话号码正则校验。若业务上必须保证号码格式需要显式在 Validation rules 中配置pattern正则表达式规则而不是依赖字段类型自带的行为。unique约束是 phone 字段的专属配置项。properties在通用属性defaultProps之外追加了unique其定义见 properties/index.ts——这是一个布尔开关勾选后字段值唯一且与primaryKey存在联动当字段被设为主键时唯一约束自动关闭主键天然唯一。这为「手机号不可重复登记」这类业务规则提供了字段级保障。defaultProps中同时定义了文档提到的两个基础配置项显示名称uiSchema.title必填与字段标识名称name带uid校验器仅允许字母、数字、下划线且以字母开头编辑态禁用export const defaultProps { uiSchema.title: { type: string, title: {{t(Field display name)}}, required: true, ... }, name: { type: string, title: {{t(Field name)}}, required: true, x-disabled: {{ !createOnly }}, x-validator: uid, description: {{t(Randomly generated and can be modified. Support letters, numbers and underscores, must start with a letter.)}}, }, };这与文档中「Field name 只支持字母、数字和下划线并且必须以字母开头」的说明完全一致。4. 创建手机号字段在数据表的「Configure fields」页面中点击「Add field」在基础basic分组下选择「手机号」即可创建。源码中group basic、order 3决定了它出现在字段界面列表基础分组的排序位置。创建表单中的配置项说明配置说明Field interface字段的界面类型。手机号对应phone决定页面中如何录入和展示。Field display name字段在界面中显示的名称比如「手机号」「联系电话」「服务热线」。建议使用业务人员能直接理解的名称。Field name字段标识名称用于 API、关系字段、权限、工作流等内部引用。创建后通常不再修改只支持字母、数字和下划线并且必须以字母开头源码中由uid校验器保证。Field type字段在数据层的类型。手机号字段默认是string且availableTypes仅此一种。Default value默认值。新增记录时如果用户没有填写可以自动带出默认值hasDefaultValue true。Validation rules校验规则。可配置min、max、length、pattern长度/正则类规则以及必填如需强制电话格式请在此配置正则表达式。Description字段说明。适合写字段含义、填写要求、数据来源或维护人。注意字段名创建后会被页面区块、权限、工作流和 API 引用。创建前先确认命名避免后续修改带来配置调整成本。5. 字段特性一览手机号字段的默认行为汇总如下实现依据见第 3 节源码表特性说明默认 Field interfacephone。默认 Field typestring。可选 Field typestring。页面组件编辑模式使用输入框并可配置电话格式校验。筛选支持文本类筛选比如包含、等于、为空、不为空。排序支持在表格区块中排序。校验支持长度、正则表达式、必填等校验。6. 编辑字段配置创建后点击字段右侧的「Edit」可以编辑手机号字段配置。编辑字段主要用于调整字段在 NocoBase 中的展示和使用方式比如修改显示名称、说明、默认值、校验规则或字段专属配置。如果字段来自主数据库中已经同步的表编辑时通常是在做字段映射——把数据库字段映射为 NocoBase 的 Field type 和 Field interface。配置允许编辑说明Field display name是修改字段在界面中的显示名称不改变字段标识名称。Field name否字段标识名称创建后通常不能在编辑表单中修改源码中name项带x-disabled: {{ !createOnly }}即仅创建时可用。Field interface条件支持主数据库字段或同步字段在字段映射时可以调整。调整后会影响页面输入、展示和校验方式。Field type条件支持主数据库字段或同步字段在字段映射时可以调整。调整前需要确认已有数据能否按新类型使用。Default value是调整新增记录时的默认值。Validation rules是调整字段校验规则。Description是补充字段含义、填写要求、数据来源或维护人。注意切换 Field type 或 Field interface 不等于简单改一个显示名称。它会影响字段的存储方式、输入组件、校验规则、筛选条件和工作流变量使用方式。已有数据较多时先确认数据格式是否匹配。7. 删除字段点击字段右侧的「Delete」可以删除手机号字段。主数据库中还可以勾选多个字段后批量删除。删除主数据库中新建的手机号字段时通常会同时删除数据库中的真实列及该列已有数据。删除从数据库同步或外部数据源映射出的字段时影响范围取决于对应数据源和字段来源。警告删除字段可能影响页面区块、表单、筛选、权限、工作流、API、导入导出和已有数据。删除前先确认字段是否仍被业务配置引用。8. 页面配置使用手机号字段适合在表单、详情、筛选和通知场景中使用场景用途表单区块录入手机号或联系电话。详情区块展示联系方式。筛选区块按手机号或号码片段筛选记录底层使用operators.string文本算子。工作流和通知作为短信、电话类通知的号码来源。系统自身也把该类型当作真实使用场景用户插件通过迁移创建了users表的 phone 字段见 add-users-phone 迁移其客户端用户资料表单 schema 也直接引用该字段见 users.ts可以推断账号体系中「手机号」作为phone类型字段已参与登录、验证等核心链路。9. 与相邻文本类字段的选型对照需要保存邮箱地址时选择邮箱字段邮箱只是普通短文本、无电话语义时选择单行文本需要多行、多号码等复杂联系信息时使用多行文本或独立联系人表。10. 延伸阅读字段 — 了解字段的作用、分类和映射逻辑普通表 — 在普通表中创建和管理字段字段界面源码目录 — 查看PhoneFieldInterface及同类字段界面的注册与实现【免费下载链接】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），仅供参考