Steedos Object Fields | 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/

子文件夹中。

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

Field Structure | 字段结构

yaml

# 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

Common Properties | 通用属性

Property	Type	Description
`name`	string	Field API name (required)
`type`	string	Field type (required, see Valid Field Types below)
`label`	string	Display label — use the language of the user's prompt (required)
`required`	boolean	Is required
`readonly`	boolean	Read-only
`hidden`	boolean	Hide from all UI
`omit`	boolean	Omit from forms
`disabled`	boolean	Disable editing
`defaultValue`	any	Default value
`group`	string	Field group name
`sort_no`	number	Display order
`is_name`	boolean	Mark as the object's display name field (see below)
`is_wide`	boolean	Full width in forms
`index`	boolean	Create database index
`unique`	boolean	Unique constraint
`searchable`	boolean	Include in global search
`filterable`	boolean	Available in filters
`sortable`	boolean	Sortable in list views
`data_type`	string	Backend data type
`visible_on`	string	Amis formula for conditional visibility
`inlineHelpText`	string	Tooltip help text

Name Field (

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:

每个对象必须有一个名称字段——在查找、相关列表和记录标题中显示的人类可读标识。系统按以下优先级确定名称字段：

A field with
```
is_name: true
```
(highest priority)
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

# autonumber as name field
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

# simple text name field (is_name not needed)
name: name
type: text
label: Product Name
required: true
searchable: true

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
属性必须为下表中的值之一，严禁自行编造字段类型。不在此列表中的值会导致错误。

Type	Description
`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)

Text Field Types | 文本字段类型

text (Short Text) | 短文本

yaml

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

textarea (Long Text) | 长文本

yaml

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

html (Rich Text) | 富文本

yaml

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

url

yaml

name: website
type: url
label: Website

email

yaml

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

Numeric Field Types | 数值字段类型

number

yaml

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

currency | 货币

yaml

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

percent | 百分比

yaml

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

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)

Date and Time Types | 日期时间类型

date

yaml

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

datetime

yaml

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

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

boolean

yaml

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

select (Single) | 单选

yaml

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

select (Multiple) | 多选

yaml

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

Relationship Fields | 关系字段

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

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

# 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.

master_detail (Parent-Child) | 主从关系

yaml

name: order
type: master_detail
label: Order
reference_to: orders
required: true
index: true

Cascade delete: deleting parent deletes all children.

Computed Fields | 计算字段

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.

summary (Rollup) | 汇总

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.

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

file

yaml

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

image

yaml

name: avatar
type: image
label: Avatar

Special Types | 特殊类型

code (Code Editor) | 代码编辑器

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.

object (JSON)

yaml

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

grid (Table/Array)

yaml

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

Amis UI Customization | Amis UI 自定义

Fields can have custom Amis rendering configuration:

yaml

# 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}"

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'}}"

Default Values | 默认值

yaml

# Static
defaultValue: 'draft'
defaultValue: 0
defaultValue: true

# Dynamic
defaultValue: '{now}'        # Current date/time
defaultValue: '{userId}'     # Current user
defaultValue: '{spaceId}'    # Current workspace

Field Dependencies | 字段依赖

yaml

# Reload field when dependency changes
name: contact
type: lookup
label: Contact
reference_to: contacts
depend_on:
  - customer
filters: [["account", "=", "{$customer}"]]

Best Practices | 最佳实践

Use specific types:
```
currency
```
not just
```
number
```
,
```
email
```
not just
```
text
```
Add indexes:
```
index: true
```
on frequently queried/filtered fields
Label follows user's language: Write
```
label
```
in the language of the user's prompt. For i18n, use the translations skill
Use sort_no: Control field display order
Group fields: Use
```
group
```
to organize related fields
Set appropriate defaults: Use
```
defaultValue
```
to reduce user input

object-fields

NPX Install

Tags

SKILL.md Content

Steedos Object Fields | Steedos 对象字段

Overview | 概述

File Location | 文件位置

Field Structure | 字段结构

Common Properties | 通用属性

Name Field (is_name) | 名称字段

Valid Field Types | 有效字段类型

Text Field Types | 文本字段类型

text (Short Text) | 短文本

textarea (Long Text) | 长文本

html (Rich Text) | 富文本

url

email

Numeric Field Types | 数值字段类型

number

currency | 货币

percent | 百分比

autonumber | 自动编号

Date and Time Types | 日期时间类型

date

datetime

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

boolean

select (Single) | 单选

select (Multiple) | 多选

Relationship Fields | 关系字段

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

master_detail (Parent-Child) | 主从关系

Computed Fields | 计算字段

formula | 公式

summary (Rollup) | 汇总

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

file

image

Special Types | 特殊类型

code (Code Editor) | 代码编辑器

object (JSON)

grid (Table/Array)

Amis UI Customization | Amis UI 自定义

Conditional Visibility | 条件可见性

Default Values | 默认值

Field Dependencies | 字段依赖

Best Practices | 最佳实践

Name Field (
`is_name`
) | 名称字段