⚠️ 重要：宜搭开发模式

与传统前端不同，宜搭有独特的开发模式：

1. 页面不是代码写的 - 页面通过宜搭可视化拖拽创建，不是 JSX/HTML 声明
2. 不要写组件声明代码 - ❌ 禁止 import Button、❌ 禁止 const Page = () => {...}
3. 只有 JS 动作面板 - 宜搭的 JS 代码是"动作面板"，只能写函数，不能写组件
4. 组件通过 fieldId 引用 - 使用 this.$('textField_xxx') 操作已存在的组件

组件 fieldId 命名规范

宜搭组件的 fieldId 格式为：组件类型_随机后缀

常见开发模式

条件显示

• 组件属性 → 高级 → 是否渲染 → 绑定变量 state.sta
• 或 JS 设置：this.$('fieldId').setBehavior('HIDDEN')

事件函数命名

• export function onChange({ value }) { } - 值变化事件
• export function didMount() { } - 页面加载完成

setTimeout 延迟

宜搭组件 onChange 事件中修改状态需要延迟：

export function onChange({ value }) {
  setTimeout(() => {
    this.setState({ sta: value === '价款合同' })
  }, 200)
}

隐藏字段

组件属性中设置 behavior: "HIDDEN" 可隐藏字段（可用于数据传递）

只读字段

组件属性中设置 behavior: "READONLY" 可设为只读

公式字段

在组件属性中设置 valueType: "formula" + formula: "#{textField_xxx}"

{
  "valueType": "formula",
  "formula": "CONCATENATE(\"XMBH\",TEXT(TODAY(),\"yyMMdd\"),MID(TEXT(TIMESTAMP(NOW())),9,5))"
}

TableField 事件

新增行时获取行数：

export function onAddClick(newGroupId) {
  const count = this.$('tableField_xxx').getValue().length
  this.$('textField_count').setValue(count + '条')
}

TableField onChange 计算不重复值

遍历子表单行，计算某列的不重复值数量：

export function onChange({ value, extra }) {
  const subFormInst = this.$('tableField_xxx')
  const items = subFormInst.getItems()
  let distinctNum = []
  items.forEach(item => {
    const rowData = subFormInst.getItemValue(item)
    if (rowData['textField_col'] && !distinctNum.includes(rowData['textField_col'])) {
      distinctNum.push(rowData['textField_col'])
    }
  })
  this.$('numberField_count').setValue(distinctNum.length)
}

EmployeeField onChange

人员选择变化时获取人员信息：

export function onChange({ value }) {
  // value 是人员对象 { name, userId, ... }
  this.$('textField_name').setValue(value.name)
}

PageSection 区块

用于分组显示，有标题头：

{
  "componentName": "PageSection",
  "props": {
    "title": { "zh_CN": "基本信息" },
    "behavior": "NORMAL",  // 或 "HIDDEN" 隐藏整个区块
    "showHeader": true
  }
}

关联表单数据填充

选择关联表单时自动填充其他字段：

{
  "dataFillingRules": [
    { "sourceType": "SelectField", "targetType": "TextField", "source": "selectField_src", "target": "textField_target" }
  ]
}

联动字段

设置 valueType: "linkage" + linkage 属性从其他表单获取数据

SUM 汇总公式

汇总子表单某列：

{
  "valueType": "formula",
  "formula": "SUM(#{numberField_column})"
}

RadioField 联动

单选切换时显示/隐藏字段（配置选项的联动规则）

onBlur 事件

失焦时执行校验（如手机号验证）：

export function onBlur() {
  let phone = this.$('textField_xxx').getValue()
  if (!phone) return
  if (!this.isPhoneNumber(phone)) {
    this.utils.toast({ title: '请输入正确的手机号', type: 'warning' })
    this.$('textField_xxx').setValue('')
  }
}

export function isPhoneNumber(input) {
  return /^1\d{10}$/.test(input.replace(/\D/g, ''))
}

NumberField 校验

设置 minValue 最小值：

