Yida Formula

宜搭表单公式编写规范

触发条件

正向触发（以下场景必须使用本技能）：

• 用户说"配置公式"、"计算字段"、"自动计算"、"字段联动"
• 用户说"求和"、"平均值"、"条件判断"、"IF 公式"
• 用户需要在表单字段上配置默认值公式、计算公式
• 用户需要配置字段的自定义校验规则
• 用户需要了解宜搭公式函数的用法和语法

概述

宜搭公式可以：

1. 自动计算字段默认值：在数值、单行文本、日期、成员等字段上配置公式，根据其他字段自动计算出值
2. 配置校验规则：在提交时校验数据是否符合规则（在表单属性的「校验」中配置）
3. 识别字段公式适用范围：字段公式只处理字段默认值、计算值和自定义校验，不处理提交后跨表写入动作。

完整函数列表参见 ../../references/formula-functions.md

官方示例中心的公式类示例基本落在普通表单或流程表单 schema 中，而不是自定义页面。遇到“日期转换、流水号、登录人、主管、相隔时间、求和”等能力时，默认先配置字段公式或字段联动；只有公式无法表达、且需要跨表提交后动作时，再用提交后编排能力实现。

⚠️ 重要：公式配置方式说明

宜搭没有独立的"公式字段"组件。公式是配置在普通字段（NumberField、TextField、DateField、EmployeeField 等）的属性上的：

公式字段的 Schema 结构

通过 openyida create-form 的 create 或 update 模式，可以直接在字段上配置公式。

字段引用格式

公式中引用其他字段时，使用 #{fieldId} 格式（不是直接写 fieldId）：

