Goal: find the right API by task. This version keeps API names, constants, parameter shapes, examples, and pitfalls, while removing screenshots, GIFs, and long demo text.
Scope
#- Global object:
window.WeFormSDK. - Form instance:
window.WeFormSDK.getWeFormInstance(moduleKey?, formId?, dataId?). - Entry points: form designer source/code block or the
ecode development platform. - Async entry: get the instance after
window.ebuilderSDK.getPageSDK().on('formReady', callback). - Fallback entry:
window.onFormReady = function (props) {}, but it is a single global callback and may be overwritten. - Runtime check:
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);
});
Instance Lookup
#| Case | API | Notes |
|---|
| Active form | window.WeFormSDK.getWeFormInstance() | Common in simple code blocks. |
| Module isolation | window.WeFormSDK.getWeFormInstance(moduleKey) | Use when one page has multiple modules. |
| Module + form isolation | window.WeFormSDK.getWeFormInstance(moduleKey, formId) | Avoid reading another form instance. |
| Module + form + data isolation | window.WeFormSDK.getWeFormInstance(moduleKey, formId, dataId) | Prefer this on multi-form pages. |
Action Events
#Before-action Guards
#weFormSdk.registerCheckEvent(type, fn) runs before an operation. Call successFn() to continue; call failFn() or do not continue to block.
| Constant | Usage |
|---|
WeFormSDK.OPER_SAVE | Before save. |
WeFormSDK.OPER_ADDROW + detailMark | Before adding a detail row. |
WeFormSDK.OPER_DELROW + detailMark | Before deleting a detail row. |
WeFormSDK.OPER_BEFOREVERIFY | Before required-field validation. |
js
weFormSdk.registerCheckEvent(window.WeFormSDK.OPER_SAVE, function (successFn, failFn) {
if (window.WeFormSDK.isMobile()) successFn();
else failFn();
});
After-action Hooks
#weFormSdk.registerAction(type, fn) runs after an action. It can be registered multiple times and runs in registration order.
| Constant | Usage |
|---|
WeFormSDK.ACTION_ADDROW + detailMark | After adding a detail row; callback receives the new row index. |
WeFormSDK.ACTION_DELROW + detailMark | After deleting detail rows; callback receives deleted indexes. |
WeFormSDK.ACTION_FORM_SUBMIT | After form submit. |
WeFormSDK.ACTION_FORM_SAVE | After form save. |
WeFormSDK.ACTION_DATA_LINKAGE | After data linkage completes. |
js
const detailMark = weFormSdk.convertFieldNameToId('detail_code', 'main', true);
weFormSdk.registerAction(window.WeFormSDK.ACTION_ADDROW + detailMark, function (index) {
console.log('add row:', index);
});
Field APIs
#| Task | API | Key Point |
|---|
| Convert field code to field mark | weFormSdk.convertFieldNameToId(fieldName, symbol?, prefix?) | symbol can be main or a detail mark; prefix=true returns the field prefix. |
| Read value | weFormSdk.getFieldValue(fieldMark) | Reads text, select values, and browser IDs. |
| Write value | weFormSdk.changeFieldValue(fieldMark, valueInfo) | Triggers linkage/drill actions; option matrix data is not supported. |
| Change display state | weFormSdk.changeFieldAttr(fieldMark, viewAttr) | 1 read-only, 2 editable, 3 required, 4 hidden. |
| Write value and state | weFormSdk.changeSingleField(fieldMark, valueInfo?, variableInfo?) | Use for one field when value and state change together. |
| Batch write | weFormSdk.changeMoreField(changeDatas, changeVariable?) | Update many fields in one call. |
| Get field metadata | weFormSdk.getFieldInfo(fieldMark) | Returns field name, type, display attribute, and related metadata. |
Value Shapes
#js
// Text, date, select
weFormSdk.changeFieldValue(textFieldMark, { value: 'text' });
weFormSdk.changeFieldValue(selectFieldMark, { value: '4765016625940566613' });
weFormSdk.changeFieldValue(dateFieldMark, { value: '2026-07-03' });
// Multi-level select or date range usually uses comma-separated values
weFormSdk.changeFieldValue(selectFieldMark, { value: 'id1,id2' });
// Browser fields use specialObj in the E10 reference
weFormSdk.changeFieldValue(browserFieldMark, {
specialObj: [
{ id: '718974312893816832', name: 'Example 1' },
{ id: '718974312893816833', name: 'Example 2' }
]
});
Field Events
#| Task | API | Notes |
|---|
| Main-field change | weFormSdk.bindFieldChangeEvent(fieldMarkStr, fn) | Join multiple fields with commas. |
| Detail-field change | weFormSdk.bindDetailFieldChangeEvent(fieldMarkStr, fn) | Works for existing and newly added rows. |
| Field-area action | weFormSdk.bindFieldAction(type, fieldMarkStr, fn) | type supports onblur, onfocus, onclick, ondbclick, mouseover, mouseout. |
js
weFormSdk.bindFieldChangeEvent(textFieldMark + ',' + selectFieldMark, function (id, value) {
console.log(id, value);
});
Detail-table APIs
#| Task | API | Notes |
|---|
| Add row | weFormSdk.addDetailRow(detailMark, initAddRowData?) | initAddRowData can set initial field values. |
| Delete row | weFormSdk.delDetailRow(detailMark, rowIdMark) | Deletes by row mark. |
| List row marks | weFormSdk.getDetailAllRowIndexStr(detailMark) | Returns a comma-separated string. |
| Count rows | weFormSdk.getDetailRowCount(detailMark) | Count only; do not use as direct row indexes. |
| Get display serial by row mark | weFormSdk.getDetailRowSerailNum(detailMark, rowId) | Original API spelling is Serail. |
| Copy last row on add | weFormSdk.setDetailAddUseCopy(detailMark, needCopy) | Usually set after initialization. |
| Get row mark by index | weFormSdk.getDetailRowIdByIndex(detailMark, index) | Used by the original demo; verify availability in the target environment. |
js
const detailMark = weFormSdk.convertFieldNameToId('detail_code', 'main', true);
const detailTextMark = weFormSdk.convertFieldNameToId('detail_text');
weFormSdk.addDetailRow(detailMark, {
[detailTextMark]: { value: 'new detail value' }
});
const rowIds = weFormSdk.getDetailAllRowIndexStr(detailMark);
Global APIs
#| Task | API | Notes |
|---|
| Read form context | weFormSdk.getBaseInfo() | Module, form, data, and request context. |
| Message | window.WeFormSDK.showMessage(msg, type?, duration?, isStatic?) | Type, duration, and static display can be controlled. |
| Confirm | window.WeFormSDK.showConfirm(content, okEvent?, cancelEvent?, otherInfo?, isStatic?) | System confirm dialog. |
| Custom dialog | window.WeFormSDK.openCustomDialog(prop) | The returned object usually supports destroy(). |
| Reload page | weFormSdk.reloadPage(params?) | The source signature appears to miss the initial r in one place. |
| Append submit params | weFormSdk.appendSubmitParam(params) | Read on the server from request parameters. |
| Trigger required validation | weFormSdk.verifyFormRequired(mustAddDetail?, fieldRequired?) | Controls required detail and field validation. |
| Global loading | WeFormSDK.getLoadingGlobal().start/end/destroy | Useful around long async work. |
js
window.WeFormSDK.showConfirm('Continue?', function () {
weFormSdk.appendSubmitParam({ cus_source: 'ecode' });
});
Field-type APIs
#| Task | API | Limit |
|---|
| Add browser data URL params | weFormSdk.appendBrowserDataUrlParam(fieldMark, jsonParam) | Browser fields; backend browser interface must read the params. |
| Read browser option IDs | weFormSdk.getBrowserOptionId(fieldMark, splitChar?) | Non-date browser fields; source marks it as pending release. |
| Read browser display names | weFormSdk.getBrowserShowName(fieldMark, splitChar?) | Joins multiple values with splitChar. |
| Remove select options | weFormSdk.removeSelectOption(fieldMark, optionKeys) | Select fields; comma-separated option keys. |
| Read select display names | weFormSdk.getSelectShowName(fieldMark, splitChar?) | Select fields. |
| Read option browser entity | weFormSdk.getBrowserOptionEntity(fieldMark, splitChar?) | Option-like fields; verify in the target environment because the source example is inconsistent. |
Reusable Templates
#Field Linkage
#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);
});
Detail Iteration
#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));
});
Pitfalls
#- In
ecode, do not keep the weFormSdk instance in a long-lived global variable; save/refresh actions may replace the form instance. - If field marks or
getBaseInfo() return undefined, the code is probably running too early; move it into formReady. - On pages with multiple forms, prefer
getWeFormInstance(moduleKey, formId, dataId). - Prefer
changeFieldValue and other SDK APIs over direct DOM operations. - Browser field assignment uses
specialObj in this E10 reference; E9 examples commonly use specialobj.
