weaver-e10-builder 1.5.13 → 1.5.15

package/skill-docs/references/code-block/ref-recipes.md

@@ -0,0 +1,164 @@
+# 按效果查代码模式
+
+本页覆盖原案例中的独立做法。字段 Key、接口和字段对象均需替换为目标表单真实数据；示例中出现的模拟接口、固定附件对象和测试 ID 不能作为正式值。
+
+| 想要的效果 | 组合方法 | 关键检查 |
+|---|---|---|
+| 保存前汇总明细人员到主表并去重 | `registerCheckEvent(OPER_SAVE)` → `getDetailAllRowIndexStr` → 逐行 `getBrowserOptionEntity` → 按 id 去重 → `changeFieldValue(...,{specialObj})` → `successFn` | 空行、重复人员、失败回调；仅拦表单保存 |
+| 附件字段回填且可预览 | 从附件模块/现有字段取完整对象 → `changeFieldValue(...,{specialObj:[{id,name,data,type:'file'}]})` | 文件权限、预览/下载入口；不可只传 id/name |
+| 多级选项等复杂值赋值 | 先 `getFieldObj` 观察已有对象 → 按 `data.content` 或 `data.dataOptions` 等原结构写 `specialObj` | 选项模板、次级选项正确显示 |
+| 将明细富文本显示为按钮或链接 | `getDetailAllRowIndexStr` 遍历每行 → `proxyFieldComp` 替换该行内容；添加行事件补新行 | 点击跳转地址与作用范围 |
+| 按两个维度分类、累加到另一明细表 | `getDetailData` 建组合 Key → 对目标行更新/新增/删除 → 监听来源值变化和增删行 | 组合 Key 唯一、消失分组删除、重复事件 |
+| 全表单跨模块识别字段并回填外部数据 | 全局 ecode `onFormReady` 取当前实例并限制 module/formId → 字段事件 → 调受支持接口 → `changeMoreField` | 权限、数据范围、主表/明细位置、失败与清空逻辑 |
+| 明细数字合计并算各行占比 | 读取明细每行数值 → `reduce` 求和 → 主表回写 → 逐行占比赋值；监听值变化及增删行 | 空值、非数字、总额 0、精度 |
+| 联动带出后再汇总并触发后续联动 | 对带出字段监听联动 scope → 汇总 → 写主表 → 必要时 `triggerFieldAllLinkage` | 避免循环；确认事件是否实际触发 |
+| 合并多个主表浏览/选项字段 | 多字段 `getBrowserOptionEntity` → 合并或按 id 去重 → 主表 `specialObj` 赋值 | 是否保留重复项、空字段 |
+| 按同行条件选择明细人员合并到主表 | `getDetailData` → 判断同行选项值 → 取人员对象 → 去重 → `changeFieldValue` | 条件变化、增删行后重算 |
+| 子明细按父行汇总金额 | 父、子关系字段匹配 → 筛子表数据 → 合计 → 回写父表指定 `rowId` | 父标识唯一、子行归属、父行删除后的处理 |
+| 按显示序号生成明细值 | 明细行数组按显示顺序 `map((row,index)=>...)` → `changeDetailData`；监听增删行 | 排序后重新计算，避免把序号当 rowId |
+| 某字段为空时触发另一字段联动 | `getFieldValue` 判空 → `triggerFieldAllLinkage(target)`；载入与源字段变化均执行 | 空字符串、0 与未选择的判定 |
+| 自定义页面参数传递/组件换肤 | 全局 ecode `regOvProps` 或表单字段 `proxyFieldContentComp`，按生效范围选择 | 组件名/props 契约、编译入口 |
+
+上述模式涉及的完整 API、参数与风险分别见 [事件](ref-events-validation.md)、[字段](ref-foundations-fields.md)、[明细](ref-details.md)、[控件](ref-controls.md) 和 [组件交互](ref-ui-global.md)。原案例存在重复与少量不完整代码：例如重复的“保存前汇总人员”，附件数据依赖文档模块，组件 props 示例有语法笔误，数字合计示例用 `eval`，全局回填示例包含模拟数据。这里保留其实现思路，代码应按专题中可运行的结构重新组装。
+
+## 保存前汇总明细人员并去重
+
+先定位明细、明细人员字段和主表目标字段；仅在表单数据保存前执行。需要流程“提交”时改用流程 SDK 的节点提交事件。
+
+```js
+const table = formSdk.convertFieldNameToId('people_detail', 'main');
+const detailPerson = formSdk.convertFieldNameToId('person', table);
+const mainPeople = formSdk.convertFieldNameToId('all_people', 'main');
+formSdk.registerCheckEvent(window.WeFormSDK.OPER_SAVE, (ok, stop) => {
+  try {
+    const rowIds = (formSdk.getDetailAllRowIndexStr(table) || '').split(',').filter(Boolean);
+    const unique = new Map();
+    for (const rowId of rowIds) {
+      for (const item of formSdk.getBrowserOptionEntity(`${detailPerson}_${rowId}`) || []) {
+        if (item?.id) unique.set(String(item.id), item);
+      }
+    }
+    formSdk.changeFieldValue(mainPeople, {specialObj: [...unique.values()]});
+    ok();
+  } catch (error) {
+    stop({msg: '人员汇总失败，请检查明细数据'});
+  }
+});
+```
+
+## 明细数值汇总并计算占比
+
+值变化、增行、删行和初次载入都要重新计算；`getDetailData` 的每行包含 `rowId`。示例以数值 0 处理空值，业务若要求空值报错，应另作校验。
+
+```js
+const table = formSdk.convertFieldNameToId('cost_detail', 'main');
+const detailAmount = formSdk.convertFieldNameToId('amount', table);
+const detailShare = formSdk.convertFieldNameToId('share', table);
+const mainTotal = formSdk.convertFieldNameToId('total', 'main');
+function recalculate() {
+  const rows = formSdk.getDetailData(table) || [];
+  const total = rows.reduce((sum, row) => sum + Number(row[detailAmount]?.value || 0), 0);
+  formSdk.changeFieldValue(mainTotal, {value: String(total)}, {jsApiChange: false});
+  for (const row of rows) {
+    const amount = Number(row[detailAmount]?.value || 0);
+    formSdk.changeFieldValue(`${detailShare}_${row.rowId}`, {value: String(total ? amount / total : 0)}, {jsApiChange: false});
+  }
+}
+formSdk.bindFieldChangeEvent(detailAmount, recalculate);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_ADDROW}${table}`, recalculate);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_DELROW}${table}`, recalculate);
+recalculate();
+```
+
+如汇总源值本身来自字段联动，普通字段变化事件可能不触发；依目标基线使用 `scope: window.WeFormSDK.CHANGE_EVENT_LINKAGE` 或监听 `ACTION_DATA_LINKAGE`。占比输出为 0～1 还是 0～100，须按目标字段的百分比显示方式确定。不要直接打开全局联动事件开关而不检查既有监听是否形成循环。
+
+## 父子明细按关系字段回写
+
+父、子明细的关系字段值相同才能归属同一父行。先配置真实二级明细关系，再对每个父行筛选对应子行。这里的业务主键与 `rowId` 分开。
+
+```js
+const parentTable = formSdk.convertFieldNameToId('parent_detail', 'main');
+const childTable = formSdk.convertFieldNameToId('child_detail', 'main');
+const parentKey = formSdk.convertFieldNameToId('parent_key', parentTable);
+const parentTotal = formSdk.convertFieldNameToId('parent_total', parentTable);
+const childKey = formSdk.convertFieldNameToId('child_parent_key', childTable);
+const childAmount = formSdk.convertFieldNameToId('child_amount', childTable);
+function recalculateParents() {
+  const children = formSdk.getDetailData(childTable) || [];
+  for (const parent of formSdk.getDetailData(parentTable) || []) {
+    const key = parent[parentKey]?.value;
+    const total = children.filter(row => row[childKey]?.value === key)
+      .reduce((sum, row) => sum + Number(row[childAmount]?.value || 0), 0);
+    formSdk.changeFieldValue(`${parentTotal}_${parent.rowId}`, {value: String(total)}, {jsApiChange: false});
+  }
+}
+formSdk.bindFieldChangeEvent(childAmount, recalculateParents);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_ADDROW}${childTable}`, recalculateParents);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_DELROW}${childTable}`, recalculateParents);
+recalculateParents();
+```
+
+关系字段若为选项而非文本，按 `getFieldObj` 的 `specialObj` 比较 ID。父行标识必须唯一；删除父行后的子行处置应由业务规则明确。用 `getDetailData` 复制子行时不要复制旧 `rowId`。
+
+## 来源明细按两列分组，同步到目标明细
+
+来源中按“部门 ID + 类型 ID”分组求和；目标中已有分组更新、缺失分组新增、来源已消失的分组删除。监听来源的两列条件字段、数值字段与增删行事件。下面只展示同步函数，绑定方式同上方汇总案例。
+
+```js
+function syncGroups(sourceTable, targetTable, sourceDept, sourceType, sourceAmount,
+                    targetDept, targetType, targetAmount) {
+  const groups = new Map();
+  for (const row of formSdk.getDetailData(sourceTable) || []) {
+    const dept = row[sourceDept]?.specialObj?.[0];
+    const type = row[sourceType]?.specialObj?.[0];
+    if (!dept?.id || !type?.id) continue;
+    const key = `${dept.id}:${type.id}`;
+    const item = groups.get(key) || {dept, type, total: 0};
+    item.total += Number(row[sourceAmount]?.value || 0);
+    groups.set(key, item);
+  }
+  const existing = new Map();
+  for (const row of formSdk.getDetailData(targetTable) || []) {
+    const deptId = row[targetDept]?.specialObj?.[0]?.id;
+    const typeId = row[targetType]?.specialObj?.[0]?.id;
+    if (!deptId || !typeId || !groups.has(`${deptId}:${typeId}`)) {
+      formSdk.delDetailRow(targetTable, row.rowId);
+    } else {
+      existing.set(`${deptId}:${typeId}`, row.rowId);
+    }
+  }
+  for (const [key, item] of groups) {
+    const rowId = existing.get(key);
+    if (rowId) {
+      formSdk.changeFieldValue(`${targetAmount}_${rowId}`, {value: String(item.total)}, {jsApiChange: false});
+    } else {
+      formSdk.addDetailRow(targetTable, {
+        [targetDept]: {specialObj: [item.dept]},
+        [targetType]: {specialObj: [item.type]},
+        [targetAmount]: {value: String(item.total)}
+      });
+    }
+  }
+}
+```
+
+这种同步会删除目标中无来源的行，只有目标表完全由来源派生时才适用；若允许用户手工维护目标行，应改为保留手工行并有明确的来源标识。跨字段 `id` 类型与数值精度须按实际表单处理。
+
+## 根据明细同行条件筛人员，合并到主表
+
+对每行读取条件选项，按不同条件分别取对应人员字段，再按人员 ID 去重并写入主表。初次载入、条件/人员字段变化、明细增删行均重新执行。
+
+```js
+function syncPeople(table, conditionField, firstPeopleField, secondPeopleField, mainPeopleField) {
+  const people = new Map();
+  for (const row of formSdk.getDetailData(table) || []) {
+    const choice = row[conditionField]?.specialObj?.[0]?.id;
+    const selected = choice === '0' ? row[firstPeopleField]?.specialObj :
+      choice === '1' ? row[secondPeopleField]?.specialObj : [];
+    for (const person of selected || []) if (person?.id) people.set(String(person.id), person);
+  }
+  formSdk.changeFieldValue(mainPeopleField, {specialObj: [...people.values()]}, {jsApiChange: false});
+}
+```
+
+条件选项 ID `'0'/'1'` 是示例占位，须读取真实选项 ID。若人员字段由系统联动带出，还要按[事件指南](ref-events-validation.md)监听联动完成事件。

