@a2simcode/ui 0.0.282 → 0.0.284

package/docs/components/table-panel.md

@@ -175,6 +175,19 @@
 | 仅显示选中模式 | 支持                                     | 支持                     |
 | 适用场景       | 需要获取选中数据，但操作在外部处理       | 需要批量操作功能         |
 
+## 跨页选中
+
+分页场景下，后端每次只返回当前页数据，需要在外部维护跨页选中状态。通过 `select-state-key` 指定选中状态字段，在 `loadData` 返回数据时根据外部维护的 ID 集合标记该字段，表格会自动根据此字段初始化每页的选中状态，无需手动调用选中 API。
+
+<Demo :source-code="tablePanelPaginationSelectStateKeyCode">
+  <template #source>
+    <table-panel-pagination-select-state-key />
+  </template>
+  <template #description>
+    设置 <code>select-state-key="selected"</code>，在 <code>loadData</code> 中根据外部维护的 ID 集合为每条记录标记 <code>selected</code> 字段；通过 <code>@select</code> 事件携带的 <code>keys</code>（跨页选中的完整 ID 列表）整体同步回 ID 集合。程序化设置选中时可调用 <code>setSelectionById(ids)</code>，选中计数立即生效。
+  </template>
+</Demo>
+
 ## 批量操作
 
 批量操作是多选功能的一种扩展使用方式，详见上面的"多选功能"章节中的"带批处理按钮的多选"部分。
@@ -289,6 +302,7 @@ import TablePanelMultipleSelection from '../examples/table-panel/multiple-select
 import TablePanelBatchOperations from '../examples/table-panel/batch-operations.vue'
 import TablePanelSubTableLazy from '../examples/table-panel/sub-table-lazy.vue'
 import TablePanelGetSelection from '../examples/table-panel/get-selection.vue'
+import TablePanelPaginationSelectStateKey from '../examples/table-panel/pagination-select-state-key.vue'
 import TablePanelButtonVisibility from '../examples/table-panel/button-visibility.vue'
 import TablePanelModelValue from '../examples/table-panel/model-value.vue'
 import TablePanelCard from '../examples/table-panel/card.vue'
@@ -305,6 +319,7 @@ import tablePanelMultipleSelectionCode from '../examples/table-panel/multiple-se
 import tablePanelBatchOperationsCode from '../examples/table-panel/batch-operations.vue?raw'
 import tablePanelSubTableLazyCode from '../examples/table-panel/sub-table-lazy.vue?raw'
 import tablePanelGetSelectionCode from '../examples/table-panel/get-selection.vue?raw'
+import tablePanelPaginationSelectStateKeyCode from '../examples/table-panel/pagination-select-state-key.vue?raw'
 import tablePanelButtonVisibilityCode from '../examples/table-panel/button-visibility.vue?raw'
 import tablePanelModelValueCode from '../examples/table-panel/model-value.vue?raw'
 import tablePanelCardCode from '../examples/table-panel/card.vue?raw'

package/docs/examples/table-panel/pagination-select-state-key.vue

