字段类型

数据模型字段是数据源的表结构基础，可以理解为 Excel 表格的表头（列），而数据可以理解为 Excel 表格的行。CloudBase 数据模型支持丰富的字段类型，满足各种业务场景的数据存储需求。

字段类型概览

CloudBase 数据模型提供了 20+ 种字段类型，涵盖基础数据、格式化验证、媒体文件、内容编辑、时间位置、特殊功能等各个方面：

字段类型完整列表

字段类型	DB字段类型	使用说明	示例
文本/单行	string	适合标题、姓名等短文本（最长 4000 字节）	"张三"
文本/多行	string	适合描述、备注等长文本（最长 4000 字节）	"这是一段描述文字"
布尔值	boolean	true 或 false	true
数字	number	支持整数和浮点数	123456.78
数组	array	根据数组元素类型进行校验	["技术", "前端", "Vue"]
对象	object	嵌套的键值对结构	{"name": "张三", "age": 25}
JSON	object	复杂的数据结构或动态属性	{"title": "博客", "tags": ["技术"]}
邮箱	string	包含 xx\@yy.zz 格式验证	"email@qq.com"
电话/固定号码	string	0开头的2-3位区号或7-8位号码	"027-1234567"
电话/手机号码	string	符合手机号规范的11位字符串	"13812341234"
网址	string	符合网址规范的字符串	"https://example.com"
图片	string	默认从前端组件获得图片的 cloudId	"cloud://xxx.xxx.xxx.png"
多媒体/视频	string	支持 ogm、wmv、mpg、webm、ogv、mov、asx、mpeg、mp4、m4v、avi	"cloud://xxx.xxx.xxx/video.mp4"
多媒体/音频	string	支持 opus、flac、webm、weba、wav、ogg、m4a、oga、mid、mp3、aiff、wma、au	"cloud://xxx.xxx.xxx/audio.wav"
富文本	string	支持格式化、链接、图片（最长 262144 字节）	"<h1>标题</h1><p>内容</p>"
Markdown	string	支持 Markdown 编辑器和实时预览	"# 这是一个Markdown示例"
日期时间	number	默认从前端组件获取的时间戳(ms)，底层db文档型数据库、mysql数据库支持相应的日期时间属性，详见日期时间存储格式说明。	1645977600000
枚举	string	所填值必须为设置的枚举值中的某一个	"牛奶"
地理位置	object	固定格式的对象，包含地址和坐标	{"geopoint": {"type": "Point", "coordinates": [40.56, 5.89]}, "address": "深圳市南山区"}
文件	string	默认从前端组件获得文件的 cloudId	"cloud://xxx.xxx.xxx.pdf"
自动编号	string	用户不填则后端自动补齐；用户传参则使用客户定义的值	"1001"
地区	string	省级行政区划	"陕西省"
关联关系	string	支持一对一、一对多、多对一	存储关联记录的 ID

逻辑列（计算字段）说明

逻辑列是在数据模型中定义但不在物理数据库表中实际存储的字段。这些字段的值由后台服务实时计算得出，通常用于表示关联关系。

三种逻辑列类型：

1. 一对多关联

   • 描述：当前模型的一条记录关联到另一个模型的多条记录
   • 特点：物理表中不存在，通过LEFT JOIN查询获得
   • 示例：一个"班级"关联多个"学生"。在班级表中，一对多字段并不真实存在。

2. 多对多关联

   • 描述：当前模型的多条记录关联到另一个模型的多条记录
   • 特点：物理表中不存在，通过中间表和LEFT JOIN查询获得
   • 示例："学生"与"课程"之间的选课关系。在学生表和课程表中，多对多字段并不真实存在。

3. 一对一反向关联

   • 描述：一对多关系的特例，通过唯一索引约束实现一对一
   • 特点：物理表中不存在，通过LEFT JOIN查询获得
   • 示例："学生证"与"学生"的一对一关系。 在学生证表中，一对一反向关联字段并不真实存在。

日期时间存储格式说明

DB类型	日期时间格式	日期时间存储类型	日期时间存储类型说明	日期时间DB存储示例
文档型数据库	日期时间	datetime	使用date类型存储	Tue Sep 23 2025 00:00:00 GMT+0800 (中国标准时间)
		number	使用number类型存储	1758560400000
	日期	number	只支持number格式	1758556800000
	时间	number	只支持number格式	3600000
Mysql数据库	日期时间	datetime	使用datetime类型存储	2025-09-23 00:00:00
		timestamp	使用timestamp类型存储	2025-09-23 02:00:00
		number	使用bigint类型存储	1758560400000
	日期	date	使用date类型存储	2025-09-23
		number	使用number类型存储	1758556800000
	时间	time	使用time类型存储	01:00:00
		number	使用number类型存储	3600000

自动编号格式说明

自动编号支持三种格式类型：

1. 字符串前缀：{前缀}-{SEQNUM:最小位数+起始值}

   • 示例：CAR-1000, CAR-1001, CAR-1002

2. 日期前缀：{DATETIMEUTC:日期格式}-{SEQNUM:最小位数+起始值}

   • 示例：2024-01-15-0001, 2024-01-15-0002

3. 自定义格式：支持多种格式组合

   • {SEQNUM:4} - 连续数字：0001, 0002
   • {DATETIMEUTC:yyyy-MM-dd} - 时间日期：2024-01-15
   • {RANDSTRING:4} - 随机字符串：AB7L

字段通用配置

基础配置项

配置项	说明	规则
字段名称	字段的显示名称	支持中英文
字段标识	字段的唯一标识符	不能为空，不能以数字开头，只能包含字母、数字或_
数据类型	字段的数据类型	从支持的字段类型中选择
是否必填	该字段是否为必填项	影响数据校验
是否唯一	该字段的取值是否允许重复	设置为唯一则不允许填重复值

主展示列配置

适用条件：数据类型为文本时可选择

功能说明：当其他数据模型配置关联关系指向本模型时，该字段会作为主展示列显示，方便用户查看

配置影响：

• ✅ 影响展示效果：在关联选择时显示该字段的值
• ❌ 不影响存储：实际存储的仍然是关联记录的 ID

主展示列最佳实践

• 选择具有业务意义的字段作为主展示列（如"产品名称"而非"产品ID"）
• 保持主展示列值的唯一性和可读性，建议设置为唯一字段
• 避免使用过长的文本作为主展示列

主展示列使用示例

以学生和课程模型为例：

学生模型配置：

{
  "name": "张三",
  "course": "93e4b6a0640e9139042f27941b0ab7e6"  // 存储课程ID
}

课程模型配置：

• 课程名称字段设置为主展示列

查询结果：

{
  "records": [{
    "name": "张三",
    "course": "93e4b6a0640e9139042f27941b0ab7e6",
    "@course": {
      "v1": {
        "primaryColumn": "courseName",  // 主展示列标识
        "record": {
          "courseName": "语文",  // 主展示列的值
          "_id": "93e4b6a0640e9139042f27941b0ab7e6"
        }
      }
    }
  }]
}

表单组件中的效果：

• 下拉选择显示：语文（主展示列值）
• 实际提交数据：93e4b6a0640e9139042f27941b0ab7e6（ID值）