# ✅ 正确：用 #{} 包裹 fieldId
ROUND(#{numberField_abc} * #{numberField_xyz}, 2)

# ❌ 错误：直接写 fieldId
ROUND(numberField_abc * numberField_xyz, 2)

字段 Schema 中的公式属性

需要同时设置以下三个属性：

create 模式：创建带公式的字段

[
  {
    "type": "NumberField",
    "label": "总金额",
    "behavior": "READONLY",
    "valueType": "formula",
    "complexValue": {
      "complexType": "formula",
      "formula": "ROUND(#{numberField_price} * #{numberField_qty}, 2)"
    },
    "formula": "ROUND(#{numberField_price} * #{numberField_qty}, 2)"
  }
]

update 模式：给已有字段配置公式

[
  {
    "action": "update",
    "label": "总金额",
    "changes": {
      "valueType": "formula",
      "complexValue": {
        "complexType": "formula",
        "formula": "ROUND(#{numberField_price} * #{numberField_qty}, 2)"
      },
      "formula": "ROUND(#{numberField_price} * #{numberField_qty}, 2)"
    }
  }
]

⚠️ 重要：公式中的 fieldId 必须是真实 ID

公式中引用的 fieldId（如 numberField_abc123）必须是表单中真实存在的字段 ID，不能猜测。正确工作流程：

Step 1: create 模式创建基础字段（不含公式）
         ↓
Step 2: openyida get-schema 获取各字段的真实 fieldId
         ↓
Step 3: create 或 update 模式添加/更新带公式的字段，引用真实 #{fieldId}

公式语法规则

基本规则

1. 函数名必须全大写：SUM、IF、CONCATENATE，不能写成 sum、if
2. 所有符号必须是英文：括号 ()、逗号 ,、引号 ""，不能用中文符号
3. 字符串常量用双引号："优秀"、"已完成"
4. 支持基本算术运算符：+（加）、-（减）、*（乘）、/（除）
5. 比较运算必须用函数，不能用符号：禁止使用 >=、<=、>、<、==、!=，必须改用 GE()、LE()、GT()、LT()、EQ()、NE() 函数
6. 隐藏字段需开启「始终提交」：否则隐藏字段不参与公式计算

字段引用规则

公式中引用表单字段时，使用 #{fieldId} 格式（必须用 #{} 包裹）：

# 引用主表字段（用 #{} 包裹 fieldId）
#{textField_abc123}

# 引用子表（TableField）内的字段
#{tableField_xxx.numberField_yyy}

# 引用当前登录用户（无需字段 ID）
USER()

# 引用当前时间（无需字段 ID）
NOW()
TODAY()

如何获取 fieldId：使用 openyida get-schema <appType> <formUuid> 获取表单 Schema，其中每个字段的 fieldId 属性即为字段 ID。

赋值类型限制

公式结果只能赋值给同类型的组件：

业务关联规则说明

业务关联规则、高级函数、INSERT/UPDATE/DELETE/UPSERT 不属于字段公式。本技能只处理普通字段公式、默认值公式和自定义校验公式。

函数分类速查

完整函数参数说明见 ../../references/formula-functions.md

文本函数（表单场域）

时间函数（表单场域）

逻辑函数（表单场域）

数学函数（表单场域）

人员函数（表单场域）

集合函数（表单场域）

校验函数（表单场域）

常见场景示例

场景 1：子表金额求和

SUM(#{tableField_items.numberField_amount})

场景 2：单价 × 数量计算总价（保留2位小数）

ROUND(#{numberField_price} * #{numberField_qty}, 2)

场景 3：子表多列乘积求和（SUMPRODUCT）

SUMPRODUCT(#{tableField_items.numberField_qty}, #{tableField_items.numberField_price})

场景 4：IF 条件判断等级

IF(GE(#{numberField_score}, 90), "A", IF(GE(#{numberField_score}, 75), "B", IF(GE(#{numberField_score}, 60), "C", "D")))

场景 5：多条件 AND 判断

IF(AND(GE(#{numberField_age}, 18), LE(#{numberField_age}, 60)), "适龄员工", "不符合条件")

场景 6：计算两个日期相差天数

DAYS(#{dateField_endDate}, #{dateField_startDate})

场景 7：在入职日期基础上加 90 天（试用期结束日）

DATEDELTA(#{dateField_joinDate}, 90)

场景 8：计算工龄（年，向下取整）

INT(DAYS(TODAY(), #{dateField_joinDate}) / 365)

场景 9：自动填充当前登录人（成员字段）

USER()

场景 10：自动填充当前登录人昵称（文本字段）

GETUSERNAME()

场景 11：自动填充当前登录人部门

DEPTNAME(LOGINUSERWORKNO())

场景 12：拼接姓名和工号

CONCATENATE(#{textField_name}, "(", #{textField_workNo}, ")")

场景 13：手机号中间4位打码

REPLACE(#{textField_phone}, 4, 4, "****")

场景 14：判断字段是否为空，为空时显示默认值

IF(ISEMPTY(#{textField_remark}), "无备注", #{textField_remark})

场景 15：生成唯一 ID

UUID()

场景 16：计算两个日期区间的工作日天数

NETWORKDAYS(#{dateField_startDate}, #{dateField_endDate})

场景 17：格式化金额为人民币大写

RMBFORMAT(#{numberField_amount})

场景 18：按逗号分割标签字符串，取第一个标签

ARRAYGET(SPLIT(#{textField_tags}, ","), 1)

注意事项

⚠️ 循环依赖

公式中不能引用当前正在配置公式的字段本身，否则会报「表单中的公式存在循环依赖」错误。

错误示例：在 numberField_total 的公式中引用 numberField_total 自身。

⚠️ 隐藏字段参与计算

隐藏字段（behavior: "HIDDEN"）默认不参与公式计算。若需要隐藏字段参与计算，必须在字段配置中开启「始终提交」选项。

⚠️ 日期字段不建议作为判断条件

日期字段的底层值是时间戳，直接用时间戳做判断条件不准确。推荐做法：

1. 用一个单行文本字段通过公式接收日期值
2. 用该单行文本字段作为判断条件

⚠️ 业务关联规则单独处理

INSERT/UPDATE/DELETE/UPSERT 属于表单事件里的业务关联规则高级函数，不属于普通字段公式。遇到这类需求时切换到 yida-business-rule。

异常处理

Memory 策略

本技能不读写 memory。公式配置通过 openyida create-form 命令写入宜搭平台，fieldId 等技术信息写入 .cache/ 临时文件，不依赖跨会话的 memory 状态。