表单脚本用于处理用户填写表单时的前端交互逻辑。
它适合做字段联动、动态必填、默认值填充、表单加载后处理等页面行为。

表单脚本属于布局能力的一部分，保存在实体的表单布局中。

表单脚本适合做什么 ​

表单脚本常见用途包括：

  • 某个字段变化后自动带出其他字段
  • 根据单选值切换某些字段是否必填
  • 新建表单打开时填充默认值
  • 在保存前补充或修正数据
  • 对引用字段回填结果继续做二次处理

如果需求属于“保存后自动执行”，应优先考虑 后台脚本 或 事件。
如果需求属于“填写过程中立刻反馈”，应使用表单脚本。

可用函数 ​

系统内置了一组表单脚本函数，便于在不改前端源码的情况下实现页面联动。

当表单数据加载完成时 ​

javascript
__formDataReady(data => {
  console.log(data)
})
  • data：当前表单数据

适合场景：

  • 编辑页面打开后，根据已有数据做初始化处理
  • 新建时根据默认值再执行一次联动

监听任意字段值变化 ​

javascript
__formValueChange((field, value) => {
  console.log(field, value)
})
  • field：字段名
  • value：字段值

适合在同一段逻辑里统一监听多个字段。

监听指定字段值变化 ​

javascript
__formFieldValueChange('field', value => {
  console.log(value)
})
  • field：字段名

如果只关心某一个字段的变化，优先使用这个函数，脚本更清晰。

保存前触发 ​

javascript
__formBeforeSave(data => {
  console.log(data)
})
  • data：最终待保存的数据

适合场景：

  • 保存前补充某些隐藏字段
  • 保存前做格式处理
  • 保存前统一计算一个展示字段

获取字段值 ​

javascript
const value = __getFormFieldValue('field')
console.log(value)

设置字段值 ​

javascript
__setFormFieldValue('field', value)

设置值时需要保证值格式符合字段类型要求。
例如引用字段通常需要类似下面的结构：

javascript
{ id: 'xxx', name: 'xxx' }

设置字段必填 / 非必填 ​

javascript
__setFormFieldRequired('field', true)

适合场景：

  • 当“客户类型 = 企业”时，统一社会信用代码必填
  • 当“是否开票 = 是”时，发票信息必填

典型示例 ​

示例 1：根据客户类型切换必填项 ​

javascript
__formFieldValueChange('customerType', value => {
  __setFormFieldRequired('companyName', value === '企业')
})

示例 2：加载完成后自动带默认值 ​

javascript
__formDataReady(data => {
  if (!data.followStatus) {
    __setFormFieldValue('followStatus', '未跟进')
  }
})

示例 3：保存前补充展示字段 ​

javascript
__formBeforeSave(data => {
  if (data.firstName && data.lastName) {
    __setFormFieldValue('fullName', data.lastName + data.firstName)
  }
})

使用建议 ​

  • 一段脚本只处理一类联动，不要把过多业务堆在一起
  • 优先监听指定字段，减少无关触发
  • 保存前脚本要谨慎，避免把用户输入覆盖掉
  • 表单脚本负责交互体验，复杂业务规则仍建议交给后台事件处理
  • 对引用字段、日期字段、选项字段，先确认真实值结构再赋值

Linker