跳到主要内容

实体属性

属性定义描述的是“这一列存什么、能不能空、是否唯一、有没有默认值、数据库列名叫什么”。

import { Entity, EntityBase, PropertyType } from '@aiao/rxdb';

@Entity({
  name: 'Product',
  displayName: '商品',
  properties: [
    {
      name: 'title',
      type: PropertyType.string,
      displayName: '标题',
      required: true,
      sortable: true
    },
    {
      name: 'status',
      type: PropertyType.enum,
      enum: ['draft', 'published', 'archived'],
      default: 'draft'
    },
    {
      name: 'productName',
      columnName: 'product_name',
      type: PropertyType.string,
      displayName: '数据库蛇形列名示例'
    }
  ]
})
export class Product extends EntityBase {}

EntityBase 自动提供的字段​

继承 EntityBase 后，无需重复声明这些字段：

  • id：uuid 主键，默认自动生成
  • createdAt：date，默认 () => new Date()
  • updatedAt：date，默认 () => new Date()
  • createdBy：可空字符串
  • updatedBy：可空字符串

支持的属性类型​

类型说明关键补充
uuidUUID 字符串可设 primary: true
string字符串可设 primary: true
enum枚举字符串必须额外提供 enum: readonly string[]
number数字支持默认值
integer整数可设 primary: true
boolean布尔值支持默认值
date日期默认值可写 Date、() => Date 或 CURRENT_TIMESTAMP
stringArray字符串数组适合标签等场景
numberArray数字数组适合简单数值集合
keyValue扁平键值对象不支持嵌套，不支持数组
json任意 JSON支持嵌套对象和数组，默认不用于结构化搜索

通用属性选项​

这些选项来自当前代码中的 IEntityObject、ISortable 和具体属性类型定义：

选项说明
name字段名，运行时属性名
columnName数据库列名，不写时默认等于 name
displayName展示名
unique唯一约束，单字段唯一时优先用它
readonly更新时忽略该字段
nullable数据库层允许 NULL
required前端校验层必填，不等于数据库 NOT NULL
sortable查询层允许排序
default默认值，支持常量或函数
primary仅部分类型支持，标记主键

required 和 nullable 的区别​

  • required: true：偏向表单/输入校验，空字符串、空数组也会被视为无效
  • nullable: false：偏向存储约束，表示数据库列不允许为 NULL

这两个选项可以同时使用，也可以只使用其中之一，不应将二者混用。

常见写法​

1. 数据库列名与代码字段名分离​

{
  name: 'productName',
  columnName: 'product_name',
  type: PropertyType.string,
  displayName: '商品名称'
}

2. 枚举字段​

{
  name: 'status',
  type: PropertyType.enum,
  enum: ['draft', 'published', 'archived'],
  default: 'draft'
}

3. 函数默认值​

{
  name: 'publishedAt',
  type: PropertyType.date,
  nullable: true,
  default: () => new Date()
}

4. keyValue 类型​

keyValue 是“扁平键值对象”，内部键需要单独声明结构：

{
  name: 'attrs',
  type: PropertyType.keyValue,
  properties: [
    { name: 'brand', type: PropertyType.string, required: true },
    { name: 'weight', type: PropertyType.number },
    { name: 'fragile', type: PropertyType.boolean, default: false }
  ]
}

如果你需要嵌套对象、数组或更自由的结构，应该改用 json。

计算属性​

当前代码还支持 computedProperties。这类字段：

  • 只读
  • 不直接落库
  • 由特性或运行时逻辑提供

树结构基类里的 hasChildren 就是一个真实例子。

computedProperties: [
  {
    name: 'hasChildren',
    type: PropertyType.boolean,
    readonly: true,
    nullable: true
  }
];

建议​

  • 单字段唯一直接用 unique: true
  • 需要兼容旧库列名时使用 columnName
  • 动态结构优先区分 keyValue 和 json，不要混用
  • 需要排序的字段再开启 sortable