整理目标：按“要做什么”找 API。本文保留接口名、常量、参数形态和常见坑点，不收录原文截图、GIF 和长演示。
使用范围
#- 全局对象：
window.WeFormSDK。 - 表单实例：
window.WeFormSDK.getWeFormInstance(moduleKey?, formId?, dataId?)。 - 开发入口：表单设计器源码/代码块、
ecode 开发平台。 - 异步入口：优先在
window.ebuilderSDK.getPageSDK().on('formReady', callback) 之后取实例。 - 兜底入口：
window.onFormReady = function (props) {}，但它是全局唯一回调，存在被覆盖风险。 - 终端判断：
window.WeFormSDK.isMobile()。
js
window.ebuilderSDK.getPageSDK().on('formReady', function () {
const weFormSdk = window.WeFormSDK.getWeFormInstance();
const fieldMark = weFormSdk.convertFieldNameToId('field_code', 'main', true);
console.log(fieldMark);
});
实例获取
#| 场景 | 写法 | 备注 |
|---|
| 当前活动表单 | window.WeFormSDK.getWeFormInstance() | 简单代码块常用。 |
| 按模块隔离 | window.WeFormSDK.getWeFormInstance(moduleKey) | 页面可能有多个模块时使用。 |
| 按模块和表单隔离 | window.WeFormSDK.getWeFormInstance(moduleKey, formId) | 防止拿到其他表单实例。 |
| 按模块、表单、数据隔离 | window.WeFormSDK.getWeFormInstance(moduleKey, formId, dataId) | 多表单或多数据窗口优先用细粒度参数。 |
动作事件
#执行前拦截
#weFormSdk.registerCheckEvent(type, fn) 在动作执行前触发。必须调用 successFn() 才会继续；调用 failFn() 或不放行会阻断。
| 常量 | 用途 |
|---|
WeFormSDK.OPER_SAVE | 保存前。 |
WeFormSDK.OPER_ADDROW + detailMark | 添加明细行前。 |
WeFormSDK.OPER_DELROW + detailMark | 删除明细行前。 |
WeFormSDK.OPER_BEFOREVERIFY | 必填校验前。 |
js
weFormSdk.registerCheckEvent(window.WeFormSDK.OPER_SAVE, function (successFn, failFn) {
if (window.WeFormSDK.isMobile()) successFn();
else failFn();
});
执行后钩子
#weFormSdk.registerAction(type, fn) 在动作完成后触发，支持多次注册，按注册顺序执行。
| 常量 | 用途 |
|---|
WeFormSDK.ACTION_ADDROW + detailMark | 添加明细行后，回调参数为新行下标。 |
WeFormSDK.ACTION_DELROW + detailMark | 删除明细行后，回调参数为删除下标集合。 |
WeFormSDK.ACTION_FORM_SUBMIT | 表单提交完成。 |
WeFormSDK.ACTION_FORM_SAVE | 表单保存完成。 |
WeFormSDK.ACTION_DATA_LINKAGE | 数据联动执行后。 |
js
const detailMark = weFormSdk.convertFieldNameToId('detail_code', 'main', true);
weFormSdk.registerAction(window.WeFormSDK.ACTION_ADDROW + detailMark, function (index) {
console.log('add row:', index);
});
字段基础操作
#| 要做什么 | API | 关键点 |
|---|
| 字段编码转字段标识 | weFormSdk.convertFieldNameToId(fieldName, symbol?, prefix?) | symbol 可传 main 或明细标识；prefix=true 返回带 field 前缀。 |
| 取字段值 | weFormSdk.getFieldValue(fieldMark) | 文本、选择框和浏览按钮主键值都走这个入口。 |
| 改字段值 | weFormSdk.changeFieldValue(fieldMark, valueInfo) | 会触发联动、钻取等；不支持选项矩阵二维数据。 |
| 改显示属性 | weFormSdk.changeFieldAttr(fieldMark, viewAttr) | 1 只读、2 可编辑、3 必填、4 隐藏。 |
| 同时改值和属性 | weFormSdk.changeSingleField(fieldMark, valueInfo?, variableInfo?) | 适合一次性改值并置只读/必填。 |
| 批量改字段 | weFormSdk.changeMoreField(changeDatas, changeVariable?) | 多字段一次更新，减少重复调用。 |
| 取字段信息 | weFormSdk.getFieldInfo(fieldMark) | 返回字段名称、类型、属性等信息。 |
值格式
#js
// 文本、日期、选择框
weFormSdk.changeFieldValue(textFieldMark, { value: '内容' });
weFormSdk.changeFieldValue(selectFieldMark, { value: '4765016625940566613' });
weFormSdk.changeFieldValue(dateFieldMark, { value: '2026-07-03' });
// 多级选择或日期区间通常用逗号拼接
weFormSdk.changeFieldValue(selectFieldMark, { value: 'id1,id2' });
// 浏览按钮使用 specialObj
weFormSdk.changeFieldValue(browserFieldMark, {
specialObj: [
{ id: '718974312893816832', name: '示例1' },
{ id: '718974312893816833', name: '示例2' }
]
});
字段事件和动作
#| 要做什么 | API | 备注 |
|---|
| 主表字段变化 | weFormSdk.bindFieldChangeEvent(fieldMarkStr, fn) | 多字段用逗号拼接；值变化即触发。 |
| 明细字段变化 | weFormSdk.bindDetailFieldChangeEvent(fieldMarkStr, fn) | 对已有行和新加行都生效。 |
| 字段区域动作 | weFormSdk.bindFieldAction(type, fieldMarkStr, fn) | type 支持 onblur、onfocus、onclick、ondbclick、mouseover、mouseout。 |
js
weFormSdk.bindFieldChangeEvent(textFieldMark + ',' + selectFieldMark, function (id, value) {
console.log(id, value);
});
明细表操作
#| 要做什么 | API | 备注 |
|---|
| 添加明细行 | weFormSdk.addDetailRow(detailMark, initAddRowData?) | initAddRowData 可传字段初始值。 |
| 删除明细行 | weFormSdk.delDetailRow(detailMark, rowIdMark) | 按行标识删除。 |
| 获取所有行标识 | weFormSdk.getDetailAllRowIndexStr(detailMark) | 返回逗号分隔字符串。 |
| 获取明细总行数 | weFormSdk.getDetailRowCount(detailMark) | 只表示总数，不建议直接当循环行号。 |
| 根据行标识取序号 | weFormSdk.getDetailRowSerailNum(detailMark, rowId) | 原接口名拼写为 Serail。 |
| 添加行默认复制最后一行 | weFormSdk.setDetailAddUseCopy(detailMark, needCopy) | 通常在初始化后设置。 |
| 按下标取行标识 | weFormSdk.getDetailRowIdByIndex(detailMark, index) | 原演示代码使用过，实际环境先验证可用性。 |
js
const detailMark = weFormSdk.convertFieldNameToId('detail_code', 'main', true);
const detailTextMark = weFormSdk.convertFieldNameToId('detail_text');
weFormSdk.addDetailRow(detailMark, {
[detailTextMark]: { value: '新增明细内容' }
});
const rowIds = weFormSdk.getDetailAllRowIndexStr(detailMark);
全局操作
#| 要做什么 | API | 备注 |
|---|
| 当前表单基础信息 | weFormSdk.getBaseInfo() | 取模块、表单、数据等上下文。 |
| 消息提示 | window.WeFormSDK.showMessage(msg, type?, duration?, isStatic?) | 可控制类型、时长和是否静态。 |
| 确认框 | window.WeFormSDK.showConfirm(content, okEvent?, cancelEvent?, otherInfo?, isStatic?) | 系统样式确认框。 |
| 自定义弹框 | window.WeFormSDK.openCustomDialog(prop) | 返回对象通常可 destroy()。 |
| 刷新页面 | weFormSdk.reloadPage(params?) | 原文签名处疑似写成 eloadPage。 |
| 追加提交参数 | weFormSdk.appendSubmitParam(params) | 服务端通过请求参数读取。 |
| 触发必填验证 | weFormSdk.verifyFormRequired(mustAddDetail?, fieldRequired?) | 可控制是否校验必须新增明细和字段必填。 |
| 全局 Loading | WeFormSDK.getLoadingGlobal().start/end/destroy | 适合长请求或批量处理。 |
js
window.WeFormSDK.showConfirm('确认继续？', function () {
weFormSdk.appendSubmitParam({ cus_source: 'ecode' });
});
特定字段类型
#| 要做什么 | API | 限定 |
|---|
| 扩展浏览按钮取数 URL 参数 | weFormSdk.appendBrowserDataUrlParam(fieldMark, jsonParam) | 浏览按钮；服务端接口需配合读取参数。 |
| 获取浏览按钮选项 ID | weFormSdk.getBrowserOptionId(fieldMark, splitChar?) | 非日期时间浏览按钮；原文标注待发布。 |
| 获取浏览按钮显示名 | weFormSdk.getBrowserShowName(fieldMark, splitChar?) | 多选时用分隔符拼接。 |
| 移除选择框选项 | weFormSdk.removeSelectOption(fieldMark, optionKeys) | 选择框；多个选项用逗号。 |
| 获取选择框显示名 | weFormSdk.getSelectShowName(fieldMark, splitChar?) | 选择框。 |
| 获取选项型字段浏览数据 | weFormSdk.getBrowserOptionEntity(fieldMark, splitChar?) | 原文示例疑似仍调用 getBrowserShowName，实际使用前验证。 |
常用模板
#字段联动模板
#js
window.ebuilderSDK.getPageSDK().on('formReady', function () {
const weFormSdk = window.WeFormSDK.getWeFormInstance();
const source = weFormSdk.convertFieldNameToId('source_code');
const target = weFormSdk.convertFieldNameToId('target_code');
function syncValue() {
const value = weFormSdk.getFieldValue(source);
weFormSdk.changeFieldValue(target, { value: value });
}
syncValue();
weFormSdk.bindFieldChangeEvent(source, syncValue);
});
明细遍历模板
#js
const detailMark = weFormSdk.convertFieldNameToId('detail_code', 'main', true);
const rowIdStr = weFormSdk.getDetailAllRowIndexStr(detailMark);
const rows = rowIdStr ? rowIdStr.split(',') : [];
rows.forEach(function (rowId) {
const fieldMark = detailFieldMark + '_' + rowId;
console.log(weFormSdk.getFieldValue(fieldMark));
});
排查清单
#ecode 中不要把 weFormSdk 实例长期挂到全局变量；流程保存、刷新数据后实例可能变化。- 取不到字段标识或
getBaseInfo() 都是 undefined 时，优先检查是否太早执行，改到 formReady 内。 - 同一页面可能打开多份表单时，尽量用
getWeFormInstance(moduleKey, formId, dataId)。 - 修改字段值优先用
changeFieldValue，不要直接操作 DOM。 - 浏览按钮赋值注意
specialObj 大小写；E9 常见写法是 specialobj，E10 原文写 specialObj。
