NocoBase 邮箱（Email）字段详解：字段定义、格式校验与源码实现

NocoBase 邮箱（Email）字段详解：字段定义、格式校验与源码实现

【免费下载链接】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 中，邮箱（Email）字段用于在数据表中保存邮箱地址，并以string类型存储、以email界面类型渲染，同时内置邮箱格式校验。本文基于 NocoBase 官方文档与仓库源码，完整讲解邮箱字段的创建配置、字段特性、编辑与删除方式、页面配置用法，并结合 邮箱字段接口实现 剖析其默认值、校验选项与筛选操作符的底层来源，帮助你在建模时准确使用邮箱字段并理解其行为边界。

一、邮箱字段是什么，适合哪些场景

NocoBase 中的邮箱字段用于保存邮箱地址。它适合客户邮箱、员工邮箱、供应商邮箱等联系方式。与普通单行文本（单行文本字段）相比，邮箱字段提供更明确的邮箱语义和格式校验：页面录入时会自动按邮箱格式校验输入内容，而单行文本只保存普通短文本、不做邮箱格式约束。

如果内容不是邮箱地址，只是普通联系人信息，选择单行文本更合适。

邮箱字段适合这些业务场景：

• 客户邮箱、联系人邮箱；
• 员工邮箱、登录联系邮箱；
• 供应商邮箱、服务邮箱；
• 通知收件地址。

从源码结构看，邮箱字段在字段接口注册中被归类为basic（基础类型），排序值为 4，因此它会出现在「Configure fields」页面基础字段分组的前列位置，具体注册逻辑见 EmailFieldInterface 类。

二、创建邮箱字段与配置项说明

在数据表的「Configure fields」页面中，点击「Add field」，选择「邮箱」即可创建邮箱字段。

创建表单中的核心配置项如下：

这些配置项并非凭空而来，它们在客户端字段配置表单中有明确的 schema 定义：

• Field display name 与 Field name由defaultProps统一定义（字段属性 schema）：uiSchema.title对应显示名称且必填；name对应字段标识，使用uid校验器约束命名规则（字母、数字、下划线，且必须以字母开头），并通过'x-disabled': '{{ !createOnly }}'实现「创建后可修改、创建后不可修改」——即字段创建完成后 Field name 在编辑表单中锁定。
• 默认值能力：EmailFieldInterface中声明hasDefaultValue = true（email.ts），因此创建表单才会展示 Default value 配置。
• 唯一值（Unique）：邮箱字段的properties在defaultProps之外额外引入了unique属性（email.ts），其定义见 unique 属性。勾选后会在数据库层面约束邮箱值唯一，适合保证一个客户只登记一个邮箱等场景；该选项仅在创建主数据库字段时可用。

注意：字段名创建后会被页面区块、权限、工作流和 API 引用。创建前先确认命名，避免后续修改带来配置调整成本。

三、字段特性：从源码看邮箱字段的默认行为

邮箱字段的默认行为在 EmailFieldInterface 中一次性声明，逐项对应如下：

几个值得展开的细节：

1. 录入组件与格式校验的联动

邮箱字段的default配置（email.ts）为：

default = { type: 'string', uiSchema: { type: 'string', 'x-component': 'Input', 'x-validator': 'email', }, };

也就是说，创建邮箱字段时，NocoBase 会同时生成两部分定义：数据层类型string（决定数据库列类型），以及 UI schema（决定页面组件）。'x-validator': 'email'会把 Formily 的邮箱校验器挂到该字段上，用户在表单中输入abc@这类不合法内容时会被直接拦截，无需额外配置 Validation rules。

2. 可选校验规则

邮箱字段声明的可用校验选项为：

availableValidationOptions = ['min', 'max', 'length', 'email', 'pattern'];

在 FieldValidation 组件 中，availableValidationOptions会与全局的FIELDS_VALIDATION_OPTIONS中string类型的校验选项做交集（交集逻辑见 constants.ts 定义的选项表），最终在 Validation rules 配置区只呈现这五类规则：

• min / max：字符串长度下限/上限；
• length：固定长度；
• email：邮箱格式校验；
• pattern：正则表达式自定义匹配，例如强制要求@company.com结尾的邮箱。

相比之下，单行文本字段的可选规则是['min', 'max', 'length', 'pattern']（input.ts），不包含email——这正是两者在配置面板上最直观的差异。

3. 筛选操作符

邮箱字段声明filterable = { operators: operators.string }，而 operators.string 定义为：

因此，在筛选区块或筛选操作（Filter action）中，邮箱字段默认展示「包含」操作符，可以按@domain.com等片段批量筛选记录。

4. 表格与看板中的省略号展示

EmailFieldInterface的schemaInitialize方法（email.ts）会在字段渲染进Table或Kanban区块时自动注入x-component-props.ellipsis = true。也就是说，邮箱这类可能较长的字符串在表格列和看板卡片中默认以省略号截断，无需手动配置列宽展示。

四、编辑邮箱字段配置

创建后，点击字段右侧的「Edit」可以编辑邮箱字段配置。编辑字段主要用于调整字段在 NocoBase 中的展示和使用方式，比如修改显示名称、说明、默认值、校验规则或字段专属配置。

如果字段来自主数据库中已经同步的表，编辑时通常是在做字段映射——把数据库字段映射为 NocoBase 的 Field type 和 Field interface。

注意：切换 Field type 或 Field interface 不等于简单改一个显示名称。它会影响字段的存储方式、输入组件、校验规则、筛选条件和工作流变量使用方式。已有数据较多时，先确认数据格式是否匹配。从源码看，Field interface 决定default.uiSchema（录入组件与校验器），Field type 决定数据库列类型（availableTypes = ['string']限定了邮箱字段只能落在string存储类型上），两者共同构成字段在页面和 API 中的完整行为。

五、删除邮箱字段

点击字段右侧的「Delete」可以删除邮箱字段。主数据库中还可以勾选多个字段后批量删除。

删除主数据库中新建的邮箱字段时，通常会同时删除数据库中的真实列及该列已有数据。删除从数据库同步或外部数据源映射出的字段时，影响范围取决于对应数据源和字段来源。

警告：删除字段可能影响页面区块、表单、筛选、权限、工作流、API、导入导出和已有数据。删除前先确认字段是否仍被业务配置引用。

六、页面配置使用

邮箱字段适合在表单、详情和通知流程中使用，典型用法包括：

由于邮箱字段titleUsable = true，它还可以被用作记录的标题字段，在表格首列以标题形式展示邮箱。

七、与其他字段的选型对比

• 内容只是普通短文本、不做格式约束：选单行文本；
• 保存联系电话：选手机号；
• 保存邮箱地址并需要格式语义：选本文的邮箱字段。

相关链接

• 字段 — 了解字段的作用、分类和映射逻辑
• 普通表 — 在普通表中创建和管理字段
• 单行文本 — 保存普通短文本
• 手机号 — 保存联系电话
• 邮箱字段接口源码 —EmailFieldInterface的完整定义
• 字符串筛选操作符 — 邮箱字段筛选操作符的定义

【免费下载链接】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