steedos-object-fields

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 | 字段结构

# 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 | 通用属性

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:

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

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：

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

Text Field Types | 文本字段类型

text (Short Text) | 短文本

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

textarea (Long Text) | 长文本

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

html (Rich Text) | 富文本

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

url

name: website
type: url
label: Website

email

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

Numeric Field Types | 数值字段类型

number

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

currency | 货币

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

percent | 百分比

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

autonumber | 自动编号

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

⚠️ Valid placeholders — ONLY these are supported in the formula field:

⚠️ {project_code}, {org_code}, {user_name} or any other field-name placeholders are NOT valid and will appear literally in the output. The {...} syntax ONLY supports the date/sequence placeholders listed above.

⚠️ {project_code}、{org_code}、{user_name} 等字段名占位符是无效的，会原样输出。{...} 语法仅支持上面列出的日期/序号占位符。

Formula examples:

# Basic: prefix + sequence
formula: 'INV-{0000}'              # → INV-0001, INV-0002

# Date + sequence (resets daily)
formula: 'ORD-{YYYY}{MM}{DD}-{0000}'  # → ORD-20260423-0001

# Date + sequence (resets monthly)
formula: 'PO-{YYYY}{MM}-{000}'        # → PO-202604-001

# Date + sequence (resets yearly)
formula: 'REQ-{YYYY}-{00000}'         # → REQ-2026-00001

# Prefix only + sequence (never resets)
formula: 'CUST-{000000}'              # → CUST-000001, CUST-000002

Sequence reset rule: The counter resets based on which date placeholders are present — {YYYY}+{MM}+{DD} resets daily, {YYYY}+{MM} resets monthly, {YYYY} only resets yearly, no date placeholder means never resets.

Date and Time Types | 日期时间类型

date

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

datetime

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

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

boolean

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

select (Single) | 单选

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

select (Multiple) | 多选

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

Relationship Fields | 关系字段

IMPORTANT: The reference_to value must be the exact API name of the target object. Built-in object names often differ from common expectations — Department is organizations (not departments), Division is company (not divisions), Workspace User is space_users. Load the steedos-builtin-objects skill for the authoritative name list.

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

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) | 主从关系

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

Cascade delete: deleting parent deletes all children.

Computed Fields | 计算字段

formula | 公式

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) | 汇总

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

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

image

name: avatar
type: image
label: Avatar

Special Types | 特殊类型

code (Code Editor) | 代码编辑器

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)

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

grid (Table/Array)

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

Amis UI Customization | Amis UI 自定义

Fields can have custom Amis rendering configuration:

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

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 | 默认值

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

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

Field Dependencies | 字段依赖

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

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