package/skill-docs/references/code-block/ref-troubleshooting.md

@@ -0,0 +1,49 @@
+# JSSDK 排查、版本与边界
+
+## 代码不生效时
+
+1. 确认保存的是目标表单的目标布局及目标终端，或正确的表单级/全局 ecode；JS 编译通过且代码已启用，CSS 单独保存。浏览器打开的是最新布局而非另一设备布局。
+2. 确认 `formSdk` 取自当前表单实例；全局 ecode 用 `onFormReady` 的事件实例并限定 formId/module。较早基线的 `pageSdk.on('formReady')` 与新基线闭包方式不要混用到未支持的入口。
+3. 用 `getBaseInfo`、`convertFieldNameToId`、`getFieldInfo` 检查当前表单和字段；数据 Key 不是字段名或物理表名。明细字段要指定明细表位置，行操作要取得真实 `rowId`。
+4. 用 `getFieldObj` 对照目标类型的数据形状。文本/数字/日期常用 `{value}`；浏览/动态选项/附件常用 `{specialObj}`。附件预览还依赖完整 `data`。
+5. 检查事件是否属于“表单保存”“流程提交”“用户改变”“联动改变”中的哪一种；必要时分开绑定。拦截回调必须调用通过或阻断函数；异步超时约 25 秒。
+6. 检查权限和组件边界。流程节点默认只读或权限锁定的字段，不能仅靠 `changeFieldAttr(2)` 放开；JS 渲染也不改变后端权限。
+
+开发调试时可按环境入口临时屏蔽不同层级二开：ecode 平台、全局初始化代码、布局源码对应不同入口。调试开关仅用于定位，不作为正式配置。对含多表单、父子页面、明细新行的场景，还要检查实例、`postMessage` 来源与渲染时机。
+
+## 设计器源码面板为空 / ECode decode failed
+
+- **症状**：打开布局源码时控制台报 `ECode decode failed, SyntaxError: Expected ':' after property name in JSON at position 5`，源码面板为空，预览按钮失效。
+- **原因**：`sourceCode.ecode` 被 `encodeURIComponent` 写入。设计器用 `JSON.parse(decodeURI(ecode))` 读取，而 `decodeURI` 不还原 `%3A`（冒号），JSON 变成 `{"js"%3A...}`。
+- **处理**：用 `form code layout set` / `wf-form code layout set` 重新写入（CLI 已使用 `encodeURI`，并在写入前、回读后按设计器路径自检）。临时恢复可把 `sourceCode.ecode` 置为空字符串，再用空 JS/CSS 文件重写。
+- **手工调接口**：必须用 `encodeURI(JSON.stringify({js, css}))`，不要用 `encodeURIComponent`。
+
+## 基线速查
+
+| 功能 | 原技术资料标注的最低基线 |
+|---|---|
+| `changeFieldValue` 的联动控制参数 | 241001 |
+| `valueInfo.type/contentObj` 特殊字段 | 241201 |
+| 字段联动拦截及联动动作的 `runData` | 240601 |
+| 字段变化事件的联动 `scope` | 250401；明细专用事件的扩展参数 250901 |
+| 明细批量添加 `addDetailData` | 241201 |
+| 布局/表单代码直接取得当前 `formSdk` | 主体说明标注 250101；另有一处写 241201，稳妥按 250101 判断 |
+| 明细批量更新 `changeDetailData` | 250101 |
+| `changeTabItemAttr` | 20250501 |
+| `controlOptionDisable` | 20250501 |
+| `convertFieldNameToId` 用明细表数据 Key 定位明细字段 | 260601 |
+| `getDetailData` 按当前明细筛选条件取数 | 260401 |
+| `triggerFieldAllLinkage(...).then(...)` | 250901 |
+| 联动赋值导致的明细行变化事件扩展 | 251101 |
+| `pluginGet/pluginExecute` | 260201 |
+
+先确认目标环境版本和实际 API 可用性；未达到基线时不要假设同名功能可用。
+
+## 原案例中需纠正的写法
+
+- 字段赋值示例声明 `textFieldMark` 后却调用 `fieldMark`，日期示例声明 `dateFieldMark` 后调用 `selectFieldMark`；按真正声明的目标字段写。
+- 字段属性示例的明细行模板字符串缺少引号闭合；正确形式为 `` `${detailField}_${rowId}` ``。
+- `getFieldCom` 章节示例调用了 `getFieldInfo`；两者用途不同，前者为组件引用，后者为字段信息。
+- 明细“默认使用末行”章节的示例实际调用 `setDetailAddUseCopy`；先确认所需是复制末行，而非仅控制默认光标或位置。
+- 案例中的 `eval(numbers.join('+'))`、测试 URL、固定附件元数据、模拟外部查询结果不能直接用于业务配置。数值合计用显式转换与 `reduce`，外部接口须有真实契约。
+- 全局 ecode 的 `import`、JSX、`regOvProps` 示例不要直接粘入布局源码；按目标编辑器支持的语法重写。布局源码中的局部字段组件复写则按其 API 单独处理。

