cloud-web-corejs 1.0.54-dev.706 → 1.0.54-dev.708

package/src/components/xform/XFormTabContainer/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,1079 @@
+# XForm 多页签业务交互实现方案
+
+> 基于 `src/components/xform` 现有组件体系，实现「列表+新增/编辑/查看」多 Tab 页签交互模式。
+
+---
+
+## 一、需求摘要（来自需求图）
+
+| # | 需求项 | 详细说明 |
+|---|--------|----------|
+| 1 | **页面样式** | 列表与详情合并，隐藏独立详情页，仅展示列表页签 |
+| 2 | **新增交互** | 点击「新增」→ 新增【**新增**】页签(带关闭符) → 暂存(刷当前页签) / 提交(回列表并刷新) |
+| 3 | **编辑交互** | 点击某行「编辑」→ 新增【**单号**】页签(带关闭符) → 暂存(刷当前页签) / 提交(回列表并刷新) |
+| 4 | **查看交互** | 点击某行「查看」→ 新增【**单号**】页签(带关闭符) → 支持同时打开多个 |
+
+---
+
+## 二、技术方案选型
+
+### 方案：封装 XFormTabContainer 容器组件
+
+在 xform 组件库之上封装一个**业务级 Tab 容器组件**，内部使用 Element UI 的 `el-tabs`（type="card", closable）管理页签生命周期。
+
+**核心思路：**
+- 不修改 xform 内部源码，而是通过**组合方式**在其外层包一层容器
+- 利用 xform 已有的 `VFormRender` 渲染表单，`VFormDesigner` 做设计态（如需要）
+- 页签状态由容器组件统一管理
+
+### 与现有 xform Tab 组件的关系
+
+xform 内部已有 `tab-widget.vue`（设计态）和 `tab-item.vue**（运行态）—— 这些是**表单内部的标签页容器组件**，用于在一个表单内分页展示不同字段组。本方案要实现的**不是这个**，而是**更高层的业务页面级别多页签**，两者互不冲突、可以共存。
+
+```
+业务层级: XFormTabContainer (本方案新建)
+  └─ el-tabs > el-tab-pane
+       ├─ [列表]      → xform-table 列表组件
+       ├─ [新增]      → VFormRender 表单渲染器
+       └─ [BH001]     → VFormRender 表单渲染器 (编辑/查看)
+
+表单内部层级: tab-item (已有)
+  └─ el-tabs > el-tab-pane
+       ├─ [基础信息]   → 字段组1
+       └─ [详细信息]   → 字段组2
+```
+
+---
+
+## 三、组件架构设计
+
+### 3.1 文件结构（建议位置）
+
+```
+src/components/xform/
+├── XFormTabContainer/
+│   ├── index.vue                  # 主容器组件 (核心)
+│   ├── useTabManager.js           # Composable: 页签状态管理
+│   └── XFormTabPane.vue           # 单个页签内容包装器
+```
+
+### 3.2 核心数据模型
+
+```js
+// tabsData 数据结构
+const tabsData = ref([
+  {
+    name: 'list',              // 唯一标识
+    title: '列表',             // 页签标题
+    closable: false,           // 是否可关闭
+    fixed: true,               // 是否固定页签
+    component: 'list',         // 组件类型: list | form | detail
+    formType: null,            // 表单类型: add | edit | view | null
+    formData: null,            // 表单数据/表单JSON
+    rowId: null,               // 编辑/查看时的行数据ID
+    billNo: null,              // 单号(用于显示标题)
+    key: 0                     // 强制刷新key
+  },
+  // 动态页签举例:
+  {
+    name: 'add_1687563200',
+    title: '新增',
+    closable: true,
+    fixed: false,
+    component: 'form',
+    formType: 'add',
+    formData: { ... },         // 新增表单的formJson
+    rowId: null,
+    billNo: null,
+    key: 0
+  },
+  {
+    name: 'edit_BH001',
+    title: 'BH001',
+    closable: true,
+    fixed: false,
+    component: 'form',
+    formType: 'edit',
+    formData: { ... },
+    rowId: 'BH001',
+    billNo: 'BH001',
+    key: 0
+  }
+])
+```
+
+### 3.3 组件接口定义
+
+#### XFormTabContainer Props
+
+```js
+props: {
+  // ========== 列表相关 ==========
+  listConfig: {
+    type: Object,
+    required: true,
+    default: () => ({})
+    // 列表配置: apiUrl, columns, searchForm, rowKey 等
+  },
+
+  // ========== 表单相关 ==========
+  formConfig: {
+    type: Object,
+    default: () => ({})
+    // 表单配置:
+    // - addFormJson:     新增表单JSON
+    // - editFormJson:    编辑表单JSON
+    // - viewFormJson:    查看表单JSON (可选,不传则用editFormJson只读模式)
+    // - saveApi:         暂存接口
+    // - submitApi:       提交接口
+    // - detailApi:       详情数据获取接口
+  },
+
+  // ========== 全局配置 ==========
+  options: {
+    type: Object,
+    default: () => ({
+      maxTabs: 10,              // 最大打开页签数
+      defaultActive: 'list',    // 默认激活页签
+      showListTab: true,        // 是否显示列表页签
+      confirmOnClose: true,     // 关闭有未保存数据时是否确认
+    })
+  }
+}
+```
+
+#### XFormTabContainer Events
+
+```js
+emits: [
+  'tab-change',       // 页签切换 (name)
+  'tab-open',         // 页签打开 (tabData)
+  'tab-close',        // 页签关闭 (tabData)
+  'before-close',     // 关闭前拦截 (tabData, done/cancel)
+  'save-success',     // 暂存成功 (data)
+  'submit-success',   // 提交成功 (data)
+  'list-refresh',     // 列表刷新触发
+]
+```
+
+#### XFormTabContainer Slots
+
+```html
+<!-- 列表区域插槽 -->
+<template #list="{ refresh, getSelection }">
+  <your-table-component @add="onAdd" @edit="onEdit" @view="onView" />
+</template>
+
+<!-- 表单区域插槽 -->
+<template #form="{ tabData, save, submit, loading }">
+  <v-form-render :form-json="tabData.formData" ... />
+</template>
+
+<!-- 工具栏扩展插槽 -->
+<template #toolbar="{ currentTab }">
+  <el-button>导出</el-button>
+</template>
+```
+
+---
+
+## 四、核心逻辑 — useTabManager.js
+
+这是整个方案的**核心状态管理 Hook**，负责所有页签的增删改查：
+
+```js
+// src/components/xform/XFormTabContainer/useTabManager.js
+
+import { ref, computed } from 'vue'
+
+export function useTabManager(options = {}) {
+  const {
+    maxTabs = 10,
+    defaultActive = 'list',
+    confirmOnClose = true
+  } = options
+
+  // ====== 状态 ======
+  const activeTabName = ref(defaultActive)
+  const tabsData = ref([
+    createListTab()
+  ])
+
+  // ====== 计算属性 ======
+  const activeTab = computed(() =>
+    tabsData.value.find(t => t.name === activeTabName.value)
+  )
+
+  const dynamicTabs = computed(() =>
+    tabsData.value.filter(t => !t.fixed)
+  )
+
+  // ====== 工厂函数 ======
+  function createListTab() {
+    return {
+      name: 'list',
+      title: '列表',
+      closable: false,
+      fixed: true,
+      component: 'list',
+      formType: null,
+      formData: null,
+      rowId: null,
+      billNo: null,
+      key: Date.now(),
+      dirty: false          // 是否有未保存的修改
+    }
+  }
+
+  function createAddTab(formJson) {
+    return {
+      name: `add_${Date.now()}`,
+      title: '新增',
+      closable: true,
+      fixed: false,
+      component: 'form',
+      formType: 'add',
+      formData: formJson,
+      rowId: null,
+      billNo: null,
+      key: Date.now(),
+      dirty: false
+    }
+  }
+
+  function createEditTab(billNo, formJson) {
+    return {
+      name: `edit_${billNo}`,
+      title: billNo,
+      closable: true,
+      fixed: false,
+      component: 'form',
+      formType: 'edit',
+      formData: formJson,
+      rowId: billNo,
+      billNo: billNo,
+      key: Date.now(),
+      dirty: false
+    }
+  }
+
+  function createViewTab(billNo, formJson) {
+    return {
+      name: `view_${billNo}_${Date.now()}`,
+      title: billNo,
+      closable: true,
+      fixed: false,
+      component: 'form',
+      formType: 'view',
+      formData: formJson,
+      rowId: billNo,
+      billNo: billNo,
+      key: Date.now(),
+      dirty: false
+    }
+  }
+
+  // ====== 核心操作 ======
+
+  /** 打开新增页签 */
+  function openAddTab(formJson) {
+    // 检查是否已存在未关闭的新增页签 (可选策略)
+    const existingAdd = tabsData.value.find(
+      t => !t.fixed && t.formType === 'add'
+    )
+    if (existingAdd) {
+      // 策略A: 直接切换到已有的新增页签
+      activeTabName.value = existingAdd.name
+      refreshTab(existingAdd.name)
+      return existingAdd
+    }
+
+    // 策略B: 总是创建新的新增页签 (推荐,符合需求图描述)
+    const newTab = createAddTab(formJson)
+    tabsData.value.push(newTab)
+    activeTabName.value = newTab.name
+    return newTab
+  }
+
+  /** 打开编辑页签 */
+  function openEditTab(billNo, formJson) {
+    // 检查是否已打开该单据的编辑页签
+    const existing = tabsData.value.find(
+      t => t.rowId === billNo && t.formType === 'edit'
+    )
+    if (existing) {
+      activeTabName.value = existing.name
+      refreshTab(existing.name)
+      return existing
+    }
+
+    const newTab = createEditTab(billNo, formJson)
+    tabsData.value.push(newTab)
+    activeTabName.value = newTab.name
+    return newTab
+  }
+
+  /** 打开查看页签 (允许同时打开多个) */
+  function openViewTab(billNo, formJson) {
+    // 查看页签允许重复打开同一单据 (每次打开新页签)
+    const newTab = createViewTab(billNo, formJson)
+    tabsData.value.push(newTab)
+    activeTabName.value = newTab.name
+    return newTab
+  }
+
+  /** 关闭页签 */
+  async function closeTab(targetName) {
+    const targetIdx = tabsData.value.findIndex(t => t.name === targetName)
+    if (targetIdx === -1) return
+
+    const target = tabsData.value[targetIdx]
+
+    // 固定页签不可关闭
+    if (target.fixed) return
+
+    // 未保存数据确认
+    if (confirmOnClose && target.dirty) {
+      // 触发 before-close 事件, 由外部处理确认弹窗
+      // 返回 false 可取消关闭
+      return { cancelled: true }
+    }
+
+    // 执行关闭
+    tabsData.value.splice(targetIdx, 1)
+
+    // 如果关闭的是当前活动页签, 切换到相邻页签
+    if (activeTabName.value === targetName) {
+      const nextIdx = Math.min(targetIdx, tabsData.value.length - 1)
+      activeTabName.value = tabsData.value[nextIdx]?.name || 'list'
+    }
+
+    return { closed: true, target }
+  }
+
+  /** 刷新指定页签内容 (用于暂存后刷新) */
+  function refreshTab(tabName) {
+    const tab = tabsData.value.find(t => t.name === tabName)
+    if (tab) {
+      tab.key = Date.now()   // 通过改变key强制重新渲染
+    }
+  }
+
+  /** 刷新当前页签 */
+  function refreshCurrentTab() {
+    refreshTab(activeTabName.value)
+  }
+
+  /** 标记当前页签为脏数据(有修改) */
+  function markDirty(tabName) {
+    const tab = tabsData.value.find(t => t.name === tabName)
+    if (tab) tab.dirty = true
+  }
+
+  /** 清除脏标记 (暂存/提交后) */
+  function clearDirty(tabName) {
+    const tab = tabsData.value.find(t => t.name === tabName)
+    if (tab) tab.dirty = false
+  }
+
+  /** 提交后返回列表并刷新 */
+  function submitAndBackToList() {
+    // 关闭当前非固定页签
+    const current = activeTab.value
+    if (current && !current.fixed) {
+      closeTab(current.name)
+    }
+    // 切换到列表
+    activeTabName.value = 'list'
+    // 列表刷新通过事件通知外部
+    return { needRefreshList: true }
+  }
+
+  /** 暂存后停留在当前页签 */
+  function saveAndStay() {
+    refreshCurrentTab()
+    clearDirty(activeTabName.value)
+    return { refreshed: true }
+  }
+
+  /** 切换页签 */
+  function switchTab(tabName) {
+    activeTabName.value = tabName
+  }
+
+  return {
+    // 状态
+    activeTabName,
+    tabsData,
+    activeTab,
+    dynamicTabs,
+
+    // 操作
+    openAddTab,
+    openEditTab,
+    openViewTab,
+    closeTab,
+    refreshTab,
+    refreshCurrentTab,
+    markDirty,
+    clearDirty,
+    submitAndBackToList,
+    saveAndStay,
+    switchTab
+  }
+}
+```
+
+---
+
+## 五、主组件骨架 — index.vue
+
+```vue
+<template>
+  <div class="xform-tab-container">
+    <!-- Tabs 页签栏 -->
+    <el-tabs
+      v-model="activeTabName"
+      type="card"
+      closable
+      @tab-click="handleTabClick"
+      @tab-remove="handleTabRemove"
+    >
+      <!-- 列表页签 -->
+      <el-tab-pane
+        v-for="tab in tabsData"
+        :key="tab.name + '_' + tab.key"
+        :label="renderTabLabel(tab)"
+        :name="tab.name"
+        :closable="tab.closable"
+      >
+        <!-- 列表内容 -->
+        <template v-if="tab.component === 'list'">
+          <slot name="list" :refresh="handleListRefresh" :tab-data="tab">
+            <div class="tab-content-list">
+              <!-- 默认或自定义列表组件 -->
+              <slot />
+            </div>
+          </slot>
+        </template>
+
+        <!-- 表单/详情内容 -->
+        <template v-else-if="tab.component === 'form'">
+          <slot name="form" :tab-data="tab" :save="handleSave" :submit="handleSubmit" :loading="loading">
+            <XFormTabPane
+              :key="tab.key"
+              :tab-data="tab"
+              :form-config="mergedFormConfig"
+              @save="handleSave"
+              @submit="handleSubmit"
+              @dirty-change="(val) => markDirty(tab.name)"
+            />
+          </slot>
+        </template>
+      </el-tab-pane>
+    </el-tabs>
+  </div>
+</template>
+
+<script>
+import { defineComponent } from 'vue'
+import { useTabManager } from './useTabManager'
+import XFormTabPane from './XFormTabPane.vue'
+
+export default defineComponent({
+  name: 'XFormTabContainer',
+
+  components: { XFormTabPane },
+
+  props: {
+    listConfig: { type: Object, required: true },
+    formConfig: { type: Object, default: () => ({}) },
+    options: { type: Object, default: () => ({}) }
+  },
+
+  emits: ['tab-change', 'tab-open', 'tab-close', 'before-close',
+           'save-success', 'submit-success', 'list-refresh'],
+
+  setup(props, { emit, slots }) {
+    const manager = useTabManager(props.options)
+    const { activeTabName, tabsData, activeTab, /* ... */ } = manager
+
+    const loading = ref(false)
+
+    // 合并表单配置
+    const mergedFormConfig = computed(() => ({
+      ...defaultFormConfig,
+      ...props.formConfig
+    }))
+
+    // ====== 事件处理 ======
+
+    /** 渲染页签 label (支持脏数据标识) */
+    function renderTabLabel(tab) {
+      const prefix = tab.dirty ? '● ' : ''
+      return `${prefix}${tab.title}`
+    }
+
+    /** 页签点击 */
+    function handleTabClick(tab) {
+      emit('tab-change', tab.paneName || tab.name)
+    }
+
+    /** 页签关闭按钮点击 */
+    async function handleTabRemove(targetName) {
+      const result = await manager.closeTab(targetName)
+      if (result?.closed) {
+        emit('tab-close', result.target)
+      }
+    }
+
+    /** 暂存操作 */
+    async function handleSave(formData) {
+      loading.value = true
+      try {
+        await callSaveApi(formData)        // 调用暂存接口
+        manager.saveAndStay()               // 刷新当前页签
+        emit('save-success', formData)
+      } finally {
+        loading.value = false
+      }
+    }
+
+    /** 提交操作 */
+    async function handleSubmit(formData) {
+      loading.value = true
+      try {
+        await callSubmitApi(formData)       // 调用提交接口
+        const result = manager.submitAndBackToList()
+        if (result.needRefreshList) {
+          emit('list-refresh')
+        }
+        emit('submit-success', formData)
+      } finally {
+        loading.value = false
+      }
+    }
+
+    /** 列表刷新 */
+    function handleListRefresh() {
+      emit('list-refresh')
+    }
+
+    // ====== 对外暴露方法 (供父组件调用) ======
+    expose({
+      openAddTab: manager.openAddTab,
+      openEditTab: manager.openEditTab,
+      openViewTab: manager.openViewTab,
+      closeTab: manager.closeTab,
+      refreshList: handleListRefresh,
+      // 允许父组件直接操作页签
+      ...manager
+    })
+
+    return {
+      activeTabName,
+      tabsData,
+      activeTab,
+      mergedFormConfig,
+      loading,
+      renderTabLabel,
+      handleTabClick,
+      handleTabRemove,
+      handleSave,
+      handleSubmit,
+      handleListRefresh,
+      // 将 manager 方法暴露到模板
+      ...manager
+    }
+  }
+})
+</script>
+
+<style scoped>
+.xform-tab-container {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+}
+
+.xform-tab-container :deep(.el-tabs__header) {
+  margin-bottom: 0;
+}
+
+.xform-tab-container :deep(.el-tabs__content) {
+  flex: 1;
+  overflow: auto;
+}
+
+.tab-content-list {
+  padding: 16px;
+}
+</style>
+```
+
+---
+
+## 六、页签内容组件 — XFormTabPane.vue
+
+```vue
+<template>
+  <div class="xform-tab-pane" v-loading="pageLoading">
+    <!-- 使用 xform 的 VFormRender 渲染表单 -->
+    <v-form-render
+      ref="vFormRef"
+      :form-json="currentFormJson"
+      :form-data="formDataModel"
+      :option-data="optionData"
+      @form-mounted="onFormMounted"
+    />
+
+    <!-- 底部操作栏 -->
+    <div class="pane-footer" v-if="showActions">
+      <el-button @click="handleDraft" :loading="saving">暂存</el-button>
+      <el-button type="primary" @click="handleSubmit" :loading="submitting">提交</el-button>
+    </div>
+  </div>
+</template>
+
+<script>
+import { defineComponent, ref, computed, watch, onMounted } from 'vue'
+
+export default defineComponent({
+  name: 'XFormTabPane',
+
+  props: {
+    tabData: { type: Object, required: true },
+    formConfig: { type: Object, default: () => ({}) }
+  },
+
+  emits: ['save', 'submit', 'dirty-change'],
+
+  setup(props, { emit }) {
+    const vFormRef = ref(null)
+    const pageLoading = ref(false)
+    const saving = ref(false)
+    const submitting = ref(false)
+    const formDataModel = ref({})
+    const optionData = ref({})
+
+    // 根据 formType 决定用哪个 formJson
+    const currentFormJson = computed(() => {
+      const cfg = props.formConfig
+      const type = props.tabData.formType
+      if (type === 'add') return cfg.addFormJson
+      if (type === 'view' && cfg.viewFormJson) return cfg.viewFormJson
+      return cfg.editFormJson   // edit 或默认
+    })
+
+    // 查看模式下隐藏操作按钮
+    const showActions = computed(() => props.tabData.formType !== 'view')
+
+    // 加载编辑/查看时的初始数据
+    onMounted(async () => {
+      const { formType, rowId } = props.tabData
+      if ((formType === 'edit' || formType === 'view') && rowId) {
+        await loadDetailData(rowId)
+      }
+    })
+
+    /** 加载详情数据 */
+    async function loadDetailData(id) {
+      pageLoading.value = true
+      try {
+        const api = props.formConfig.detailApi
+        const res = await fetch(`${api}/${id}`)
+        formDataModel.value = res.data
+      } finally {
+        pageLoading.value = false
+      }
+    }
+
+    /** 获取表单数据 */
+    function getFormData() {
+      return vFormRef.value?.getFormData()
+    }
+
+    /** 校验表单 */
+    async function validateForm() {
+      return vFormRef.value?.validateForm()
+    }
+
+    /** 暂存 */
+    async function handleDraft() {
+      try {
+        await validateForm()
+        const data = getFormData()
+        saving.value = true
+        emit('save', data)          // 由父组件调接口
+      } catch (e) {
+        console.warn('表单校验未通过:', e)
+      } finally {
+        saving.value = false
+      }
+    }
+
+    /** 提交 */
+    async function handleSubmit() {
+      try {
+        await validateForm()
+        const data = getFormData()
+        submitting.value = true
+        emit('submit', data)        // 由父组件调接口
+      } catch (e) {
+        console.warn('表单校验未通过:', e)
+      } finally {
+        submitting.value = false
+      }
+    }
+
+    /** 表单数据变化 -> 标记脏数据 */
+    function onFormMounted() {
+      // 监听表单内部数据变化
+      if (vFormRef.value) {
+        vFormRef.value.$watch?.(() => {
+          emit('dirty-change', true)
+        })
+      }
+    }
+
+    return {
+      vFormRef, pageLoading, saving, submitting,
+      formDataModel, optionData,
+      currentFormJson, showActions,
+      handleDraft, handleSubmit, onFormMounted
+    }
+  }
+})
+</script>
+
+<style scoped>
+.xform-tab-pane {
+  height: 100%;
+  padding: 16px;
+}
+.pane-footer {
+  text-align: right;
+  padding-top: 16px;
+  border-top: 1px solid #eee;
+  margin-top: 16px;
+}
+</style>
+```
+
+---
+
+## 七、使用示例
+
+```vue
+<template>
+  <XFormTabContainer
+    ref="containerRef"
+    :list-config="listConfig"
+    :form-config="formConfig"
+    :options="{ maxTabs: 10, confirmOnClose: true }"
+    @tab-open="onTabOpen"
+    @tab-close="onTabClose"
+    @submit-success="onSubmitSuccess"
+    @list-refresh="fetchListData"
+  >
+    <!-- 自定义列表内容 -->
+    <template #list="{ refresh }">
+      <XFormTable
+        :columns="tableColumns"
+        :data="tableData"
+        :loading="tableLoading"
+        @row-add="handleAdd"
+        @row-edit="handleEdit"
+        @row-view="handleView"
+      >
+        <template #toolbar>
+          <el-button type="primary" icon="el-icon-plus" @click="handleAdd">
+            新增
+          </el-button>
+        </template>
+      </XFormTable>
+    </template>
+
+    <!-- 自定义表单内容 (可选,默认用内置的 XFormTabPane) -->
+    <!-- <template #form="{ tabData, save, submit, loading }"> -->
+    <!--   自定义表单UI... -->
+    <!-- </template> -->
+
+    <!-- 工具栏扩展 -->
+    <template #toolbar="{ currentTab }">
+      <el-button v-if="currentTab?.name !== 'list'" @click="exportData">
+        导出
+      </el-button>
+    </template>
+  </XFormTabContainer>
+</template>
+
+<script>
+import { defineComponent, ref, onMounted } from 'vue'
+import XFormTabContainer from '@/components/xform/XFormTabContainer/index.vue'
+
+export default defineComponent({
+  components: { XFormTabContainer },
+
+  setup() {
+    const containerRef = ref(null)
+    const tableData = ref([])
+    const tableLoading = ref(false)
+
+    const listConfig = ref({
+      apiUrl: '/api/orders/list',
+      rowKey: 'billNo'
+    })
+
+    const formConfig = ref({
+      addFormJson: require('./forms/order-add.json'),
+      editFormJson: require('./forms/order-edit.json'),
+      viewFormJson: require('./forms/order-view.json'),
+      saveApi: '/api/orders/draft',
+      submitApi: '/api/orders/submit',
+      detailApi: '/api/orders/detail'
+    })
+
+    // ====== 操作方法 ======
+
+    function handleAdd() {
+      containerRef.value.openAddTab(formConfig.value.addFormJson)
+    }
+
+    function handleEdit(row) {
+      containerRef.value.openEditTab(row.billNo, formConfig.value.editFormJson)
+    }
+
+    function handleView(row) {
+      containerRef.value.openViewTab(row.billNo, formConfig.value.viewFormJson)
+    }
+
+    function onSubmitSuccess(data) {
+      Message.success('提交成功')
+      // submitAndBackToList 已经自动处理了页签关闭和切换
+    }
+
+    function fetchListData() {
+      tableLoading.value = true
+      fetchList().then(res => {
+        tableData.value = res.data
+      }).finally(() => {
+        tableLoading.value = false
+      })
+    }
+
+    onMounted(() => {
+      fetchListData()
+    })
+
+    return {
+      containerRef, listConfig, formConfig,
+      tableData, tableLoading,
+      handleAdd, handleEdit, handleView,
+      onSubmitSuccess, fetchListData
+    }
+  }
+})
+</script>
+```
+
+---
+
+## 八、交互流程详解
+
+### 8.1 新增流程
+
+```
+用户点击[新增]按钮
+    │
+    ▼
+handleAdd()
+    │
+    ▼
+containerRef.openAddTab(addFormJson)
+    │  ← useTabManager.createAddTab() → push 到 tabsData
+    │  ← activeTabName 切换到新页签
+    ▼
+el-tabs 自动渲染新页签
+    │
+    ▼
+XFormTabPane 加载 addFormJson → VFormRender 渲染空表单
+    │
+    ▼
+用户填写表单...
+    │
+    ├──► 点击[暂存]
+    │      │
+    │      ▼
+    │   handleSave(formData) → API调用
+    │      │
+    │      ▼
+    │   saveAndStay() → refreshCurrentTab() → key++ → 强制刷新当前页签
+    │   (用户留在当前页签,看到更新后的数据)
+    │
+    └──► 点击[提交]
+           │
+           ▼
+        handleSubmit(formData) → API调用
+           │
+           ▼
+        submitAndBackToList() → closeTab(current) + activeTab='list'
+        emit('list-refresh') → 外部重新请求列表数据
+        (用户回到列表页签,看到最新列表)
+```
+
+### 8.2 编辑流程
+
+```
+用户点击某行的[编辑]按钮
+    │
+    ▼
+handleEdit(row)
+    │
+    ▼
+containerRef.openEditTab(row.billNo, editFormJson)
+    │  ← 检查是否已打开该单据的编辑页签
+    │     ├─ 已打开 → 切换过去 + refresh
+    │     └─ 未打开 → 创建新页签
+    ▼
+XFormTabPane 加载 editFormJson → VFormRender 渲染
+    │  → 同时加载详情数据 (loadDetailData/billNo) 填充表单
+    │
+    ▼
+用户修改表单... (后续同新增: 暂存/提交)
+```
+
+### 8.3 查看流程
+
+```
+用户点击某行的[查看]按钮
+    │
+    ▼
+handleView(row)
+    │
+    ▼
+containerRef.openViewTab(row.billNo, viewFormJson)
+    │  ← 注意: 查看**每次都创建新页签**, 不做去重
+    │  → 允许同时打开多个查看页签
+    ▼
+XFormTabPane 以只读/禁用模式渲染 (showActions=false)
+    │
+    ▼
+用户点击页签右上角 ✕ → closeTab() → 关闭该页签
+```
+
+### 8.4 页签关闭流程
+
+```
+用户点击页签 ✕ 按钮
+    │
+    ▼
+handleTabRemove(targetName)
+    │
+    ▼
+closeTab(targetName)
+    │
+    ├──► 该页签有未保存修改 (dirty=true)?
+    │      │
+    │      ├── 是 → 触发 before-close → 弹窗确认 → 取消/确定
+    │      │
+    │      └── 否 / 用户确认 → splice 从 tabsData 移除
+    │
+    └──► 当前活动页签就是被关的那个?
+           │
+           └── 是 → activeTabName = 相邻页签 or 'list'
+```
+
+---
+
+## 九、关键实现细节
+
+### 9.1 页签唯一性命名规则
+
+| 场景 | name 格式 | 示例 | 去重策略 |
+|------|-----------|------|----------|
+| 列表 | `'list'` | `'list'` | 固定,不可删除 |
+| 新增 | `'add_' + timestamp` | `'add_1687563200'` | 可选:复用已有新增页签 |
+| 编辑 | `'edit_' + billNo` | `'edit_BH001'` | **按 billNo 去重**,已打开则切换 |
+| 查看 | `'view_' + billNo + '_' + timestamp` | `'view_BH001_1687563300'` | **不去重**,每次新建 |
+
+### 9.2 强制刷新机制
+
+通过 Vue 的 `:key` 属性实现页签内容强制重新渲染：
+- 每次 `refreshTab()` 时将 `tab.key = Date.now()`
+- Vue 检测 key 变化会销毁旧组件、创建新组件
+- 配合 `el-tab-pane` 的 `:key="tab.name + '_' + tab.key"` 绑定
+
+### 9.3 脏数据检测与防丢失
+
+```
+用户在表单中输入 → VFormRender 内部数据变化
+    │
+    ▼
+emit('dirty-change', true) → markDirty(tabName) → tab.dirty = true
+    │
+    ▼
+页签标题前显示 ● 标识 (renderTabLabel 中处理)
+    │
+    ▼
+尝试关闭时 → confirmOnClose && dirty → 弹出确认对话框
+```
+
+### 9.4 与现有 xform 组件的关系
+
+| 现有 xform 组件 | 本方案中的角色 |
+|-----------------|---------------|
+| `VFormRender` (`form-render/index.vue`) | 在每个表单页签中渲染表单 JSON |
+| `tab-item.vue` (运行态 Tab) | **不受影响** — 这是表单内部容器组件,与本方案的业务层 Tab 是不同维度 |
+| `tab-widget.vue` (设计态 Tab) | **不受影响** — 设计器内部使用 |
+| `widgetsConfig.js` (组件注册) | **不需要修改** — 本方案在外部组合 |
+
+### 9.5 样式适配要点
+
+- 使用 `el-tabs` 的 `type="card"` 样式,自带关闭按钮和圆角卡片风格
+- 页签栏高度约 40px, 内容区 `flex: 1` 占满剩余空间
+- 切换动画使用 Element UI 内置的 `fade-in-linear` transition
+- 多页签时自动出现左右滚动箭头 (el-tabs 内置行为)
+
+---
+
+## 十、实施步骤建议
+
+### Phase 1：基础框架 (预计 2-3 天)
+1. 创建 `XFormTabContainer/` 目录结构
+2. 实现 `useTabManager.js` — 页签状态管理
+3. 实现 `index.vue` — 主容器骨架
+4. 实现 `XFormTabPane.vue` — 页签内容包装
+5. **验证**: 手动添加/关闭页签, 切换正常
+
+### Phase 2：集成 xform (预计 2 天)
+1. 在 `XFormTabPane` 中集成 `VFormRender` 组件
+2. 实现表单 JSON 加载和数据回填
+3. 接入暂存/提交 API 调用
+4. **验证**: 新增页签能正常渲染表单, 暂存和提交流程跑通
+
+### Phase 3：列表集成 (预计 1-2 天)
+1. 在列表页签中接入实际的列表组件
+2. 实现列表的新增/编辑/查看按钮回调
+3. 实现提交后的列表自动刷新
+4. **验证**: 完整 CRUD 流程走通
+
+### Phase 4：体验优化 (预计 1-2 天)
+1. 脏数据检测与关闭确认
+2. 页签最大数量限制
+3. 页签标题脏数据标识 (●)
+4. 键盘快捷键支持 (Ctrl+S 暂存, Ctrl+W 关闭等)
+5. **验收**: 符合需求图中全部 4 条交互要求
+
+---
+
+## 十一、风险与注意事项
+
+| 风险点 | 影响 | 应对措施 |
+|--------|------|----------|
+| 大量页签导致内存占用过高 | 页面卡顿 | 设置 `maxTabs` 上限; 关闭时彻底销毁组件实例 |
+| 表单 JSON 过大导致切换卡顿 | 用户体验差 | 按需加载(懒渲染); 使用 `keepAlive` 缓存最近 N 个 |
+| 并发编辑冲突 | 数据覆盖 | 提交前校验版本号; 乐观锁机制 |
+| 浏览器后退按钮 | 意外离开 | 监听 `beforeunload` 事件提示保存 |
+| 与路由系统配合 | URL 不同步 | 可选: 将当前活跃页签同步到 query 参数 |