{ "validation": [{ "type": "minValue", "param": "0" }] }

组件属性参考

SelectField 下拉选择

TableField 明细表

TableField JS 操作

const table = this.$('tableField_xxx')
table.getValue()           // 获取所有行数据
table.getItems()           // 获取行实例数组
table.getItemValue(item)   // 获取某行数据
table.addItem()            // 新增一行
table.removeItem(item)    // 删除一行

NumberField

RadioField

ColumnsLayout 多列布局

布局格式: 2:2:2:2:4 (总和=12), 多行: 4:4:4\|6:6

Button 按钮

Icon 图标

EmployeeField 人员选择

DateField 日期选择

TextField 单行输入

TextareaField 多行输入

USER() 公式

人员字段自动填充当前登录人：

{ "valueType": "formula", "formula": "USER()" }

关联表单数据过滤

设置 dataFilterRules 过滤可选数据

页面级校验器

在页面属性 → 数据校验 中配置，检测重复数据：

{
  "displayRule": "EXIST(角色名称)",
  "rule": "EXIST(#{formUuid}, \"textField_lenz6y7q\", #{textField_lenz6y7q})",
  "message": "角色名称不能重复"
}

## 核心概念

### 全局变量 (State)
类似 React state，用于页面全局状态管理：
- 创建：在数据源面板 → 添加变量
- 读取：`this.state.name` 或 `state.name`（变量绑定时）
- 更改：`this.setState({ name: 'Jack' })`
- 特殊变量：`urlParams` - 获取 URL 参数

⚠️ 注意：setState 后可立即获取新值（不同于 React），但无回调函数

