Back to Details

object-fields

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Steedos Object Fields | Steedos 对象字段

Steedos 对象字段

Overview | 概述

概述

Fields define how data is stored, validated, and displayed. Each field is defined as a separate 
.field.yml
file in the object's 
fields/
subfolder.
字段定义数据的存储、验证和显示方式。每个字段作为独立的 
.field.yml
文件定义在对象的 
fields/
子文件夹中。
字段定义数据的存储、验证和显示方式。每个字段作为独立的 
.field.yml
文件定义在对象的 
fields/
子文件夹中。

File Location | 文件位置

文件位置

steedos-packages/
└── my-package/
    └── main/default/
        └── objects/
            └── orders/
                └── fields/
                    ├── order_number.field.yml
                    ├── customer.field.yml
                    ├── status.field.yml
                    ├── total_amount.field.yml
                    └── shipping_address.field.yml
steedos-packages/
└── my-package/
    └── main/default/
        └── objects/
            └── orders/
                └── fields/
                    ├── order_number.field.yml
                    ├── customer.field.yml
                    ├── status.field.yml
                    ├── total_amount.field.yml
                    └── shipping_address.field.yml

Field Structure | 字段结构

字段结构

yaml
undefined
yaml
undefined

objects/orders/fields/customer.field.yml

objects/orders/fields/customer.field.yml

name: customer type: lookup label: 客户 reference_to: customers required: true index: true searchable: true filterable: true sortable: true sort_no: 200 group: Basic Information
undefined
name: customer type: lookup label: 客户 reference_to: customers required: true index: true searchable: true filterable: true sortable: true sort_no: 200 group: Basic Information
undefined

Common Properties | 通用属性

通用属性

PropertyTypeDescription
name
stringField API name (required)
type
stringField type (required, see Valid Field Types below)
label
stringDisplay label — use the language of the user's prompt (required)
required
booleanIs required
readonly
booleanRead-only
hidden
booleanHide from all UI
omit
booleanOmit from forms
disabled
booleanDisable editing
defaultValue
anyDefault value
group
stringField group name
sort_no
numberDisplay order
is_name
booleanMark as the object's display name field (see below)
is_wide
booleanFull width in forms
index
booleanCreate database index
unique
booleanUnique constraint
searchable
booleanInclude in global search
filterable
booleanAvailable in filters
sortable
booleanSortable in list views
data_type
stringBackend data type
visible_on
stringAmis formula for conditional visibility
inlineHelpText
stringTooltip help text
属性类型描述
name
string字段API名称（必填）
type
string字段类型（必填，详见下方有效字段类型）
label
string显示标签——使用用户界面的语言（必填）
required
boolean是否必填
readonly
boolean是否只读
hidden
boolean是否在所有UI中隐藏
omit
boolean是否在表单中省略
disabled
boolean是否禁用编辑
defaultValue
any默认值
group
string字段分组名称
sort_no
number显示顺序
is_name
boolean标记为对象的显示名称字段（详见下文）
is_wide
boolean在表单中占满宽度
index
boolean是否创建数据库索引
unique
boolean是否唯一约束
searchable
boolean是否纳入全局搜索
filterable
boolean是否可用于筛选
sortable
boolean是否可在列表视图中排序
data_type
string后端数据类型
visible_on
string控制条件可见性的Amis公式
inlineHelpText
string提示框帮助文本

Name Field (
is_name
) | 名称字段

名称字段（
is_name
）

Every object must have a name field — the human-readable identifier shown in lookups, related lists, and record titles. The system determines the name field by:
每个对象必须有一个名称字段——在查找、相关列表和记录标题中显示的人类可读标识。系统按以下优先级确定名称字段：
  1. A field with 
    is_name: true
    (highest priority)
  2. A field named 
    name
    (fallback)
Use 
is_name: true
when the display name is not a simple 
name
text field:
当显示名称不是简单的 
name
文本字段时，使用 
is_name: true
：
yaml
undefined
每个对象必须有一个名称字段——在查找、相关列表和记录标题中显示的人类可读标识。系统按以下优先级确定名称字段：
  1. 设置了
    is_name: true
    的字段（优先级最高）
  2. 名为
    name
    的字段（备选）
