10 KiB
Field
概览
数据表字段管理类（抽象类）。同时是所有字段类型的基类，其他任意字段类型均通过继承该类来实现。
如何自定义字段可参考扩展字段类型
构造函数
通常不会直接由开发者调用，主要通过 db.collection({ fields: [] }) 方法作为代理入口调用。
在扩展字段时主要通过继承 Field 抽象类，再注册到 Database 实例中来实现。
签名
constructor(options: FieldOptions, context: FieldContext)
参数
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
options |
FieldOptions |
- | 字段配置对象 |
options.name |
string |
- | 字段名称 |
options.type |
string |
- | 字段类型，对应在 db 中注册的字段类型名称 |
context |
FieldContext |
- | 字段上下文对象 |
context.database |
Database |
- | 数据库实例 |
context.collection |
Collection |
- | 数据表实例 |
实例成员
name
字段名称。
type
字段类型。
dataType
字段数据库存储类型。
options
字段初始化配置参数。
context
字段上下文对象。
配置方法
on()
基于数据表事件的快捷定义方式。相当于 db.on(this.collection.name + '.' + eventName, listener)。
继承时通常无需覆盖此方法。
签名
on(eventName: string, listener: (...args: any[]) => void)
参数
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
eventName |
string |
- | 事件名称 |
listener |
(...args: any[]) => void |
- | 事件监听器 |
off()
基于数据表事件的快捷移除方式。相当于 db.off(this.collection.name + '.' + eventName, listener)。
继承时通常无需覆盖此方法。
签名
off(eventName: string, listener: (...args: any[]) => void)
参数
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
eventName |
string |
- | 事件名称 |
listener |
(...args: any[]) => void |
- | 事件监听器 |
bind()
当字段被添加到数据表时触发的执行内容。通常用于添加数据表事件监听器和其他处理。
继承时需要先调用对应的 super.bind() 方法。
签名
bind()
unbind()
当字段从数据表中移除时触发的执行内容。通常用于移除数据表事件监听器和其他处理。
继承时需要先调用对应的 super.unbind() 方法。
签名
unbind()
get()
获取字段的配置项的值。
签名
get(key: string): any
参数
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
key |
string |
- | 配置项名称 |
示例
const field = db.collection('users').getField('name');
// 获取字段名称配置项的值，返回 'name'
console.log(field.get('name'));
merge()
合并字段的配置项的值。
签名
merge(options: { [key: string]: any }): void
参数
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
options |
{ [key: string]: any } |
- | 要合并的配置项对象 |
示例
const field = db.collection('users').getField('name');
field.merge({
// 添加一个索引配置
index: true
});
remove()
从数据表中移除字段（仅从内存中移除）。
示例
const books = db.getCollections('books');
books.getField('isbn').remove();
// really remove from db
await books.sync();
数据库方法
removeFromDb()
从数据库中移除字段。
签名
removeFromDb(options?: Transactionable): Promise<void>
参数
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
options.transaction? |
Transaction |
- | 事务实例 |
existsInDb()
判断字段是否存在于数据库中。
签名
existsInDb(options?: Transactionable): Promise<boolean>
参数
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
options.transaction? |
Transaction |
- | 事务实例 |
内置字段类型列表
NocoBase 内置了一些常用的字段类型，可以直接在定义数据表的字段是使用对应的 type 名称来指定类型。不同类型的字段参数配置不同，具体可参考下面的列表。
所有字段类型的配置项除了以下额外介绍的以外，都会透传至 Sequelize，所以所有 Sequelize 支持的字段配置项都可以在这里使用（如 allowNull、defaultValue 等）。
另外 server 端的字段类型主要解决数据库存储和部分算法的问题，与前端的字段展示类型和使用组件基本无关。前端字段类型可以参考教程对应说明。
'boolean'
逻辑值类型。
示例
db.collection({
name: 'books',
fields: [
{
type: 'boolean',
name: 'published'
}
]
});
'integer'
整型（32 位）。
示例
db.collection({
name: 'books',
fields: [
{
type: 'integer',
name: 'pages'
}
]
});
'bigInt'
长整型（64 位）。
示例
db.collection({
name: 'books',
fields: [
{
type: 'bigInt',
name: 'words'
}
]
});
'double'
双精度浮点型（64 位）。
示例
db.collection({
name: 'books',
fields: [
{
type: 'double',
name: 'price'
}
]
});
'real'
实数类型（仅 PG 适用）。
'decimal'
十进制小数类型。
'string'
字符串类型。相当于大部分数据库的 VARCHAR 类型。
示例
db.collection({
name: 'books',
fields: [
{
type: 'string',
name: 'title'
}
]
});
'text'
文本类型。相当于大部分数据库的 TEXT 类型。
示例
db.collection({
name: 'books',
fields: [
{
type: 'text',
name: 'content'
}
]
});
'password'
密码类型（NocoBase 扩展）。基于 Node.js 原生的 crypto 包的 scrypt 方法进行密码加密。
示例
db.collection({
name: 'users',
fields: [
{
type: 'password',
name: 'password',
length: 64, // 长度，默认 64
randomBytesSize: 8 // 随机字节长度，默认 8
}
]
});
参数
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
length |
number |
64 | 字符长度 |
randomBytesSize |
number |
8 | 随机字节大小 |
'date'
日期类型。
'time'
时间类型。
'array'
数组类型（仅 PG 适用）。
'json'
JSON 类型。
'jsonb'
JSONB 类型（仅 PG 适用，其他会被兼容为 'json' 类型）。
'uuid'
UUID 类型。
'uid'
UID 类型（NocoBase 扩展）。短随机字符串标识符类型。
'formula'
公式类型（NocoBase 扩展）。可配置基于 mathjs 的数学公式计算，公式中可以引用同一条记录中其他列的数值参与计算。
示例
db.collection({
name: 'orders',
fields: [
{
type: 'double',
name: 'price'
},
{
type: 'integer',
name: 'quantity'
},
{
type: 'formula',
name: 'total',
expression: 'price * quantity'
}
]
});
'radio'
单选类型（NocoBase 扩展）。全表最多有一行数据的该字段值为 true，其他都为 false 或 null。
示例
整个系统只有一个被标记为 root 的用户，任意另一个用户的 root 值被改为 true 之后，其他所有 root 为 true 的记录均会被修改为 false：
db.collection({
name: 'users',
fields: [
{
type: 'radio',
name: 'root',
}
]
});
'sort'
排序类型（NocoBase 扩展）。基于整型数字进行排序，为新记录自动生成新序号，当移动数据时进行序号重排。
数据表如果定义了 sortable 选项，也会自动生成对应字段。
示例
文章基于所属用户可排序：
db.collection({
name: 'posts',
fields: [
{
type: 'belongsTo',
name: 'user',
},
{
type: 'sort',
name: 'priority',
scopeKey: 'userId' // 以 userId 相同值分组的数据进行排序
}
]
});
'virtual'
虚拟类型。不实际储存数据，仅用于特殊 getter/setter 定义时使用。
'belongsTo'
多对一关联类型。外键储存在自身表，与 hasOne/hasMany 相对。
示例
任意文章属于某个作者：
db.collection({
name: 'posts',
fields: [
{
type: 'belongsTo',
name: 'author',
target: 'users', // 不配置默认为 name 复数名称的表名
foreignKey: 'authorId', // 不配置默认为 <name> + Id 的格式
sourceKey: 'id' // 不配置默认为 target 表的 id
}
]
});
'hasOne'
一对一关联类型。外键储存在关联表，与 belongsTo 相对。
示例
任意用户都有一份个人资料：
db.collection({
name: 'users',
fields: [
{
type: 'hasOne',
name: 'profile',
target: 'profiles', // 可省略
}
]
})
'hasMany'
一对多关联类型。外键储存在关联表，与 belongsTo 相对。
示例
任意用户可以拥有多篇文章：
db.collection({
name: 'users',
fields: [
{
type: 'hasMany',
name: 'posts',
foreignKey: 'authorId',
sourceKey: 'id'
}
]
});
'belongsToMany'
多对多关联类型。使用中间表储存双方外键，如不指定已存在的表为中间表的话，将会自动创建中间表。
示例
任意文章可以加任意多个标签，任意标签也可以被任意多篇文章添加：
db.collection({
name: 'posts',
fields: [
{
type: 'belongsToMany',
name: 'tags',
target: 'tags', // 同名可省略
through: 'postsTags', // 中间表不配置将自动生成
foreignKey: 'postId', // 自身表在中间表的外键
sourceKey: 'id', // 自身表的主键
otherKey: 'tagId' // 关联表在中间表的外键
}
]
});
db.collection({
name: 'tags',
fields: [
{
type: 'belongsToMany',
name: 'posts',
through: 'postsTags', // 同一组关系指向同一张中间表
}
]
});