### 远程数据源
配置远程 API 进行异步请求：
```js
// 手动加载
this.dataSourceMap.apiName.load({ params }).then(res => {})

// 重新加载所有自动加载的数据源
this.reloadDataSource()

数据处理函数：

• willFetch - 请求发送前修改参数
• fit - 响应数据适配
• didFetch - 请求成功后的数据处理
• onError - 错误处理

生命周期

export function didMount() { }    // 页面加载完成
export function willUnmount() { } // 页面卸载前

事件处理

给组件绑定动作事件，在动作面板实现处理逻辑：

export function onClick() {
  const { name, age } = this.params  // 获取绑定时设置的参数
}

表单校验

内置规则 + 自定义校验函数：

function validateRule(value) {
  if (/^杭州/.test(value)) return true
  return false
}

手动触发校验：

this.$('textField_xxx').validate((errors, values) => {})

常用校验示例：

• 银行卡号（Luhn算法）：16或19位数字
• 身份证号：18位，末尾校验码

循环渲染

循环数据要求是数组，绑定变量获取循环数据：

• this.item - 获取当前行数据
• this.index - 获取当前行索引

容器组件绑定循环数据后可遍历渲染，内部组件通过变量绑定访问数据。

条件渲染

组件高级属性 → 是否渲染 → 绑定变量控制显隐

// 绑定 state.xxx 控制显示
state.urlParams.showName  // 根据URL参数控制

自定义样式

两种方式：

1. 基础样式配置 - 可视化配置布局、文字、背景等
2. 手工编码模式 - CSS 选择器、伪类等

名词解释

集成自动化（连接器）

触发类型：

• 表单事件触发 - 提交/流程状态更新
• 定时触发 - 周期循环
• 应用事件触发 - 钉钉生态事件
• Webhook 触发

节点类型：

• 触发器
• 一方连接器（钉钉消息、待办等）
• 自定义连接器
• 数据节点（新增/更新/获取/删除）
• 分支节点（条件分支/并行分支）
• 发起审批
• 消息节点
• 开发者节点（Groovy 脚本）

自定义组件

⚠️ 仅限专属版

概念

• 普通组件 - 展示型，无数据存储
• 表单组件 - 可提交数据（暂未开放）

开发流程

1. 创建组件 - 应用设置 → 组件管理 → 新增组件
2. 开发调试 - 定义属性 + 搭建视图 + 编写逻辑
3. 发布版本 - 开发版(0.1.0) / 正式版(1.x.x)
4. 安装使用 - 选择页面类型安装

组件属性 (propTypes)

• 属性类型：文本、布尔、数字、对象、数组、函数、元素
• 设置器：TextSetter、BoolSetter、NumberSetter、JsonSetter、OptionsSetter、ActionSetter、SlotSetter 等

组件生命周期

export function componentDidMount() { }   // 渲染完成
export function componentDidUpdate() { }  // 更新完成
export function componentDidCatch() { }   // 错误捕获
export function componentWillUnmount() { } // 销毁前

组件内获取属性

this.props.xxx  // 获取传入的属性

页面中操作自定义组件

this.$('fieldId').get('propName')  // 获取属性
this.$('fieldId').set('propName', value)  // 设置属性

组件联动

添加 function 类型属性作为事件回调，在组件内通过 this.props.xxx() 触发

注意事项

• fieldId 不能随意修改，会影响公式和存储
• 线上应用请安装正式版本 (1.x.x)
• 不支持删除/卸载组件

调试方法

• debugger 断点调试
• 浏览器控制台 cmd/ctrl + p → page.js 添加断点
• URL 加 ?__showDevtools 打开调试面板
• URL 加 ?__debug 查看/编辑 Schema
• 移动端调试：引入 vConsole

const vConsole = 'https://g.alicdn.com/code/lib/vConsole/3.11.2/vconsole.min.js';
const js = document.createElement('script');
js.src = vConsole;
document.body.append(js);
js.onload = function() { window.vConsole = new window.VConsole(); };

API 体系

宜搭 JS-API

前端页面调用，包括：

• 全局变量：this.state.xxx / this.setState()
• 远程数据：this.dataSourceMap.xxx.load() / this.reloadDataSource()
• 组件操作：this.$(fieldId).getValue() / this.$(fieldId).setValue()
• 工具类：this.utils.toast() / this.utils.dialog() / this.utils.router.push()
• 校验：this.$(fieldId).validate() / this.$(fieldId).setValidation()

跨应用数据源 API (OpenAPI)

远程数据源配置中调用，用于表单数据操作：

• 新建：POST /v1/form/saveFormData.json
• 更新：POST /v1/form/updateFormData.json
• 删除：POST /v1/form/deleteFormData.json
• 查询：GET /v1/form/searchFormDatas.json
• 流程发起：POST /v1/process/startInstance.json

钉钉 JS-API

需手动加载：https://g.alicdn.com/dingding/dingtalk-jsapi/2.10.3/dingtalk.open.js

• 弹框：device.notification.alert/confirm/prompt
• 扫码：biz.util.scan
• 地图：biz.map.locate/view
• 通讯录：biz.contact.choose/complexPicker

服务端 OpenAPI

需通过钉钉开放平台调用，需要鉴权：

• 创建钉钉应用 → 添加权限 → 获取 access_token
• 调用服务端接口

2026 年新功能

2026.02.03 集成自动化升级

• 异常日志支持批量重试
• 日志实例ID交互优化
• 数据节点过滤条件增加"父级条件"
• 新增 AI 节点

2026.01.20 新功能

• 宜搭表单新增「钉钉文档」选择组件
• 富文本支持钉钉文档链接自动识别
• 附件/图片支持批量下载
• 关联表单/关联列表支持自定义显示字段

2026.01.05 新功能

• 贴一贴：附件上传快捷黏贴（Ctrl+V）
• 实例标题支持变量动态更新
• 数据管理文本筛选动态匹配
• 关联表单数据搜索升级（大小写自动匹配）

快速参考

组件操作

// ✅ 正确：操作已存在的组件（通过 fieldId）
this.$('textField_m2iqeyip').getValue()
this.$('textField_m2iqeyip').setValue('hello')

// ❌ 错误：不要声明/导入组件
// const MyButton = () => {...}  // 禁止！

状态管理

this.setState({ key: 'value' })
const value = this.state.key

// URL 参数（默认全局变量）
const param = this.state.urlParams.xxx

生命周期

export function didMount() { }   // 页面加载完成
export function willUnmount() { } // 页面卸载前

远程数据源

this.dataSourceMap.api.load(params).then(res => { })
this.reloadDataSource()

常用工具

this.utils.toast({ title: '成功', type: 'success' })
this.utils.router.push('/pageId')
this.utils.getLoginUserId()

详细文档

• JS-API 完整参考 - 组件操作、校验、弹窗、路由等
• 故障排查指南 - 调试方法、常见问题
• TodoMVC 入门教程 - 新人入门完整示例

调试方法

• URL 加 ?__showDevtools 打开调试面板
• URL 加 ?__debug 查看 Schema
• 代码加 debugger 断点
• 使用 console.log 输出调试信息

参考资源

服务端 OpenAPI (open.dingtalk.com)

需通过钉钉开放平台调用，需要创建应用并获取授权。

流程 API

表单 API (V2)

请求示例

// 发起流程
const params = {
  processCode: "TPROC--CFYJ5HYUN89NJ1JW3IXBI7A95RXM3652O9MKK3",
  formUuid: "FORM-CFYJ5HYUN89NJ1JW3IXBI7A95RXM3552O9MKK2",
  formDataJson: JSON.stringify({ textField_kkm9o5cd: "123" })
};
this.dataSourceMap.myDatasource.load(params);

更多 API

• 批量操作、子表数据、审批记录等详见开放平台文档

场景案例专题

表单专题

常见表单开发场景：

• 数据权限：只允许查看自己的数据（表单权限设置）
• 子表单：获取子表单值赋值给主表、子表单序号生成、子表单批量导入
• 数据联动：数据源获取主表数据在子表展示、下拉框赋值、关联表单填充
• 校验：子表单重复校验、组件实时校验唯一性、自定义校验
• 高级：图片裁剪上传、扫码识别、地址组件动态类型、公历转农历

自定义页面专题

• 页面搭建、组件使用、事件处理

连接器专题

• 集成自动化、钉钉消息、待办通知

实用工具专题

• 常用工具组件使用

报表专题

• 数据可视化、图表配置

公式专题

• 公式函数使用、计算逻辑

方案专题

• 行业解决方案、业务场景案例

Schema 生成

宜搭页面使用 JSON Schema 定义，可以直接粘贴到设计器中。

基础结构

{
  "type": "nodeSchema",
  "componentsMap": {},
  "componentsTree": [
    {
      "componentName": "PageSection",
      "props": { ... },
      "children": [ ... ]
    }
  ]
}

常用组件 Schema

TextField (单行文本)

{
  "componentName": "TextField",
  "props": {
    "fieldId": "textField_xxxxx",
    "label": { "type": "i18n", "zh_CN": "字段名称", "en_US": "字段名称" },
    "behavior": "NORMAL",
    "valueType": "custom",
    "validation": [{ "type": "required" }],
    "placeholder": { "type": "i18n", "zh_CN": "请输入", "en_US": "请输入" },
    "maxLength": 200,
    "visibility": ["PC", "MOBILE"]
  }
}

NumberField (数字)

{
  "componentName": "NumberField",
  "props": {
    "fieldId": "numberField_xxxxx",
    "label": { "type": "i18n", "zh_CN": "金额", "en_US": "金额" },
    "precision": 2,
    "step": 1,
    "behavior": "NORMAL",
    "valueType": "custom",
    "validation": [
      { "type": "required" },
      { "type": "minValue", "param": 0 },
      { "type": "maxLength", "param": 25 }
    ]
  }
}

DateField (日期)

{
  "componentName": "DateField",
  "props": {
    "fieldId": "dateField_xxxxx",
    "label": { "type": "i18n", "zh_CN": "日期", "en_US": "日期" },
    "format": "YYYY-MM-DD",
    "behavior": "NORMAL",
    "valueType": "custom",
    "validation": [{ "type": "required" }]
  }
}

SelectField (下拉选择)

{
  "componentName": "SelectField",
  "props": {
    "fieldId": "selectField_xxxxx",
    "label": { "type": "i18n", "zh_CN": "选项", "en_US": "选项" },
    "mode": "single",
    "showSearch": true,
    "behavior": "NORMAL",
    "valueType": "custom",
    "defaultDataSource": {
      "customStashOptions": [
        { "text": { "zh_CN": "选项一", "en_US": "选项一" }, "value": "选项一", "sid": "serial_xxx" }
      ]
    }
  }
}

RadioField (单选)

{
  "componentName": "RadioField",
  "props": {
    "fieldId": "radioField_xxxxx",
    "label": { "type": "i18n", "zh_CN": "类型", "en_US": "类型" },
    "itemDirection": "hoz",
    "behavior": "NORMAL",
    "valueType": "custom",
    "dataSource": [
      { "text": { "zh_CN": "选项A", "en_US": "选项A" }, "value": "A", "sid": "serial_a" },
      { "text": { "zh_CN": "选项B", "en_US": "选项B" }, "value": "B", "sid": "serial_b" }
    ]
  }
}

EmployeeField (人员选择)

{
  "componentName": "EmployeeField",
  "props": {
    "fieldId": "employeeField_xxxxx",
    "label": { "type": "i18n", "zh_CN": "申请人", "en_US": "申请人" },
    "multiple": false,
    "behavior": "NORMAL",
    "valueType": "custom",
    "userRangeType": "ALL",
    "validation": [{ "type": "required" }]
  }
}

AssociationFormField (关联表单)

{
  "componentName": "AssociationFormField",
  "props": {
    "fieldId": "associationFormField_xxxxx",
    "label": { "type": "i18n", "zh_CN": "关联数据", "en_US": "关联数据" },
    "behavior": "NORMAL",
    "multiple": false,
    "associationForm": {
      "formUuid": "FORM-XXXXXXXX",
      "appType": "APP_XXXXXXXX"
    },
    "validation": [{ "type": "required" }]
  }
}

Image (图片)

{
  "componentName": "Image",
  "props": {
    "fieldId": "image_xxxxx",
    "src": "https://example.com/image.jpg",
    "width": 100,
    "height": 100,
    "fit": "cover"
  }
}

Text (文本)

{
  "componentName": "Text",
  "props": {
    "fieldId": "text_xxxxx",
    "content": { "type": "i18n", "zh_CN": "文本内容", "en_US": "文本内容" },
    "__style__": ":root { font-size: 16px; font-weight: 600; }"
  }
}

LinkBlock (链接块)

{
  "componentName": "LinkBlock",
  "props": {
    "fieldId": "linkBlock_xxxxx",
    "link": { "type": "url", "url": "https://example.com", "isBlank": true },
    "__style__": ":root { margin: 10px; }"
  }
}

Div (容器)

{
  "componentName": "Div",
  "props": {
    "fieldId": "div_xxxxx",
    "__style__": ":root { padding: 20px; background: #fff; }"
  }
}

布局组件

PageSection (区块)

{
  "componentName": "PageSection",
  "props": {
    "fieldId": "pageSection_xxxxx",
    "title": { "type": "i18n", "zh_CN": "基本信息", "en_US": "基本信息" },
    "showHeader": true,
    "behavior": "NORMAL"
  }
}

ColumnsLayout + Column (多列布局)

{
  "componentName": "ColumnsLayout",
  "props": {
    "fieldId": "columnsLayout_xxxxx",
    "layout": "4:4:4"
  },
  "children": [
    { "componentName": "Column", "props": { "fieldId": "column_1" } },
    { "componentName": "Column", "props": { "fieldId": "column_2" } },
    { "componentName": "Column", "props": { "fieldId": "column_3" } }
  ]
}

常用属性

生成字段 ID

字段 ID 格式：组件类型_随机后缀，例如：

• textField_abc123
• numberField_def456
• selectField_ghi789

示例 App ID

当前应用：APP_F22M8EK6I2HZTBIYV3U5