当显示名称不是简单的
name
文本字段时，使用
is_name: true
：
yaml
undefined

autonumber as name field

自动编号作为名称字段

name: order_number type: autonumber label: Order Number formula: 'ORD-{YYYY}{MM}{DD}-{0000}' is_name: true readonly: true
name: order_number type: autonumber label: Order Number formula: 'ORD-{YYYY}{MM}{DD}-{0000}' is_name: true readonly: true

lookup as name field

查找字段作为名称字段

name: permission_set type: master_detail label: Permission Set reference_to: permission_set required: true is_name: true
name: permission_set type: master_detail label: Permission Set reference_to: permission_set required: true is_name: true

simple text name field (is_name not needed)

简单文本名称字段（无需设置is_name）

name: name type: text label: Product Name required: true searchable: true
undefined
name: name type: text label: Product Name required: true searchable: true
undefined

Valid Field Types | 有效字段类型

有效字段类型

⚠️ CRITICAL: The 
type
property MUST be one of the values listed below. NEVER invent field types. Any value NOT in this list will cause an error.
⚠️ 重要：
type
属性必须为下表中的值之一，严禁自行编造字段类型。不在此列表中的值会导致错误。
TypeDescription
text
Short text
textarea
Long text (multiline)
html
Rich text (HTML editor)
select
Single or multiple choice (with 
options
)
boolean
True/false
toggle
Toggle switch (same as boolean, different UI)
date
Date only
datetime
Date and time
time
Time only
number
Integer or decimal
currency
Money amount
percent
Percentage
autonumber
Auto-generated sequential number
lookup
Reference to another object (many-to-one)
master_detail
Parent-child reference (cascade delete)
grid
Inline table (array of objects)
url
URL
email
Email address
image
Image upload
file
File upload
code
Code editor
markdown
Markdown editor
color
Color picker
location
Geographic location
object
JSON object
formula
Computed formula field
summary
Roll-up summary field
password
Password (masked)
⚠️ 重要：
type
属性必须为下表中的值之一，严禁自行编造字段类型。不在此列表中的值会导致错误。
类型描述
text
短文本
textarea
长文本（多行）
html
富文本（HTML编辑器）
select
单选或多选（需配置
options
）
boolean
布尔值（是/否）
toggle
开关控件（功能同boolean，UI不同）
date
仅日期
datetime
日期和时间
time
仅时间
number
整数或小数
currency
货币金额
percent
百分比
autonumber
自动生成的序列号
lookup
引用其他对象（多对一）
master_detail
主从引用（级联删除）
grid
内嵌表格（对象数组）
url
网址
email
邮箱地址
image
图片上传
file
文件上传
code
代码编辑器
markdown
Markdown编辑器
color
颜色选择器
location
地理位置
object
JSON对象
formula
公式计算字段
summary
汇总字段
password
密码（掩码显示）

Text Field Types | 文本字段类型

文本字段类型

text (Short Text) | 短文本

text（短文本）

yaml
name: customer_name
type: text
label: Customer Name
required: true
searchable: true
index: true
yaml
name: customer_name
type: text
label: Customer Name
required: true
searchable: true
index: true

textarea (Long Text) | 长文本

textarea（长文本）

yaml
name: description
type: textarea
label: Description
rows: 4
is_wide: true
yaml
name: description
type: textarea
label: Description
rows: 4
is_wide: true

html (Rich Text) | 富文本

html（富文本）

yaml
name: content
type: html
label: Content
is_wide: true
yaml
name: content
type: html
label: Content
is_wide: true

url

url

yaml
name: website
type: url
label: Website
yaml
name: website
type: url
label: Website

email

email

yaml
name: email
type: email
label: Email
unique: true
index: true
yaml
name: email
type: email
label: Email
unique: true
index: true

Numeric Field Types | 数值字段类型

数值字段类型

number

number

yaml
name: quantity
type: number
label: Quantity
scale: 0
min: 0
max: 999999
yaml
name: quantity
type: number
label: Quantity
scale: 0
min: 0
max: 999999

