cloud-web-corejs 1.0.54-dev.73 → 1.0.54-dev.730

package/src/components/xform/XFormTabContainer//346/226/260/345/242/236/351/241/265/347/255/276/346/250/241/345/274/217-/346/234/200/347/273/210/345/256/236/347/216/260.md

@@ -0,0 +1,195 @@
+# xform 表单「新增页签模式」——最终实现（已落地）
+
+> 本文记录**实际已落地**的实现，替代前几版方案文档（`新增页签模式实现方案.md` / `新增页签模式-落地实施文档.md` / `新增页签模式-归一落地方案.md` / 弃用的 `IMPLEMENTATION_PLAN.md`）。
+> 需求：去掉固定「常规」页签承载新增 → 新增打开独立可关闭页签（标题"新增"）→ 保存后本页变编辑态（标题变名称字段）→ 提交（启动流程）后可配置「关闭页签回列表刷新」或「刷新本页」，并正确处理保存成功/提交失败/取消等边界。
+
+---
+
+## 一、最终交互与配置
+
+### 配置项（列表表单 formConfig，设计器「列表标签页信息」分组）
+
+| 字段 | 类型 | 默认 | 含义 |
+|------|------|------|------|
+| `addTabEnabled` | Boolean | `false` | 新增打开独立页签总开关。开启后新增走动态可关闭页签，不走「常规」 |
+| `submitBehavior` | String | `"closeToList"` | 提交后行为：`closeToList`（关页签回列表刷新）/ `refreshCurrent`（刷新本页出流程信息） |
+
+> 新增页签初始标题**固定为「新增」**，不提供配置项（保存后升级为名称字段值）。
+
+复用既有字段（未新造）：`hideNormalTab`（隐藏常规页签）、`multiTabLabelField`（页签标题字段，新增/编辑共用）、`multiTabEnabled`（编辑页签多开，语义不变）。
+
+> **配置位置统一在「列表表单」**，与 `multiTabEnabled` 同处。`submitBehavior` 运行时优先读列表表单配置。
+
+### 端到端行为（详情内容恰好刷新一次）
+
+| 分支 | 行为 | 详情刷新 |
+|------|------|:---:|
+| 新增保存（纯保存） | 页签升级编辑态、标题变名称字段、`dataId`=单号 | 1（编辑态重载） |
+| 保存并提交 → 提交成功 + `refreshCurrent` | 刷新本页，出流程信息 | 1 |
+| 保存并提交 → 提交成功 + `closeToList` | 关当前页签 → 切列表 → 刷新列表 | 0（详情） |
+| 保存并提交 → 提交失败 / 取消候选人弹框 | 刷新当前详情到编辑态（不重复入库） | 1 |
+| 直接启动流程（`wfStartBindSave` 开）→ 失败/取消 | 刷新到编辑态 | 1 |
+| **直接启动流程（`wfStartBindSave` 关）→ 失败/取消** | **不刷新表单** | 0 |
+| 直接启动流程 → 成功 | 按 `submitBehavior` 关页签/刷新 | 0 或 1 |
+
+---
+
+## 二、设计要点
+
+1. **归一**：新增 = 一个「还没有单号的编辑页签」，复用现有 `x-tabs` + `editTab` 插槽机制，不另写容器/分支体系。
+2. **合成唯一 id**：新增时给虚拟 row 合成 `id = tabName = "add_<时间戳>_<随机>"`，使 `x-tabs` 去重（按 `data.id`）/`tabName`/`paneName` 三者对齐；`dataId` 显式置 `null`，避免被当真实单号去 `getOne`。
+3. **元数据升级与内容重载解耦**：表单不 `watch` `dataId`，故改 `tab.dataId` 不触发重载。保存成功先只升级页签元数据（`dataId`/`isAdd`/`formCode`/标题），内容的那一次刷新交给流程结束后的分支，保证详情不刷两次。
+4. **wf 组件零业务耦合**：`wf.js` 只认通用钩子 `option.onStartSuccess` / `onStartFail` / `onCancel`，页签相关逻辑全部收在 xform 侧（`indexMixin`）。
+5. **两个入口统一**：「保存并提交」（`defaultHandle`）与「直接启动流程」（`indexMixin` 构造的 wf option）都通过同一批 xform 方法处理。
+
+---
+
+## 三、改动清单（实际代码）
+
+### 1. `components/xform/utils/util.js` — `getDefaultFormConfig()`
+新增 2 个默认字段（**真正生效的默认值源**，非 designer.js 内联对象）：
+```js
+addTabEnabled: false,
+submitBehavior: "closeToList",
+```
+
+### 2. `components/xform/form-designer/setting-panel/form-setting.vue`
+「列表标签页信息」分组新增：`addTabEnabled` 开关、`submitBehavior` 单选（新增页签标题固定「新增」，无输入项）。
+
+### 3. `components/vb-tabs/x-tabs.vue` — `removeTab` 既有 bug 修复
+`tabNameEnable=true` 且关闭非首个页签时引用了未定义的 `tab`，修为 `this.tabs[tabIndex-1]`：
+```js
+let prev = this.tabs[tabIndex - 1];
+this.activeName = tabNameEnable ? prev.tabName : prev.data[paneKeyName] + "";
+```
+
+### 4. `views/user/form/view/list.vue`
+
+**`openEditDialog`** — 归一分支，新增合成唯一 id、`dataId:null`、`isAdd`：
+```js
+let isAdd = !dataId;
+let addTab = formConfig.addTabEnabled && isAdd && tabLabelField;
+if ((multiTabEnabled && dataId) || addTab) {
+  let key = isAdd ? "add_" + Date.now() + "_" + Math.random().toString(36).slice(2,6) : dataId;
+  let openRow = isAdd ? { ...row, id: key, [tabLabelField]: "新增" } : row;
+  this.$refs.xTabs.openEditTab(openRow, param, {
+    tabParam: { formCode, tabLabelField, tabName: key, isAdd, ...(isAdd ? { dataId: null } : {}) },
+  });
+} else { /* 原「常规」分支不变 */ }
+```
+
+**新增方法**（`editTab` 插槽 `@reload` 改为 `(...args) => onEditTabReload(tab, ...args)`）：
+- `resolveFormModel(target)`：逐级解析真实表单 `formDataModel`（`target` → `target.$refs.vFormRef` → `target.getFormRef()`）。
+- `applyTabSaveResult(tab, dataId, formCode, formModel)`：升级编辑态 + 同步标题（标题取名称字段值，无值不回退单号）。**不含内容重渲染**。
+- `onEditTabReload(tab, target, param)`：纯保存路径 → `applyTabSaveResult` + `reloadTabContent`（重渲染）。
+- `promoteActiveAddTab(dataId, formCode, target)`：保存并提交路径 → 只对当前活动页签 `applyTabSaveResult`，**不重渲染**。
+
+### 5. `components/xform/mixins/defaultHandle.js` — `saveAndSubmitWfHandle`
+保存成功回调里：**先只升级页签元数据**（不刷详情），再开流程弹框，注入统一钩子：
+```js
+success: (res) => {
+  let editFormCode = formConfig.editFormCode;
+  let listPageRef = formRef.getListPageRef && formRef.getListPageRef();
+  if (listPageRef && listPageRef.promoteActiveAddTab) {
+    listPageRef.promoteActiveAddTab(res.objx, editFormCode, formRef); // 元数据升级，防重复入库，不刷详情
+  }
+  openStartWfDialog(formRef, {
+    objId: res.objx, wfCode: ..., formCode: ..., serviceId: ..., skipStartConfirm: true,
+    onStartSuccess: () => formRef.onWfStartSuccess && formRef.onWfStartSuccess(),
+    onStartFail:   () => formRef.onWfStartAbort  && formRef.onWfStartAbort(),   // 有保存 → 失败刷编辑态
+    onCancel:      () => formRef.onWfStartAbort  && formRef.onWfStartAbort(),   // 有保存 → 取消刷编辑态
+  });
+  option?.config?.success && option.config.success(res);
+},
+```
+
+### 6. `components/xform/form-render/indexMixin.js`
+
+**wf option 构造处**（直接启动按钮入口，约 L1379）：
+```js
+onStartSuccess: () => this.onWfStartSuccess(),   // 成功始终处理
+// ...
+if (formConfig.wfStartBindSave) {                // 仅当伴随自动保存时，失败/取消才刷新
+  option.onStartFail = () => this.onWfStartAbort();
+  option.onCancel   = () => this.onWfStartAbort();
+  option.onStart = ...; option.onBeforeStartSubmit = ...; // 既有自动保存逻辑
+}
+```
+
+**新增方法**（`switchToListTab` 附近）：
+```js
+getAddTabContext() {
+  // 返回 {xTabs, currentName, submitBehavior}，仅当处于开启 addTabEnabled 的动态页签内；否则 null
+}
+onWfStartSuccess() {
+  let ctx = this.getAddTabContext();
+  if (ctx) {
+    if (ctx.submitBehavior === "refreshCurrent") this.$baseReload();
+    else { this.switchToListTab({ handleType: "reload" }); ctx.xTabs.removeTab(ctx.currentName); }
+    return;
+  }
+  this.$baseReload(); // 非本模式：原默认行为
+}
+onWfStartAbort() {
+  // 失败/取消：本模式下刷新当前详情到编辑态（dataId 已升级为单号）；非本模式不处理
+  if (this.getAddTabContext()) this.$baseReload();
+}
+```
+> `getAddTabContext` 判定：当前页签名非 `first`/`second`/`otherTab*`，且列表表单 `addTabEnabled` 为真。
+
+### 7. `components/wf/wf.js` — `wfStartMixin`（仅通用钩子，无业务逻辑）
+- `data` 增 `wfSubmitted: false`。
+- `startSubmitHanlde` 首行 `this.wfSubmitted = true;`（进入提交后关闭弹框不算取消）。
+- 新增 `handleWfCancel()`：未提交则一次性回调 `option.onCancel`（防多弹框重复触发）。
+- `close()` 调 `handleWfCancel()`；新增 `watch.showSetCandidateDialog2`：候选人弹框未提交就关闭 → `handleWfCancel()`。
+- 失败分支沿用既有 `option.onStartFail && option.onStartFail()`。
+
+---
+
+## 四、关键边界与结论
+
+- **多次新增不覆盖**：合成唯一 id 保证每次新增各开一页签。
+- **新增不误触发 getOne**：`tabParam.dataId = null` 覆盖 x-tabs 默认取 `row.id`。
+- **标题**：取名称字段（`multiTabLabelField`）真实值，编辑态改名再保存会同步；无值保持原标题不回退单号。
+- **防重复入库**：保存成功即升级 `tab.dataId`=单号，提交失败/取消后再保存走更新。
+- **详情最多刷一次**：元数据升级不重渲染，内容刷新集中在流程结束分支。
+- **wf 解耦**：`wf.js` 仅新增通用 `onCancel` 钩子；页签逻辑全在 xform。
+- **`wfStartBindSave` 关 + 直接启动 + 失败/取消**：无保存，不注入 abort 钩子 → 不刷新表单。
+- **向后兼容**：`addTabEnabled` 默认 false，存量表单（含 `multiTabEnabled=true`）行为不变；非 xform 的 wf 表单不受影响。
+
+---
+
+## 五、测试清单
+
+| # | 场景 | 预期 |
+|---|------|------|
+| 1 | 旧表单未开 `addTabEnabled` 点新增 | 走「常规」，不变 |
+| 2 | 存量 `multiTabEnabled=true` 未开 `addTabEnabled` | 编辑开页签，新增仍走常规 |
+| 3 | 连续点新增 | 各开一页签，不覆盖 |
+| 4 | 新增点开 | 空白新增表单，不调 getOne |
+| 5 | 新增保存 | 标题变名称字段、转编辑态、`dataId` 正确、不新开页签、详情刷一次 |
+| 6 | 编辑态改名再保存 | 页签标题同步为新名称 |
+| 7 | 保存并提交成功 + `refreshCurrent` | 详情刷一次，出流程信息 |
+| 8 | 保存并提交成功 + `closeToList` | 关页签、切列表、列表刷新 |
+| 9 | 保存并提交 → 提交失败 | 详情刷到编辑态，不重复入库 |
+| 10 | 保存并提交 → 关候选人弹框取消 | 详情刷到编辑态，不重复入库 |
+| 11 | 保存并提交后重复提交 | 走更新，不产生重复单据 |
+| 12 | `wfStartBindSave` 关 + 直接启动 + 失败/取消 | 表单不刷新 |
+| 13 | `wfStartBindSave` 开 + 直接启动 + 失败/取消 | 刷到编辑态 |
+| 14 | 关闭非首个动态页签 | 不报错（x-tabs 修复） |
+| 15 | 非 xform 表单用流程 | 失败/取消不刷新，成功行为不变 |
+
+---
+
+## 六、涉及文件
+
+| 文件 | 改动 |
+|------|------|
+| `components/xform/utils/util.js` | `getDefaultFormConfig` 加 3 字段 |
+| `components/xform/form-designer/setting-panel/form-setting.vue` | 配置 UI |
+| `components/vb-tabs/x-tabs.vue` | `removeTab` bug 修复 |
+| `views/user/form/view/list.vue` | `openEditDialog` 归一分支 + `resolveFormModel`/`applyTabSaveResult`/`onEditTabReload`/`promoteActiveAddTab` |
+| `components/xform/mixins/defaultHandle.js` | `saveAndSubmitWfHandle` 元数据升级 + 注入钩子 |
+| `components/xform/form-render/indexMixin.js` | wf option 注入 + `getAddTabContext`/`onWfStartSuccess`/`onWfStartAbort` |
+| `components/wf/wf.js` | `wfStartMixin` 通用 `onCancel` 钩子 + `wfSubmitted` 标志 |
+</content>

