cloud-web-corejs 1.0.54-dev.71 → 1.0.54-dev.711

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

@@ -0,0 +1,511 @@
+# xform 表单「新增页签模式」实现方案
+
+> 面向 `src/components/xform` 表单/页面，增加一种可配置的页签交互模式：
+> 去掉固定「常规」页签 → 新增打开独立页签（标题"新增"）→ 保存后本页变编辑态（标题变单号）→ 提交（启动流程）后可配置「关闭页签回列表刷新」或「刷新本页」。
+>
+> 本文档只做方案设计，不含落地代码改动。
+
+---
+
+## 一、需求理解与术语对齐
+
+### 1.1 需求逐条拆解
+
+| # | 需求描述 | 语义明确化 |
+|---|---------|-----------|
+| 1 | **去掉常规** | 启用本模式后，不再使用 `list.vue` 中固定 `name="first"`、label 为「常规」的 el-tab-pane 承载新增/编辑；列表页签保留，新增与编辑都走**动态可关闭页签** |
+| 2 | **新增打开页签（页签名新增）** | 点击「新增」按钮 → 新开一个标题为「新增」的可关闭页签，渲染新增表单（`addFormCode`） |
+| 3 | **保存后刷新本页面变成编辑界面（页签名为单号）** | 暂存/保存成功后：①当前页签标题从「新增」变为返回的单号（`res.objx`）；②`dataId` 更新为单号；③`formCode` 切到 `editFormCode`；④重新加载表单进入编辑态。**不新开页签、不切到列表** |
+| 4 | **提交（启动流程）后支持配置** | 在表单配置里新增枚举项 `submitBehavior`，取值二选一：<br>• `closeToList`：关闭当前页签 → 切到列表页签 → 刷新列表<br>• `refreshCurrent`：刷新当前页签（保持编辑态） |
+
+### 1.2 关键术语
+
+- **常规页签**：`src/views/user/form/view/list.vue` 第 10 行 `<el-tab-pane :label="$t2('常规')" name="first">`，是固定的新增/编辑容器。
+- **列表页签**：同文件 label 为「列表」/`customListTabLabel`，`name="second"`。
+- **动态编辑页签**：`#editTab` 插槽渲染，`closable=true`，标题取 `tab.data[tab.tabLabelField]`。已有 `multiTabEnabled` 仅对**编辑**（有 dataId）生效。
+- **单号**：保存接口返回的 `res.objx`，即新增记录的主键/dataId。
+
+---
+
+## 二、现状分析
+
+### 2.1 两套页签系统（必须先厘清）
+
+| 系统 | 位置 | 作用 | 标题来源 | 本方案是否涉及 |
+|------|------|------|----------|---------------|
+| **A. 路由级 tagsView** | `src/layout/components/TagsView/index.vue` + `store/modules/tagsView.js`（混淆） | 顶部导航栏，每个路由一个页签 | `route.meta.title` | **不涉及**（本需求是页面内交互，不动路由页签） |
+| **B. 页面内 x-tabs** | `src/components/vb-tabs/x-tabs.vue` + `src/views/user/form/view/list.vue` | 单页面内 列表/常规/动态编辑 子页签 | `tab.data[tab.tabLabelField]` | **本方案核心改造对象** |
+
+> ⚠️ `src/components/xform/XFormTabContainer/IMPLEMENTATION_PLAN.md` 是一份 **Vue3 风格**（ref/setup/defineComponent）的草案，与本项目 **Vue 2 Options API** 不匹配，且采用「新建独立容器组件」的思路，与现有 `list.vue` + `x-tabs` 体系割裂。**本方案不沿用该草案**，而是基于现有 `x-tabs` 最小化扩展。
+
+### 2.2 相关文件清单
+
+| 文件 | 作用 | 本方案是否改动 |
+|------|------|---------------|
+| `src/components/xform/form-designer/designer.js` (L51-108) | `formConfig` 默认值定义 | ✅ 新增 3 个默认字段 |
+| `src/components/xform/form-designer/setting-panel/form-setting.vue` | 表单级配置 UI（`el-collapse` 分组） | ✅ 新增/扩展配置分组 |
+| `src/views/user/form/view/list.vue` | xform 动态表单视图页（列表+页签宿主） | ✅ 改造 `openEditDialog` 新增分支、`reload` 回调 |
+| `src/components/xform/mixins/defaultHandle.js` (L113-199) | `saveDefaultHandle` / `saveAndSubmitWfHandle` | ✅ 保存后通知父组件更新页签标题；提交后按配置分支 |
+| `src/components/xform/form-render/indexMixin.js` (L2774-2791) | `switchToListTab` / `getListPageRef` | ⛔ 不改，直接复用 |
+| `src/components/wf/wf.js` (L1817-1852) | `startSubmitHanlde` 流程启动回调 | ⛔ 不改，通过 `onStartSuccess` 注入行为 |
+| `src/components/vb-tabs/x-tabs.vue` | 页面内页签组件 | ⛔ 不改（通过传入构造好的 row + tabParam 复用现有 API） |
+| `src/layout/components/TagsView/index.vue` | 路由级页签 | ⛔ 不涉及 |
+
+### 2.3 现有 `multiTabEnabled` 的局限
+
+`list.vue:302`：
+
+```js
+if (multiTabEnabled && dataId) {   // ← 必须有 dataId 才开页签
+  this.$refs.xTabs.openEditTab(row, param, {
+    tabParam: { formCode, tabLabelField, tabName: formCode + dataId },
+  });
+} else {
+  this.formCode1 = formCode;
+  this.activeName = option.activeName || "first";   // ← 新增(dataId=null)走"常规"页签
+  this.$openEditView("showEdit");
+}
+```
+
+**新增（`dataId=null`）永远走 else 分支 → 进「常规」页签**。本方案要补齐的正是这个缺口。
+
+### 2.4 保存与提交的现有链路
+
+```
+saveDefaultHandle (defaultHandle.js:153)
+  └─ success: formRef.reloadForm({ updateParam: { dataId: res.objx, formCode: editFormCode } })
+       └─ reloadForm (indexMixin.js:2792) → this.$emit("reload", this, param)
+            └─ list.vue 的 reload(...) 接收  ← 【本方案在此更新页签标题】
+
+saveAndSubmitWfHandle (defaultHandle.js:113)
+  └─ success: openStartWfDialog(formRef, { objId: res.objx, ... })
+       └─ wf.js:1829 startSubmitHanlde
+            └─ 默认 that.$baseReload()  或  option.onStartSuccess()  ← 【本方案在此按配置分支】
+```
+
+`switchToListTab({ handleType: 'reload' })`（indexMixin.js:2774）已是现成方法：切到 `name="second"` 列表页签并刷新列表。
+
+---
+
+## 三、设计决策
+
+### 3.1 核心原则
+
+1. **基于现有 `x-tabs` 扩展，不新建容器组件**。`IMPLEMENTATION_PLAN.md` 的 Vue3 容器方案与本项目技术栈不符，弃用。
+2. **最小侵入 + 向后兼容**。新增配置项默认关闭，旧表单行为完全不变。
+3. **复用现有 API**：`xTabs.openEditTab`、`switchToListTab`、`reloadForm`、`onStartSuccess` 钩子。
+4. **页签标题响应式更新**：x-tabs 标题绑定 `tab.data[tabLabelField]`，保存后更新该字段即可自动变标题，**无需改 x-tabs**。
+
+### 3.2 配置项设计
+
+在 `formConfig` 中新增 3 个字段（`designer.js` 默认值 + `form-setting.vue` UI）：
+
+| 字段名 | 类型 | 默认值 | 含义 | 依赖 |
+|--------|------|--------|------|------|
+| `addTabEnabled` | Boolean | `false` | **新增是否打开独立页签**（本模式总开关）。开启后：新增不再走「常规」页签，而是开一个标题「新增」的可关闭页签 | 无 |
+| `addTabLabel` | String | `"新增"` | 新增页签的初始标题文本（支持 i18n key） | `addTabEnabled` |
+| `submitBehavior` | String | `"closeToList"` | 提交（启动流程）成功后的行为枚举：<br>• `closeToList`：关闭当前页签 → 切列表 → 刷新列表<br>• `refreshCurrent`：刷新当前页签（保持编辑态） | `addTabEnabled` 或 `wfEnabled` |
+
+> 💡 **与现有 `multiTabEnabled` 的关系**：
+> - `multiTabEnabled` 控制编辑页签（有 dataId）是否多开，保持原语义不变。
+> - `addTabEnabled` 控制新增页签是否多开，**独立开关**，互不干扰。
+> - 二者可同时开启（推荐：完整的列表+多页签新增/编辑体验），也可单独开启。
+> - 当 `addTabEnabled=true` 时，**「常规」页签（name="first"）在新增加页签场景下不再被激活**；但为兼容其它走 `activeName="first"` 的逻辑（如复制编辑 `openCopyEditTab`），保留该 pane 不删除，仅在 `openEditDialog` 新增分支里改走 `xTabs.openEditTab`。
+
+### 3.3 UI 配置位置
+
+在 `form-setting.vue` 的 `el-collapse` 中**新增一个分组**（建议 name="9"，标题「页签交互模式」），紧挨「列表标签页信息」(name=4) 之后：
+
+```html
+<el-collapse-item name="9" title="页签交互模式">
+  <el-form-item :label="i18nt('新增打开页签')">
+    <el-switch v-model="formConfig.addTabEnabled"></el-switch>
+    <span class="hint">开启后新增将打开独立可关闭页签，不再使用"常规"页签</span>
+  </el-form-item>
+  <el-form-item :label="i18nt('新增页签标题')">
+    <el-input type="text" v-model="formConfig.addTabLabel"
+              placeholder="默认'新增'"></el-input>
+  </el-form-item>
+  <el-form-item :label="i18nt('提交后行为')">
+    <el-radio-group v-model="formConfig.submitBehavior">
+      <el-radio label="closeToList">关闭页签并回列表刷新</el-radio>
+      <el-radio label="refreshCurrent">刷新当前页签</el-radio>
+    </el-radio-group>
+    <span class="hint">仅在启用流程(wfEnabled)时生效</span>
+  </el-form-item>
+</el-collapse-item>
+```
+
+---
+
+## 四、核心改造点详解
+
+### 4.1 改造点 1：`designer.js` 新增默认字段
+
+**文件**：`src/components/xform/form-designer/designer.js`（L51-108 的 formConfig 对象）
+
+**改动**：在 `multiTabEnabled` 附近新增：
+
+```js
+formConfig: {
+  // ... 现有字段
+  multiTabEnabled: false,
+  multiTabLabelField: null,
+  // ★ 新增
+  addTabEnabled: false,        // 新增打开独立页签
+  addTabLabel: "新增",          // 新增页签初始标题
+  submitBehavior: "closeToList", // 提交后行为: closeToList | refreshCurrent
+  // ...
+}
+```
+
+### 4.2 改造点 2：`list.vue` 的 `openEditDialog` 新增分支
+
+**文件**：`src/views/user/form/view/list.vue`（L269-319）
+
+**现状**：`if (multiTabEnabled && dataId)` 只对编辑开页签，新增走 else。
+
+**改造**：在新增（`!dataId`）场景下，根据 `addTabEnabled` 决定是否开页签。
+
+```js
+openEditDialog(row, param, option) {
+  // ... 现有 otherTab / H5 分支不变
+
+  let formConfig = this.formJson.formConfig;
+  let tabLabelField = option?.multiTabLabelField || formConfig.multiTabLabelField;
+  let multiTabEnabled = /* 现有计算逻辑不变 */;
+
+  let dataId = row && row.id ? row.id : null;
+  this.dataId = dataId;
+  let formCode = !dataId
+    ? (option?.formCode || this.addFormCode)
+    : (option?.formCode || this.formCode2);
+
+  // ★ 新增：addTabEnabled 分支
+  let addTabEnabled = formConfig.addTabEnabled && !dataId && tabLabelField;
+
+  if (multiTabEnabled && dataId) {
+    // —— 现有编辑页签分支，保持不变 ——
+    this.$refs.xTabs.openEditTab(row, param, {
+      tabParam: { formCode, tabLabelField, tabName: formCode + dataId },
+    });
+  } else if (addTabEnabled) {
+    // ★ 新增页签分支
+    //   构造一个"虚拟 row"，让 x-tabs 标题先显示"新增"
+    //   保存成功后在 reload 回调里把 tabLabelField 字段更新为真实单号
+    let addLabel = formConfig.addTabLabel || "新增";
+    let virtualRow = { ...row };
+    if (tabLabelField) virtualRow[tabLabelField] = addLabel;
+    let tabName = "add_" + Date.now();   // 唯一，避免新增页签互相覆盖
+    this.$refs.xTabs.openEditTab(virtualRow, param, {
+      tabParam: { formCode, tabLabelField, tabName },
+    });
+  } else {
+    // —— 现有"常规"页签分支，保持不变（向后兼容） ——
+    this.formCode1 = formCode;
+    this.activeName = option.activeName || "first";
+    this.showEdit = false;
+    this.showEditDialog = true;
+    this.param = param;
+    this.formData = null;
+    this.$openEditView("showEdit");
+  }
+}
+```
+
+**要点**：
+- 新增页签用 `virtualRow[tabLabelField] = "新增"` 作为初始标题，因为 x-tabs 标题绑定 `tab.data[tabLabelField]`，是响应式的。
+- `tabName = "add_" + Date.now()` 保证每次新增都是新页签（不去重）。
+- `tabLabelField` 必须配置（即 `multiTabLabelField`），否则无法显示标题；UI 上可加校验提示。
+
+### 4.3 改造点 3：`list.vue` 的 `reload` 回调更新页签标题
+
+**文件**：`src/views/user/form/view/list.vue`（reload 方法，需定位）
+
+**目的**：保存成功后 `defaultHandle.js` 会调 `reloadForm({updateParam:{dataId, formCode}})` → emit "reload" → list.vue 的 reload 接收。在此处把当前新增页签的标题从「新增」改为单号。
+
+```js
+reload(target, param) {
+  // 现有逻辑保持不变 ...
+
+  // ★ 新增：若当前活动页签是新增页签（tabName 以 "add_" 开头），
+  //   且 param.updateParam.dataId 有值，更新该页签的标题字段为单号
+  let updateParam = param?.updateParam;
+  let newDataId = updateParam?.dataId;
+  if (newDataId && this.$refs.xTabs) {
+    let activeName = this.$refs.xTabs.activeName;
+    let tab = this.$refs.xTabs.tabs.find(t => t.tabName === activeName);
+    if (tab && /^add_/.test(tab.tabName) && tab.tabLabelField) {
+      // 1. 更新标题字段 → 响应式触发 tab label 变单号
+      this.$set(tab.data, tab.tabLabelField, newDataId);
+      // 2. 更新 dataId（后续编辑/提交要用）
+      tab.dataId = newDataId;
+      // 3. 同步 formCode 到编辑表单（如果配置了 editFormCode）
+      if (updateParam.formCode) tab.formCode = updateParam.formCode;
+      // 4. （可选）更新 tabName 保持一致性，避免后续重复开同单号页签
+      //    注意：改 tabName 需同步 el-tabs 的 name，谨慎处理；可不改，靠 dataId 去重
+    }
+  }
+
+  // 现有的表单刷新逻辑（reloadForm 透传）保持不变 ...
+}
+```
+
+**要点**：
+- 用 `this.$set` 确保 Vue 2 响应式触发标题更新。
+- 标题字段值 = 单号 = `res.objx`，与编辑页签的标题来源一致，视觉上自然过渡。
+- `reloadForm` 本身已通过 `updateParam` 把 `dataId`/`formCode` 透传给 `vFormRender`，表单会重新加载编辑表单和数据 → **编辑界面自动切换**，无需额外处理。
+
+### 4.4 改造点 4：`defaultHandle.js` 的 `saveAndSubmitWfHandle` 按配置分支
+
+**文件**：`src/components/xform/mixins/defaultHandle.js`（L113-152）
+
+**现状**：`openStartWfDialog` 未传 `onStartSuccess`，wf.js 默认走 `$baseReload()`（刷新当前页）。
+
+**改造**：根据 `formConfig.submitBehavior` 注入 `onStartSuccess`：
+
+```js
+saveAndSubmitWfHandle(option) {
+  let formRef = this.getFormRef ? this.getFormRef() : this;
+  let formConfig = formRef.formConfig;
+  let reportTemplate = formRef.reportTemplate;
+  // ... 现有校验不变
+
+  let submitBehavior = formConfig.submitBehavior || "closeToList";
+
+  this.saveDefaultHandle({
+    ...option,
+    config: {
+      ...option?.config,
+      successMsg: option?.config?.successMsg ?? true,
+      isConfirm: option?.config?.isConfirm ?? true,
+      confirmText: option?.config?.confirmText || confirmText,
+      success: (res) => {
+        openStartWfDialog(formRef, {
+          objId: res.objx,
+          wfCode: reportTemplate.objTypeCode,
+          formCode: reportTemplate.formCode,
+          serviceId: reportTemplate.serviceName,
+          skipStartConfirm: true,
+          // ★ 新增：注入流程启动成功回调
+          onStartSuccess: () => {
+            if (submitBehavior === "refreshCurrent") {
+              // 行为A：刷新当前页签（保持编辑态）—— 现有默认行为
+              formRef.$baseReload();
+            } else {
+              // 行为B：关闭当前页签 → 切列表 → 刷新列表
+              //   复用 indexMixin.js 的 switchToListTab
+              //   并显式关闭当前 x-tabs 页签
+              formRef.switchToListTab({ handleType: "reload" });
+              //   switchToListTab 只切到列表页签，不关当前页签；
+              //   若要"关闭当前页签"，需额外调 xTabs.removeTab(currentTabName)
+              let listPageRef = formRef.getListPageRef?.();
+              let xTabs = listPageRef?.$refs?.xTabs;
+              let currentName = xTabs?.activeName;
+              if (xTabs && currentName && /^add_|edit_/.test(currentName)) {
+                xTabs.removeTab(currentName);
+              }
+            }
+            option?.config?.onStartSuccess?.();
+          },
+        });
+        option?.config?.success && option.config.success(res);
+      },
+    },
+  });
+}
+```
+
+**要点**：
+- `submitBehavior === "refreshCurrent"`：等价于现状（`$baseReload`），保持编辑态。
+- `submitBehavior === "closeToList"`：①`switchToListTab({handleType:"reload"})` 切列表并刷新；②额外 `xTabs.removeTab(currentName)` 关闭当前新增/编辑页签。
+- `switchToListTab` 和 `getListPageRef` 都在 `indexMixin.js` 已有，`formRef`（vFormRender 实例）通过 mixin 拥有这些方法。
+- 关闭页签前用正则判断当前是动态页签（`add_`/`edit_`），避免误关列表页签。
+
+### 4.5 改造点 5（可选）：`wf.js` 的 `startSubmitHanlde` 透传 `onStartSuccess`
+
+**文件**：`src/components/wf/wf.js`（L1817-1852）
+
+**现状**（探索报告）：
+
+```js
+callback: (resultMsg) => {
+  if (resultMsg.type == "success") {
+    that.$message({
+      message: resultMsg.content, type: "success", duration: 500,
+      onClose: (t) => {
+        if (!option.onStartSuccess) {
+          that.$baseReload();        // 默认刷新当前页
+        } else {
+          option.onStartSuccess();   // 自定义回调
+        }
+      },
+    });
+  }
+}
+```
+
+**结论**：wf.js **已支持** `onStartSuccess` 钩子，**无需改动**。只需在 `defaultHandle.js` 的 `openStartWfDialog` 调用里传入即可（见 4.4）。
+
+> ⚠️ 需验证 `openStartWfDialog` 是否把 `option.onStartSuccess` 透传给 `startSubmitHanlde`。若未透传，需在 `openStartWfDialog` 内补一行透传（属小改）。落地时第一步先确认此处。
+
+---
+
+## 五、端到端流程图解
+
+### 5.1 新增 → 保存 → 编辑态
+
+```
+用户点[新增]按钮
+    │
+    ▼
+list.vue openEditDialog(row={id:null}, ...)
+    │  addTabEnabled=true && !dataId && tabLabelField
+    ▼
+xTabs.openEditTab(virtualRow={[tabLabelField]:"新增"}, param, {tabParam:{tabName:"add_xxx"}})
+    │  → 创建可关闭页签，标题="新增"，渲染 addFormCode 表单
+    ▼
+用户填写表单 → 点[保存]
+    │
+    ▼
+defaultHandle.saveDefaultHandle
+    │  success: res.objx = 单号
+    ▼
+formRef.reloadForm({updateParam:{dataId:单号, formCode:editFormCode}})
+    │  → emit("reload", this, {updateParam})
+    ▼
+list.vue reload(target, param)
+    │  ★ 检测当前 tabName 以 "add_" 开头
+    │  ★ $set(tab.data, tabLabelField, 单号)  → 标题响应式变单号
+    │  ★ tab.dataId = 单号; tab.formCode = editFormCode
+    ▼
+vFormRender 收到 updateParam → 重新加载编辑表单 + 拉取已存数据
+    │
+    ▼
+页面保持在同一页签，标题=单号，表单=编辑态 ✅
+```
+
+### 5.2 提交（启动流程）→ closeToList
+
+```
+用户点[提交]（或保存并提交）
+    │
+    ▼
+defaultHandle.saveAndSubmitWfHandle
+    │  success: openStartWfDialog({..., onStartSuccess})
+    ▼
+wf.js startSubmitHanlde → 流程启动成功
+    │  → option.onStartSuccess()
+    ▼
+submitBehavior === "closeToList" 分支
+    │  ① formRef.switchToListTab({handleType:"reload"})
+    │     → activeName="second" + 刷新列表
+    │  ② xTabs.removeTab(currentName)  // 关闭当前 add_/edit_ 页签
+    ▼
+用户回到列表页签，看到最新列表，原新增/编辑页签已关闭 ✅
+```
+
+### 5.3 提交（启动流程）→ refreshCurrent
+
+```
+submitBehavior === "refreshCurrent" 分支
+    │  formRef.$baseReload()
+    ▼
+当前页签内容刷新，保持编辑态（标题仍为单号） ✅
+```
+
+---
+
+## 六、兼容性与回退
+
+### 6.1 向后兼容
+
+| 场景 | 旧表单（未配置新字段） | 新表单（启用本模式） |
+|------|----------------------|--------------------|
+| `addTabEnabled` 未设置 / false | 新增走「常规」页签，行为完全不变 | — |
+| `addTabEnabled = true` | — | 新增开独立页签 |
+| `submitBehavior` 未设置 | 默认 `"closeToList"`，但仅在 `addTabEnabled` 或 `wfEnabled` 时生效；旧表单 `wfEnabled=false` 不触发提交分支 | 按配置 |
+| `multiTabEnabled` | 编辑页签多开，语义不变 | 与 `addTabEnabled` 可叠加 |
+
+**结论**：所有新字段默认值都保证旧表单零行为变化，可灰度上线。
+
+### 6.2 回退方案
+
+- **配置回退**：把 `addTabEnabled` 关掉即恢复「常规」页签模式，无需改代码。
+- **代码回退**：5 个改造点均为**新增分支**，未删除/修改现有逻辑分支（除 4.4 在 `openStartWfDialog` 多传一个 `onStartSuccess` 参数）。回退只需 revert 改动文件。
+
+### 6.3 已知风险与注意事项
+
+| 风险点 | 影响 | 应对 |
+|--------|------|------|
+| `tabLabelField`（即 `multiTabLabelField`）未配置 | 新增页签无标题，x-tabs 可能渲染空 label | UI 上 `addTabEnabled=true` 时校验必填 `multiTabLabelField`，或默认用 `addTabLabel` 兜底 |
+| 新增页签 `tabName` 用 `Date.now()`，快速双击新增可能撞名 | 极低概率 | 改用 `add_${Date.now()}_${Math.random().toString(36).slice(2,6)}` |
+| `openStartWfDialog` 未透传 `onStartSuccess` 到 `startSubmitHanlde` | 提交后行为配置失效，退化为默认 `$baseReload` | 落地第一步先验证此处透传链路，必要时在 `openStartWfDialog` 补透传 |
+| 保存后改了 `tab.data[tabLabelField]` 但 `tabName` 仍为 `add_xxx` | 同一单号再次从列表打开编辑页签时，`openEditTab` 按 `row[paneKeyName]` 去重可能失效（因为新增页签 tabName 不是 `formCode+dataId`） | 保存后同步把 `tabName` 改为 `formCode+dataId`；或接受"可能重复开"，由 `multiTabEnabled` 的编辑去重兜底 |
+| 「常规」页签（name="first"）仍存在于 DOM | 视觉上可能多一个空页签 | 当 `addTabEnabled=true` 时，用 `v-if` 隐藏「常规」pane；或保持不变（不激活用户看不到） |
+| 移动端 H5（`layoutType=="H5"`）走 `openEditH5Dialog`，不走 x-tabs | 本模式在 H5 不生效 | UI 上 `addTabEnabled` 仅对 PC 生效，H5 仍走原 `openEditH5Dialog`；文档注明 |
+
+---
+
+## 七、实施步骤建议
+
+### Phase 1：配置项骨架（0.5 天）
+1. `designer.js` 加 3 个默认字段
+2. `form-setting.vue` 加「页签交互模式」collapse 分组
+3. 验证：设计器能配置并保存到 formJson
+
+### Phase 2：新增页签打开（0.5 天）
+1. `list.vue` `openEditDialog` 增加 `addTabEnabled` 分支
+2. 验证：点新增能开标题为「新增」的可关闭页签，渲染新增表单
+
+### Phase 3：保存后变编辑态（0.5 天）
+1. `list.vue` `reload` 回调增加页签标题更新逻辑
+2. 验证：保存后页签标题变单号，表单切到编辑态，dataId 正确
+
+### Phase 4：提交后行为配置（0.5 天）
+1. 先验证 `openStartWfDialog` → `startSubmitHanlde` 的 `onStartSuccess` 透传链路
+2. `defaultHandle.js` `saveAndSubmitWfHandle` 注入按 `submitBehavior` 分支的回调
+3. 验证：`closeToList` 关页签回列表刷新；`refreshCurrent` 刷新当前页
+
+### Phase 5：边界与体验（0.5 天）
+1. `tabLabelField` 必填校验 + 兜底
+2. 「常规」pane 在 `addTabEnabled=true` 时的显隐
+3. H5 场景的兼容处理
+4. 多次新增、保存后再次编辑、提交后再次打开同单号等边界测试
+
+**合计约 2.5 天**。
+
+---
+
+## 八、测试要点清单
+
+| # | 场景 | 预期 |
+|---|------|------|
+| 1 | 旧表单（未启用本模式）点新增 | 走「常规」页签，行为不变 |
+| 2 | 启用本模式，点新增 | 开标题「新增」可关闭页签 |
+| 3 | 新增页签填写后保存 | 标题变单号，表单变编辑态，不新开页签 |
+| 4 | 新增页签直接关闭（不保存） | 页签正常关闭，不影响列表 |
+| 5 | 编辑页签（multiTabEnabled）仍正常 | 不受影响 |
+| 6 | 提交，`submitBehavior=closeToList` | 当前页签关闭，切列表，列表刷新 |
+| 7 | 提交，`submitBehavior=refreshCurrent` | 当前页签刷新，保持编辑态 |
+| 8 | 同一单号从列表再次打开编辑 | 不重复开页签（去重生效） |
+| 9 | H5 端访问 | 走 `openEditH5Dialog`，不报错 |
+| 10 | `tabLabelField` 未配置 | 给提示或用 `addTabLabel` 兜底，不崩 |
+
+---
+
+## 九、附录：关键文件锚点速查
+
+| 锚点 | 位置 |
+|------|------|
+| 「常规」页签定义 | `src/views/user/form/view/list.vue:10` |
+| `openEditDialog` 新增/编辑分支 | `src/views/user/form/view/list.vue:269-319` |
+| `formConfig` 默认值 | `src/components/xform/form-designer/designer.js:51-108` |
+| 配置 UI collapse 分组 | `src/components/xform/form-designer/setting-panel/form-setting.vue:211-273`（name=4,5） |
+| `saveDefaultHandle` | `src/components/xform/mixins/defaultHandle.js:153-199` |
+| `saveAndSubmitWfHandle` | `src/components/xform/mixins/defaultHandle.js:113-152` |
+| `reloadForm` | `src/components/xform/form-render/indexMixin.js:2792-2806` |
+| `switchToListTab` / `getListPageRef` | `src/components/xform/form-render/indexMixin.js:2734-2791` |
+| 流程启动回调 | `src/components/wf/wf.js:1817-1852` |
+| x-tabs `openEditTab` / `removeTab` | `src/components/vb-tabs/x-tabs.vue` |
+| 弃用的 Vue3 草案 | `src/components/xform/XFormTabContainer/IMPLEMENTATION_PLAN.md` |

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,128 @@
+# 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`
+- **存储名称字段**（`vabSearchName`）：选中后名称持久化到的表单字段名
+- **输入提示**（`placeholder`）
+- **可清空**（`clearable`）
+- **聚焦即查询**（`triggerOnFocus`）：聚焦空输入框时是否触发一次查询
+- **防抖(ms)**（`debounce`）：输入防抖毫秒数
+- **ID反查脚本编码**（`getByIdScriptCode`）：选填，编辑态根据 ID 反查名称
+- **清空回调**（`onSearchClear`）
+- **下拉项模板**（`autocompleteItemTemplate`）：脚本，入参 `item`，返回 HTML 字符串
+- **选中回填**（`autocompleteFillConfig`）：数组，每项 `{ targetField, targetFormField, sourceField }`
+
+### 请求访问设置（复用 `formScriptEnabled-editor`）
+- **表单脚本编码**（`formScriptCode`）：远程搜索的后台逻辑脚本编码（必填）
+- **查询参数**（`formScriptParam`）：脚本，返回额外请求参数对象
+- **查询回调**（`formScriptSuccess`）：脚本，入参 `res`、`rows`，可返回处理后的数组
+
+## 远程搜索请求约定
+
+`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" }
+    ]
+  }
+}
+```