currency | 货币

currency（货币）

yaml
name: price
type: currency
label: Price
scale: 2
min: 0
yaml
name: price
type: currency
label: Price
scale: 2
min: 0

percent | 百分比

percent（百分比）

yaml
name: discount_rate
type: percent
label: Discount Rate
scale: 2
min: 0
max: 100
yaml
name: discount_rate
type: percent
label: Discount Rate
scale: 2
min: 0
max: 100

autonumber | 自动编号

autonumber（自动编号）

yaml
name: order_number
type: autonumber
label: Order Number
formula: 'ORD-{YYYY}{MM}{DD}-{0000}'
readonly: true
Format placeholders: 
{YYYY}
, 
{YY}
, 
{MM}
, 
{DD}
, 
{0000}
(sequential with padding)
yaml
name: order_number
type: autonumber
label: Order Number
formula: 'ORD-{YYYY}{MM}{DD}-{0000}'
readonly: true
格式占位符：
{YYYY}
、
{YY}
、
{MM}
、
{DD}
、
{0000}
（带填充的序列号）

Date and Time Types | 日期时间类型

日期时间类型

date

date

yaml
name: order_date
type: date
label: Order Date
defaultValue: '{now}'
yaml
name: order_date
type: date
label: Order Date
defaultValue: '{now}'

datetime

datetime

yaml
name: submitted_at
type: datetime
label: Submitted At
readonly: true
yaml
name: submitted_at
type: datetime
label: Submitted At
readonly: true

Boolean and Selection Types | 布尔和选择类型

布尔和选择类型

boolean

boolean

yaml
name: is_active
type: boolean
label: Is Active
defaultValue: true
yaml
name: is_active
type: boolean
label: Is Active
defaultValue: true

select (Single) | 单选

select（单选）

yaml
name: status
type: select
label: Status
options:
  - label: Draft
    value: draft
  - label: Submitted
    value: submitted
  - label: Approved
    value: approved
defaultValue: draft
yaml
name: status
type: select
label: Status
options:
  - label: Draft
    value: draft
  - label: Submitted
    value: submitted
  - label: Approved
    value: approved
defaultValue: draft

select (Multiple) | 多选

select（多选）

yaml
name: tags
type: select
label: Tags
multiple: true
options:
  - label: Technology
    value: tech
  - label: Sales
    value: sales
yaml
name: tags
type: select
label: Tags
multiple: true
options:
  - label: Technology
    value: tech
  - label: Sales
    value: sales

Relationship Fields | 关系字段

关系字段

lookup (Many-to-One) | 查找关系

lookup（多对一）

yaml
name: customer
type: lookup
label: Customer
reference_to: customers
required: true
index: true
yaml
name: customer
type: lookup
label: Customer
reference_to: customers
required: true
index: true

With filters

带筛选条件

name: contact type: lookup label: Contact reference_to: contacts filters: [["account", "=", "{$customer}"]] depend_on:
  • customer
name: contact type: lookup label: Contact reference_to: contacts filters: [["account", "=", "{$customer}"]] depend_on:
  • customer

Multiple selection

多选

name: assigned_users type: lookup label: Assigned Users reference_to: users multiple: true

Lookup properties:
- `reference_to` — target object API name (required)
- `multiple` — allow selecting multiple records (`true`/`false`)
- `filters` — filter condition for lookup dropdown
- `depend_on` — re-fetch options when these fields change
- `deleted_lookup_record_behavior` — when referenced record is deleted. **⚠️ MUST be `clear` (set to null) or `retain` (keep stale reference). Only these two values are valid.**
name: assigned_users type: lookup label: Assigned Users reference_to: users multiple: true

Lookup属性说明：
- `reference_to` — 目标对象API名称（必填）
- `multiple` — 是否允许选择多条记录（`true`/`false`）
- `filters` — 查找下拉框的筛选条件
- `depend_on` — 当这些字段变化时重新获取选项
- `deleted_lookup_record_behavior` — 当引用记录被删除时的处理方式。**⚠️ 必须设置为`clear`（设为null）或`retain`（保留过期引用），仅这两个值有效。**