package/skill-docs/references/code-block/ref-ui-global.md

@@ -0,0 +1,47 @@
+# 组件渲染、全局交互与扩展
+
+## 当前表单与全局操作
+
+`formSdk.getBaseInfo()` 读取当前表单基本信息；`formSdk.isMobile()` 判断移动端。布局级代码优先使用当前作用域 `formSdk`；提示、弹窗由全局 `window.WeFormSDK` 提供。
+
+| 效果 | API 与要点 |
+|---|---|
+| 提示 | `window.WeFormSDK.showMessage(message, type?, duration?)`；type 为 `1` 警告、`2` 错误、`3` 成功；时长单位秒 |
+| 确认 | `window.WeFormSDK.showConfirm(content, onOk, onCancel?, {title,okText,cancelText}?)`；title 仅 PC 有效 |
+| 自定义弹窗 | `window.WeFormSDK.openCustomDialog({content,width,height,onOk,onCancel,footer?,...})`；返回对象可 `destroy()` |
+| 页面刷新 | `formSdk.reloadPage(params?)` |
+| 提交附加参数 | `formSdk.appendSubmitParam({customParam:{...}})`；接收端仍须能处理该参数 |
+| 主动做必填检查 | `formSdk.verifyFormRequired(mustAddDetail?,fieldRequired?)` |
+| 全局加载 | `window.WeFormSDK.getLoadingGlobal()` 取加载控件，调用 `start()`、`end()`、`destroy()` |
+| 关闭页面提示 | `formSdk.setFormTipCloseStatus(true/false)`；只控制提示状态，不执行保存 |
+
+自定义 footer 使用 `@weapp/ui` 的 import/JSX 是 ecode 构建环境示例；布局源码只允许其编辑器可编译的语法和已暴露对象，不能直接套用 ecode 依赖。
+
+## 字段区域事件和局部渲染
+
+`bindFieldAction(type, fields, handler)` 绑定失焦、聚焦、点击、双击、移入/移出；事件类型为 `onblur/onfocus/onclick/ondbclick/mouseover/mouseout`。
+
+| 需求 | API |
+|---|---|
+| 将当前字段内容替换为自定义内容 | `proxyFieldComp(fieldMark, reactNode或文本, range?)` |
+| 在字段后追加内容 | `afterFieldComp(fieldMark, reactNode或文本, range?)` |
+| 用函数包装原字段内容并利用 props 决定样式 | `proxyFieldContentComp(fieldMark, (props, componentFn) => React.createElement(..., componentFn()))` |
+
+`range` 省略时作用于全部读写状态；`'1'` 只读、`'2'` 可编辑、`'3'` 必填，多个值以逗号分隔。`proxyFieldContentComp` 的回调必须返回组件，第二参数 `componentFn` 可生成原字段内容。`React` 可用性和编译语法要以目标代码入口为准。明细字段不加行 ID 可作用于整列，指定行则加 `_rowId`；新添行的专门逻辑应在添加行事件后检查是否生效。此能力是当前表单字段的局部渲染，不等于发布平台级新组件，也不等于改写后端接口。
+
+```js
+const field = formSdk.convertFieldNameToId('status', 'main');
+formSdk.proxyFieldContentComp(field, (props, original) =>
+  React.createElement('div', {style: {backgroundColor: props?.widgetValue?.content === '1' ? '#e3f2fd' : ''}}, original())
+);
+```
+
+## 插件与页面间通信
+
+260201 及以后基线提供 `formSdk.pluginGet(fieldMark, property)` 和 `formSdk.pluginExecute(fieldMark, method, ...args)`；只能操作该插件实际公开的属性/方法。具体 WPS 或其他插件须取得该插件契约，不能从 JSSDK 通用接口推断方法名。
+
+`window.open` 打开的子页面可通过 `window.opener` 访问父窗口；同源时可操作父页面的表单实例。跨源时用 `postMessage`，接收方检查 `event.origin` 和 `event.data.type`，发送方指定目标 origin；只发送必要数据，不传鉴权信息。
+
+子表控件数据变化后，如需刷新相关显示，布局源码中可调用 `pageSdk.events.emit('field.change', '纯数字字段ID')`；ecode 中可调用 `window.ebuilderSDK.getPageSDK().events.emit('field.change', '纯数字字段ID')`。原资料还提到可附第三个字段数据参数：文本传文本，浏览型传以逗号分隔的 ID；按实际刷新需求决定是否传值。此处第二参数是纯数字字段 ID，不是带 `field` 前缀的标识。
+
+全局 ecode 的 `regOvProps` 可复写特定组件 props，但其包名与目标组件名是项目级契约；它和布局内 `proxyFieldContentComp` 是不同层级。采用哪一层，应以所需生效范围为准。