@@ -0,0 +1,176 @@
+<template>
+  <div style="margin-bottom: 10px; display: flex; gap: 8px; align-items: center">
+    <j-button type="primary" label="获取跨页选中" @click="getAllSelected" />
+    <j-button type="primary" label="设置跨页选中" @click="setAllSelected" />
+  </div>
+  <div style="position: relative; width: 100%; height: 500px">
+    <j-table-panel
+      ref="tablePanelRef"
+      row-key="orderId"
+      is-multiple
+      select-state-key="selected"
+      :columns="columns"
+      :load-data="loadData"
+      :is-page="true"
+      :page-size="10"
+      @select="handleSelect"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ElMessageBox } from 'element-plus'
+
+const tablePanelRef = ref()
+// 外部维护选中的 ID 集合
+const selectedIds = ref(new Set<string>())
+
+// 选中变化时用事件携带的 keys（跨页选中的完整 ID 列表）整体同步，清空选中时 keys 为空数组
+const handleSelect = ({ keys }: { keys: string[] }) => {
+  selectedIds.value = new Set(keys)
+}
+
+// 获取所有页选中的数据
+const getAllSelected = () => {
+  const ids = Array.from(selectedIds.value)
+  console.log('跨页选中的 ID:', ids)
+  ElMessageBox.alert(`跨页共选中 ${ids.length} 条，ID 列表详情请看控制台`, '提示', {
+    confirmButtonText: '知道了',
+    type: 'info',
+  })
+}
+
+// 程序化设置跨页选中
+const ids = ['ORD-000001', 'ORD-000030']
+const setAllSelected = () => {
+  selectedIds.value = new Set(ids)
+  // 按 ID 设置跨页选中，选中计数立即生效（无需等待对应页数据加载）
+  tablePanelRef.value?.setSelectionById?.(ids)
+  // 刷新表格，loadData 会根据 selectedIds 标记 selected 字段
+  tablePanelRef.value?.refreshData?.()
+}
+
+const columns = ref([
+  {
+    id: 'orderId',
+    type: '',
+    config: {
+      label: '订单号',
+      width: 150,
+      filter: {
+        isSearchKeyword: true,
+      },
+    },
+  },
+  {
+    id: 'customerId',
+    type: '',
+    config: {
+      label: '客户编号',
+      width: 120,
+      filter: {
+        isSearchKeyword: true,
+      },
+    },
+  },
+  {
+    id: 'productName',
+    type: '',
+    config: {
+      label: '产品名称',
+      filter: {
+        isSearchKeyword: true,
+      },
+    },
+  },
+  {
+    id: 'category',
+    type: '',
+    config: {
+      label: '类别',
+      width: 120,
+    },
+  },
+  {
+    id: 'region',
+    type: '',
+    config: {
+      label: '区域',
+      width: 100,
+    },
+  },
+  {
+    id: 'sales',
+    type: '',
+    config: {
+      label: '销售额',
+      width: 100,
+      align: 'right',
+    },
+  },
+])
+
+// 生成模拟数据
+const generateMockData = (count: number): Record<string, any>[] => {
+  const categories = ['办公用品', '科技产品', '家具']
+  const regions = ['华东', '华南', '华北', '华中', '西南', '西北']
+  const data: Record<string, any>[] = []
+
+  for (let i = 1; i <= count; i++) {
+    data.push({
+      orderId: `ORD-${String(i).padStart(6, '0')}`,
+      customerId: `CUS-${String(Math.floor(Math.random() * 10000)).padStart(5, '0')}`,
+      productName: `产品名称 ${i}`,
+      category: categories[Math.floor(Math.random() * categories.length)],
+      region: regions[Math.floor(Math.random() * regions.length)],
+      sales: (Math.random() * 10000).toFixed(2),
+    })
+  }
+
+  return data
+}
+
+const allData = generateMockData(100)
+
+// 模拟后端分页接口
+// 使用 select-state-key 时，需要在数据加载时标记 selected 字段
+const loadData = async (params: Record<string, any>) => {
+  const hasKeyword = params.keyword?.value
+  const hasFilter = params.filter?.cond?.length > 0
+
+  if (hasKeyword || hasFilter) {
+    ElMessageBox.alert(
+      '查询过滤功能需要后端支持。在实际使用中，请将查询参数（keyword 和 filter）传递给后端接口进行数据过滤。',
+      '提示',
+      {
+        confirmButtonText: '知道了',
+        type: 'info',
+      }
+    )
+  }
+
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      const { pagination } = params
+      const { rows, page } = pagination || { rows: 10, page: 1 }
+      const start = (page - 1) * rows
+      const end = start + rows
+
+      // 获取当前页数据
+      const pageData = allData.slice(start, end)
+
+      // 根据 selectedIds 标记 selected 字段
+      // select-state-key="selected" 会让表格自动根据此字段初始化选中状态
+      pageData.forEach((item) => {
+        item.selected = selectedIds.value.has(item.orderId)
+      })
+
+      resolve({
+        rows: pageData,
+        records: allData.length,
+      })
+    }, 300)
+  })
+}
+</script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2simcode/ui",
-  "version": "0.0.282",
+  "version": "0.0.284",
   "description": "A Vue 3 UI Component Library",
   "type": "module",
   "main": "./dist/simcode-ui.umd.js",