master_detail (Parent-Child) | 主从关系

master_detail（主从关系）

yaml
name: order
type: master_detail
label: Order
reference_to: orders
required: true
index: true
Cascade delete: deleting parent deletes all children.
yaml
name: order
type: master_detail
label: Order
reference_to: orders
required: true
index: true
级联删除：删除父记录时会删除所有子记录。

Computed Fields | 计算字段

计算字段

formula | 公式

formula（公式）

yaml
name: total_price
type: formula
label: Total Price
data_type: currency
scale: 2
formula_blank_value: zeroes
formula: !!js/function |
  function() {
    return (this.quantity || 0) * (this.unit_price || 0);
  }
data_type
— the output type of the formula. ⚠️ MUST be one of: 
text
, 
number
, 
currency
, 
percent
, 
boolean
, 
date
, 
datetime
. Do NOT use other values.
formula_blank_value
— how to treat blank fields. ⚠️ MUST be 
zeroes
(default, treat as 0) or 
blanks
(treat as null). Only these two values are valid.
yaml
name: total_price
type: formula
label: Total Price
data_type: currency
scale: 2
formula_blank_value: zeroes
formula: !!js/function |
  function() {
    return (this.quantity || 0) * (this.unit_price || 0);
  }
data_type
— 公式的输出类型。⚠️ 必须为以下值之一：
text
、
number
、
currency
、
percent
、
boolean
、
date
、
datetime
，禁止使用其他值。
formula_blank_value
— 如何处理空字段。⚠️ 必须设置为
zeroes
（默认，视为0）或
blanks
（视为null），仅这两个值有效。

summary (Rollup) | 汇总

summary（汇总）

yaml
name: total_orders
type: summary
label: Total Orders
summary_object: orders
summary_type: count
summary_field: customer
summary_filters: [["status", "!=", "cancelled"]]
⚠️ 
summary_type
MUST be one of: 
count
, 
sum
, 
avg
, 
min
, 
max
. Do NOT use other values.
yaml
name: total_orders
type: summary
label: Total Orders
summary_object: orders
summary_type: count
summary_field: customer
summary_filters: [["status", "!=", "cancelled"]]
⚠️ 
summary_type
必须为以下值之一：
count
、
sum
、
avg
、
min
、
max
，禁止使用其他值。

File and Media Types | 文件和媒体类型

文件和媒体类型

file

file

yaml
name: attachment
type: file
label: Attachment
multiple: true
yaml
name: attachment
type: file
label: Attachment
multiple: true

image

image

yaml
name: avatar
type: image
label: Avatar
yaml
name: avatar
type: image
label: Avatar

Special Types | 特殊类型

特殊类型

code (Code Editor) | 代码编辑器

code（代码编辑器）

yaml
name: custom_script
type: code
label: Script
language: javascript
is_wide: true
⚠️ 
language
MUST be one of: 
javascript
, 
typescript
, 
json
, 
html
, 
css
, 
sql
, 
python
, 
java
, 
ruby
, 
go
, 
shell
, 
yaml
, 
xml
, 
markdown
, 
php
, 
csharp
, 
cpp
, 
c
, 
swift
, 
lua
, 
r
. Do NOT use other values.
yaml
name: custom_script
type: code
label: Script
language: javascript
is_wide: true
⚠️ 
language
必须为以下值之一：
javascript
、
typescript
、
json
、
html
、
css
、
sql
、
python
、
java
、
ruby
、
go
、
shell
、
yaml
、
xml
、
markdown
、
php
、
csharp
、
cpp
、
c
、
swift
、
lua
、
r
，禁止使用其他值。

object (JSON)

object（JSON）

yaml
name: metadata
type: object
label: Metadata
blackbox: true
is_wide: true
yaml
name: metadata
type: object
label: Metadata
blackbox: true
is_wide: true

grid (Table/Array)

grid（表格/数组）

yaml
name: line_items
type: grid
label: Line Items
is_wide: true
yaml
name: line_items
type: grid
label: Line Items
is_wide: true