package/src/components/xform/docs/autocomplete /350/207/252/345/212/250/345/256/214/346/210/220/347/273/204/344/273/266/350/257/264/346/230/216.md"

@@ -0,0 +1,126 @@
+# autocomplete 自动完成组件
+
+基于 `el-autocomplete` 的远程搜索表单字段，支持**同时存储 ID 和名称**，可配置**后台逻辑脚本编码**进行远程搜索。
+
+## 特性
+
+- 远程搜索：输入关键词实时调用后台逻辑脚本获取候选项
+- 双值存储：选中后 ID 存入字段本身（`keyName`），名称存入展示字段（`vabSearchName`）
+- 逻辑脚本配置：复用 `httpConfig`（`formScriptCode` / `formScriptParam` / `formScriptSuccess`）
+- 选中回填：选中某项后可自动回填其他表单字段
+- ID 反查：编辑态可选通过反查脚本根据 ID 获取名称回显
+- 自定义下拉项模板：支持脚本自定义候选项展示 HTML
+- 支持子表单、只读模式、流程属性、显示规则等通用能力
+
+## 文件清单
+
+| 文件 | 作用 |
+|------|------|
+| `form-designer/form-widget/field-widget/autocomplete-widget.vue` | 运行期/设计期共用字段组件 |
+| `form-designer/form-widget/field-widget/mixins/autocomplete-mixin.js` | 核心逻辑（远程搜索、选择、回填、反查） |
+| `form-designer/widget-panel/widgetsConfig.js` | `autocompleteConfig` schema + 注册到 `advancedFields` |
+| `form-designer/setting-panel/property-editor/field-autocomplete/autocomplete-vabSearchName-editor.vue` | 属性编辑器（展示字段、回填配置等） |
+| `lang/zh-CN.js` / `lang/en-US.js` | 组件库标签 i18n |
+
+## 设计器配置
+
+在表单设计器左侧「高级字段」分组中拖入「自动完成」组件，右侧属性面板可配置：
+
+### 自动完成设置（`autocomplete-vabSearchName-editor`）
+
+面板精简为核心配置（参考「搜索框」组件的精简风格）：
+- **来源ID字段**（`valueField`）：候选项数据中 ID 对应的字段名，留空则使用字段本身 `keyName`；ID 始终存入字段本身
+- **来源名称字段**（`vabSearchName`）：候选项数据中名称对应的字段名，同时作为名称持久化的展示字段
+- **选中回填**（`autocompleteFillConfig`）：数组，每项 `{ targetField, targetFormField, sourceField }`
+
+其余通用项由标准编辑器提供：**输入提示**（`placeholder`）、**可清空**（`clearable`）在「常用设置」中配置；**清空回调**（`onSearchClear`）在「事件设置」中配置；**查询脚本编码**等在下方「请求访问设置」区块维护。
+
+> 以下选项仍保留在 `autocompleteConfig` schema 中（保证旧表单兼容与运行时行为），但已从设计器面板移除，如需使用可直接写入组件 `options` JSON：
+> - `triggerOnFocus`（默认 `true`）：聚焦空输入框时是否触发一次查询
+> - `debounce`（默认 `300`）：输入防抖毫秒数
+> - `getByIdScriptCode`：编辑态根据 ID 反查名称的脚本编码
+> - `autocompleteItemTemplate`：自定义下拉项模板脚本（入参 `item`，返回 HTML 字符串）
+
+## 远程搜索请求约定
+
+`querySearchAsync` 调用 `formHttp`，请求结构：
+
+```js
+{
+  scriptCode: formScriptCode,        // 配置的逻辑脚本编码
+  data: {
+    formCode,                        // 当前表单编码
+    formVersion,                     // 表单版本
+    taBm: fieldKeyName,              // 字段名
+    data: {
+      ...accessParam,                // formScriptParam 返回的额外参数
+      keyword: queryString           // 用户输入的关键词
+    }
+  }
+}
+```
+
+后台脚本返回的数据（`res.objx`）应为数组（或 `{ records: [...] }`），每个元素至少包含：
+- ID 字段：对应配置的 `valueField`（或字段 `keyName`）
+- 名称字段：对应配置的 `vabSearchName`
+
+`formScriptSuccess` 回调可对返回结果二次处理，返回新数组。
+
+## 选中行为
+
+`handleSelect(item)`：
+1. 取 `item[valueField]` 作为 ID，写入 `currentData[fieldKeyName]`（提交字段）
+2. 取 `item[labelField]` 作为名称，写入 `currentData[vabSearchName]`（展示字段）
+3. 按 `autocompleteFillConfig` 把 `item[sourceField]` 回填到目标字段/属性
+4. 触发 `onChange(value, oldValue, item)` 自定义事件
+
+## 清空行为
+
+`handleClear()`：同时清空 ID 与名称，触发 `onSearchClear`。
+
+## 编辑态回显
+
+- 默认：表单数据中 ID（`keyName`）与名称（`vabSearchName`）同时存在时，直接回显名称
+- 仅 ID 无名称：若配置了 `getByIdScriptCode`，`mounted` 时自动调用反查脚本获取名称回显
+
+反查脚本请求结构：
+```js
+{
+  scriptCode: getByIdScriptCode,
+  data: { formCode, formVersion, taBm, data: { ...accessParam, id } }
+}
+```
+
+## 与 vabsearch 的区别
+
+| 维度 | vabsearch | autocomplete |
+|------|-----------|--------------|
+| 交互 | 点击弹框选择 | 输入实时搜索下拉选择 |
+| 组件 | `el-input` + 弹框 | `el-autocomplete` |
+| 多选 | 支持 | 不支持（单选） |
+| 脚本 | 弹框表单编码 | 逻辑脚本编码（远程搜索） |
+| 存储 | ID + 名称 | ID + 名称（同） |
+
+## 关键选项 JSON 示例
+
+```json
+{
+  "type": "autocomplete",
+  "options": {
+    "name": "input123456",
+    "keyNameEnabled": true,
+    "keyName": "customer_id",
+    "vabSearchName": "customer_name",
+    "label": "客户",
+    "valueField": "id",
+    "formScriptEnabled": true,
+    "formScriptCode": "searchCustomer",
+    "triggerOnFocus": true,
+    "debounce": 300,
+    "clearable": true,
+    "autocompleteFillConfig": [
+      { "targetFormField": "customer_code", "sourceField": "code" }
+    ]
+  }
+}
+```