Amis UI Customization | Amis UI 自定义

Amis UI 自定义

Fields can have custom Amis rendering configuration:
yaml
undefined
字段可配置自定义Amis渲染规则：
yaml
undefined

objects/materials/fields/classification.field.yml

objects/materials/fields/classification.field.yml

name: classification type: text label: Classification amis: id: 'u:classification' type: tree-select label: Classification multiple: true clearable: true source: url: /graphql method: post requestAdaptor: | api.data = { query: 
{ hierarchical_picklist_items(filters: ["list", "=", "classification"]) { label, value, parent } }
} adaptor: | const items = payload.data?.hierarchical_picklist_items || []; return { options: buildTree(items) }; cache: 86400000 onEvent: change: weight: 0 actions: - actionType: setValue args: value: related_field: "${event.data.value}"
undefined
name: classification type: text label: Classification amis: id: 'u:classification' type: tree-select label: Classification multiple: true clearable: true source: url: /graphql method: post requestAdaptor: | api.data = { query: 
{ hierarchical_picklist_items(filters: ["list", "=", "classification"]) { label, value, parent } }
} adaptor: | const items = payload.data?.hierarchical_picklist_items || []; return { options: buildTree(items) }; cache: 86400000 onEvent: change: weight: 0 actions: - actionType: setValue args: value: related_field: "${event.data.value}"
undefined

Conditional Visibility | 条件可见性

条件可见性

Use 
visible_on
with Amis formula syntax:
yaml
name: rejection_reason
type: textarea
label: Rejection Reason
visible_on: "{{status == 'rejected'}}"

name: tracking_number
type: text
label: Tracking Number
visible_on: "{{status == 'shipped' || status == 'completed'}}"
使用
visible_on
配置Amis公式语法：
yaml
name: rejection_reason
type: textarea
label: Rejection Reason
visible_on: "{{status == 'rejected'}}"

name: tracking_number
type: text
label: Tracking Number
visible_on: "{{status == 'shipped' || status == 'completed'}}"

Default Values | 默认值

默认值

yaml
undefined
yaml
undefined

Static

静态默认值

defaultValue: 'draft' defaultValue: 0 defaultValue: true
defaultValue: 'draft' defaultValue: 0 defaultValue: true

Dynamic

动态默认值

defaultValue: '{now}' # Current date/time defaultValue: '{userId}' # Current user defaultValue: '{spaceId}' # Current workspace
undefined
defaultValue: '{now}' # 当前日期/时间 defaultValue: '{userId}' # 当前用户ID defaultValue: '{spaceId}' # 当前工作区ID
undefined

Field Dependencies | 字段依赖

字段依赖

yaml
undefined
yaml
undefined

Reload field when dependency changes

当依赖字段变化时重新加载当前字段

name: contact type: lookup label: Contact reference_to: contacts depend_on:
  • customer filters: [["account", "=", "{$customer}"]]
undefined
name: contact type: lookup label: Contact reference_to: contacts depend_on:
  • customer filters: [["account", "=", "{$customer}"]]
undefined

Best Practices | 最佳实践

最佳实践

  1. Use specific types: 
    currency
    not just 
    number
    , 
    email
    not just 
    text
  2. Add indexes: 
    index: true
    on frequently queried/filtered fields
  3. Label follows user's language: Write 
    label
    in the language of the user's prompt. For i18n, use the translations skill
  4. Use sort_no: Control field display order
  5. Group fields: Use 
    group
    to organize related fields
  6. Set appropriate defaults: Use 
    defaultValue
    to reduce user input
  1. 使用特定类型：优先使用
    currency
    而非
    number
    ，使用
    email
    而非
    text
  2. 添加索引：对频繁查询/筛选的字段设置
    index: true
  3. 标签符合用户语言：
    label
    使用用户界面的语言，如需国际化请使用翻译功能
  4. 使用sort_no：控制字段的显示顺序
  5. 分组字段：使用
    group
    组织相关字段
  6. 设置合适的默认值：使用
    defaultValue
    减少用户输入