@tu-design/vue 0.5.8 → 0.5.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.mts +221 -137
- package/dist/index.mjs +1278 -498
- package/dist/registry/vue/alert-dialog.json +1 -1
- package/dist/registry/vue/alert.json +1 -1
- package/dist/registry/vue/avatar-group.json +1 -1
- package/dist/registry/vue/avatar.json +1 -1
- package/dist/registry/vue/badge.json +1 -1
- package/dist/registry/vue/button.json +1 -1
- package/dist/registry/vue/calendar.json +1 -1
- package/dist/registry/vue/card.json +1 -1
- package/dist/registry/vue/cascader.json +1 -1
- package/dist/registry/vue/checkbox.json +2 -2
- package/dist/registry/vue/context-menu.json +1 -1
- package/dist/registry/vue/currency-input.json +1 -1
- package/dist/registry/vue/date-picker.json +1 -1
- package/dist/registry/vue/date-range-picker.json +1 -1
- package/dist/registry/vue/date-shared.json +1 -1
- package/dist/registry/vue/dialog.json +1 -1
- package/dist/registry/vue/drawer.json +1 -1
- package/dist/registry/vue/dropdown-menu.json +1 -1
- package/dist/registry/vue/empty.json +1 -1
- package/dist/registry/vue/form-render.json +9 -9
- package/dist/registry/vue/form.json +2 -2
- package/dist/registry/vue/icon-shared.json +8 -2
- package/dist/registry/vue/input.json +2 -2
- package/dist/registry/vue/label.json +1 -1
- package/dist/registry/vue/month-picker.json +1 -1
- package/dist/registry/vue/number-input.json +1 -1
- package/dist/registry/vue/overlay-shared.json +1 -1
- package/dist/registry/vue/password-input.json +1 -1
- package/dist/registry/vue/pin-input.json +1 -1
- package/dist/registry/vue/popconfirm.json +1 -1
- package/dist/registry/vue/popover.json +1 -1
- package/dist/registry/vue/progress.json +1 -1
- package/dist/registry/vue/radio-group.json +1 -1
- package/dist/registry/vue/registry.json +54 -54
- package/dist/registry/vue/select.json +1 -1
- package/dist/registry/vue/separator.json +1 -1
- package/dist/registry/vue/skeleton.json +1 -1
- package/dist/registry/vue/slider.json +1 -1
- package/dist/registry/vue/slot.json +1 -1
- package/dist/registry/vue/spin.json +1 -1
- package/dist/registry/vue/switch.json +1 -1
- package/dist/registry/vue/table-render.json +24 -11
- package/dist/registry/vue/tabs.json +1 -1
- package/dist/registry/vue/textarea.json +2 -2
- package/dist/registry/vue/timeline.json +1 -1
- package/dist/registry/vue/toast.json +1 -1
- package/dist/registry/vue/tokens.json +1 -1
- package/dist/registry/vue/tooltip.json +1 -1
- package/dist/registry/vue/tree-select.json +1 -1
- package/dist/registry/vue/tree-shared.json +1 -1
- package/dist/registry/vue/utils.json +1 -1
- package/dist/registry/vue/week-picker.json +1 -1
- package/dist/registry/vue/year-picker.json +1 -1
- package/package.json +1 -1
|
@@ -1,15 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
|
|
3
3
|
"name": "table-render",
|
|
4
|
-
"version": "0.5.
|
|
4
|
+
"version": "0.5.9",
|
|
5
5
|
"type": "registry:ui",
|
|
6
|
-
"description": "配置驱动表格渲染器:defineTable 聚合 TanStack Table 实例与列配置,静态/服务端双模式(onLoad 回写分页排序),搜索表单联动(search 接 FormRender),左右固定列 sticky 横向滚动,表体虚拟滚动(virtual + height,TanStack Virtual 动态测量行高),树形数据(tree:子行展开/收起、depth 缩进、caret
|
|
6
|
+
"description": "配置驱动表格渲染器:defineTable 聚合 TanStack Table 实例与列配置,静态/服务端双模式(onLoad 回写分页排序),搜索表单联动(search 接 FormRender),左右固定列 sticky 横向滚动,表体虚拟滚动(virtual + height,TanStack Virtual 动态测量行高),树形数据(tree:子行展开/收起、depth 缩进、caret 位于首列),行拖拽排序(draggable:把手列页内 DnD + drag-sort 事件,静态模式引擎先行重排、服务端模式只发事件;与 tree/virtual 互斥,排序激活/rowKey 缺失时把手置灰),列显隐(columnSettings 面板 + visibleKeys 受控,面板树形三态),表头分组(任意层级多级表头,分组列/固定列/多行 sticky 全兼容),错误态占位与重试(#error 插槽 + load-error),ellipsis 支持 tooltip 形态,v-model 受控(pageIndex/pageSize/sort/selectedKeys),Ark Pagination 分页条 + 原生 select 每页条数,排序表头 aria-sort、加载骨架与空态插槽,语义化 table + Tailwind tokens。",
|
|
7
7
|
"registryDependencies": [
|
|
8
8
|
"badge",
|
|
9
9
|
"button",
|
|
10
10
|
"checkbox",
|
|
11
11
|
"form-render",
|
|
12
12
|
"icon-shared",
|
|
13
|
+
"popconfirm",
|
|
13
14
|
"popover",
|
|
14
15
|
"separator",
|
|
15
16
|
"skeleton",
|
|
@@ -26,37 +27,43 @@
|
|
|
26
27
|
"path": "table-render/TableBodyRow.vue",
|
|
27
28
|
"type": "registry:component",
|
|
28
29
|
"target": "components/ui/table-render/TableBodyRow.vue",
|
|
29
|
-
"content": "<script setup lang=\"ts\">\nimport type { PropType, VNodeChild } from \"vue\";\nimport { cloneVNode, h, isVNode } from \"vue\";\nimport { Checkbox } from \"@/components/ui/checkbox\";\nimport { Tooltip } from \"@/components/ui/tooltip\";\nimport { SELECTION_CELL } from \"./constants\";\nimport ChevronIcon from \"../icon-shared/ChevronIcon.vue\";\nimport { stickyClass, stickyStyle, type StickyMap } from \"./sticky\";\nimport type { TableBodyLine, TableColumnOptions } from \"./types\";\n\nconst props = defineProps({\n /** 表体行数据(cells 值矩阵已由父层按可见列计算) */\n line: { type: Object as PropType<TableBodyLine>, required: true },\n /** 可见业务列(与 line.cells 同序) */\n columns: { type: Array as PropType<TableColumnOptions[]>, required: true },\n /** 选择列形态;undefined 不渲染选择单元格 */\n selection: {\n type: String as PropType<\"radio\" | \"checkbox\" | undefined>,\n default: undefined,\n },\n selected: { type: Boolean, default: false },\n sticky: { type: Object as PropType<StickyMap>, required: true },\n /** 树形缩进基准 px;undefined 表示未启用树形(不渲染 depth 缩进与 caret) */\n treeIndent: { type: Number, default: undefined },\n});\n\nconst emit = defineEmits<{\n select: [checked: boolean];\n \"row-click\": [event: MouseEvent];\n \"row-dblclick\": [event: MouseEvent];\n \"row-contextmenu\": [event: MouseEvent];\n \"cell-click\": [columnKey: string, event: MouseEvent];\n}>();\n\nfunction cellText(line: TableBodyLine, index: number): string {\n const value = line.cells[index];\n return isVNode(value) ? \"\" : String(value ?? \"\");\n}\n\n/**\n * ellipsis: \"tooltip\" 的单元格内容:默认插槽承载截断内容(触发元素本体,不额外包裹),content 显示完整文本。\n * VNode(render 工厂)单元格经 cloneVNode 复制进触发位(VNode 不可二次挂载)。\n * @param value - 单元格原始内容(VNode 或文本)\n * @param text - 用于 tooltip content 与纯文本兜底的完整文本\n * @returns 包裹 Tooltip 后的渲染结果\n */\nfunction tooltipCell(value: VNodeChild, text: string): VNodeChild {\n const trigger = isVNode(value) ? cloneVNode(value) : h(\"span\", { class: \"block truncate\" }, text);\n return h(Tooltip, { delayDuration: 0, content: text }, { default: () => [trigger] });\n}\n</script>\n\n<template>\n <tr\n class=\"border-b transition-colors hover:bg-muted/50\"\n @click=\"emit('row-click', $event)\"\n @dblclick=\"emit('row-dblclick', $event)\"\n @contextmenu=\"emit('row-contextmenu', $event)\"\n >\n <!-- 选择单元格:阻断冒泡避免触发行 row-click
|
|
30
|
+
"content": "<script setup lang=\"ts\">\nimport type { PropType, VNodeChild } from \"vue\";\nimport { cloneVNode, h, isVNode } from \"vue\";\nimport { Checkbox } from \"@/components/ui/checkbox\";\nimport { Tooltip } from \"@/components/ui/tooltip\";\nimport { DRAG_CELL, SELECTION_CELL } from \"./constants\";\nimport ChevronIcon from \"../icon-shared/ChevronIcon.vue\";\nimport GripIcon from \"../icon-shared/GripIcon.vue\";\nimport { stickyClass, stickyStyle, type StickyMap } from \"./sticky\";\nimport type { TableBodyLine, TableColumnOptions } from \"./types\";\n\nconst props = defineProps({\n /** 表体行数据(cells 值矩阵已由父层按可见列计算) */\n line: { type: Object as PropType<TableBodyLine>, required: true },\n /** 可见业务列(与 line.cells 同序) */\n columns: { type: Array as PropType<TableColumnOptions[]>, required: true },\n /** 选择列形态;undefined 不渲染选择单元格 */\n selection: {\n type: String as PropType<\"radio\" | \"checkbox\" | undefined>,\n default: undefined,\n },\n selected: { type: Boolean, default: false },\n sticky: { type: Object as PropType<StickyMap>, required: true },\n /** 树形缩进基准 px;undefined 表示未启用树形(不渲染 depth 缩进与 caret) */\n treeIndent: { type: Number, default: undefined },\n /** 是否渲染拖拽把手列(draggable 启用且未被守卫降级) */\n dragColumn: { type: Boolean, default: false },\n /** 本行把手禁用(排序激活 / rowKey 缺失 / 行级谓词 false) */\n dragDisabled: { type: Boolean, default: false },\n /** 本行正在被拖拽(占位态:半透明 + 虚线描边,实时让位预览中即落点提示) */\n dragging: { type: Boolean, default: false },\n});\n\nconst emit = defineEmits<{\n select: [checked: boolean];\n \"row-click\": [event: MouseEvent];\n \"row-dblclick\": [event: MouseEvent];\n \"row-contextmenu\": [event: MouseEvent];\n \"cell-click\": [columnKey: string, event: MouseEvent];\n /** 把手 dragstart(仅把手可起拖,整行不可拖) */\n \"drag-start\": [event: DragEvent];\n /** 行 dragover(实时让位预览判定) */\n \"drag-over\": [event: DragEvent];\n /** 行 drop(成功落位) */\n drop: [event: DragEvent];\n /** 把手 dragend(含取消路径,仅清理状态) */\n \"drag-end\": [event: DragEvent];\n}>();\n\nfunction cellText(line: TableBodyLine, index: number): string {\n const value = line.cells[index];\n return isVNode(value) ? \"\" : String(value ?? \"\");\n}\n\n/**\n * ellipsis: \"tooltip\" 的单元格内容:默认插槽承载截断内容(触发元素本体,不额外包裹),content 显示完整文本。\n * VNode(render 工厂)单元格经 cloneVNode 复制进触发位(VNode 不可二次挂载)。\n * @param value - 单元格原始内容(VNode 或文本)\n * @param text - 用于 tooltip content 与纯文本兜底的完整文本\n * @returns 包裹 Tooltip 后的渲染结果\n */\nfunction tooltipCell(value: VNodeChild, text: string): VNodeChild {\n const trigger = isVNode(value) ? cloneVNode(value) : h(\"span\", { class: \"block truncate\" }, text);\n return h(Tooltip, { delayDuration: 0, content: text }, { default: () => [trigger] });\n}\n</script>\n\n<template>\n <tr\n class=\"border-b transition-colors hover:bg-muted/50\"\n :class=\"{\n 'opacity-50 [&>td]:outline-2 [&>td]:outline-dashed [&>td]:-outline-offset-2 [&>td]:outline-primary/40':\n props.dragging,\n }\"\n @click=\"emit('row-click', $event)\"\n @dblclick=\"emit('row-dblclick', $event)\"\n @contextmenu=\"emit('row-contextmenu', $event)\"\n @dragover=\"emit('drag-over', $event)\"\n @drop=\"emit('drop', $event)\"\n >\n <!-- 选择单元格:阻断冒泡避免触发行 row-click;radio 为原生控件 -->\n <td\n v-if=\"props.selection\"\n class=\"w-12 p-2 text-center align-middle\"\n :class=\"stickyClass(props.sticky, SELECTION_CELL)\"\n :style=\"stickyStyle(props.sticky, SELECTION_CELL, false)\"\n @click.stop\n >\n <input\n v-if=\"props.selection === 'radio'\"\n type=\"radio\"\n class=\"accent-primary size-4 cursor-pointer disabled:cursor-not-allowed disabled:opacity-50\"\n :checked=\"props.selected\"\n :disabled=\"!props.line.canSelect\"\n :aria-label=\"`选择第 ${props.line.index + 1} 行`\"\n @click=\"emit('select', !props.selected)\"\n />\n <Checkbox\n v-else\n :checked=\"props.selected\"\n :disabled=\"!props.line.canSelect\"\n :aria-label=\"`选择第 ${props.line.index + 1} 行`\"\n @update:checked=\"(checked: boolean) => emit('select', checked)\"\n />\n </td>\n <!-- 拖拽把手单元格:仅把手可起拖(draggable 在按钮上,整行不可拖);阻断冒泡避免触发行 row-click -->\n <td\n v-if=\"props.dragColumn\"\n class=\"p-1 text-center align-middle\"\n :class=\"stickyClass(props.sticky, DRAG_CELL)\"\n :style=\"stickyStyle(props.sticky, DRAG_CELL, false)\"\n @click.stop\n >\n <button\n type=\"button\"\n data-drag-handle\n class=\"text-muted-foreground inline-flex size-6 cursor-grab items-center justify-center rounded-sm active:cursor-grabbing disabled:cursor-not-allowed disabled:opacity-50\"\n :disabled=\"props.dragDisabled\"\n :draggable=\"!props.dragDisabled\"\n :aria-label=\"`拖拽排序第 ${props.line.index + 1} 行`\"\n @dragstart=\"emit('drag-start', $event)\"\n @dragend=\"emit('drag-end', $event)\"\n >\n <GripIcon class=\"size-4\" />\n </button>\n </td>\n <td\n v-for=\"(value, index) in props.line.cells\"\n :key=\"props.columns[index].key\"\n class=\"p-2 align-middle\"\n :class=\"[\n stickyClass(props.sticky, props.columns[index].key),\n { truncate: props.columns[index].ellipsis === true },\n ]\"\n :title=\"props.columns[index].ellipsis === true ? cellText(props.line, index) : undefined\"\n :style=\"[\n { textAlign: props.columns[index].align ?? 'center' },\n stickyStyle(props.sticky, props.columns[index].key, false),\n ]\"\n @click=\"emit('cell-click', props.columns[index].key, $event)\"\n >\n <!-- 首列(tree 启用时):depth 缩进 + 展开 caret(点击 stop 避免误触发行点击) -->\n <span\n v-if=\"props.treeIndent !== undefined && index === 0\"\n class=\"inline-flex max-w-full items-center gap-1\"\n :style=\"{ marginLeft: `${props.line.row.depth * props.treeIndent}px` }\"\n >\n <button\n v-if=\"props.line.row.getCanExpand()\"\n type=\"button\"\n class=\"hover:bg-muted text-muted-foreground inline-flex size-4 shrink-0 cursor-pointer items-center justify-center rounded-sm\"\n :aria-expanded=\"props.line.row.getIsExpanded()\"\n :aria-label=\"props.line.row.getIsExpanded() ? '收起' : '展开'\"\n @click.stop=\"props.line.row.toggleExpanded()\"\n >\n <ChevronIcon\n class=\"size-3.5 transition-transform\"\n :class=\"{ 'rotate-90': props.line.row.getIsExpanded() }\"\n />\n </button>\n <!-- VNode 必须走子节点渲染;文本插值会序列化 vnode 导致循环引用 -->\n <component :is=\"value\" v-if=\"isVNode(value)\" />\n <span v-else class=\"min-w-0 truncate\">{{ value }}</span>\n </span>\n <!-- ellipsis: \"tooltip\":Tooltip 包装(VNode 经 cloneVNode 复制,避免二次挂载) -->\n <component\n :is=\"tooltipCell(value, cellText(props.line, index))\"\n v-else-if=\"props.columns[index].ellipsis === 'tooltip'\"\n />\n <template v-else>\n <!-- VNode 必须走子节点渲染;文本插值会序列化 vnode 导致循环引用 -->\n <component :is=\"value\" v-if=\"isVNode(value)\" />\n <template v-else>{{ value }}</template>\n </template>\n </td>\n </tr>\n</template>\n"
|
|
30
31
|
},
|
|
31
32
|
{
|
|
32
33
|
"path": "table-render/TablePagination.vue",
|
|
33
34
|
"type": "registry:component",
|
|
34
35
|
"target": "components/ui/table-render/TablePagination.vue",
|
|
35
|
-
"content": "<script setup lang=\"ts\">\nimport type { PropType } from \"vue\";\nimport type { TableRenderDefinition } from \"./types\";\nimport {\n PaginationEllipsis as ArkPaginationEllipsis,\n PaginationItem as ArkPaginationItem,\n PaginationNextTrigger as ArkPaginationNextTrigger,\n PaginationPrevTrigger as ArkPaginationPrevTrigger,\n PaginationRoot as ArkPaginationRoot,\n} from \"@ark-ui/vue/pagination\";\nimport { computed } from \"vue\";\nimport { cn } from \"@/lib/utils\";\n\n// boolean props 用运行时声明 + default: undefined 禁用 Vue 的 Boolean casting\n// (casting 会让未传的 prop 变 false;TableRender/FormRender 同款约定)\nconst props = defineProps({\n /** 组合式:传 defineTable 返回值,自动接线 page
|
|
36
|
+
"content": "<script setup lang=\"ts\">\nimport type { PropType } from \"vue\";\nimport type { TableRenderDefinition } from \"./types\";\nimport {\n PaginationEllipsis as ArkPaginationEllipsis,\n PaginationItem as ArkPaginationItem,\n PaginationNextTrigger as ArkPaginationNextTrigger,\n PaginationPrevTrigger as ArkPaginationPrevTrigger,\n PaginationRoot as ArkPaginationRoot,\n} from \"@ark-ui/vue/pagination\";\nimport { computed } from \"vue\";\nimport { cn } from \"@/lib/utils\";\n\n// boolean props 用运行时声明 + default: undefined 禁用 Vue 的 Boolean casting\n// (casting 会让未传的 prop 变 false;TableRender/FormRender 同款约定)\nconst props = defineProps({\n /** 组合式:传 defineTable 返回值,自动接线 page/动作并单页自隐藏;\n * 与手动分页 props 同传时以 definition 为准(DEV 警告) */\n definition: { type: Object as PropType<TableRenderDefinition<any>> },\n /** 1-based 当前页码(手动模式) */\n pageIndex: { type: Number, default: undefined },\n pageSize: { type: Number, default: undefined },\n pageSizeOpts: { type: Array as PropType<readonly number[]>, default: undefined },\n total: { type: Number, default: undefined },\n /** 「共 N 条」,缺省 true */\n showTotal: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 条/页 select,缺省 false(组合式简形分页条可保持关闭) */\n showSizeSelect: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 上一页/下一页形态:text 文字(缺省)/ icon 图标 */\n navMode: { type: String as PropType<\"text\" | \"icon\">, default: \"text\" },\n});\n\nconst emit = defineEmits<{\n \"update:pageIndex\": [pageIndex: number];\n \"update:pageSize\": [pageSize: number];\n}>();\n\n// 输入解析在 setup 期定版(definition/手动模式不支持运行时切换,同 TableRender 约定):\n// ① definition 与手动分页 props 同传 → 以 definition 为准(DEV 警告);\n// ② 仅手动且缺 pageIndex/pageSize/total 任一 → DEV 警告 + 不渲染\nif (import.meta.env.DEV) {\n if (\n props.definition &&\n (props.pageIndex !== undefined ||\n props.pageSize !== undefined ||\n props.pageSizeOpts !== undefined ||\n props.total !== undefined)\n ) {\n console.warn(\n \"[tu-design] <TablePagination> definition 与手动分页 props 同传,已按 definition 渲染。\",\n );\n }\n if (\n !props.definition &&\n (props.pageIndex === undefined || props.pageSize === undefined || props.total === undefined)\n ) {\n console.warn(\n \"[tu-design] <TablePagination> 缺少 definition 或 pageIndex/pageSize/total,组件不渲染。\",\n );\n }\n}\n\n// definition 优先投影;手动模式直读 props(缺省 undefined 走 visible 兜底)\nconst pageIndex = computed(() => props.definition?.page.pageIndex ?? props.pageIndex);\nconst pageSize = computed(() => props.definition?.page.pageSize ?? props.pageSize);\nconst pageSizeOpts = computed(() => props.definition?.page.pageSizeOpts ?? props.pageSizeOpts);\nconst total = computed(() => props.definition?.page.total ?? props.total);\nconst totalPages = computed(() =>\n Math.max(1, Math.ceil((total.value ?? 0) / (pageSize.value ?? 1))),\n);\n\n/** 可见性:definition 模式单页自隐藏;手动模式须 pageIndex/pageSize/total 齐备(缺项 DEV 警告 + 不渲染) */\nconst visible = computed(() => {\n if (props.definition !== undefined) {\n return Math.ceil((total.value ?? 0) / (pageSize.value ?? 1)) > 1;\n }\n return props.pageIndex !== undefined && props.pageSize !== undefined && props.total !== undefined;\n});\n\nconst showTotalBar = computed(() => props.showTotal ?? true);\nconst showSelect = computed(() => props.showSizeSelect ?? false);\nconst iconMode = computed(() => props.navMode === \"icon\");\nconst hasLeft = computed(() => showTotalBar.value || showSelect.value);\n\n// definition 模式经实例动作接线;事件恒 emit(幂等:同值重复设置无害),便于本地联动\nfunction onPageIndex(value: number) {\n props.definition?.setPageIndex(value);\n emit(\"update:pageIndex\", value);\n}\n\nfunction onPageSize(value: number) {\n props.definition?.setPageSize(value);\n emit(\"update:pageSize\", value);\n}\n\n/** 页码窗口:首页/尾页 + 当前页 ±1,跳过段用省略号 */\nconst pages = computed<(number | string)[]>(() => {\n const count = totalPages.value;\n const current = pageIndex.value ?? 1;\n const window = [...new Set([1, count, current - 1, current, current + 1])]\n .filter((page) => page >= 1 && page <= count)\n .sort((a, b) => a - b);\n\n const items: (number | string)[] = [];\n let previous = 0;\n for (const page of window) {\n if (previous && page - previous > 1) items.push(\"…\");\n items.push(page);\n previous = page;\n }\n return items;\n});\n</script>\n\n<template>\n <!-- 不带 border-t(布局归使用方,TableRender 内置使用处显式补);左区缺省时页码靠右 -->\n <div\n v-if=\"visible\"\n :class=\"\n cn(\n 'flex w-full items-center gap-4 p-2 text-sm',\n hasLeft ? 'justify-between' : 'justify-end',\n $attrs.class,\n )\n \"\n >\n <div v-if=\"hasLeft\" class=\"flex items-center gap-2 text-muted-foreground\">\n <span v-if=\"showTotalBar\">共 {{ total }} 条</span>\n <select\n v-if=\"showSelect\"\n class=\"h-8 rounded-md border bg-transparent px-2 text-sm\"\n :value=\"pageSize\"\n @change=\"onPageSize(Number(($event.target as HTMLSelectElement).value))\"\n >\n <option v-for=\"size in pageSizeOpts\" :key=\"size\" :value=\"size\">{{ size }} 条/页</option>\n </select>\n </div>\n\n <!-- Root 渲染为裸 nav 且 Ellipsis 是块级 div,必须显式 flex 才不会断行 -->\n <ArkPaginationRoot\n class=\"flex items-center gap-1\"\n :count=\"total ?? 0\"\n :page=\"pageIndex ?? 1\"\n :page-size=\"pageSize ?? 1\"\n :sibling-count=\"1\"\n @page-change=\"onPageIndex($event.page)\"\n >\n <ArkPaginationPrevTrigger\n class=\"h-8 rounded-md border px-2 disabled:opacity-50\"\n :class=\"{ 'px-3': !iconMode }\"\n :disabled=\"(pageIndex ?? 1) <= 1\"\n :aria-label=\"iconMode ? '上一页' : undefined\"\n >\n <svg\n v-if=\"iconMode\"\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"size-4\"\n aria-hidden=\"true\"\n >\n <path d=\"m15 18-6-6 6-6\" />\n </svg>\n <template v-else>上一页</template>\n </ArkPaginationPrevTrigger>\n\n <template\n v-for=\"(item, index) in pages\"\n :key=\"typeof item === 'number' ? item : `gap-${index}`\"\n >\n <ArkPaginationEllipsis v-if=\"typeof item === 'string'\" :index=\"index\" />\n <ArkPaginationItem\n v-else\n type=\"page\"\n class=\"h-8 min-w-8 rounded-md border px-2 data-[selected]:bg-primary data-[selected]:text-primary-foreground\"\n :value=\"item\"\n >\n {{ item }}\n </ArkPaginationItem>\n </template>\n\n <ArkPaginationNextTrigger\n class=\"h-8 rounded-md border px-2 disabled:opacity-50\"\n :class=\"{ 'px-3': !iconMode }\"\n :disabled=\"(pageIndex ?? 1) >= totalPages\"\n :aria-label=\"iconMode ? '下一页' : undefined\"\n >\n <svg\n v-if=\"iconMode\"\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"size-4\"\n aria-hidden=\"true\"\n >\n <path d=\"m9 18 6-6-6-6\" />\n </svg>\n <template v-else>下一页</template>\n </ArkPaginationNextTrigger>\n </ArkPaginationRoot>\n </div>\n</template>\n"
|
|
36
37
|
},
|
|
37
38
|
{
|
|
38
39
|
"path": "table-render/TableRender.vue",
|
|
39
40
|
"type": "registry:component",
|
|
40
41
|
"target": "components/ui/table-render/TableRender.vue",
|
|
41
|
-
"content": "<script setup lang=\"ts\">\nimport type { ComponentPublicInstance, PropType, VNodeChild } from \"vue\";\nimport { useVirtualizer } from \"@tanstack/vue-virtual\";\nimport { columnRenders } from \"./column-renders\";\nimport { computed, inject, onMounted, ref, watch } from \"vue\";\nimport { Button } from \"@/components/ui/button\";\nimport { Checkbox } from \"@/components/ui/checkbox\";\nimport { FormRender, type FormRenderDefinition } from \"@/components/ui/form-render\";\nimport { Popover } from \"@/components/ui/popover\";\nimport { Separator } from \"@/components/ui/separator\";\nimport { Skeleton } from \"@/components/ui/skeleton\";\nimport { Tooltip } from \"@/components/ui/tooltip\";\nimport { cn } from \"@/lib/utils\";\nimport { PAGE_TABLE_FILL_KEY, SELECTION_CELL } from \"./constants\";\nimport { stickyClass, stickyStyle, type StickyMap } from \"./sticky\";\nimport TableBodyRow from \"./TableBodyRow.vue\";\nimport TablePagination from \"./TablePagination.vue\";\nimport type {\n ColumnVisibilityOptions,\n DataRecord,\n SortableOptions,\n TableBodyLine,\n TableColumnOptions,\n TableLoadParams,\n TableRenderDefinition,\n TableSelectionOptions,\n TreeOptions,\n} from \"./types\";\nimport { useTableRender } from \"./useTableRender\";\n\n// boolean flags 用运行时声明 + default: undefined 禁用 Vue 的 Boolean casting\n// (casting 会让未传的 prop 变 false;Checkbox/Dialog/FormRender 同款约定)\nconst props = defineProps({\n /** 聚合式(推荐):defineTable 返回的定义对象 */\n definition: { type: Object as PropType<TableRenderDefinition<any>> },\n /** 数据主键(记录缺字段时以行索引兜底) */\n rowKey: { type: String, required: true },\n /** 拆分式:与 definition 二选一,definition 优先 */\n columns: { type: Array as PropType<TableColumnOptions[]> },\n onLoad: {\n type: Function as PropType<(params: TableLoadParams) => void | Promise<unknown>>,\n },\n data: { type: Array as PropType<DataRecord[]> },\n autoLoad: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 每页条数 / 受控每页条数(D11):传入即受控(pageIndex 未受控时 R9 归位内部处理并通知) */\n pageSize: { type: Number },\n pageSizeOpts: { type: Array as PropType<number[]> },\n loading: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n emptyText: { type: String },\n /** 行选择(仅拆分式生效;聚合式请在 defineTable 配置):\"radio\" | \"checkbox\" | 对象 */\n rowSelection: {\n type: [String, Object] as PropType<\"radio\" | \"checkbox\" | TableSelectionOptions>,\n default: undefined,\n },\n /** 搜索表单(defineForm 返回值):拆分式直接传;聚合式请在 defineTable 配置(definition 优先,同传 DEV 警告) */\n search: { type: Object as PropType<FormRenderDefinition<any>> },\n /** 虚拟滚动:开启后表体行虚拟化渲染;聚合式请在 defineTable 配置(definition 优先);须同时给 height */\n virtual: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 虚拟滚动容器高度(数字 px 或 CSS 高度);仅 virtual: true 时生效 */\n height: { type: [Number, String] as PropType<number | string> },\n /** 树形数据(子行展开/收起);拆分式直接传,聚合式请在 defineTable 配置 */\n tree: { type: Object as PropType<TreeOptions> },\n /** 受控页码(1-based):传入即受控,缺省非受控;内部翻页经 update:page-index 通知 */\n pageIndex: { type: Number },\n /** 受控排序:传入即受控;内部/外部变化均经 sort-change 通知 */\n sort: { type: Object as PropType<SortableOptions> },\n /** 受控选中集(数组,与 update:selected-keys 载荷同构):传入即受控 */\n selectedKeys: { type: Array as PropType<Array<string | number>> },\n /** 受控可见列 key(columns 原序子集):传入即受控;内部显隐经 update:visible-keys 通知 */\n visibleKeys: { type: Array as PropType<string[]> },\n /** 拆分式默认可见列集;与聚合式 columnVisibility.defaultVisibleKeys 同传时 DEV 警告(R26,definition 优先) */\n defaultVisibleKeys: { type: Array as PropType<string[]> },\n /** 列设置触发器/面板开关(默认 true);false 时不渲染 UI,受控 API 不受影响 */\n columnSettings: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 搜索区渲染开关(R27):false 关闭内置搜索区(组合式外置 FormRender);数据链路不变 */\n showSearch: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 分页条渲染开关(R28):false 关闭内置分页条(组合式外置 TablePagination);缺省模式 R13 不变 */\n showPagination: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 填充模式:根容器 h-full 纵向 flex,滚动区 flex-1 内滚;表头 sticky 钉住。\n * 父链需有确定高度(如页面布局的 .table-body);无确定高度时安全退化为自然高度。\n * 显式 prop 优先于布局 provide(key: \"tu-design:page-table-fill\");显式传 false 可强制关闭。\n * 纯布局属性,不进 defineTable/definition(virtual/height 例外),setup 期定版不支持运行时切换。 */\n fillHeight: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n});\n\n// ---- 填充模式(fillHeight)---------------------------------------------------\n// 布局上下文:页面布局容器 provide 同名 key,slot 内 TableRender 自动 fill。\n// 字符串 key 跨包约定(常量 PAGE_TABLE_FILL_KEY 已导出,消费方零依赖时按字符串值 provide),\n// setup 期定版,不支持运行时切换(与 virtual/search 同约定)。\nconst pageTableFill = inject<boolean>(PAGE_TABLE_FILL_KEY, false);\nconst fill = props.fillHeight ?? pageTableFill;\n\nconst emit = defineEmits<{\n \"update:page-index\": [pageIndex: number];\n \"update:page-size\": [pageSize: number];\n \"sort-change\": [sort: SortableOptions | undefined];\n \"row-click\": [record: DataRecord, index: number, event: MouseEvent];\n /** 行双击(与 row-click 独立,双击会先后触发 click 两次,属预期) */\n \"row-dblclick\": [record: DataRecord, index: number, event: MouseEvent];\n /** 行右键;不主动 preventDefault */\n \"row-contextmenu\": [record: DataRecord, index: number, event: MouseEvent];\n /** 单元格点击(columnKey 定位列);冒泡并存——cell-click 触发时 row-click 也会触发 */\n \"cell-click\": [record: DataRecord, columnKey: string, index: number, event: MouseEvent];\n \"selection-change\": [rows: DataRecord[]];\n \"update:selected-keys\": [keys: Array<string | number>];\n /** 搜索:FormRender 校验通过后触发;载荷为当前表单值 */\n search: [values: DataRecord];\n /** 重置:FormRender 已重置为 defaults 后触发;载荷为重置后的表单值 */\n reset: [values: DataRecord];\n /** 服务端模式 onLoad 抛错/ rejects 时触发;下一次 load 开始时 error 投影清除 */\n \"load-error\": [error: Error];\n /** 可见列变化(受控回写通知 / v-model:visible-keys) */\n \"update:visible-keys\": [keys: string[]];\n /** 列显隐变化(受控/非受控均触发,供业务持久化;载荷 = 可见列 key 有序数组,columns 原序) */\n \"column-visibility-change\": [keys: string[]];\n}>();\n\ndefineSlots<{\n empty?: () => VNodeChild;\n /** 错误态占位(服务端模式 onLoad 失败时渲染,优先于数据区) */\n error?: (props: { error: Error | undefined; retry: () => void }) => VNodeChild;\n}>();\n\n/** 加载态骨架行数(R14) */\nconst SKELETON_ROWS = [1, 2, 3, 4, 5];\n\n/** 内置渲染器单例:render 工厂按列求值时复用(工厂本身轻量,仅为整洁) */\nconst RENDERS = columnRenders();\n\n// 聚合式直接复用 defineTable 建好的内核;拆分式在本组件 setup 内建内核\n// (TanStack useVueTable 只能在 setup 调用,故不能放进条件分支深处)\nif (props.definition && props.columns && import.meta.env.DEV) {\n console.warn(\"[tu-design] <TableRender> definition 与 columns 同时传入,已按 definition 渲染。\");\n}\nif (props.definition && props.rowSelection && import.meta.env.DEV) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 rowSelection 请在 defineTable 配置,组件 prop 已忽略。\",\n );\n}\nconst instance =\n props.definition ??\n useTableRender({\n columns: props.columns ?? [],\n onLoad: props.onLoad,\n data: () => props.data,\n autoLoad: props.autoLoad,\n pageSizeOpts: props.pageSizeOpts,\n rowKey: props.rowKey,\n rowSelection: props.rowSelection,\n search: props.search,\n virtual: props.virtual,\n height: props.height,\n tree: props.tree,\n pageIndex: () => props.pageIndex,\n pageSize: () => props.pageSize,\n sort: () => props.sort,\n selectedKeys: () => props.selectedKeys,\n columnVisibility: props.definition?.columnVisibility,\n defaultVisibleKeys: () => props.defaultVisibleKeys,\n visibleKeys: () => props.visibleKeys,\n });\n// 拆分式已传 rowKey;聚合式由组件回填(S1:选择引擎依赖 rowKey 就绪)\ninstance.setRowKey(props.rowKey);\n\n// ---- 搜索表单(FormRender 联动) --------------------------------------------\n// 与 rowSelection 不同:聚合式下 prop 未被 definition 覆盖时回填引擎(不做聚合式忽略限制);\n// definition 与 prop 二选一,definition 优先,同传 DEV 警告\nif (props.definition && props.search) {\n if (instance.search && import.meta.env.DEV) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 search 已在 defineTable 配置,组件 prop 已忽略。\",\n );\n } else {\n instance.setSearch(props.search);\n }\n}\n// search 不支持运行时切换(与 FormRender definition/form 同款约定),setup 期定版即可\nconst search = instance.search;\n\n// 列设置触发器的 Tooltip 受控开合(Tooltip 与 Popover 触发器嵌套会吞点击,故手动控制、不嵌套触发器)\nconst settingsTipOpen = ref(false);\n\n// ---- 列显隐(column visibility,R20–R26) ------------------------------------\n// R26:聚合式(columnVisibility.defaultVisibleKeys 经引擎解析回传)与拆分式 prop 同传 → definition 优先。\n// 引擎是唯一解析点;聚合式受控回填经 setVisibleKeys(normalize 等值守卫防回弹);\n// 拆分式由引擎受控 watch 直接同步(源 = props getter)\nif (\n props.definition &&\n instance.defaultVisibleKeys !== undefined &&\n props.defaultVisibleKeys !== undefined &&\n import.meta.env.DEV\n) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 defaultVisibleKeys 已在 columnVisibility 配置,组件 prop 已忽略。\",\n );\n}\nwatch(\n () => props.visibleKeys,\n (next) => {\n if (props.definition && next !== undefined) instance.setVisibleKeys(next);\n },\n { immediate: true },\n);\n\n/**\n * 当前搜索表单值快照(浅拷贝;无 search 时为空对象)\n * @returns 表单值快照\n */\nfunction searchValues(): DataRecord {\n return search ? { ...search.form.state.values } : {};\n}\n\n/** 搜索:校验已由 FormRender 完成;归位第 1 页重载,分页/排序取数自动携带最新表单值 */\nfunction onSearch() {\n emit(\"search\", searchValues());\n instance.reload(true);\n}\n\n/** 重置:FormRender 已同步重置为 defaults(TanStack reset 为同步 setState),此刻读取即 defaults */\nfunction onReset() {\n emit(\"reset\", searchValues());\n instance.reload(true);\n}\n\nconst columns = computed(() => instance.columns);\nconst rows = computed(() => instance.table.getRowModel().rows);\n/** 内部加载态 ∪ 外部受控加载态(R14) */\nconst loading = computed(() => props.loading === true || instance.loading.value);\nconst showPagination = computed(() => Math.ceil(instance.page.total / instance.page.pageSize) > 1);\n/** 内置分页条开关(R28):showPagination=false 关闭;R13 仅作用于缺省模式 */\nconst showPaginationBar = computed(() => showPagination.value && props.showPagination !== false);\n/** 内置搜索区开关(R27):配置了 search 且未被 showSearch=false 关闭;列设置触发器不受影响 */\nconst showSearchArea = computed(() => search !== undefined && props.showSearch !== false);\n\n// ---- 错误态(服务端模式 onLoad 失败) ----------------------------------------\n// loading 判定优先;error 优先于正常数据(load 开始时引擎已清除旧错误,loading 期间 error 恒空)\nconst loadError = computed(() => instance.error.value);\nconst showError = computed(() => !loading.value && loadError.value !== undefined);\n\nwatch(loadError, (err) => {\n if (err) emit(\"load-error\", err);\n});\n\nfunction retry() {\n instance.reload();\n}\n\n// ---- 行选择(S 系列) -------------------------------------------------------\nconst selection = computed(() => instance.selection);\nconst selectedKeys = instance.selectedKeys;\nconst hasSelection = computed(() => selection.value.enabled);\n\n// ---- 列显隐(column visibility,R20–R26) -------------------------------------\nconst visibleKeySet = computed(() => new Set(instance.visibleKeys.value));\n/** 可见业务列(columns 原序子集):header/body/骨架/colspan/sticky 全部基于此渲染(R23/R25) */\nconst visibleColumns = computed(() =>\n columns.value.filter((column) => visibleKeySet.value.has(column.key)),\n);\n/** 列设置触发器/面板开关(默认 true);false 时不渲染 UI,受控 API 不受影响 */\nconst showColumnSettings = computed(() => props.columnSettings ?? true);\n\nfunction isColumnVisible(key: string): boolean {\n return visibleKeySet.value.has(key);\n}\n\n/**\n * 最少一列(R20):唯一可见列不可隐藏\n * @param key - 列 key\n * @returns 是否允许隐藏该列\n */\nfunction canHideColumn(key: string): boolean {\n return !(instance.visibleKeys.value.length <= 1 && visibleKeySet.value.has(key));\n}\n\nfunction toggleColumnVisible(key: string) {\n if (!canHideColumn(key)) return;\n instance.setVisibleKeys(\n isColumnVisible(key)\n ? instance.visibleKeys.value.filter((k) => k !== key)\n : [...instance.visibleKeys.value, key],\n );\n}\n\nconst allColumnsVisible = computed(\n () => columns.value.length > 0 && visibleColumns.value.length === columns.value.length,\n);\n\nfunction selectAllColumns() {\n if (allColumnsVisible.value) return;\n instance.setVisibleKeys(columns.value.map((column) => column.key));\n}\n\nfunction resetColumns() {\n // R21:恢复 defaultVisibleKeys;未配置 = 全部可见\n instance.setVisibleKeys(instance.defaultVisibleKeys ?? columns.value.map((column) => column.key));\n}\n\n// 受控/非受控均通知:统一投影变化 → 双事件(载荷 = columns 原序可见 key)\nwatch(instance.visibleKeys, (keys) => {\n emit(\"update:visible-keys\", [...keys]);\n emit(\"column-visibility-change\", [...keys]);\n});\n\n/** 总列数 = 可见业务列 + 选择列(空态 colspan 与骨架行,S8/R23) */\nconst columnCount = computed(() => visibleColumns.value.length + (hasSelection.value ? 1 : 0));\n\n// ---- 固定列(sticky) --------------------------------------------------------\n\n// DEV 校验:sticky 偏移只能从数字 width(px)推算,否则降级普通列(columns setup 期定版,只查一次)\nfor (const column of columns.value) {\n if (column.fixed !== undefined && typeof column.width !== \"number\") {\n console.warn(\n `[tu-design] <TableRender> fixed 列 \"${column.key}\" 需要数字 width,已忽略 fixed。`,\n );\n }\n}\n\n// DEV 提示(一次性,columns setup 期定版,R32):多列宽表全列无数字 width 时,\n// min-width 横滚不可达 —— 宽表请为列声明数字 width(px)。\nif (columns.value.length >= 10 && !columns.value.some((c) => typeof c.width === \"number\")) {\n console.warn(\n `[tu-design] <TableRender> ${columns.value.length} 列均无数字 width,` +\n `窄容器下不会出现横向滚动(R32);宽表请为列声明数字 width(px)。`,\n );\n}\n\n/** sticky 单元格映射(纯渲染层 computed,不进 TanStack pinning state):\n * 选择列视作最左 fixed 列参与累计(offset 0);fixed-left 按列序累加,\n * fixed-right 从最右列反向累计。edge = 该 sticky 组朝滚动方向的交界列(加分隔边框)。\n * 全部基于**可见集**(R23):sticky 组因隐藏变空则无该组输出(不输出边框)。\n */\nconst stickyOf = computed<StickyMap>(() => {\n const map: StickyMap = new Map();\n // instance.columns 是联合数组(聚合式 any / 拆分式 DataRecord),联合上的 filter\n // 类型谓词重载解析不可靠,故 map 提取时以断言收窄 width(条件已含 typeof 守卫)\n const lefts = visibleColumns.value\n .filter((column) => column.fixed === \"left\" && typeof column.width === \"number\")\n .map((column) => ({ key: column.key, width: column.width as number }));\n const rights = visibleColumns.value\n .filter((column) => column.fixed === \"right\" && typeof column.width === \"number\")\n .map((column) => ({ key: column.key, width: column.width as number }));\n\n let acc = 0;\n if (hasSelection.value) {\n map.set(SELECTION_CELL, { side: \"left\", offset: 0, edge: lefts.length === 0 });\n acc = selection.value.width;\n }\n lefts.forEach((left, index) => {\n map.set(left.key, { side: \"left\", offset: acc, edge: index === lefts.length - 1 });\n acc += left.width;\n });\n\n let racc = 0;\n for (let index = rights.length - 1; index >= 0; index--) {\n const right = rights[index]!;\n map.set(right.key, { side: \"right\", offset: racc, edge: index === 0 });\n racc += right.width;\n }\n return map;\n});\n\n// ---- 表格 min-width(列宽硬约束,R32) ----------------------------------------\n// 可见业务列数字 width 之和(含选择列)作为 <table> min-width 下限:\n// 容器不足 → 表格被顶到 Σwidth,auto 布局下列渲染宽度 == 指定宽度,stickyOf 偏移精确成立,\n// 滚动区 overflow-x-auto 横滚;容器充足 → 表格仍 100% 拉伸(有宽列可能被拉伸,\n// sticky 偏移按指定值累计的漂移为既有限制,非 R32 引入)。\n// 字符串 width 仅渲染提示值,不参与求和(与 stickyOf 口径一致);和为 0 不挂 style(零回归)。\nconst tableMinWidth = computed(() => {\n let sum = 0;\n for (const column of visibleColumns.value) {\n if (typeof column.width === \"number\" && column.width > 0) sum += column.width;\n }\n if (hasSelection.value && selection.value.width > 0) sum += selection.value.width;\n return sum;\n});\n\n/** 列宽 inline style 值(R33):数字补 px 单位——Vue :style 不自动加单位,\n * 裸数字会被浏览器当非法 CSS 值丢弃,列宽即失效;字符串视为已带单位原样输出。\n * @param width - 列宽配置\n * @returns 可直接用于 :style 的 CSS 宽度值;未配置返回 undefined\n */\nfunction widthOf(width?: number | string) {\n return typeof width === \"number\" ? `${width}px` : width;\n}\n\n/** 表头全选三态(S10):本页可选行与选中集求交派生(TanStack getter 追踪不稳,自算) */\nconst selectableKeys = computed(() =>\n rows.value.filter((row) => row.getCanSelect()).map((row) => rowKeyOf(row.original, row.index)),\n);\nconst headerChecked = computed(\n () =>\n hasSelection.value &&\n selection.value.type === \"checkbox\" &&\n selectableKeys.value.length > 0 &&\n selectableKeys.value.every((key) => selectedKeys.value.has(key)),\n);\nconst headerIndeterminate = computed(\n () =>\n hasSelection.value &&\n !headerChecked.value &&\n selectableKeys.value.some((key) => selectedKeys.value.has(key)),\n);\n\nfunction onHeaderSelect(checked: boolean) {\n instance.table.toggleAllPageRowsSelected(checked);\n}\n\n/**\n * 行选择控件切换;radio 不可取消由引擎 S4 守卫,不选中态点击传 checked=true\n * @param line - 行数据(含行 key)\n * @param checked - 目标选中态\n */\nfunction onRowSelect(line: { key: string }, checked: boolean) {\n instance.toggleRowSelected(line.key, checked);\n}\n\n// 选中集变化 → 对外事件(S7):排序/翻页不改变选中集,故不会误发\nwatch(instance.selectedKeys, (keys) => {\n emit(\"selection-change\", [...selection.value.value]);\n emit(\"update:selected-keys\", [...keys]);\n});\n\n/** 行 → 单元格值矩阵:render > formatter > record[key](R17) */\nconst body = computed<TableBodyLine[]>(() => {\n // 渲染器工厂按列求值一次(而非每单元格),避免用户工厂内的重分配被放大\n const renderFns = new Map(\n columns.value.filter((c) => c.render).map((c) => [c, c.render!(RENDERS)]),\n );\n return rows.value.map((row) => ({\n /** TanStack Row:树形渲染读 depth / getCanExpand / getIsExpanded / toggleExpanded */\n row,\n key: rowKeyOf(row.original, row.index),\n index: row.index,\n record: row.original,\n /** 行级可选过滤(S5):selectable 谓词交由引擎 enableRowSelection 判定 */\n canSelect: row.getCanSelect(),\n // 可见列的值矩阵(列显隐只裁剪列;R25 状态不受影响)\n cells: visibleColumns.value.map((column): VNodeChild => {\n const render = renderFns.get(column);\n if (render) return render(row.original, row.index, column);\n if (column.formatter) return column.formatter(row.original) as VNodeChild;\n return String(row.original[column.key] ?? \"\");\n }),\n }));\n});\n\n// ---- 树形数据(T 系列) ------------------------------------------------------\n// 引擎是唯一解析点(无效配置已 warn 并忽略,回传 undefined);tree 为 undefined 时不渲染缩进与 caret\nconst tree = instance.tree;\nconst treeIndent = tree?.indentSize ?? 16;\n\nlet missingRowKeyWarned = false;\n\n/**\n * 行主键:rowKey 字段缺失时以行索引兜底(R3)\n * @param record - 行记录\n * @param index - 行索引(兜底来源)\n * @returns 稳定的行主键字符串\n */\nfunction rowKeyOf(record: DataRecord, index: number): string {\n const value = record[props.rowKey];\n if (value === undefined || value === null) {\n if (!missingRowKeyWarned && import.meta.env.DEV) {\n missingRowKeyWarned = true;\n console.warn(\n `[tu-design] <TableRender> 部分记录缺少 rowKey 字段 \"${props.rowKey}\",已退化为按行索引标识。`,\n );\n }\n return `index-${index}`;\n }\n return String(value);\n}\n\n// ---- 虚拟滚动 / 填充模式 ------------------------------------------------------\n// definition 优先于 prop(配置定版,不支持运行时切换)\nconst virtualRaw = instance.virtual ?? props.virtual;\nconst heightRaw = instance.height ?? props.height;\n// fill 模式自带真实滚动盒(flex-1 实测高度),virtual 无需显式 height\nif (virtualRaw === true && heightRaw === undefined && !fill) {\n console.warn(\"[tu-design] <TableRender> virtual 需要配置 height,已降级普通渲染。\");\n}\nconst virtualEnabled = virtualRaw === true && (heightRaw !== undefined || fill);\nconst scrollHeight = computed(() => (typeof heightRaw === \"number\" ? `${heightRaw}px` : heightRaw));\n/** 表头 sticky 仅在组件内存在真实纵向滚动盒时生效(fill / virtual),普通模式不挂载,行为不变 */\nconst theadSticky = fill || virtualEnabled;\n/** 滚动区样式:virtual 用固定 height;fill 交给 flex 分配(二者同传以 fill 优先) */\nconst scrollStyle = computed(() => {\n if (fill || !virtualEnabled) return undefined;\n return { height: scrollHeight.value, overflowY: \"auto\" as const };\n});\n/** sticky 表头普通列类:不透明底防行内容透出;分隔线归 th(thead 行级 border 会随行滚走);\n * z-20 高于表体 fixed 列(--z-sticky: 10),纵向滚动行滑过表头时不穿透;\n * 表头 fixed 列的 z 由 stickyStyle inline style(var(--z-sticky-head))提供,inline 优先级天然覆盖此处 class */\nconst theadThClass = theadSticky ? \"sticky top-0 z-20 border-b border-border bg-background\" : \"\";\n/** sticky 态 table 改分离边框:preflight 为 border-collapse: collapse,\n * 折叠边框几何归属 table,Chrome 下 sticky th 粘住后自身 border-b 渲染丢失;\n * separate + spacing-0 恢复单元格边框。普通模式保持 collapse,零回归。 */\nconst tableClass = theadSticky ? \"border-separate border-spacing-0\" : \"\";\n\nconst scrollEl = ref<HTMLElement | null>(null);\nconst theadEl = ref<HTMLElement | null>(null);\n/** 滚动容器内 thead 占据的前缀高度(scrollMargin);表头内容静态,挂载后测量一次 */\nconst theadOffset = ref(0);\n\n// 仅 virtual: true 且 height 就绪时创建(配置 setup 期定版,顶层条件分支可安全注册生命周期)\nconst virtualizerRef = virtualEnabled\n ? useVirtualizer(\n computed(() => ({\n count: rows.value.length, // 翻页/重载后行窗口变化 → options 更新(setOptions 自动生效)\n getScrollElement: () => scrollEl.value,\n estimateSize: () => 40,\n overscan: 8,\n getItemKey: (index: number) => rowKeyOf(rows.value[index]!, index), // rowKey 作为虚拟行 key\n scrollMargin: theadOffset.value, // thead 在滚动容器内的 offset 前缀\n })),\n )\n : null;\n\nonMounted(() => {\n if (virtualEnabled) theadOffset.value = theadEl.value?.offsetHeight ?? 0;\n});\n\nconst virtualRows = computed(() => (virtualizerRef ? virtualizerRef.value.getVirtualItems() : []));\nconst virtualTotal = computed(() => (virtualizerRef ? virtualizerRef.value.getTotalSize() : 0));\n/** 窗口行 + 对应全量行数据(cells 矩阵已由 body computed 缓存,虚拟化只裁剪 DOM 节点) */\nconst virtualLines = computed(() =>\n virtualRows.value.map((row) => ({ row, line: body.value[row.index]! })),\n);\nconst padTop = computed(() => virtualRows.value[0]?.start ?? 0);\nconst padBottom = computed(() => {\n const items = virtualRows.value;\n return items.length === 0 ? 0 : Math.max(0, virtualTotal.value - items[items.length - 1]!.end);\n});\n\n/** 行高动态测量:measureElement 读 data-index 把实测高度写回(行内容高度可变,不假设固定行高)。\n * 行组件为函数 ref,拿到的是组件实例,需经 $el 取真实 tr。\n * @param node - 函数 ref 收到的行元素或组件实例\n */\nfunction measureRow(node: Element | ComponentPublicInstance | null) {\n const el = node instanceof Element ? node : (node?.$el as Element | undefined);\n if (el instanceof Element) virtualizerRef?.value.measureElement(el);\n}\n\n/**\n * aria-sort 仅在该列当前被排序时标注(R16)\n * @param column - 列配置\n * @returns 当前排序方向对应的 aria-sort 值;未排序返回 undefined\n */\nfunction ariaSort(column: TableColumnOptions): \"ascending\" | \"descending\" | undefined {\n if (instance.sort.value?.key !== column.key) return undefined;\n return instance.sort.value.direction === \"asc\" ? \"ascending\" : \"descending\";\n}\n\nfunction sortMark(column: TableColumnOptions): string {\n const direction = instance.sort.value?.key === column.key ? instance.sort.value.direction : \"\";\n return direction === \"asc\" ? \"↑\" : direction === \"desc\" ? \"↓\" : \"\";\n}\n\nfunction onSort(key: string) {\n instance.toggleSort(key);\n emit(\"sort-change\", instance.sort.value);\n}\n\nfunction onPageIndex(pageIndex: number) {\n instance.setPageIndex(pageIndex);\n lastEmittedPage.pageIndex = pageIndex;\n emit(\"update:page-index\", pageIndex);\n}\n\nfunction onPageSize(pageSize: number) {\n instance.setPageSize(pageSize);\n lastEmittedPage.pageSize = pageSize;\n emit(\"update:page-size\", pageSize);\n}\n\n// ---- 受控模式(v-model):page 投影 → update:* 通知 ---------------------------\n// 仅 page-index/page-size 至少一方受控时安装;lastEmittedPage 去重——\n// 动作路径已 emit 过的值不再重复发(受控回写/内部归位只通知「未通知过的」变化)\nconst pageControlled = () => props.pageIndex !== undefined || props.pageSize !== undefined;\nconst lastEmittedPage = {\n pageIndex: undefined as number | undefined,\n pageSize: undefined as number | undefined,\n};\n\nif (pageControlled()) {\n watch(\n () => [instance.page.pageIndex, instance.page.pageSize] as const,\n ([pageIndex, pageSize]) => {\n if (pageIndex !== lastEmittedPage.pageIndex) {\n lastEmittedPage.pageIndex = pageIndex;\n emit(\"update:page-index\", pageIndex);\n }\n if (pageSize !== lastEmittedPage.pageSize) {\n lastEmittedPage.pageSize = pageSize;\n emit(\"update:page-size\", pageSize);\n }\n },\n );\n}\n\nfunction onRowClick(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-click\", record, index, event);\n}\n\nfunction onRowDblclick(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-dblclick\", record, index, event);\n}\n\nfunction onRowContextmenu(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-contextmenu\", record, index, event);\n}\n\nfunction onCellClick(record: DataRecord, columnKey: string, index: number, event: MouseEvent) {\n emit(\"cell-click\", record, columnKey, index, event);\n}\n\ndefineExpose({\n table: instance.table,\n page: instance.page,\n sort: instance.sort,\n loading: instance.loading,\n error: instance.error,\n visibleKeys: instance.visibleKeys,\n setVisibleKeys: instance.setVisibleKeys,\n reload: instance.reload,\n toggleSort: onSort,\n setPageIndex: onPageIndex,\n setPageSize: onPageSize,\n selection: instance.selection,\n selectedKeys: instance.selectedKeys,\n setSelection: instance.setSelection,\n clearSelection: instance.clearSelection,\n});\n</script>\n\n<template>\n <div :class=\"cn('w-full', fill && 'flex h-full min-h-0 flex-col', $attrs.class)\">\n <!-- 搜索区 + 列设置触发器:同行右对齐(items-end);无搜索时触发器位于表格上方(R27:showSearch=false 关闭搜索区) -->\n <div\n v-if=\"showSearchArea || showColumnSettings\"\n :class=\"cn('mb-2 flex items-end justify-between gap-2', fill && 'shrink-0')\"\n >\n <FormRender\n v-if=\"showSearchArea\"\n class=\"min-w-0 flex-1\"\n :definition=\"search\"\n :searchable=\"search.actions ? undefined : true\"\n @search=\"onSearch\"\n @reset=\"onReset\"\n />\n\n <!-- 列设置:Popover 面板(R20 最少一列 / R21 重置 / R22 不含选择列);\n 触发钮 Tooltip 手动受控开合(Tooltip 与 Popover 触发器嵌套会吞点击,故并列渲染、不走 hover 自动触发) -->\n <template v-if=\"showColumnSettings\">\n <Popover align=\"end\" content-class=\"w-56 p-0\">\n <Button\n variant=\"ghost\"\n size=\"icon\"\n aria-label=\"列设置\"\n aria-haspopup=\"true\"\n @pointerenter=\"settingsTipOpen = true\"\n @pointerleave=\"settingsTipOpen = false\"\n >\n <!-- lucide Settings2(内联 SVG,跟随项目图标现状) -->\n <svg\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"size-4\"\n aria-hidden=\"true\"\n >\n <path d=\"M20 7h-9\" />\n <path d=\"M14 17H5\" />\n <circle cx=\"17\" cy=\"17\" r=\"3\" />\n <circle cx=\"7\" cy=\"7\" r=\"3\" />\n </svg>\n </Button>\n <template #content>\n <div class=\"flex items-center justify-end gap-3 px-3 py-2\">\n <button\n type=\"button\"\n class=\"text-muted-foreground hover:text-foreground cursor-pointer text-xs disabled:cursor-not-allowed disabled:opacity-50\"\n :disabled=\"allColumnsVisible\"\n @click=\"selectAllColumns\"\n >\n 全选\n </button>\n <button\n type=\"button\"\n class=\"text-muted-foreground hover:text-foreground cursor-pointer text-xs\"\n @click=\"resetColumns\"\n >\n 重置\n </button>\n </div>\n <Separator />\n <div class=\"max-h-64 overflow-y-auto py-1\">\n <div\n v-for=\"column in columns\"\n :key=\"column.key\"\n data-column-item\n :data-column-key=\"column.key\"\n class=\"hover:bg-accent/50 flex h-8 cursor-pointer items-center gap-2 px-3\"\n @click=\"toggleColumnVisible(column.key)\"\n >\n <Checkbox\n :checked=\"isColumnVisible(column.key)\"\n :disabled=\"!canHideColumn(column.key)\"\n @update:checked=\"toggleColumnVisible(column.key)\"\n @click.stop\n />\n <span class=\"min-w-0 flex-1 truncate\">{{ column.title }}</span>\n <!-- 有效 fixed 列(数字 width)标识 -->\n <svg\n v-if=\"column.fixed !== undefined && typeof column.width === 'number'\"\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"text-muted-foreground size-3 shrink-0\"\n aria-hidden=\"true\"\n >\n <path d=\"M12 17v5\" />\n <path\n d=\"M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V7h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1z\"\n />\n </svg>\n </div>\n </div>\n </template>\n </Popover>\n <!-- 纯受控气泡(无默认插槽,不渲染触发器):开合由触发钮 pointerenter/leave 驱动 -->\n <Tooltip :open=\"settingsTipOpen\" content=\"列设置\" />\n </template>\n </div>\n\n <!-- 滚动容器:横向滚动时 fixed 列 sticky 生效;virtual/fill 模式兼任纵向滚动(分页条不参与滚动) -->\n <div\n ref=\"scrollEl\"\n :class=\"cn('overflow-x-auto', fill && 'min-h-0 flex-1 overflow-y-auto')\"\n :style=\"scrollStyle\"\n >\n <table\n class=\"w-full caption-bottom text-sm\"\n :class=\"tableClass\"\n :style=\"tableMinWidth > 0 ? { minWidth: `${tableMinWidth}px` } : undefined\"\n >\n <thead ref=\"theadEl\" :class=\"theadSticky ? undefined : '[&_tr]:border-b'\">\n <tr>\n <!-- 选择列:checkbox 型表头为本页全选三态(S3/S10);radio 型占位;视作最左固定列 -->\n <th\n v-if=\"hasSelection\"\n scope=\"col\"\n class=\"h-10 w-12 px-2 text-center align-middle font-medium text-muted-foreground\"\n :class=\"[stickyClass(stickyOf, SELECTION_CELL), theadThClass]\"\n :style=\"[\n { width: `${selection.width}px` },\n stickyStyle(stickyOf, SELECTION_CELL, true),\n ]\"\n >\n <Checkbox\n v-if=\"selection.type === 'checkbox'\"\n :checked=\"headerIndeterminate ? 'indeterminate' : headerChecked\"\n :aria-label=\"'全选本页'\"\n @update:checked=\"onHeaderSelect\"\n />\n </th>\n <th\n v-for=\"column in visibleColumns\"\n :key=\"column.key\"\n scope=\"col\"\n class=\"h-10 px-2 align-middle font-medium text-muted-foreground\"\n :class=\"[stickyClass(stickyOf, column.key), theadThClass]\"\n :style=\"[\n { width: widthOf(column.width), textAlign: column.align ?? 'center' },\n stickyStyle(stickyOf, column.key, true),\n ]\"\n :aria-sort=\"ariaSort(column)\"\n >\n <button\n v-if=\"column.sortable\"\n type=\"button\"\n class=\"inline-flex items-center gap-1 hover:text-foreground\"\n @click=\"onSort(column.key)\"\n >\n {{ column.title }}\n <span aria-hidden=\"true\" class=\"text-xs\">{{ sortMark(column) }}</span>\n </button>\n <template v-else>{{ column.title }}</template>\n </th>\n </tr>\n </thead>\n\n <tbody class=\"[&_tr:last-child]:border-0\">\n <!-- 加载态:固定 5 行骨架(R14);选择列一并占位(S8);骨架不虚拟化;loading 判定优先 -->\n <template v-if=\"loading\">\n <tr v-for=\"row in SKELETON_ROWS\" :key=\"row\" data-skeleton>\n <td\n v-if=\"hasSelection\"\n class=\"p-2 text-center align-middle\"\n :class=\"stickyClass(stickyOf, SELECTION_CELL)\"\n :style=\"stickyStyle(stickyOf, SELECTION_CELL, false)\"\n >\n <Skeleton class=\"size-4\" />\n </td>\n <td\n v-for=\"column in visibleColumns\"\n :key=\"column.key\"\n class=\"p-2 align-middle\"\n :class=\"stickyClass(stickyOf, column.key)\"\n :style=\"[\n { textAlign: column.align ?? 'center' },\n stickyStyle(stickyOf, column.key, false),\n ]\"\n >\n <Skeleton class=\"h-4 w-full\" />\n </td>\n </tr>\n </template>\n\n <!-- 错误态:error 优先于正常数据;插槽可自定义(slot props { error, retry }) -->\n <template v-else-if=\"showError\">\n <tr data-error>\n <td :colspan=\"columnCount\" class=\"p-8 text-center text-muted-foreground\">\n <slot name=\"error\" :error=\"loadError\" :retry=\"retry\">\n <div class=\"flex flex-col items-center gap-3\">\n <p>{{ loadError?.message ?? \"加载失败\" }}</p>\n <Button variant=\"outline\" size=\"sm\" @click=\"retry\">重试</Button>\n </div>\n </slot>\n </td>\n </tr>\n </template>\n\n <!-- 虚拟滚动:窗口行 + 前后占位行(总高撑开滚动区间;行高经 measureElement 动态测量) -->\n <template v-else-if=\"virtualEnabled\">\n <tr aria-hidden=\"true\" data-virtual-pad :style=\"{ height: `${padTop}px` }\">\n <td :colspan=\"columnCount\" class=\"border-0 p-0\"></td>\n </tr>\n <TableBodyRow\n v-for=\"item in virtualLines\"\n :key=\"item.line.key\"\n :ref=\"measureRow\"\n :data-index=\"item.row.index\"\n :line=\"item.line\"\n :columns=\"visibleColumns\"\n :selection=\"hasSelection ? selection.type : undefined\"\n :selected=\"selectedKeys.has(item.line.key)\"\n :sticky=\"stickyOf\"\n :tree-indent=\"tree ? treeIndent : undefined\"\n @select=\"(checked: boolean) => onRowSelect(item.line, checked)\"\n @row-click=\"onRowClick(item.line.record, item.line.index, $event)\"\n @row-dblclick=\"onRowDblclick(item.line.record, item.line.index, $event)\"\n @row-contextmenu=\"onRowContextmenu(item.line.record, item.line.index, $event)\"\n @cell-click=\"\n (columnKey: string, event: MouseEvent) =>\n onCellClick(item.line.record, columnKey, item.line.index, event)\n \"\n />\n <tr aria-hidden=\"true\" data-virtual-pad :style=\"{ height: `${padBottom}px` }\">\n <td :colspan=\"columnCount\" class=\"border-0 p-0\"></td>\n </tr>\n </template>\n\n <template v-else>\n <TableBodyRow\n v-for=\"line in body\"\n :key=\"line.key\"\n :line=\"line\"\n :columns=\"visibleColumns\"\n :selection=\"hasSelection ? selection.type : undefined\"\n :selected=\"selectedKeys.has(line.key)\"\n :sticky=\"stickyOf\"\n :tree-indent=\"tree ? treeIndent : undefined\"\n @select=\"(checked: boolean) => onRowSelect(line, checked)\"\n @row-click=\"onRowClick(line.record, line.index, $event)\"\n @row-dblclick=\"onRowDblclick(line.record, line.index, $event)\"\n @row-contextmenu=\"onRowContextmenu(line.record, line.index, $event)\"\n @cell-click=\"\n (columnKey: string, event: MouseEvent) =>\n onCellClick(line.record, columnKey, line.index, event)\n \"\n />\n </template>\n\n <!-- 空态:横跨全列的单单元格,不虚拟化;错误态优先 -->\n <tr v-if=\"!loading && !showError && body.length === 0\" data-empty>\n <td :colspan=\"columnCount\" class=\"p-8 text-center text-muted-foreground\">\n <slot name=\"empty\">{{ emptyText ?? \"暂无数据\" }}</slot>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n\n <!-- R31:手动接线(须经 onPageIndex/onPageSize 包装器保留受控去重);显式补 border-t 与 size select 保持现状 -->\n <TablePagination\n v-if=\"showPaginationBar\"\n :class=\"cn('border-t', fill && 'shrink-0')\"\n :page-index=\"instance.page.pageIndex\"\n :page-size=\"instance.page.pageSize\"\n :page-size-opts=\"instance.page.pageSizeOpts\"\n :total=\"instance.page.total\"\n :show-size-select=\"true\"\n @update:page-index=\"onPageIndex\"\n @update:page-size=\"onPageSize\"\n />\n </div>\n</template>\n"
|
|
42
|
+
"content": "<script setup lang=\"ts\">\nimport type { ComponentPublicInstance, PropType, VNodeChild } from \"vue\";\nimport { useVirtualizer } from \"@tanstack/vue-virtual\";\nimport { columnRenders } from \"./column-renders\";\nimport { computed, inject, nextTick, onMounted, ref, watch } from \"vue\";\nimport { Button } from \"@/components/ui/button\";\nimport { Checkbox } from \"@/components/ui/checkbox\";\nimport { FormRender, type FormRenderDefinition } from \"@/components/ui/form-render\";\nimport { Popover } from \"@/components/ui/popover\";\nimport { Separator } from \"@/components/ui/separator\";\nimport { Skeleton } from \"@/components/ui/skeleton\";\nimport { Tooltip } from \"@/components/ui/tooltip\";\nimport { cn } from \"@/lib/utils\";\nimport { isColumnGroup } from \"./columns\";\nimport { PAGE_TABLE_FILL_KEY, DRAG_CELL, SELECTION_CELL } from \"./constants\";\nimport { stickyClass, stickyStyle, type StickyMap } from \"./sticky\";\nimport TableBodyRow from \"./TableBodyRow.vue\";\nimport TablePagination from \"./TablePagination.vue\";\nimport type {\n ColumnVisibilityOptions,\n DataRecord,\n SortableOptions,\n TableBodyLine,\n TableColumnGroupOptions,\n TableColumnNode,\n TableColumnOptions,\n TableDraggableOptions,\n TableDragSortPayload,\n TableLoadParams,\n TableRenderDefinition,\n TableSelectionOptions,\n TreeOptions,\n} from \"./types\";\nimport { useTableRender } from \"./useTableRender\";\nimport { createRowSnapshot, useRowDrag } from \"./useRowDrag\";\n\n// boolean flags 用运行时声明 + default: undefined 禁用 Vue 的 Boolean casting\n// (casting 会让未传的 prop 变 false;Checkbox/Dialog/FormRender 同款约定)\nconst props = defineProps({\n /** 聚合式(推荐):defineTable 返回的定义对象 */\n definition: { type: Object as PropType<TableRenderDefinition<any>> },\n /** 数据主键(记录缺字段时以行索引兜底) */\n rowKey: { type: String, required: true },\n /** 拆分式:与 definition 二选一,definition 优先(支持分组列节点) */\n columns: { type: Array as PropType<TableColumnNode[]> },\n onLoad: {\n type: Function as PropType<(params: TableLoadParams) => void | Promise<unknown>>,\n },\n data: { type: Array as PropType<DataRecord[]> },\n autoLoad: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 每页条数 / 受控每页条数:传入即受控(pageIndex 未受控时页码归位内部处理并通知) */\n pageSize: { type: Number },\n pageSizeOpts: { type: Array as PropType<number[]> },\n loading: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n emptyText: { type: String },\n /** 行选择(仅拆分式生效;聚合式请在 defineTable 配置):\"radio\" | \"checkbox\" | 对象 */\n rowSelection: {\n type: [String, Object] as PropType<\"radio\" | \"checkbox\" | TableSelectionOptions>,\n default: undefined,\n },\n /** 搜索表单(defineForm 返回值):拆分式直接传;聚合式请在 defineTable 配置(definition 优先,同传 DEV 警告) */\n search: { type: Object as PropType<FormRenderDefinition<any>> },\n /** 虚拟滚动:开启后表体行虚拟化渲染;聚合式请在 defineTable 配置(definition 优先);须同时给 height */\n virtual: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 虚拟滚动容器高度(数字 px 或 CSS 高度);仅 virtual: true 时生效 */\n height: { type: [Number, String] as PropType<number | string> },\n /** 树形数据(子行展开/收起);拆分式直接传,聚合式请在 defineTable 配置 */\n tree: { type: Object as PropType<TreeOptions> },\n /** 行拖拽排序(仅拆分式生效;聚合式请在 defineTable 配置):true 或对象配置;与 tree/virtual 互斥 */\n draggable: {\n type: [Boolean, Object] as PropType<boolean | TableDraggableOptions>,\n default: undefined,\n },\n /** 受控页码(1-based):传入即受控,缺省非受控;内部翻页经 update:page-index 通知 */\n pageIndex: { type: Number },\n /** 受控排序:传入即受控;内部/外部变化均经 sort-change 通知 */\n sort: { type: Object as PropType<SortableOptions> },\n /** 受控选中集(数组,与 update:selected-keys 载荷同构):传入即受控 */\n selectedKeys: { type: Array as PropType<Array<string | number>> },\n /** 受控可见列 key(columns 原序子集):传入即受控;内部显隐经 update:visible-keys 通知 */\n visibleKeys: { type: Array as PropType<string[]> },\n /** 拆分式默认可见列集;与聚合式 columnVisibility.defaultVisibleKeys 同传时 DEV 警告(definition 优先) */\n defaultVisibleKeys: { type: Array as PropType<string[]> },\n /** 列设置触发器/面板开关(默认 true);false 时不渲染 UI,受控 API 不受影响 */\n columnSettings: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 搜索区渲染开关:false 关闭内置搜索区(组合式外置 FormRender);数据链路不变 */\n showSearch: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 分页条渲染开关:false 关闭内置分页条(组合式外置 TablePagination);缺省模式单页自隐藏不变 */\n showPagination: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 填充模式:根容器 h-full 纵向 flex,滚动区 flex-1 内滚;表头 sticky 钉住。\n * 父链需有确定高度(如页面布局的 .table-body);无确定高度时安全退化为自然高度。\n * 显式 prop 优先于布局 provide(key: \"tu-design:page-table-fill\");显式传 false 可强制关闭。\n * 纯布局属性,不进 defineTable/definition(virtual/height 例外),setup 期定版不支持运行时切换。 */\n fillHeight: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n});\n\n// ---- 填充模式(fillHeight)---------------------------------------------------\n// 布局上下文:页面布局容器 provide 同名 key,slot 内 TableRender 自动 fill。\n// 字符串 key 跨包约定(常量 PAGE_TABLE_FILL_KEY 已导出,消费方零依赖时按字符串值 provide),\n// setup 期定版,不支持运行时切换(与 virtual/search 同约定)。\nconst pageTableFill = inject<boolean>(PAGE_TABLE_FILL_KEY, false);\nconst fill = props.fillHeight ?? pageTableFill;\n\nconst emit = defineEmits<{\n \"update:page-index\": [pageIndex: number];\n \"update:page-size\": [pageSize: number];\n \"sort-change\": [sort: SortableOptions | undefined];\n \"row-click\": [record: DataRecord, index: number, event: MouseEvent];\n /** 行双击(与 row-click 独立,双击会先后触发 click 两次,属预期) */\n \"row-dblclick\": [record: DataRecord, index: number, event: MouseEvent];\n /** 行右键;不主动 preventDefault */\n \"row-contextmenu\": [record: DataRecord, index: number, event: MouseEvent];\n /** 单元格点击(columnKey 定位列);冒泡并存——cell-click 触发时 row-click 也会触发 */\n \"cell-click\": [record: DataRecord, columnKey: string, index: number, event: MouseEvent];\n \"selection-change\": [rows: DataRecord[]];\n \"update:selected-keys\": [keys: Array<string | number>];\n /** 搜索:FormRender 校验通过后触发;载荷为当前表单值 */\n search: [values: DataRecord];\n /** 重置:FormRender 已重置为 defaults 后触发;载荷为重置后的表单值 */\n reset: [values: DataRecord];\n /** 服务端模式 onLoad 抛错/ rejects 时触发;下一次 load 开始时 error 投影清除 */\n \"load-error\": [error: Error];\n /** 可见列变化(受控回写通知 / v-model:visible-keys) */\n \"update:visible-keys\": [keys: string[]];\n /** 列显隐变化(受控/非受控均触发,供业务持久化;载荷 = 可见列 key 有序数组,columns 原序) */\n \"column-visibility-change\": [keys: string[]];\n /** 行拖拽落位(仅成功 drop 触发,取消路径不发):from/to 为页内索引,rows = 当前页新行序。\n * 静态模式引擎已先行重排,调用方应回写自身数据源;服务端模式需持久化后 reload */\n \"drag-sort\": [payload: TableDragSortPayload];\n}>();\n\ndefineSlots<{\n empty?: () => VNodeChild;\n /** 错误态占位(服务端模式 onLoad 失败时渲染,优先于数据区) */\n error?: (props: { error: Error | undefined; retry: () => void }) => VNodeChild;\n}>();\n\n/** 加载态骨架行数 */\nconst SKELETON_ROWS = [1, 2, 3, 4, 5];\n\n/** 内置渲染器单例:render 工厂按列求值时复用(工厂本身轻量,仅为整洁) */\nconst RENDERS = columnRenders();\n\n// 聚合式直接复用 defineTable 建好的内核;拆分式在本组件 setup 内建内核\n// (TanStack useVueTable 只能在 setup 调用,故不能放进条件分支深处)\nif (props.definition && props.columns && import.meta.env.DEV) {\n console.warn(\"[tu-design] <TableRender> definition 与 columns 同时传入,已按 definition 渲染。\");\n}\nif (props.definition && props.rowSelection && import.meta.env.DEV) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 rowSelection 请在 defineTable 配置,组件 prop 已忽略。\",\n );\n}\nif (props.definition && props.draggable !== undefined && import.meta.env.DEV) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 draggable 请在 defineTable 配置,组件 prop 已忽略。\",\n );\n}\nconst instance =\n props.definition ??\n useTableRender({\n columns: props.columns ?? [],\n onLoad: props.onLoad,\n data: () => props.data,\n autoLoad: props.autoLoad,\n pageSizeOpts: props.pageSizeOpts,\n rowKey: props.rowKey,\n rowSelection: props.rowSelection,\n search: props.search,\n virtual: props.virtual,\n height: props.height,\n tree: props.tree,\n draggable: props.draggable,\n pageIndex: () => props.pageIndex,\n pageSize: () => props.pageSize,\n sort: () => props.sort,\n selectedKeys: () => props.selectedKeys,\n columnVisibility: props.definition?.columnVisibility,\n defaultVisibleKeys: () => props.defaultVisibleKeys,\n visibleKeys: () => props.visibleKeys,\n });\n// 拆分式已传 rowKey;聚合式由组件回填(选择引擎依赖 rowKey 就绪)\ninstance.setRowKey(props.rowKey);\n\n// ---- 搜索表单(FormRender 联动) --------------------------------------------\n// 与 rowSelection 不同:聚合式下 prop 未被 definition 覆盖时回填引擎(不做聚合式忽略限制);\n// definition 与 prop 二选一,definition 优先,同传 DEV 警告\nif (props.definition && props.search) {\n if (instance.search && import.meta.env.DEV) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 search 已在 defineTable 配置,组件 prop 已忽略。\",\n );\n } else {\n instance.setSearch(props.search);\n }\n}\n// search 不支持运行时切换(与 FormRender definition/form 同款约定),setup 期定版即可\nconst search = instance.search;\n\n// 列设置触发器的 Tooltip 受控开合(Tooltip 与 Popover 触发器嵌套会吞点击,故手动控制、不嵌套触发器)\nconst settingsTipOpen = ref(false);\n\n// ---- 列显隐(column visibility) ------------------------------------\n// 聚合式(columnVisibility.defaultVisibleKeys 经引擎解析回传)与拆分式 prop 同传 → definition 优先。\n// 引擎是唯一解析点;聚合式受控回填经 setVisibleKeys(normalize 等值守卫防回弹);\n// 拆分式由引擎受控 watch 直接同步(源 = props getter)\nif (\n props.definition &&\n instance.defaultVisibleKeys !== undefined &&\n props.defaultVisibleKeys !== undefined &&\n import.meta.env.DEV\n) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 defaultVisibleKeys 已在 columnVisibility 配置,组件 prop 已忽略。\",\n );\n}\nwatch(\n () => props.visibleKeys,\n (next) => {\n if (props.definition && next !== undefined) instance.setVisibleKeys(next);\n },\n { immediate: true },\n);\n\n/**\n * 当前搜索表单值快照(浅拷贝;无 search 时为空对象)\n * @returns 表单值快照\n */\nfunction searchValues(): DataRecord {\n return search ? { ...search.form.state.values } : {};\n}\n\n/** 搜索:校验已由 FormRender 完成;归位第 1 页重载,分页/排序取数自动携带最新表单值 */\nfunction onSearch() {\n emit(\"search\", searchValues());\n instance.reload(true);\n}\n\n/** 重置:FormRender 已同步重置为 defaults(TanStack reset 为同步 setState),此刻读取即 defaults */\nfunction onReset() {\n emit(\"reset\", searchValues());\n instance.reload(true);\n}\n\nconst columns = computed(() => instance.columns);\nconst rows = computed(() => instance.table.getRowModel().rows);\n/** 内部加载态 ∪ 外部受控加载态 */\nconst loading = computed(() => props.loading === true || instance.loading.value);\nconst showPagination = computed(() => Math.ceil(instance.page.total / instance.page.pageSize) > 1);\n/** 内置分页条开关:showPagination=false 关闭;单页自隐藏仅作用于缺省模式 */\nconst showPaginationBar = computed(() => showPagination.value && props.showPagination !== false);\n/** 内置搜索区开关:配置了 search 且未被 showSearch=false 关闭;列设置触发器不受影响 */\nconst showSearchArea = computed(() => search !== undefined && props.showSearch !== false);\n\n// ---- 错误态(服务端模式 onLoad 失败) ----------------------------------------\n// loading 判定优先;error 优先于正常数据(load 开始时引擎已清除旧错误,loading 期间 error 恒空)\nconst loadError = computed(() => instance.error.value);\nconst showError = computed(() => !loading.value && loadError.value !== undefined);\n\nwatch(loadError, (err) => {\n if (err) emit(\"load-error\", err);\n});\n\nfunction retry() {\n instance.reload();\n}\n\n// ---- 行选择(S 系列) -------------------------------------------------------\nconst selection = computed(() => instance.selection);\nconst selectedKeys = instance.selectedKeys;\nconst hasSelection = computed(() => selection.value.enabled);\n\n// ---- 列显隐(column visibility) -------------------------------------\nconst visibleKeySet = computed(() => new Set(instance.visibleKeys.value));\n/** 可见业务列(columns 原序子集):header/body/骨架/colspan/sticky 全部基于此渲染 */\nconst visibleColumns = computed(() =>\n columns.value.filter((column) => visibleKeySet.value.has(column.key)),\n);\n\n// ---- 表头分组(多级表头) -------------------------------------------\n// 原始列节点树(definition.columnTree 缺省时回退扁平列 = 单级表头)\nconst columnsTree = computed<TableColumnNode<DataRecord>[]>(\n () => (instance.columnTree as TableColumnNode<DataRecord>[]) ?? columns.value,\n);\n\n/** 可见表头树节点:按 visibleKeySet 剪枝后的结构(空分组已被剔除) */\ninterface HeaderNodeView {\n node: TableColumnNode<DataRecord>;\n isGroup: boolean;\n /** DFS 索引路径(如 \"0-1\"):分组单元格 key 的唯一来源,与 title 解耦 */\n path: string;\n children: HeaderNodeView[];\n}\n\n/**\n * 按可见集递归构建表头树:分组子树可见叶子为 0 时整支剔除(与列显隐同口径)。\n * @param nodes - 列节点树(或其子树)\n * @param parentPath - 父级 DFS 索引路径(根为 \"\")\n * @returns 剪枝后的可见表头树\n */\nfunction buildVisibleHeaderTree(\n nodes: TableColumnNode<DataRecord>[],\n parentPath: string,\n): HeaderNodeView[] {\n const views: HeaderNodeView[] = [];\n nodes.forEach((node, index) => {\n const path = parentPath === \"\" ? `${index}` : `${parentPath}-${index}`;\n if (isColumnGroup(node)) {\n const children = buildVisibleHeaderTree(node.children, path);\n if (children.length > 0) views.push({ node, isGroup: true, path, children });\n } else if (visibleKeySet.value.has(node.key)) {\n views.push({ node, isGroup: false, path, children: [] });\n }\n });\n return views;\n}\n\n/** 唯一派生源:可见表头树(maxDepth 与表头矩阵同源于此,杜绝口径漂移) */\nconst visibleHeaderTree = computed(() => buildVisibleHeaderTree(columnsTree.value, \"\"));\n\n/** 表头深度(可见树):无分组时为 1 */\nconst maxDepth = computed(() => {\n const depthOf = (view: HeaderNodeView): number =>\n view.children.length > 0 ? 1 + Math.max(...view.children.map(depthOf)) : 1;\n return visibleHeaderTree.value.length > 0 ? Math.max(...visibleHeaderTree.value.map(depthOf)) : 1;\n});\n\n/** 表头单元格:分组跨列、叶子下沉贴底 */\ninterface HeaderCell {\n node: TableColumnNode<DataRecord>;\n /** Vue 列表 key:叶子用列 key,分组用 DFS 路径(唯一稳定) */\n key: string;\n path: string;\n depth: number;\n colSpan: number;\n rowSpan: number;\n isGroup: boolean;\n /** 该单元格覆盖的可见叶子列 key(分组为子树全部,叶子为自身) */\n leafKeys: string[];\n}\n\n/** 表头矩阵:行 × 单元格(叶子 rowSpan = maxDepth - depth,分组 colSpan = 子树可见叶子数) */\nconst headerRows = computed<HeaderCell[][]>(() => {\n const rows: HeaderCell[][] = Array.from({ length: maxDepth.value }, () => []);\n const collectLeaves = (view: HeaderNodeView): string[] =>\n view.isGroup\n ? view.children.flatMap(collectLeaves)\n : [(view.node as TableColumnOptions<DataRecord>).key];\n\n const walk = (views: HeaderNodeView[], depth: number) => {\n for (const view of views) {\n const leafKeys = collectLeaves(view);\n if (view.isGroup) {\n rows[depth]!.push({\n node: view.node,\n key: `g:${view.path}`,\n path: view.path,\n depth,\n colSpan: leafKeys.length,\n rowSpan: 1,\n isGroup: true,\n leafKeys,\n });\n } else {\n rows[depth]!.push({\n node: view.node,\n key: (view.node as TableColumnOptions<DataRecord>).key,\n path: view.path,\n depth,\n colSpan: 1,\n rowSpan: maxDepth.value - depth,\n isGroup: false,\n leafKeys,\n });\n }\n walk(view.children, depth + 1);\n }\n };\n walk(visibleHeaderTree.value, 0);\n return rows;\n});\n\n/** 列设置触发器/面板开关(默认 true);false 时不渲染 UI,受控 API 不受影响 */\nconst showColumnSettings = computed(() => props.columnSettings ?? true);\n\nfunction isColumnVisible(key: string): boolean {\n return visibleKeySet.value.has(key);\n}\n\n/**\n * 最少一列:唯一可见列不可隐藏\n * @param key - 列 key\n * @returns 是否允许隐藏该列\n */\nfunction canHideColumn(key: string): boolean {\n return !(instance.visibleKeys.value.length <= 1 && visibleKeySet.value.has(key));\n}\n\nfunction toggleColumnVisible(key: string) {\n if (!canHideColumn(key)) return;\n instance.setVisibleKeys(\n isColumnVisible(key)\n ? instance.visibleKeys.value.filter((k) => k !== key)\n : [...instance.visibleKeys.value, key],\n );\n}\n\nconst allColumnsVisible = computed(\n () => columns.value.length > 0 && visibleColumns.value.length === columns.value.length,\n);\n\nfunction selectAllColumns() {\n if (allColumnsVisible.value) return;\n instance.setVisibleKeys(columns.value.map((column) => column.key));\n}\n\nfunction resetColumns() {\n // 恢复 defaultVisibleKeys;未配置 = 全部可见\n instance.setVisibleKeys(instance.defaultVisibleKeys ?? columns.value.map((column) => column.key));\n}\n\n// ---- 列设置面板:树形行 ------------------------------------------------\n/** 面板行(全树扁平化,避免模板递归):分组行为父级三态,叶子行为勾选项 */\ninterface PanelRow {\n node: TableColumnNode<DataRecord>;\n depth: number;\n isGroup: boolean;\n /** 该节点覆盖的叶子 key(分组为子树全部) */\n leafKeys: string[];\n path: string;\n key: string;\n}\n\n/** 面板行派生:以原始列节点树(非可见剪枝)为准,保证隐藏后仍可恢复 */\nconst panelRows = computed<PanelRow[]>(() => {\n const rows: PanelRow[] = [];\n const collectLeaves = (node: TableColumnNode<DataRecord>): string[] =>\n isColumnGroup(node) ? node.children.flatMap(collectLeaves) : [node.key];\n const walk = (nodes: TableColumnNode<DataRecord>[], depth: number, parentPath: string) => {\n nodes.forEach((node, index) => {\n const path = parentPath === \"\" ? `${index}` : `${parentPath}-${index}`;\n const isGroup = isColumnGroup(node);\n rows.push({\n node,\n depth,\n isGroup,\n leafKeys: collectLeaves(node),\n path,\n key: isGroup ? `g:${path}` : node.key,\n });\n if (isGroup) walk(node.children, depth + 1, path);\n });\n };\n walk(columnsTree.value, 0, \"\");\n return rows;\n});\n\n/**\n * 分组勾选三态:全部可见 = true,部分可见 = \"indeterminate\",全隐 = false\n * @param row - 面板分组行\n * @returns 该分组的三态勾选值\n */\nfunction groupCheckedState(row: PanelRow): boolean | \"indeterminate\" {\n const visibleCount = row.leafKeys.filter((key) => visibleKeySet.value.has(key)).length;\n if (visibleCount === 0) return false;\n if (visibleCount === row.leafKeys.length) return true;\n return \"indeterminate\";\n}\n\n/**\n * 分组批量显隐(最少一列恒按叶子口径):\n * 隐藏整组会导致 0 列可见时,保留该组最后一枚可见叶子(父级呈 indeterminate)。\n * @param row - 面板分组行\n */\nfunction toggleGroupVisible(row: PanelRow) {\n const leafSet = new Set(row.leafKeys);\n const allVisible = row.leafKeys.every((key) => visibleKeySet.value.has(key));\n if (!allVisible) {\n // 显示整组:与当前可见集按 columns 原序合并(normalize 会纠正顺序)\n instance.setVisibleKeys(\n columns.value\n .map((column) => column.key)\n .filter((key) => visibleKeySet.value.has(key) || leafSet.has(key)),\n );\n return;\n }\n const remaining = instance.visibleKeys.value.filter((key) => !leafSet.has(key));\n if (remaining.length === 0) {\n // 钳制:不得清空可见集,保留最后一枚叶子\n instance.setVisibleKeys([row.leafKeys[row.leafKeys.length - 1]!]);\n return;\n }\n instance.setVisibleKeys(remaining);\n}\n\n/**\n * 面板行点击(分组批量显隐 / 叶子单列切换)\n * @param row - 面板行(分组或叶子)\n */\nfunction onPanelRowClick(row: PanelRow) {\n if (row.isGroup) toggleGroupVisible(row);\n else toggleColumnVisible(row.key);\n}\n\n// 受控/非受控均通知:统一投影变化 → 双事件(载荷 = columns 原序可见 key)\nwatch(instance.visibleKeys, (keys) => {\n emit(\"update:visible-keys\", [...keys]);\n emit(\"column-visibility-change\", [...keys]);\n});\n\n/** 总列数 = 可见业务列 + 选择列(空态 colspan 与骨架行) */\nconst columnCount = computed(\n () => visibleColumns.value.length + (hasSelection.value ? 1 : 0) + (dragEnabled.value ? 1 : 0),\n);\n\n// ---- 固定列(sticky) --------------------------------------------------------\n\n// DEV 校验:sticky 偏移只能从数字 width(px)推算,否则降级普通列(columns setup 期定版,只查一次)\nfor (const column of columns.value) {\n if (column.fixed !== undefined && typeof column.width !== \"number\") {\n console.warn(\n `[tu-design] <TableRender> fixed 列 \"${column.key}\" 需要数字 width,已忽略 fixed。`,\n );\n }\n}\n\n// DEV 校验(一次性):分组节点误配 key/sortable/fixed/width、空 children(列节点树定版)\nif (import.meta.env.DEV) {\n const validateNodes = (nodes: TableColumnNode<DataRecord>[], depth: number) => {\n for (const node of nodes) {\n if (isColumnGroup(node)) {\n if (\"key\" in node && (node as { key?: unknown }).key !== undefined) {\n console.warn(\n \"[tu-design] <TableRender> 分组节点不应配置 key(分组不是数据列),已忽略。\",\n );\n }\n if ((node as { sortable?: unknown }).sortable !== undefined) {\n console.warn(\n `[tu-design] <TableRender> 分组「${node.title}」不支持 sortable(仅叶子列可排序),已忽略。`,\n );\n }\n if ((node as { fixed?: unknown }).fixed !== undefined) {\n console.warn(\n `[tu-design] <TableRender> 分组「${node.title}」不支持 fixed(请配置到叶子列),已忽略。`,\n );\n }\n if (node.children.length === 0) {\n console.warn(`[tu-design] <TableRender> 分组「${node.title}」children 为空,将被忽略。`);\n }\n validateNodes(node.children, depth + 1);\n } else if (\"children\" in node && (node as { children?: unknown }).children !== undefined) {\n console.warn(\n `[tu-design] <TableRender> 叶子列 \"${node.key}\" 不应配置 children,已按叶子渲染。`,\n );\n }\n }\n };\n validateNodes(columnsTree.value, 0);\n}\n\n// DEV 提示(一次性,columns setup 期定版):多列宽表全列无数字 width 时,\n// min-width 横滚不可达 —— 宽表请为列声明数字 width(px)。\nif (columns.value.length >= 10 && !columns.value.some((c) => typeof c.width === \"number\")) {\n console.warn(\n `[tu-design] <TableRender> ${columns.value.length} 列均无数字 width,` +\n `窄容器下不会出现横向滚动;宽表请为列声明数字 width(px)。`,\n );\n}\n\n/** sticky 单元格映射(纯渲染层 computed,不进 TanStack pinning state):\n * 选择列视作最左 fixed 列参与累计(offset 0);fixed-left 按列序累加,\n * fixed-right 从最右列反向累计。edge = 该 sticky 组朝滚动方向的交界列(加分隔边框)。\n * 全部基于**可见集**:sticky 组因隐藏变空则无该组输出(不输出边框)。\n */\nconst stickyOf = computed<StickyMap>(() => {\n const map: StickyMap = new Map();\n // instance.columns 是联合数组(聚合式 any / 拆分式 DataRecord),联合上的 filter\n // 类型谓词重载解析不可靠,故 map 提取时以断言收窄 width(条件已含 typeof 守卫)\n const lefts = visibleColumns.value\n .filter((column) => column.fixed === \"left\" && typeof column.width === \"number\")\n .map((column) => ({ key: column.key, width: column.width as number }));\n const rights = visibleColumns.value\n .filter((column) => column.fixed === \"right\" && typeof column.width === \"number\")\n .map((column) => ({ key: column.key, width: column.width as number }));\n\n let acc = 0;\n if (hasSelection.value) {\n map.set(SELECTION_CELL, {\n side: \"left\",\n offset: 0,\n edge: lefts.length === 0 && !dragEnabled.value,\n });\n acc = selection.value.width;\n }\n // 把手列紧随选择列(选择列保持 offset 0 视觉锚点),同视作最左固定列参与累计\n if (dragEnabled.value) {\n map.set(DRAG_CELL, { side: \"left\", offset: acc, edge: lefts.length === 0 });\n acc += dragWidth;\n }\n lefts.forEach((left, index) => {\n map.set(left.key, { side: \"left\", offset: acc, edge: index === lefts.length - 1 });\n acc += left.width;\n });\n\n let racc = 0;\n for (let index = rights.length - 1; index >= 0; index--) {\n const right = rights[index]!;\n map.set(right.key, { side: \"right\", offset: racc, edge: index === 0 });\n racc += right.width;\n }\n return map;\n});\n\n// ---- 表格 min-width(列宽硬约束) ----------------------------------------\n// 可见业务列数字 width 之和(含选择列)作为 <table> min-width 下限:\n// 容器不足 → 表格被顶到 Σwidth,auto 布局下列渲染宽度 == 指定宽度,stickyOf 偏移精确成立,\n// 滚动区 overflow-x-auto 横滚;容器充足 → 表格仍 100% 拉伸(有宽列可能被拉伸,\n// sticky 偏移按指定值累计的漂移为既有限制)。\n// 字符串 width 仅渲染提示值,不参与求和(与 stickyOf 口径一致);和为 0 不挂 style(零回归)。\nconst tableMinWidth = computed(() => {\n let sum = 0;\n for (const column of visibleColumns.value) {\n if (typeof column.width === \"number\" && column.width > 0) sum += column.width;\n }\n if (hasSelection.value && selection.value.width > 0) sum += selection.value.width;\n if (dragEnabled.value && dragWidth > 0) sum += dragWidth;\n return sum;\n});\n\n/** 列宽 inline style 值:数字补 px 单位——Vue :style 不自动加单位,\n * 裸数字会被浏览器当非法 CSS 值丢弃,列宽即失效;字符串视为已带单位原样输出。\n * @param width - 列宽配置\n * @returns 可直接用于 :style 的 CSS 宽度值;未配置返回 undefined\n */\nfunction widthOf(width?: number | string) {\n return typeof width === \"number\" ? `${width}px` : width;\n}\n\n// ---- 分组表头单元格 ------------------------------------------------\n\n/** 混合固定组警告去重(同名分组仅警告一次) */\nconst warnedMixedFixedGroups = new Set<string>();\n\n/**\n * 分组单元格的 sticky 样式:子树可见叶子同侧且连续固定时整格 sticky,\n * 偏移取首个可见叶子;混合侧 → 返回 undefined(降级普通格)并 DEV 警告一次。\n * @param cell - 表头单元格(分组)\n * @returns 分组单元格的 sticky inline style;不适用时返回 undefined\n */\nfunction groupStickyStyle(cell: HeaderCell) {\n const sides = new Set(\n cell.leafKeys\n .map((key) => columns.value.find((column) => column.key === key)?.fixed)\n .filter((side): side is \"left\" | \"right\" => side !== undefined),\n );\n // 混合侧(同时含 left 与 right):单元格无法部分固定 → 降级普通格\n if (sides.size > 1) {\n if (!warnedMixedFixedGroups.has(cell.key)) {\n warnedMixedFixedGroups.add(cell.key);\n if (import.meta.env.DEV) {\n console.warn(\n `[tu-design] <TableRender> 分组「${(cell.node as TableColumnGroupOptions).title}」内固定方向混合,已降级为普通表头格。`,\n );\n }\n }\n return undefined;\n }\n if (sides.size === 0) return undefined;\n // 组内固定列不连续(中间夹普通列)时,分组格跨过非固定列会遮挡滚动内容 → 同样降级\n const fixedLeaves = cell.leafKeys.filter((key) => {\n const column = columns.value.find((c) => c.key === key);\n return column?.fixed !== undefined && typeof column.width === \"number\";\n });\n if (fixedLeaves.length !== cell.leafKeys.length) return undefined;\n const side = [...sides][0]!;\n const first = stickyOf.value.get(cell.leafKeys[0]!);\n if (!first) return undefined;\n return {\n position: \"sticky\" as const,\n [side]: `${first.offset}px`,\n zIndex: \"var(--z-sticky-head)\",\n };\n}\n\n/**\n * 表头行的行级样式:sticky 模式下逐行累积 top 偏移(多行表头),避免顶边重叠。\n * @param rowIndex - 表头行下标\n * @returns 行级 inline style;非 sticky 模式返回 undefined\n */\nfunction headerRowStyle(rowIndex: number) {\n if (!theadSticky) return undefined;\n return { top: `${rowTop.value[rowIndex] ?? rowIndex * HEADER_ROW_FALLBACK}px` };\n}\n\n/**\n * 表头单元格的视觉规约:分组格与其后单元格之间加竖向分隔线。\n *\n * 横向底边线沿用既有机制(非 sticky 走 thead 行级 `[&_tr]:border-b`;\n * sticky 走 `theadThClass` 的 `border-b`),此处**不重复绘制**;\n * 单级表头(无分组)直接返回空,保证扁平列 DOM 零变化。\n * @param cell - 表头单元格\n * @param isLastInRow - 是否为本行最后一个单元格\n * @returns class 列表\n */\nfunction headerCellClass(cell: HeaderCell, isLastInRow: boolean) {\n if (maxDepth.value === 1) return [];\n return cell.isGroup && !isLastInRow ? [\"border-r border-border\"] : [];\n}\n\n/**\n * 分组单元格水平对齐(分组无 align 以外的能力)\n * @param cell - 表头单元格\n * @returns 对齐值,默认居中\n */\nfunction headerCellAlign(cell: HeaderCell) {\n return cell.isGroup\n ? ((cell.node as TableColumnGroupOptions).align ?? \"center\")\n : ((cell.node as TableColumnOptions).align ?? \"center\");\n}\n\n/** 分组无需排序能力标记(sortable 仅叶子生效,对分组 sortable 警告) */\n\n/** 表头全选三态:本页可选行与选中集求交派生(TanStack getter 追踪不稳,自算) */\nconst selectableKeys = computed(() =>\n rows.value.filter((row) => row.getCanSelect()).map((row) => rowKeyOf(row.original, row.index)),\n);\nconst headerChecked = computed(\n () =>\n hasSelection.value &&\n selection.value.type === \"checkbox\" &&\n selectableKeys.value.length > 0 &&\n selectableKeys.value.every((key) => selectedKeys.value.has(key)),\n);\nconst headerIndeterminate = computed(\n () =>\n hasSelection.value &&\n !headerChecked.value &&\n selectableKeys.value.some((key) => selectedKeys.value.has(key)),\n);\n\nfunction onHeaderSelect(checked: boolean) {\n instance.table.toggleAllPageRowsSelected(checked);\n}\n\n/**\n * 行选择控件切换;radio 不可取消由引擎守卫,不选中态点击传 checked=true\n * @param line - 行数据(含行 key)\n * @param checked - 目标选中态\n */\nfunction onRowSelect(line: { key: string }, checked: boolean) {\n instance.toggleRowSelected(line.key, checked);\n}\n\n// 选中集变化 → 对外事件:排序/翻页不改变选中集,故不会误发\nwatch(instance.selectedKeys, (keys) => {\n emit(\"selection-change\", [...selection.value.value]);\n emit(\"update:selected-keys\", [...keys]);\n});\n\n/** 行 → 单元格值矩阵:render > formatter > record[key] */\nconst body = computed<TableBodyLine[]>(() => {\n // 渲染器工厂按列求值一次(而非每单元格),避免用户工厂内的重分配被放大\n const renderFns = new Map(\n columns.value.filter((c) => c.render).map((c) => [c, c.render!(RENDERS)]),\n );\n return rows.value.map((row) => ({\n /** TanStack Row:树形渲染读 depth / getCanExpand / getIsExpanded / toggleExpanded */\n row,\n key: rowKeyOf(row.original, row.index),\n index: row.index,\n record: row.original,\n /** 行级可选过滤:selectable 谓词交由引擎 enableRowSelection 判定 */\n canSelect: row.getCanSelect(),\n // 可见列的值矩阵(列显隐只裁剪列;状态不受影响)\n cells: visibleColumns.value.map((column): VNodeChild => {\n const render = renderFns.get(column);\n if (render) return render(row.original, row.index, column);\n if (column.formatter) return column.formatter(row.original) as VNodeChild;\n return String(row.original[column.key] ?? \"\");\n }),\n }));\n});\n\n// ---- 树形数据(T 系列) ------------------------------------------------------\n// 引擎是唯一解析点(无效配置已 warn 并忽略,回传 undefined);tree 为 undefined 时不渲染缩进与 caret\nconst tree = instance.tree;\nconst treeIndent = tree?.indentSize ?? 16;\n\nlet missingRowKeyWarned = false;\n\n/**\n * 行主键:rowKey 字段缺失时以行索引兜底\n * @param record - 行记录\n * @param index - 行索引(兜底来源)\n * @returns 稳定的行主键字符串\n */\nfunction rowKeyOf(record: DataRecord, index: number): string {\n const value = record[props.rowKey];\n if (value === undefined || value === null) {\n if (!missingRowKeyWarned && import.meta.env.DEV) {\n missingRowKeyWarned = true;\n console.warn(\n `[tu-design] <TableRender> 部分记录缺少 rowKey 字段 \"${props.rowKey}\",已退化为按行索引标识。`,\n );\n }\n return `index-${index}`;\n }\n return String(value);\n}\n\n// ---- 虚拟滚动 / 填充模式 ------------------------------------------------------\n// definition 优先于 prop(配置定版,不支持运行时切换)\nconst virtualRaw = instance.virtual ?? props.virtual;\nconst heightRaw = instance.height ?? props.height;\n// fill 模式自带真实滚动盒(flex-1 实测高度),virtual 无需显式 height\nif (virtualRaw === true && heightRaw === undefined && !fill) {\n console.warn(\"[tu-design] <TableRender> virtual 需要配置 height,已降级普通渲染。\");\n}\nconst virtualEnabled = virtualRaw === true && (heightRaw !== undefined || fill);\n\n// ---- 行拖拽排序(draggable) --------------------------------------------------\n// 引擎是唯一配置解析点(tree/virtual 冲突已 warn 并忽略);此处兜底聚合式 definition\n// 与组件 prop virtual 同传的边界(引擎解析时看不到 prop)。配置 setup 期定版。\nconst dragConfig = instance.draggable;\nconst dragEnabled = computed(() => dragConfig !== undefined && !virtualEnabled);\nconst dragWidth = dragConfig?.width ?? 32;\nconst drag = useRowDrag();\n\n// rowKey 记录级守卫:当前页任一记录缺 rowKey 字段 → 禁用拖拽(索引兜底态下行身份不稳定)\nconst dragKeysValid = computed(\n () => !dragEnabled.value || body.value.every((line) => line.record[props.rowKey] != null),\n);\nlet dragRowKeyWarned = false;\nwatch(\n dragKeysValid,\n (valid) => {\n if (!valid && !dragRowKeyWarned && import.meta.env.DEV) {\n dragRowKeyWarned = true;\n console.warn(\n `[tu-design] <TableRender> 部分记录缺少 rowKey 字段 \"${props.rowKey}\",已禁用行拖拽排序。`,\n );\n }\n },\n { immediate: true },\n);\n\n/**\n * 本行把手禁用判定:排序激活(动态守卫,取消排序恢复)/ rowKey 缺失 / 行级谓词 false\n * @param line - 行数据\n * @returns 是否禁用本行把手\n */\nfunction rowDragDisabled(line: TableBodyLine): boolean {\n if (instance.sort.value !== undefined || !dragKeysValid.value) return true;\n return dragConfig?.draggable ? !dragConfig.draggable(line.record) : false;\n}\n\n// ---- 实时让位预览(组件层 overlay:引擎零改动、预览期间零事件) ----------------\n// 只有被拖行在预览序中移动,其他行相对序恒定 → 让位后被拖行恰落在光标下,\n// 后续 dragover 命中自身被忽略,天然不振荡(无需几何测量)。\nconst previewKeys = ref<string[] | undefined>(undefined);\n\n/** 显示序:拖拽中按预览序重排(失效 key 过滤、新增行追加,防中途外部 data 变更);平时即引擎序 */\nconst displayBody = computed<TableBodyLine[]>(() => {\n const keys = previewKeys.value;\n if (!keys) return body.value;\n const byKey = new Map(body.value.map((line) => [line.key, line]));\n const ordered: TableBodyLine[] = [];\n for (const key of keys) {\n const line = byKey.get(key);\n if (line) {\n ordered.push(line);\n byKey.delete(key);\n }\n }\n return ordered.concat([...byKey.values()]);\n});\n\n/** 离屏整行快照(仅真实浏览器 dataTransfer 存在时创建);drop/dragend 时移除 */\nlet dragSnapshot: HTMLElement | undefined;\n\nfunction removeDragSnapshot() {\n dragSnapshot?.remove();\n dragSnapshot = undefined;\n}\n\n/**\n * 起拖(把手 dragstart):禁用行不接收;离屏克隆整行作为拖拽快照(幽灵影 = 带边框整行截图)\n * @param line - 源行数据\n * @param event - 原生 dragstart 事件\n */\nfunction onRowDragStart(line: TableBodyLine, event: DragEvent) {\n if (rowDragDisabled(line)) return;\n const tr = (event.target as HTMLElement | null)?.closest?.(\"tr\");\n let image: { el: Element; offsetX: number; offsetY: number } | undefined;\n if (event.dataTransfer && tr) {\n const rect = tr.getBoundingClientRect();\n dragSnapshot = createRowSnapshot(tr);\n image = {\n el: dragSnapshot,\n offsetX: event.clientX - rect.left,\n offsetY: event.clientY - rect.top,\n };\n }\n drag.start(line.key, event, image);\n}\n\n/**\n * 悬停让位:把被拖行移到悬停行在当前预览序中的位置(仅被拖行移动)\n * @param line - 悬停行数据\n * @param event - 原生 dragover 事件\n */\nfunction onRowDragOver(line: TableBodyLine, event: DragEvent) {\n if (!drag.over(line.key, event)) return;\n const dragging = drag.draggingKey.value!;\n const keys = [...(previewKeys.value ?? body.value.map((item) => item.key))];\n const fromIndex = keys.indexOf(dragging);\n const toIndex = keys.indexOf(line.key);\n if (fromIndex < 0 || toIndex < 0 || fromIndex === toIndex) return;\n keys.splice(fromIndex, 1);\n keys.splice(toIndex, 0, dragging);\n previewKeys.value = keys;\n}\n\n/**\n * 成功落位:提交预览序。多跳预览的复合结果 ≡ 单次「源行原位移 → 最终预览位」,\n * 故 from = 原 body 索引、to = 预览序中被拖行最终索引,直接复用引擎 reorderRows。\n * @param line - 落位行数据\n * @param event - 原生 drop 事件\n */\nfunction onRowDrop(line: TableBodyLine, event: DragEvent) {\n const preview = previewKeys.value;\n const result = drag.drop(line.key, event);\n previewKeys.value = undefined;\n removeDragSnapshot();\n if (!result) return;\n const from = body.value.findIndex((item) => item.key === result.fromKey);\n // 有预览:提交最终预览位(含落在自身占位);无预览:落在自身 = 无操作(from === to 引擎守卫)\n const to = preview\n ? preview.indexOf(result.fromKey)\n : body.value.findIndex((item) => item.key === result.toKey);\n if (from < 0 || to < 0) return;\n const payload = instance.reorderRows(from, to);\n if (payload) emit(\"drag-sort\", payload);\n}\n\n/** 拖拽结束(含取消路径):清理状态 + 预览序弹回引擎原序 + 移除离屏快照 */\nfunction onRowDragEnd() {\n drag.end();\n previewKeys.value = undefined;\n removeDragSnapshot();\n}\n\nconst scrollHeight = computed(() => (typeof heightRaw === \"number\" ? `${heightRaw}px` : heightRaw));\n/** 表头 sticky 仅在组件内存在真实纵向滚动盒时生效(fill / virtual),普通模式不挂载,行为不变 */\nconst theadSticky = fill || virtualEnabled;\n/** 滚动区样式:virtual 用固定 height;fill 交给 flex 分配(二者同传以 fill 优先) */\nconst scrollStyle = computed(() => {\n if (fill || !virtualEnabled) return undefined;\n return { height: scrollHeight.value, overflowY: \"auto\" as const };\n});\n/** sticky 表头普通列类:不透明底防行内容透出;分隔线归 th(thead 行级 border 会随行滚走);\n * z-20 高于表体 fixed 列(--z-sticky: 10),纵向滚动行滑过表头时不穿透;\n * 表头 fixed 列的 z 由 stickyStyle inline style(var(--z-sticky-head))提供,inline 优先级天然覆盖此处 class */\nconst theadThClass = theadSticky ? \"sticky top-0 z-20 border-b border-border bg-background\" : \"\";\n/** sticky 态 table 改分离边框:preflight 为 border-collapse: collapse,\n * 折叠边框几何归属 table,Chrome 下 sticky th 粘住后自身 border-b 渲染丢失;\n * separate + spacing-0 恢复单元格边框。普通模式保持 collapse,零回归。 */\nconst tableClass = theadSticky ? \"border-separate border-spacing-0\" : \"\";\n\nconst scrollEl = ref<HTMLElement | null>(null);\nconst theadEl = ref<HTMLElement | null>(null);\n/** 滚动容器内 thead 占据的前缀高度(scrollMargin);表头内容静态,挂载后测量一次 */\nconst theadOffset = ref(0);\n\n// ---- 多行表头测量 --------------------------------------------------\n/** 表头行元素(模板 ref 收集,逐行求高度) */\nconst headerRowEls = ref<(HTMLElement | null)[]>([]);\n/** 各行顶部偏移(前缀和):多行 sticky 表头逐行钉住,避免顶边重叠 */\nconst rowTop = ref<number[]>([]);\n/** 行高兜底:表头行 class 为 h-10(2.5rem = 40px);happy-dom 下 offsetHeight 恒 0 */\nconst HEADER_ROW_FALLBACK = 40;\n\n/**\n * 测量所有表头行高度并派生行顶偏移与 thead 总高(唯一测量源)。\n *\n * 两处口径有意区分:\n * - `rowTop`(多行 sticky 逐行 top)用兜底 h-10(40px)——测量不可用时避免表头行重叠;\n * - `theadOffset`(virtual 的 scrollMargin)用**实测原值**,与既有行为一致\n * (happy-dom 无布局 → 0;真实浏览器 → 真实高度)。\n */\nfunction measureHeaderRows() {\n const raw = headerRowEls.value.map((el) => el?.offsetHeight ?? 0);\n const heights = raw.map((height) => height || HEADER_ROW_FALLBACK);\n rowTop.value = heights.map((_, index) => heights.slice(0, index).reduce((a, h) => a + h, 0));\n if (virtualEnabled) theadOffset.value = raw.reduce((a, h) => a + h, 0);\n}\n\n// 仅 virtual: true 且 height 就绪时创建(配置 setup 期定版,顶层条件分支可安全注册生命周期)\nconst virtualizerRef = virtualEnabled\n ? useVirtualizer(\n computed(() => ({\n count: rows.value.length, // 翻页/重载后行窗口变化 → options 更新(setOptions 自动生效)\n getScrollElement: () => scrollEl.value,\n estimateSize: () => 40,\n overscan: 8,\n getItemKey: (index: number) => rowKeyOf(rows.value[index]!, index), // rowKey 作为虚拟行 key\n scrollMargin: theadOffset.value, // thead 在滚动容器内的 offset 前缀\n })),\n )\n : null;\n\nonMounted(measureHeaderRows);\n// 可见表头树变化(列显隐)→ 行数/单元格可能变化,DOM 更新后重测\nwatch(headerRows, () => void nextTick(measureHeaderRows), { flush: \"post\" });\n\nconst virtualRows = computed(() => (virtualizerRef ? virtualizerRef.value.getVirtualItems() : []));\nconst virtualTotal = computed(() => (virtualizerRef ? virtualizerRef.value.getTotalSize() : 0));\n/** 窗口行 + 对应全量行数据(cells 矩阵已由 body computed 缓存,虚拟化只裁剪 DOM 节点) */\nconst virtualLines = computed(() =>\n virtualRows.value.map((row) => ({ row, line: body.value[row.index]! })),\n);\nconst padTop = computed(() => virtualRows.value[0]?.start ?? 0);\nconst padBottom = computed(() => {\n const items = virtualRows.value;\n return items.length === 0 ? 0 : Math.max(0, virtualTotal.value - items[items.length - 1]!.end);\n});\n\n/** 行高动态测量:measureElement 读 data-index 把实测高度写回(行内容高度可变,不假设固定行高)。\n * 行组件为函数 ref,拿到的是组件实例,需经 $el 取真实 tr。\n * @param node - 函数 ref 收到的行元素或组件实例\n */\nfunction measureRow(node: Element | ComponentPublicInstance | null) {\n const el = node instanceof Element ? node : (node?.$el as Element | undefined);\n if (el instanceof Element) virtualizerRef?.value.measureElement(el);\n}\n\n/**\n * aria-sort 仅在该列当前被排序时标注\n * @param column - 列配置\n * @returns 当前排序方向对应的 aria-sort 值;未排序返回 undefined\n */\nfunction ariaSort(column: TableColumnOptions): \"ascending\" | \"descending\" | undefined {\n if (instance.sort.value?.key !== column.key) return undefined;\n return instance.sort.value.direction === \"asc\" ? \"ascending\" : \"descending\";\n}\n\nfunction sortMark(column: TableColumnOptions): string {\n const direction = instance.sort.value?.key === column.key ? instance.sort.value.direction : \"\";\n return direction === \"asc\" ? \"↑\" : direction === \"desc\" ? \"↓\" : \"\";\n}\n\nfunction onSort(key: string) {\n instance.toggleSort(key);\n emit(\"sort-change\", instance.sort.value);\n}\n\nfunction onPageIndex(pageIndex: number) {\n instance.setPageIndex(pageIndex);\n lastEmittedPage.pageIndex = pageIndex;\n emit(\"update:page-index\", pageIndex);\n}\n\nfunction onPageSize(pageSize: number) {\n instance.setPageSize(pageSize);\n lastEmittedPage.pageSize = pageSize;\n emit(\"update:page-size\", pageSize);\n}\n\n// ---- 受控模式(v-model):page 投影 → update:* 通知 ---------------------------\n// 仅 page-index/page-size 至少一方受控时安装;lastEmittedPage 去重——\n// 动作路径已 emit 过的值不再重复发(受控回写/内部归位只通知「未通知过的」变化)\nconst pageControlled = () => props.pageIndex !== undefined || props.pageSize !== undefined;\nconst lastEmittedPage = {\n pageIndex: undefined as number | undefined,\n pageSize: undefined as number | undefined,\n};\n\nif (pageControlled()) {\n watch(\n () => [instance.page.pageIndex, instance.page.pageSize] as const,\n ([pageIndex, pageSize]) => {\n if (pageIndex !== lastEmittedPage.pageIndex) {\n lastEmittedPage.pageIndex = pageIndex;\n emit(\"update:page-index\", pageIndex);\n }\n if (pageSize !== lastEmittedPage.pageSize) {\n lastEmittedPage.pageSize = pageSize;\n emit(\"update:page-size\", pageSize);\n }\n },\n );\n}\n\nfunction onRowClick(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-click\", record, index, event);\n}\n\nfunction onRowDblclick(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-dblclick\", record, index, event);\n}\n\nfunction onRowContextmenu(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-contextmenu\", record, index, event);\n}\n\nfunction onCellClick(record: DataRecord, columnKey: string, index: number, event: MouseEvent) {\n emit(\"cell-click\", record, columnKey, index, event);\n}\n\ndefineExpose({\n table: instance.table,\n page: instance.page,\n sort: instance.sort,\n loading: instance.loading,\n error: instance.error,\n visibleKeys: instance.visibleKeys,\n setVisibleKeys: instance.setVisibleKeys,\n reload: instance.reload,\n toggleSort: onSort,\n setPageIndex: onPageIndex,\n setPageSize: onPageSize,\n selection: instance.selection,\n selectedKeys: instance.selectedKeys,\n setSelection: instance.setSelection,\n clearSelection: instance.clearSelection,\n});\n</script>\n\n<template>\n <div :class=\"cn('w-full', fill && 'flex h-full min-h-0 flex-col', $attrs.class)\">\n <!-- 搜索区 + 列设置触发器:同行右对齐(items-end);无搜索时触发器位于表格上方(showSearch=false 关闭搜索区) -->\n <div\n v-if=\"showSearchArea || showColumnSettings\"\n :class=\"cn('mb-2 flex items-end justify-between gap-2', fill && 'shrink-0')\"\n >\n <FormRender\n v-if=\"showSearchArea\"\n class=\"min-w-0 flex-1\"\n :definition=\"search\"\n :searchable=\"search.actions ? undefined : true\"\n @search=\"onSearch\"\n @reset=\"onReset\"\n />\n\n <!-- 列设置:Popover 面板(最少一列 / 重置 / 不含选择列);\n 触发钮 Tooltip 手动受控开合(Tooltip 与 Popover 触发器嵌套会吞点击,故并列渲染、不走 hover 自动触发) -->\n <template v-if=\"showColumnSettings\">\n <Popover align=\"end\" content-class=\"w-56 p-0\">\n <Button\n variant=\"ghost\"\n size=\"icon\"\n aria-label=\"列设置\"\n aria-haspopup=\"true\"\n @pointerenter=\"settingsTipOpen = true\"\n @pointerleave=\"settingsTipOpen = false\"\n >\n <!-- lucide Settings2(内联 SVG,跟随项目图标现状) -->\n <svg\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"size-4\"\n aria-hidden=\"true\"\n >\n <path d=\"M20 7h-9\" />\n <path d=\"M14 17H5\" />\n <circle cx=\"17\" cy=\"17\" r=\"3\" />\n <circle cx=\"7\" cy=\"7\" r=\"3\" />\n </svg>\n </Button>\n <template #content>\n <div class=\"flex items-center justify-end gap-3 px-3 py-2\">\n <button\n type=\"button\"\n class=\"text-muted-foreground hover:text-foreground cursor-pointer text-xs disabled:cursor-not-allowed disabled:opacity-50\"\n :disabled=\"allColumnsVisible\"\n @click=\"selectAllColumns\"\n >\n 全选\n </button>\n <button\n type=\"button\"\n class=\"text-muted-foreground hover:text-foreground cursor-pointer text-xs\"\n @click=\"resetColumns\"\n >\n 重置\n </button>\n </div>\n <Separator />\n <div class=\"max-h-64 overflow-y-auto py-1\">\n <div\n v-for=\"row in panelRows\"\n :key=\"row.key\"\n data-column-item\n :data-column-key=\"row.isGroup ? undefined : row.key\"\n :data-column-group=\"row.isGroup ? row.path : undefined\"\n class=\"hover:bg-accent/50 flex h-8 cursor-pointer items-center gap-2 px-3\"\n :style=\"{ paddingLeft: `${12 + row.depth * 12}px` }\"\n @click=\"onPanelRowClick(row)\"\n >\n <Checkbox\n :checked=\"row.isGroup ? groupCheckedState(row) : isColumnVisible(row.key)\"\n :disabled=\"row.isGroup ? false : !canHideColumn(row.key)\"\n @update:checked=\"onPanelRowClick(row)\"\n @click.stop\n />\n <span class=\"min-w-0 flex-1 truncate\">{{ row.node.title }}</span>\n <!-- 有效 fixed 列(数字 width)标识:仅叶子 -->\n <svg\n v-if=\"\n !row.isGroup &&\n (row.node as TableColumnOptions).fixed !== undefined &&\n typeof (row.node as TableColumnOptions).width === 'number'\n \"\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"text-muted-foreground size-3 shrink-0\"\n aria-hidden=\"true\"\n >\n <path d=\"M12 17v5\" />\n <path\n d=\"M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V7h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1z\"\n />\n </svg>\n </div>\n </div>\n </template>\n </Popover>\n <!-- 纯受控气泡(无默认插槽,不渲染触发器):开合由触发钮 pointerenter/leave 驱动 -->\n <Tooltip :open=\"settingsTipOpen\" content=\"列设置\" />\n </template>\n </div>\n\n <!-- 滚动容器:横向滚动时 fixed 列 sticky 生效;virtual/fill 模式兼任纵向滚动(分页条不参与滚动) -->\n <div\n ref=\"scrollEl\"\n :class=\"cn('overflow-x-auto', fill && 'min-h-0 flex-1 overflow-y-auto')\"\n :style=\"scrollStyle\"\n >\n <table\n class=\"w-full caption-bottom text-sm\"\n :class=\"tableClass\"\n :style=\"tableMinWidth > 0 ? { minWidth: `${tableMinWidth}px` } : undefined\"\n >\n <thead ref=\"theadEl\" :class=\"theadSticky ? undefined : '[&_tr]:border-b'\">\n <tr\n v-for=\"(cells, rowIndex) in headerRows\"\n :key=\"rowIndex\"\n :ref=\"(el) => (headerRowEls[rowIndex] = el as HTMLElement | null)\"\n :style=\"headerRowStyle(rowIndex)\"\n >\n <!-- 选择列:checkbox 型表头为本页全选三态;radio 型占位;视作最左固定列 -->\n <th\n v-if=\"hasSelection && rowIndex === 0\"\n scope=\"col\"\n :rowspan=\"headerRows.length\"\n class=\"h-10 w-12 px-2 text-center align-middle font-medium text-muted-foreground\"\n :class=\"[stickyClass(stickyOf, SELECTION_CELL), theadThClass]\"\n :style=\"[\n { width: `${selection.width}px` },\n stickyStyle(stickyOf, SELECTION_CELL, true),\n ]\"\n >\n <Checkbox\n v-if=\"selection.type === 'checkbox'\"\n :checked=\"headerIndeterminate ? 'indeterminate' : headerChecked\"\n :aria-label=\"'全选本页'\"\n @update:checked=\"onHeaderSelect\"\n />\n </th>\n <!-- 拖拽把手列表头:占位(对齐 radio 选择列范式);视作最左固定列(紧随选择列) -->\n <th\n v-if=\"dragEnabled && rowIndex === 0\"\n scope=\"col\"\n :rowspan=\"headerRows.length\"\n class=\"h-10 px-1 text-center align-middle font-medium text-muted-foreground\"\n :class=\"[stickyClass(stickyOf, DRAG_CELL), theadThClass]\"\n :style=\"[{ width: `${dragWidth}px` }, stickyStyle(stickyOf, DRAG_CELL, true)]\"\n >\n <span class=\"sr-only\">拖拽排序</span>\n </th>\n <th\n v-for=\"(cell, cellIndex) in cells\"\n :key=\"cell.key\"\n :scope=\"cell.isGroup ? 'colgroup' : 'col'\"\n :colspan=\"cell.colSpan > 1 ? cell.colSpan : undefined\"\n :rowspan=\"cell.rowSpan > 1 ? cell.rowSpan : undefined\"\n class=\"h-10 px-2 align-middle font-medium text-muted-foreground\"\n :class=\"[\n cell.isGroup ? undefined : stickyClass(stickyOf, cell.key),\n theadThClass,\n headerCellClass(cell, cellIndex === cells.length - 1),\n ]\"\n :style=\"[\n cell.isGroup\n ? { textAlign: headerCellAlign(cell) }\n : {\n width: widthOf((cell.node as TableColumnOptions).width),\n textAlign: headerCellAlign(cell),\n },\n cell.isGroup ? groupStickyStyle(cell) : stickyStyle(stickyOf, cell.key, true),\n ]\"\n :aria-sort=\"cell.isGroup ? undefined : ariaSort(cell.node as TableColumnOptions)\"\n >\n <button\n v-if=\"!cell.isGroup && (cell.node as TableColumnOptions).sortable\"\n type=\"button\"\n class=\"inline-flex items-center gap-1 hover:text-foreground\"\n @click=\"onSort((cell.node as TableColumnOptions).key)\"\n >\n {{ (cell.node as TableColumnOptions).title }}\n <span aria-hidden=\"true\" class=\"text-xs\">{{\n sortMark(cell.node as TableColumnOptions)\n }}</span>\n </button>\n <template v-else>{{ cell.node.title }}</template>\n </th>\n </tr>\n </thead>\n\n <tbody class=\"[&_tr:last-child]:border-0\">\n <!-- 加载态:固定 5 行骨架;选择列一并占位;骨架不虚拟化;loading 判定优先 -->\n <template v-if=\"loading\">\n <tr v-for=\"row in SKELETON_ROWS\" :key=\"row\" data-skeleton>\n <td\n v-if=\"hasSelection\"\n class=\"p-2 text-center align-middle\"\n :class=\"stickyClass(stickyOf, SELECTION_CELL)\"\n :style=\"stickyStyle(stickyOf, SELECTION_CELL, false)\"\n >\n <Skeleton class=\"size-4\" />\n </td>\n <td\n v-if=\"dragEnabled\"\n class=\"p-1 text-center align-middle\"\n :class=\"stickyClass(stickyOf, DRAG_CELL)\"\n :style=\"stickyStyle(stickyOf, DRAG_CELL, false)\"\n >\n <Skeleton class=\"size-4\" />\n </td>\n <td\n v-for=\"column in visibleColumns\"\n :key=\"column.key\"\n class=\"p-2 align-middle\"\n :class=\"stickyClass(stickyOf, column.key)\"\n :style=\"[\n { textAlign: column.align ?? 'center' },\n stickyStyle(stickyOf, column.key, false),\n ]\"\n >\n <Skeleton class=\"h-4 w-full\" />\n </td>\n </tr>\n </template>\n\n <!-- 错误态:error 优先于正常数据;插槽可自定义(slot props { error, retry }) -->\n <template v-else-if=\"showError\">\n <tr data-error>\n <td :colspan=\"columnCount\" class=\"p-8 text-center text-muted-foreground\">\n <slot name=\"error\" :error=\"loadError\" :retry=\"retry\">\n <div class=\"flex flex-col items-center gap-3\">\n <p>{{ loadError?.message ?? \"加载失败\" }}</p>\n <Button variant=\"outline\" size=\"sm\" @click=\"retry\">重试</Button>\n </div>\n </slot>\n </td>\n </tr>\n </template>\n\n <!-- 虚拟滚动:窗口行 + 前后占位行(总高撑开滚动区间;行高经 measureElement 动态测量) -->\n <template v-else-if=\"virtualEnabled\">\n <tr aria-hidden=\"true\" data-virtual-pad :style=\"{ height: `${padTop}px` }\">\n <td :colspan=\"columnCount\" class=\"border-0 p-0\"></td>\n </tr>\n <TableBodyRow\n v-for=\"item in virtualLines\"\n :key=\"item.line.key\"\n :ref=\"measureRow\"\n :data-index=\"item.row.index\"\n :line=\"item.line\"\n :columns=\"visibleColumns\"\n :selection=\"hasSelection ? selection.type : undefined\"\n :selected=\"selectedKeys.has(item.line.key)\"\n :sticky=\"stickyOf\"\n :tree-indent=\"tree ? treeIndent : undefined\"\n :drag-column=\"dragEnabled\"\n :drag-disabled=\"rowDragDisabled(item.line)\"\n :dragging=\"drag.draggingKey.value === item.line.key\"\n @select=\"(checked: boolean) => onRowSelect(item.line, checked)\"\n @row-click=\"onRowClick(item.line.record, item.line.index, $event)\"\n @row-dblclick=\"onRowDblclick(item.line.record, item.line.index, $event)\"\n @row-contextmenu=\"onRowContextmenu(item.line.record, item.line.index, $event)\"\n @cell-click=\"\n (columnKey: string, event: MouseEvent) =>\n onCellClick(item.line.record, columnKey, item.line.index, event)\n \"\n @drag-start=\"onRowDragStart(item.line, $event)\"\n @drag-over=\"onRowDragOver(item.line, $event)\"\n @drop=\"onRowDrop(item.line, $event)\"\n @drag-end=\"onRowDragEnd()\"\n />\n <tr aria-hidden=\"true\" data-virtual-pad :style=\"{ height: `${padBottom}px` }\">\n <td :colspan=\"columnCount\" class=\"border-0 p-0\"></td>\n </tr>\n </template>\n\n <template v-else>\n <TableBodyRow\n v-for=\"line in displayBody\"\n :key=\"line.key\"\n :line=\"line\"\n :columns=\"visibleColumns\"\n :selection=\"hasSelection ? selection.type : undefined\"\n :selected=\"selectedKeys.has(line.key)\"\n :sticky=\"stickyOf\"\n :tree-indent=\"tree ? treeIndent : undefined\"\n :drag-column=\"dragEnabled\"\n :drag-disabled=\"rowDragDisabled(line)\"\n :dragging=\"drag.draggingKey.value === line.key\"\n @select=\"(checked: boolean) => onRowSelect(line, checked)\"\n @row-click=\"onRowClick(line.record, line.index, $event)\"\n @row-dblclick=\"onRowDblclick(line.record, line.index, $event)\"\n @row-contextmenu=\"onRowContextmenu(line.record, line.index, $event)\"\n @cell-click=\"\n (columnKey: string, event: MouseEvent) =>\n onCellClick(line.record, columnKey, line.index, event)\n \"\n @drag-start=\"onRowDragStart(line, $event)\"\n @drag-over=\"onRowDragOver(line, $event)\"\n @drop=\"onRowDrop(line, $event)\"\n @drag-end=\"onRowDragEnd()\"\n />\n </template>\n\n <!-- 空态:横跨全列的单单元格,不虚拟化;错误态优先 -->\n <tr v-if=\"!loading && !showError && body.length === 0\" data-empty>\n <td :colspan=\"columnCount\" class=\"p-8 text-center text-muted-foreground\">\n <slot name=\"empty\">{{ emptyText ?? \"暂无数据\" }}</slot>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n\n <!-- 手动接线(须经 onPageIndex/onPageSize 包装器保留受控去重);显式补 border-t 与 size select 保持现状 -->\n <TablePagination\n v-if=\"showPaginationBar\"\n :class=\"cn('border-t', fill && 'shrink-0')\"\n :page-index=\"instance.page.pageIndex\"\n :page-size=\"instance.page.pageSize\"\n :page-size-opts=\"instance.page.pageSizeOpts\"\n :total=\"instance.page.total\"\n :show-size-select=\"true\"\n @update:page-index=\"onPageIndex\"\n @update:page-size=\"onPageSize\"\n />\n </div>\n</template>\n"
|
|
42
43
|
},
|
|
43
44
|
{
|
|
44
45
|
"path": "table-render/column-renders.ts",
|
|
45
46
|
"type": "registry:lib",
|
|
46
47
|
"target": "components/ui/table-render/column-renders.ts",
|
|
47
|
-
"content": "import type { BadgeVariants } from \"../badge\";\nimport type { ButtonVariants } from \"../button\";\nimport type { VNodeChild } from \"vue\";\nimport type { DataRecord, TableColumnOptions } from \"./types\";\nimport { h } from \"vue\";\nimport Badge from \"../badge/Badge.vue\";\nimport Button from \"../button/Button.vue\";\n\n/** 单元格渲染器:与 TableColumnOptions.render 同签名(column 用于读取字段值) */\nexport type ColumnRender<T extends DataRecord> = (\n record: T,\n index: number,\n column: TableColumnOptions<T>,\n) => VNodeChild;\n\nexport type DictEntryVariant = BadgeVariants[\"variant\"];\n\nexport type DictColumnMapping = Record<\n string | number,\n string | { label: string; variant?: DictEntryVariant }\n>;\n\nexport interface DictColumnOptions {\n /** 整列统一 Badge 形态;条目级 variant 优先 */\n badge?: DictEntryVariant | true;\n}\n\n/** 日期模式串(迷你令牌 yyyy MM dd HH mm ss),如 \"yyyy-MM-dd HH:mm\" */\nexport type DateColumnPattern = string;\n\nexport interface SerialColumnOptions {\n /** 起始序号,默认 1 */\n base?: number;\n}\n\nexport interface TableActionButton<T extends DataRecord> {\n text: string | ((record: T, index: number) => string);\n onClick?: (record: T, index: number) => void;\n variant?: ButtonVariants[\"variant\"];\n disabled?: (record: T, index: number) => boolean;\n}\n\nexport interface ColumnRenders<T extends DataRecord> {\n /** 逃逸口:自定义渲染器与内置同一范式(对齐 x-render renderRenderColumn) */\n render: (fn: ColumnRender<T>) => ColumnRender<T>;\n dict: (mapping: DictColumnMapping, options?: DictColumnOptions) => ColumnRender<T>;\n date: (pattern?: DateColumnPattern) => ColumnRender<T>;\n currency: (currency?: string, locale?: string) => ColumnRender<T>;\n serial: (base?: number) => ColumnRender<T>;\n /** 操作列按钮组;按钮组为行内级(inline-flex),随单元格 align 对齐(默认居中) */\n button: (items: Array<TableActionButton<T> | string>) => ColumnRender<T>;\n}\n\n/**\n * 两位补零\n * @param value - 数字(月/日/时/分/秒)\n * @returns 补零后的两位字符串\n */\nconst pad = (value: number) => String(value).padStart(2, \"0\");\n\n/**\n * 迷你日期令牌格式化,不引入 date-fns;非法输入原样返回\n * @param input - 单元格原始值(Date 或可构造 Date 的字符串/数字)\n * @param pattern - 令牌模板(支持 yyyy/MM/dd/HH/mm/ss)\n * @returns 格式化后的文本;输入非法时原样返回\n */\nfunction formatDate(input: unknown, pattern: string): VNodeChild {\n const date = input instanceof Date ? input : new Date(input as string | number);\n if (Number.isNaN(date.getTime())) return input as VNodeChild;\n const tokens: Record<string, string> = {\n yyyy: String(date.getFullYear()),\n MM: pad(date.getMonth() + 1),\n dd: pad(date.getDate()),\n HH: pad(date.getHours()),\n mm: pad(date.getMinutes()),\n ss: pad(date.getSeconds()),\n };\n return pattern.replace(/yyyy|MM|dd|HH|mm|ss/g, (token) => tokens[token]!);\n}\n\n/**\n * 内置列渲染器工厂(对标 x-render table-columns,v1:dict/date/currency/serial/button)。\n * 返回值直接填入 TableColumnOptions.render;column 参数用于读取字段值。\n * 与 FormRender widget 的 r.xxx() 范式共词根(D10)。\n * @returns 各内置渲染器集合(render/dict/date/currency/serial/button)\n */\nexport function columnRenders<T extends DataRecord>(): ColumnRenders<T> {\n return {\n render: (fn) => fn,\n\n dict(mapping, options) {\n return (record, _index, column) => {\n const raw = (record as Record<string, unknown>)[column.key];\n const entry = mapping[raw as string | number];\n if (entry === undefined) return (raw ?? \"\") as VNodeChild;\n\n const label = typeof entry === \"string\" ? entry : entry.label;\n const entryVariant = typeof entry === \"object\" ? entry.variant : undefined;\n // Badge 形态:条目级 variant,或整列 badge 简写\n if (entryVariant !== undefined || options?.badge !== undefined) {\n const variant = entryVariant ?? (options?.badge === true ? undefined : options?.badge);\n return h(Badge, { variant }, () => label);\n }\n return label;\n };\n },\n\n date(pattern = \"yyyy-MM-dd\") {\n return (record, _index, column) =>\n formatDate((record as Record<string, unknown>)[column.key], pattern);\n },\n\n currency(currency = \"CNY\", locale = \"zh-CN\") {\n const format = new Intl.NumberFormat(locale, { style: \"currency\", currency });\n return (record, _index, column) => {\n const raw = (record as Record<string, unknown>)[column.key];\n const value = typeof raw === \"string\" ? Number(raw) : raw;\n if (typeof value !== \"number\" || Number.isNaN(value)) return raw as VNodeChild;\n return format.format(value);\n };\n },\n\n serial(base = 1) {\n return (_record, index) => index + base;\n },\n\n // inline-flex(行内级):按钮组随单元格 align 对齐(默认居中);块级 flex 占满单元格、恒左起\n button(items) {\n return (record, index) => {\n if (items.length === 0) return \"\";\n return h(\n \"div\",\n { class: \"inline-flex items-center gap-1\" },\n items.map((item) => {\n const action = typeof item === \"string\" ? { text: item } : item;\n return h(\n Button,\n {\n size: \"sm\",\n variant: action.variant ?? \"link\",\n disabled: action.disabled?.(record, index),\n onClick: () => action.onClick?.(record, index),\n },\n () => (typeof action.text === \"function\" ? action.text(record, index) : action.text),\n );\n }),\n );\n };\n },\n };\n}\n"
|
|
48
|
+
"content": "import type { BadgeVariants } from \"../badge\";\nimport type { ButtonVariants } from \"../button\";\nimport type { PropType, VNodeChild } from \"vue\";\nimport type { DataRecord, TableColumnOptions } from \"./types\";\nimport { defineComponent, h, ref, watch } from \"vue\";\nimport Badge from \"../badge/Badge.vue\";\nimport Button from \"../button/Button.vue\";\nimport Popconfirm from \"../popconfirm/Popconfirm.vue\";\n\n/** 单元格渲染器:与 TableColumnOptions.render 同签名(column 用于读取字段值) */\nexport type ColumnRender<T extends DataRecord> = (\n record: T,\n index: number,\n column: TableColumnOptions<T>,\n) => VNodeChild;\n\nexport type DictEntryVariant = BadgeVariants[\"variant\"];\n\nexport type DictColumnMapping = Record<\n string | number,\n string | { label: string; variant?: DictEntryVariant }\n>;\n\nexport interface DictColumnOptions {\n /** 整列统一 Badge 形态;条目级 variant 优先 */\n badge?: DictEntryVariant | true;\n}\n\n/** 日期模式串(迷你令牌 yyyy MM dd HH mm ss),如 \"yyyy-MM-dd HH:mm\" */\nexport type DateColumnPattern = string;\n\nexport interface SerialColumnOptions {\n /** 起始序号,默认 1 */\n base?: number;\n}\n\n/** 操作按钮二次确认配置(气泡形态,复用 Popconfirm);title/description 支持按行求值 */\nexport interface TableActionConfirm<T extends DataRecord> {\n /** 气泡标题(必填) */\n title: string | ((record: T, index: number) => string);\n /** 气泡描述(可选) */\n description?: string | ((record: T, index: number) => string);\n /** 确认按钮文案,默认 \"确定\" */\n confirmText?: string;\n /** 取消按钮文案,默认 \"取消\" */\n cancelText?: string;\n /** 确认按钮风格;缺省时按钮 variant 为 destructive 则推断 destructive,否则 default */\n variant?: \"default\" | \"destructive\";\n}\n\nexport interface TableActionButton<T extends DataRecord> {\n text: string | ((record: T, index: number) => string);\n /** 点击回调;有 confirm 时仅在气泡确认后触发。返回 Promise 时确认钮 loading 并锁定关闭通道,resolve 自动关闭、reject 保持打开(其余返回值忽略) */\n onClick?: (record: T, index: number) => unknown;\n variant?: ButtonVariants[\"variant\"];\n disabled?: (record: T, index: number) => boolean;\n /** 二次确认:字符串简写 = 气泡标题;对象形态全字段可配。不传则点击直接执行 onClick */\n confirm?: string | TableActionConfirm<T>;\n}\n\n/** 图片列配置;单元格值取自 record[column.key],须为非空字符串 URL(其余值渲染为空) */\nexport interface ImageColumnOptions<T extends DataRecord> {\n /** 方形边长 px,默认 40(inline style,不占用 Tailwind 类) */\n size?: number;\n /** 图片适应方式,默认 cover */\n fit?: \"cover\" | \"contain\" | \"fill\" | \"none\" | \"scale-down\";\n /** 外形,默认 rounded(rounded-md) */\n shape?: \"rounded\" | \"square\" | \"circle\";\n /** 替代文本,默认 \"\"(装饰图语义);建议按行传入有意义的描述 */\n alt?: string | ((record: T, index: number) => string);\n /** 加载失败时的备用图 URL(仅切换一次,备用也失败则显示占位盒);支持按行求值 */\n fallback?: string | ((record: T, index: number) => string);\n}\n\nexport interface ColumnRenders<T extends DataRecord> {\n /** 逃逸口:自定义渲染器与内置同一范式 */\n render: (fn: ColumnRender<T>) => ColumnRender<T>;\n dict: (mapping: DictColumnMapping, options?: DictColumnOptions) => ColumnRender<T>;\n date: (pattern?: DateColumnPattern) => ColumnRender<T>;\n currency: (currency?: string, locale?: string) => ColumnRender<T>;\n serial: (base?: number) => ColumnRender<T>;\n /** 操作列按钮组;按钮组为行内级(inline-flex),随单元格 align 对齐(默认居中) */\n button: (items: Array<TableActionButton<T> | string>) => ColumnRender<T>;\n /** 图片缩略图列;原生 img + loading=\"lazy\",失败切 fallback、再失败占位盒 */\n image: (options?: ImageColumnOptions<T>) => ColumnRender<T>;\n}\n\n/**\n * 两位补零\n * @param value - 数字(月/日/时/分/秒)\n * @returns 补零后的两位字符串\n */\nconst pad = (value: number) => String(value).padStart(2, \"0\");\n\n/**\n * 迷你日期令牌格式化,不引入 date-fns;非法输入原样返回\n * @param input - 单元格原始值(Date 或可构造 Date 的字符串/数字)\n * @param pattern - 令牌模板(支持 yyyy/MM/dd/HH/mm/ss)\n * @returns 格式化后的文本;输入非法时原样返回\n */\nfunction formatDate(input: unknown, pattern: string): VNodeChild {\n const date = input instanceof Date ? input : new Date(input as string | number);\n if (Number.isNaN(date.getTime())) return input as VNodeChild;\n const tokens: Record<string, string> = {\n yyyy: String(date.getFullYear()),\n MM: pad(date.getMonth() + 1),\n dd: pad(date.getDate()),\n HH: pad(date.getHours()),\n mm: pad(date.getMinutes()),\n ss: pad(date.getSeconds()),\n };\n return pattern.replace(/yyyy|MM|dd|HH|mm|ss/g, (token) => tokens[token]!);\n}\n\n// 字面类名映射(Tailwind 静态扫描要求完整类名,禁止 `object-${fit}` 式插值拼接)\nconst FIT_CLASS = {\n cover: \"object-cover\",\n contain: \"object-contain\",\n fill: \"object-fill\",\n none: \"object-none\",\n \"scale-down\": \"object-scale-down\",\n} as const;\n\nconst SHAPE_CLASS = {\n rounded: \"rounded-md\",\n square: \"rounded-none\",\n circle: \"rounded-full\",\n} as const;\n\n/**\n * 单元格图片内部组件(不导出):error 计数状态机驱动 原图 → fallback → 占位盒。\n * errors 单调递增防循环切换;watch src 复位,防虚拟滚动/分页行复用串图。\n */\nconst CellImage = defineComponent({\n name: \"TuCellImage\",\n props: {\n src: { type: String, required: true },\n alt: { type: String, default: \"\" },\n fallback: { type: String, default: undefined },\n size: { type: Number, default: 40 },\n fit: { type: String as PropType<keyof typeof FIT_CLASS>, default: \"cover\" },\n shape: { type: String as PropType<keyof typeof SHAPE_CLASS>, default: \"rounded\" },\n },\n setup(props) {\n const errors = ref(0);\n watch(\n () => props.src,\n () => {\n errors.value = 0;\n },\n );\n return () => {\n const sizeStyle = { width: `${props.size}px`, height: `${props.size}px` };\n const shapeClass = SHAPE_CLASS[props.shape];\n // 0 → 原图;1 且有 fallback → 备用图;其余(无 fallback / 备用也失败)→ 占位盒\n const currentSrc =\n errors.value === 0 ? props.src : errors.value === 1 ? props.fallback : undefined;\n if (!currentSrc) {\n return h(\n \"div\",\n {\n class: [\"bg-muted text-muted-foreground flex items-center justify-center\", shapeClass],\n style: sizeStyle,\n \"aria-hidden\": \"true\",\n },\n [\n h(\n \"svg\",\n {\n viewBox: \"0 0 24 24\",\n fill: \"none\",\n stroke: \"currentColor\",\n \"stroke-width\": \"2\",\n \"stroke-linecap\": \"round\",\n \"stroke-linejoin\": \"round\",\n class: \"size-1/2\",\n \"aria-hidden\": \"true\",\n },\n [\n h(\"rect\", { width: \"18\", height: \"18\", x: \"3\", y: \"3\", rx: \"2\", ry: \"2\" }),\n h(\"circle\", { cx: \"9\", cy: \"9\", r: \"2\" }),\n h(\"path\", { d: \"m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21\" }),\n ],\n ),\n ],\n );\n }\n return h(\"img\", {\n src: currentSrc,\n alt: props.alt,\n loading: \"lazy\",\n class: [\"bg-muted\", shapeClass, FIT_CLASS[props.fit]],\n style: sizeStyle,\n onError: () => {\n errors.value++;\n },\n });\n };\n },\n});\n\n/**\n * 内置列渲染器工厂:dict/date/currency/serial/button/image。\n * 返回值直接填入 TableColumnOptions.render;column 参数用于读取字段值。\n * 与 FormRender widget 的 r.xxx() 范式共词根。\n * @returns 各内置渲染器集合(render/dict/date/currency/serial/button/image)\n */\nexport function columnRenders<T extends DataRecord>(): ColumnRenders<T> {\n return {\n render: (fn) => fn,\n\n dict(mapping, options) {\n return (record, _index, column) => {\n const raw = (record as Record<string, unknown>)[column.key];\n const entry = mapping[raw as string | number];\n if (entry === undefined) return (raw ?? \"\") as VNodeChild;\n\n const label = typeof entry === \"string\" ? entry : entry.label;\n const entryVariant = typeof entry === \"object\" ? entry.variant : undefined;\n // Badge 形态:条目级 variant,或整列 badge 简写\n if (entryVariant !== undefined || options?.badge !== undefined) {\n const variant = entryVariant ?? (options?.badge === true ? undefined : options?.badge);\n return h(Badge, { variant }, () => label);\n }\n return label;\n };\n },\n\n date(pattern = \"yyyy-MM-dd\") {\n return (record, _index, column) =>\n formatDate((record as Record<string, unknown>)[column.key], pattern);\n },\n\n currency(currency = \"CNY\", locale = \"zh-CN\") {\n const format = new Intl.NumberFormat(locale, { style: \"currency\", currency });\n return (record, _index, column) => {\n const raw = (record as Record<string, unknown>)[column.key];\n const value = typeof raw === \"string\" ? Number(raw) : raw;\n if (typeof value !== \"number\" || Number.isNaN(value)) return raw as VNodeChild;\n return format.format(value);\n };\n },\n\n serial(base = 1) {\n return (_record, index) => index + base;\n },\n\n // inline-flex(行内级):按钮组随单元格 align 对齐(默认居中);块级 flex 占满单元格、恒左起\n button(items) {\n return (record, index) => {\n if (items.length === 0) return \"\";\n return h(\n \"div\",\n { class: \"inline-flex items-center gap-1\" },\n items.map((item) => {\n const action = typeof item === \"string\" ? { text: item } : item;\n const buttonNode = h(\n Button,\n {\n size: \"sm\",\n variant: action.variant ?? \"link\",\n disabled: action.disabled?.(record, index),\n // 有 confirm 时 Button 不挂 onClick:触发点击只开气泡,onClick 仅经\n // Popconfirm.onConfirm 在确认后执行(asChild 合并监听器,不剥离即双触发)\n onClick: action.confirm ? undefined : () => action.onClick?.(record, index),\n },\n () => (typeof action.text === \"function\" ? action.text(record, index) : action.text),\n );\n if (!action.confirm) return buttonNode;\n\n const confirm: TableActionConfirm<T> =\n typeof action.confirm === \"string\" ? { title: action.confirm } : action.confirm;\n const resolveText = (value?: string | ((rec: T, i: number) => string)) =>\n typeof value === \"function\" ? value(record, index) : value;\n // pending 语义零成本继承:useConfirmPending 从 vnode.props.onConfirm 直取处理器,\n // onClick 返回 Promise → loading + 锁定关闭通道 + resolve 自动关闭 / reject 保持打开\n return h(\n Popconfirm,\n {\n title: resolveText(confirm.title)!,\n description: resolveText(confirm.description),\n confirmText: confirm.confirmText,\n cancelText: confirm.cancelText,\n variant:\n confirm.variant ?? (action.variant === \"destructive\" ? \"destructive\" : \"default\"),\n onConfirm: () => action.onClick?.(record, index),\n },\n () => buttonNode,\n );\n }),\n );\n };\n },\n\n image(options) {\n return (record, index, column) => {\n const raw = (record as Record<string, unknown>)[column.key];\n // 非字符串(含 null/undefined/number)与空串 → 空字符串,不产生节点(对齐 dict 兜底)\n if (typeof raw !== \"string\" || raw === \"\") return \"\";\n const resolveText = (value?: string | ((rec: T, i: number) => string)) =>\n typeof value === \"function\" ? value(record, index) : value;\n return h(CellImage, {\n src: raw,\n alt: resolveText(options?.alt) ?? \"\",\n fallback: resolveText(options?.fallback),\n size: options?.size,\n fit: options?.fit,\n shape: options?.shape,\n });\n };\n },\n };\n}\n"
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
"path": "table-render/columns.ts",
|
|
52
|
+
"type": "registry:lib",
|
|
53
|
+
"target": "components/ui/table-render/columns.ts",
|
|
54
|
+
"content": "import type {\n DataRecord,\n TableColumnGroupOptions,\n TableColumnNode,\n TableColumnOptions,\n} from \"./types\";\n\n/**\n * 列节点工具:分组判别与叶子扁平化(多级表头支撑)。\n *\n * 设计取向:叶子口径全局不变 —— 引擎(TanStack 列定义)、列显隐、sticky 偏移、\n * min-width 求和、体单元格矩阵全部继续消费「扁平叶子」,分组能力只叠加在\n * 表头渲染与列设置面板两处。故此处是唯一的结构归一入口。\n */\n\n/**\n * 判别节点是否为分组(含 children)。\n * @param node - 列节点(叶子或分组)\n * @returns 该节点是否为分组\n */\nexport function isColumnGroup<T extends DataRecord>(\n node: TableColumnNode<T>,\n): node is TableColumnGroupOptions<T> {\n return Array.isArray((node as TableColumnGroupOptions<T>).children);\n}\n\n/**\n * 扁平化列节点树为叶子列数组(深度优先,保持声明顺序)。\n * @param nodes - 列节点树\n * @returns 深度优先展开的叶子列数组(下游全部消费此层)\n */\nexport function flattenColumns<T extends DataRecord>(\n nodes: TableColumnNode<T>[],\n): TableColumnOptions<T>[] {\n const leaves: TableColumnOptions<T>[] = [];\n const walk = (list: TableColumnNode<T>[]) => {\n for (const node of list) {\n if (isColumnGroup(node)) walk(node.children);\n else leaves.push(node);\n }\n };\n walk(nodes);\n return leaves;\n}\n"
|
|
48
55
|
},
|
|
49
56
|
{
|
|
50
57
|
"path": "table-render/constants.ts",
|
|
51
58
|
"type": "registry:lib",
|
|
52
59
|
"target": "components/ui/table-render/constants.ts",
|
|
53
|
-
"content": "/** 选择列在 sticky 映射中的哨兵键(选择列不在 columns 内,表头/表体单独渲染) */\nexport const SELECTION_CELL = \"__selection__\";\n\n/** 布局容器与 TableRender 的跨包填充协议 key:provide(true) 声明容器内 TableRender 应填满、内部滚动、表头固定 */\nexport const PAGE_TABLE_FILL_KEY = \"tu-design:page-table-fill\";\n"
|
|
60
|
+
"content": "/** 选择列在 sticky 映射中的哨兵键(选择列不在 columns 内,表头/表体单独渲染) */\nexport const SELECTION_CELL = \"__selection__\";\n\n/** 拖拽把手列在 sticky 映射中的哨兵键(同选择列:不在 columns 内,表头/表体单独渲染) */\nexport const DRAG_CELL = \"__drag__\";\n\n/** 布局容器与 TableRender 的跨包填充协议 key:provide(true) 声明容器内 TableRender 应填满、内部滚动、表头固定 */\nexport const PAGE_TABLE_FILL_KEY = \"tu-design:page-table-fill\";\n"
|
|
54
61
|
},
|
|
55
62
|
{
|
|
56
63
|
"path": "table-render/define-columns.ts",
|
|
57
64
|
"type": "registry:lib",
|
|
58
65
|
"target": "components/ui/table-render/define-columns.ts",
|
|
59
|
-
"content": "import type { DataRecord,
|
|
66
|
+
"content": "import type { DataRecord, TableColumnNode } from \"./types\";\n\n/**\n * 列定义辅助:补全泛型推导,便于把列配置抽到独立文件。\n *\n * 纯类型辅助,原样返回入参——裸数组同样可直接传给 defineTable(无需此函数)。\n * @param columns - 列节点树(叶子列或分组)\n * @returns 原样返回的列节点树\n */\nexport function defineColumns<T extends DataRecord = DataRecord>(\n columns: TableColumnNode<T>[],\n): TableColumnNode<T>[] {\n return columns;\n}\n"
|
|
60
67
|
},
|
|
61
68
|
{
|
|
62
69
|
"path": "table-render/define-table.ts",
|
|
@@ -68,7 +75,7 @@
|
|
|
68
75
|
"path": "table-render/index.ts",
|
|
69
76
|
"type": "registry:lib",
|
|
70
77
|
"target": "components/ui/table-render/index.ts",
|
|
71
|
-
"content": "export { default as TablePagination } from \"./TablePagination.vue\";\nexport { default as TableRender } from \"./TableRender.vue\";\nexport { columnRenders } from \"./column-renders\";\nexport { PAGE_TABLE_FILL_KEY } from \"./constants\";\nexport type {\n ColumnRenders,\n DictColumnMapping,\n DictColumnOptions,\n DictEntryVariant,\n SerialColumnOptions,\n TableActionButton,\n} from \"./column-renders\";\nexport { defineColumns } from \"./define-columns\";\nexport { defineTable } from \"./define-table\";\nexport { useTableRender } from \"./useTableRender\";\nexport type {\n DataRecord,\n DefineTableOptions,\n PageableOptions,\n SortableOptions,\n TableColumnOptions,\n TableLoadParams,\n TableRenderDefinition,\n TreeOptions,\n UseTableRenderOptions,\n} from \"./types\";\n"
|
|
78
|
+
"content": "export { default as TablePagination } from \"./TablePagination.vue\";\nexport { default as TableRender } from \"./TableRender.vue\";\nexport { columnRenders } from \"./column-renders\";\nexport { PAGE_TABLE_FILL_KEY } from \"./constants\";\nexport type {\n ColumnRenders,\n DictColumnMapping,\n DictColumnOptions,\n DictEntryVariant,\n ImageColumnOptions,\n SerialColumnOptions,\n TableActionButton,\n TableActionConfirm,\n} from \"./column-renders\";\nexport { defineColumns } from \"./define-columns\";\nexport { defineTable } from \"./define-table\";\nexport { flattenColumns, isColumnGroup } from \"./columns\";\nexport { useTableRender } from \"./useTableRender\";\nexport type {\n DataRecord,\n DefineTableOptions,\n PageableOptions,\n SortableOptions,\n TableColumnGroupOptions,\n TableColumnNode,\n TableColumnOptions,\n TableDraggableOptions,\n TableDragSortPayload,\n TableLoadParams,\n TableRenderDefinition,\n TreeOptions,\n UseTableRenderOptions,\n} from \"./types\";\n"
|
|
72
79
|
},
|
|
73
80
|
{
|
|
74
81
|
"path": "table-render/sticky.ts",
|
|
@@ -80,13 +87,19 @@
|
|
|
80
87
|
"path": "table-render/types.ts",
|
|
81
88
|
"type": "registry:lib",
|
|
82
89
|
"target": "components/ui/table-render/types.ts",
|
|
83
|
-
"content": "import type { ColumnRender, ColumnRenders } from \"./column-renders\";\nimport type { FormRenderDefinition } from \"../form-render\";\nimport type { Row, Table as TanstackTable } from \"@tanstack/vue-table\";\nimport type { MaybeRefOrGetter, Ref, VNodeChild } from \"vue\";\n\n/** 任意数据行(表格是弱类型数据容器,行结构由调用方的 T 决定) */\nexport interface DataRecord {\n [key: string]: any;\n}\n\n/** 表体行渲染单元:TanStack Row 引用 + 可见列值矩阵(TableRender → TableBodyRow) */\nexport interface TableBodyLine {\n /** TanStack Row:树形渲染读 depth / getCanExpand / getIsExpanded / toggleExpanded */\n row: Row<DataRecord>;\n key: string;\n index: number;\n record: DataRecord;\n /**
|
|
90
|
+
"content": "import type { ColumnRender, ColumnRenders } from \"./column-renders\";\nimport type { FormRenderDefinition } from \"../form-render\";\nimport type { Row, Table as TanstackTable } from \"@tanstack/vue-table\";\nimport type { MaybeRefOrGetter, Ref, VNodeChild } from \"vue\";\n\n/** 任意数据行(表格是弱类型数据容器,行结构由调用方的 T 决定) */\nexport interface DataRecord {\n [key: string]: any;\n}\n\n/** 表体行渲染单元:TanStack Row 引用 + 可见列值矩阵(TableRender → TableBodyRow) */\nexport interface TableBodyLine {\n /** TanStack Row:树形渲染读 depth / getCanExpand / getIsExpanded / toggleExpanded */\n row: Row<DataRecord>;\n key: string;\n index: number;\n record: DataRecord;\n /** 行级可选过滤:selectable 谓词交由引擎 enableRowSelection 判定 */\n canSelect: boolean;\n /** 可见列的值矩阵(列显隐只裁剪列;状态不受影响) */\n cells: VNodeChild[];\n}\n\n/**\n * 列配置。\n *\n * 命名总纲:能力/性质用 `-able` 形容词(sortable/ellipsis),\n * 配置值用名词(title/align/width),无 `allow-*`。\n */\nexport interface TableColumnOptions<T extends DataRecord = DataRecord> {\n /** 列标识,同时作为默认取值字段 */\n key: string;\n title: string;\n /** 单元格水平对齐;未配置默认居中(表头/表体一致),显式 \"left\" 退出默认 */\n align?: \"left\" | \"center\" | \"right\";\n /** 列宽。数字(px):布局硬约束 —— 参与表格 min-width 求和与 fixed 列 sticky 偏移推算;\n * 字符串(如 \"10rem\"):仅渲染提示值,不参与求和与 sticky。 */\n width?: number | string;\n /** 自定义单元格渲染,取值链 render > formatter > record[key] */\n render?: (r: ColumnRenders<T>) => ColumnRender<T>;\n /** 纯数据格式化;render 存在时被忽略 */\n formatter?: (record: T) => string | number | Date | undefined;\n /** 超宽截断 + 原生 title 提示;\"tooltip\" 形态改用库内 Tooltip(不设原生 title) */\n ellipsis?: boolean | \"tooltip\";\n /** 是否可排序(能力开关) */\n sortable?: boolean;\n /** 初始排序方向;需 sortable: true,否则 DEV 警告并忽略 */\n defaultSort?: \"asc\" | \"desc\";\n /** 固定列:横向滚动时 sticky 在左/右;须同时提供数字 width,否则 DEV 警告并按普通列渲染 */\n fixed?: \"left\" | \"right\";\n}\n\n/**\n * 表头分组成员(多级表头)。\n *\n * 仅承载展示语义(title/align);排序、宽度、固定等能力全部下沉到叶子列,\n * 分组不参与 sortable/fixed/width(配置时 DEV 警告并忽略)。\n */\nexport interface TableColumnGroupOptions<T extends DataRecord = DataRecord> {\n /** 分组标题(表头单元格文本) */\n title: string;\n /** 分组单元格水平对齐;未配置默认居中 */\n align?: \"left\" | \"center\" | \"right\";\n /** 子列节点(叶子列或更深分组),任意层级 */\n children: TableColumnNode<T>[];\n}\n\n/** 列节点:叶子列或分组(递归),defineTable/defineColumns 的入参元素类型 */\nexport type TableColumnNode<T extends DataRecord = DataRecord> =\n | TableColumnOptions<T>\n | TableColumnGroupOptions<T>;\n\nexport interface PageableOptions {\n /** 1-based 页码(对外 API 唯一口径) */\n pageIndex: number;\n pageSize: number;\n total: number;\n /** 只读:状态投影不允许调用方直接改写每页条数选项 */\n pageSizeOpts: readonly number[];\n}\n\nexport interface SortableOptions {\n key: string;\n direction: \"asc\" | \"desc\";\n}\n\n/** onLoad 入参:数据协议与 x-render 同构,request 生态由调用方自理 */\nexport interface TableLoadParams<T extends DataRecord = DataRecord> {\n /** 搜索表单值(来自 options.search 的表单当前值);未配置 search 时为 {} */\n form: DataRecord;\n page: PageableOptions;\n /** 无排序或已取消排序时为 undefined */\n sort?: SortableOptions;\n /** 回写数据;total 缺省时保留旧值 */\n update: (data: T[], total?: number) => void;\n}\n\n/** defineTable 的声明式配置 */\nexport interface DefineTableOptions<T extends DataRecord = DataRecord> {\n /** 列节点树:叶子列或分组(多级表头),任意层级;扁平数组天然合法 */\n columns: TableColumnNode<T>[];\n /** 服务端模式数据源;与 data 二选一,onLoad 优先 */\n onLoad?: (params: TableLoadParams<T>) => void | Promise<unknown>;\n /** 静态模式数据源(本地分页/排序) */\n data?: T[];\n /** 是否在挂载后自动加载,默认 true;仅服务端模式生效 */\n autoLoad?: boolean;\n /**\n * 每页条数 / 受控每页条数。约定:传入(非 undefined)即受控,缺省(undefined)时\n * 以默认 10 行运行;页码归位:pageIndex 未受控时内部归位第 1 页并经 update:page-index 通知,\n * 两个都受控时由父层自行联动。支持传 ref/getter(聚合式受控)\n */\n pageSize?: MaybeRefOrGetter<number | undefined>;\n pageSizeOpts?: number[];\n /** 行选择:radio 单选 / checkbox 多选;字符串为简写 */\n rowSelection?: \"radio\" | \"checkbox\" | TableSelectionOptions<T>;\n /** 行主键字段;rowSelection 启用且此值无效时禁用选择 */\n rowKey?: string;\n /**\n * 搜索表单(defineForm 返回值):仅服务端模式生效,每次 onLoad 的 form 参数\n * 携带 `search.form.state.values` 当前值。静态模式传入时 DEV 警告并忽略。\n * 泛型为 any:FormRenderDefinition 对 T 不变(FormRenderItem.key 字面量收窄),\n * DataRecord 版会拒收一切具体 defineForm<Q> 结果(对齐 FormRender.vue prop 约定)。\n */\n search?: FormRenderDefinition<any>;\n /** 虚拟滚动:开启后表体行在当前页行窗口内虚拟化(分页语义不变);须同时配置 height,否则 DEV 警告并降级普通渲染 */\n virtual?: boolean;\n /** 虚拟滚动容器高度(数字 px 或 CSS 高度);仅 virtual: true 时生效 */\n height?: number | string;\n /** 树形数据:子行展开/收起(展开按钮在首个业务列内);配置无效时 DEV 警告并忽略 */\n tree?: TreeOptions;\n /**\n * 行拖拽排序(仅当前页内,把手列触发):true 或对象配置。\n * 与 tree/virtual 互斥(DEV 警告并忽略);列排序激活期间把手置灰;\n * 当前页存在缺 rowKey 字段的记录时禁用(DEV 警告一次)。\n * 静态模式引擎先行重排内部数据并经 drag-sort 通知(调用方应回写自身数据源);\n * 服务端模式只发 drag-sort,由调用方持久化后 reload\n */\n draggable?: boolean | TableDraggableOptions<T>;\n /**\n * 受控页码(1-based)。约定:传入(非 undefined)即受控,缺省保持非受控;\n * 内部翻页经 update:page-index 通知,外部变更经受控 watch 同步(语义等值跳过,防回弹循环)\n */\n pageIndex?: MaybeRefOrGetter<number | undefined>;\n /** 受控排序。内部/外部变化均经 sort-change 通知;指向不可排序列时 DEV 警告并忽略 */\n sort?: MaybeRefOrGetter<SortableOptions | undefined>;\n /** 受控选中集(数组,与 update:selected-keys 载荷同构)。经 setSelection 写入(selectable 过滤、待定 key 继承) */\n selectedKeys?: MaybeRefOrGetter<Array<string | number> | undefined>;\n /**\n * 列显隐:默认可见列集(「重置」基准;未知 key 静默忽略;未传 = 全部可见)。\n * 列显隐不触发 onLoad、不重置 pageIndex/sort/selectedKeys\n */\n columnVisibility?: ColumnVisibilityOptions;\n /**\n * 受控可见列 key(columns 原序子集)。约定:传入(非 undefined)即受控;\n * 内部显隐经 update:visible-keys 通知;空数组钳制为首列可见(warn 一次)\n */\n visibleKeys?: MaybeRefOrGetter<string[] | undefined>;\n /**\n * 拆分式默认可见列集;与聚合式 columnVisibility.defaultVisibleKeys 同传时\n * DEV 警告 definition 优先\n */\n defaultVisibleKeys?: MaybeRefOrGetter<string[] | undefined>;\n}\n\n/** 行拖拽排序配置(draggable 对象形态;true 等价 {}) */\nexport interface TableDraggableOptions<T extends DataRecord = DataRecord> {\n /** 行级可拖过滤(对齐 selectable 范式);返回 false 的行把手置灰 */\n draggable?: (record: T) => boolean;\n /** 把手列宽,默认 32(对齐 selection.width 范式) */\n width?: number;\n}\n\n/** drag-sort 事件载荷:from/to 为页内索引(0-based,与 rows 同口径);rows = 当前页新行序 */\nexport interface TableDragSortPayload<T extends DataRecord = DataRecord> {\n from: number;\n to: number;\n record: T;\n rows: T[];\n}\n\n/** 树形数据配置(T 系列) */\nexport interface TreeOptions {\n /** 子行字段名,默认 \"children\" */\n childrenKey?: string;\n /** 默认全部展开,默认 false */\n defaultExpandAll?: boolean;\n /** 每层缩进 px,默认 16 */\n indentSize?: number;\n}\n\n/** 列显隐配置 */\nexport interface ColumnVisibilityOptions {\n /** 默认可见列 key 列表(「重置」基准);未知 key 静默忽略;未传 = 全部可见 */\n defaultVisibleKeys?: string[];\n}\n\n/** 行选择配置(S 系列) */\nexport interface TableSelectionOptions<T extends DataRecord = DataRecord> {\n type: \"radio\" | \"checkbox\";\n /** 选择列宽,默认 48 */\n width?: number;\n /** 行级可选过滤;false 的行选择控件置灰且被全选跳过 */\n selectable?: (record: T) => boolean;\n /** radio 再点已选中行是否取消,默认 true */\n cancelable?: boolean;\n /** 翻页/重载后是否保留选中,默认 true */\n reserveOnPageChange?: boolean;\n}\n\n/** useTableRender 的入参:data 额外支持 ref/getter(拆分模式下 props 天然响应式) */\nexport interface UseTableRenderOptions<T extends DataRecord = DataRecord> extends Omit<\n DefineTableOptions<T>,\n \"data\"\n> {\n data?: MaybeRefOrGetter<T[] | undefined>;\n}\n\n/** defineTable / useTableRender 的返回物:列配置 + 引擎实例 + 只读状态 + 实例动作 */\nexport interface TableRenderDefinition<T extends DataRecord = DataRecord> {\n columns: TableColumnOptions<T>[];\n /**\n * 原始列节点树(表头矩阵与列设置面板的树形结构来源)。\n * 可选:手工构造定义对象时缺省,组件侧回退为扁平的 `columns`(单级表头)。\n */\n columnTree?: TableColumnNode<T>[];\n /** TanStack 表格实例(逃逸舱口) */\n table: TanstackTable<T>;\n page: Readonly<PageableOptions>;\n sort: Readonly<{ value: SortableOptions | undefined }>;\n loading: Readonly<{ value: boolean }>;\n /** 重新加载;resetPage 为 true 时先回到第 1 页 */\n reload: (resetPage?: boolean) => void;\n /** 排序三态切换:无 → asc → desc → 取消 */\n toggleSort: (key: string) => void;\n setPageIndex: (pageIndex: number) => void;\n setPageSize: (pageSize: number) => void;\n /** 选中行快照(含跨页保留行;跨页行可能为过期数据) */\n selection: Readonly<{\n value: T[];\n /** rowSelection 配置有效(含 rowKey 就绪)时为 true */\n enabled: boolean;\n type: \"radio\" | \"checkbox\";\n width: number;\n }>;\n /** 选中主键集合;每次选中集变化替换为新 Set */\n selectedKeys: Readonly<Ref<Set<string | number>>>;\n /** 程序化设置选中集;不存在的 key 保留 */\n setSelection: (keys: Array<string | number>) => void;\n clearSelection: () => void;\n /** 行控件切换:checked 为 false 时移除(radio 受 cancelable 约束) */\n toggleRowSelected: (key: string, checked: boolean) => void;\n /** 搜索表单定义(options.search 校验后的回传,供 TableRender 渲染搜索区;被忽略时为 undefined) */\n search: FormRenderDefinition<any> | undefined;\n /** 内部装配口:definition 未配置 search 时由 TableRender 回填组件 prop(对齐 setRowKey) */\n setSearch: (search: FormRenderDefinition<any> | undefined) => void;\n /** 虚拟滚动配置透传(未配置为 undefined),供组件渲染层判定(definition 优先于 prop) */\n virtual: boolean | undefined;\n /** 虚拟滚动容器高度配置透传(仅 virtual: true 时被组件使用) */\n height: number | string | undefined;\n /** 树形配置(引擎校验后的回传,供组件读取 indentSize;无效配置被忽略时为 undefined) */\n tree: TreeOptions | undefined;\n /** 行拖拽配置(引擎校验后的回传;与 tree/virtual 冲突被忽略时为 undefined) */\n draggable: TableDraggableOptions<T> | undefined;\n /**\n * 页内重排(from/to 为页内 0-based 索引):静态模式先行重排内部全量数据,\n * 服务端模式不改内部数据;返回 drag-sort 载荷(守卫不通过/无效索引时为 undefined)\n */\n reorderRows: (from: number, to: number) => TableDragSortPayload<T> | undefined;\n /** 最近一次 onLoad 失败的 Error(仅服务端模式产生);下一次 load 开始时清除 */\n error: Readonly<Ref<Error | undefined>>;\n /** 可见列 key(columns 原序子集);受控/非受控统一投影 */\n visibleKeys: Readonly<Ref<readonly string[]>>;\n /** 列显隐动作:规范化(未知忽略、columns 原序、空钳制为首列)后更新 */\n setVisibleKeys: (keys: string[]) => void;\n /** 解析后的默认可见集(重置基准;未配置为 undefined = 全部可见) */\n defaultVisibleKeys: string[] | undefined;\n /** 聚合式列显隐配置回传(拆分式为 undefined) */\n columnVisibility: ColumnVisibilityOptions | undefined;\n /** 内部装配口:拆分式由 TableRender 在 setup 时回填 rowKey */\n setRowKey: (rowKey: string | undefined) => void;\n}\n"
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
"path": "table-render/useRowDrag.ts",
|
|
94
|
+
"type": "registry:lib",
|
|
95
|
+
"target": "components/ui/table-render/useRowDrag.ts",
|
|
96
|
+
"content": "import { ref } from \"vue\";\n\n/**\n * 行拖拽状态机(原生 HTML5 DnD):内部状态是唯一事实源,不读 dataTransfer\n * (happy-dom 的 DragEvent 是 Event 别名、无 dataTransfer,测试直接派发普通 Event)。\n * dataTransfer 写入仅作真实浏览器兼容(Firefox 需 setData 才起拖、setDragImage 整行快照),\n * 全部 optional 守卫。\n *\n * 落位语义由组件层预览序决定(实时让位):本状态机只负责起拖/接收/落位/清理。\n * @returns 拖拽状态(draggingKey)与事件动作(start/over/drop/end)\n */\nexport function useRowDrag() {\n const draggingKey = ref<string | undefined>(undefined);\n\n /**\n * 起拖(把手 dragstart)\n * @param key - 源行主键\n * @param event - 原生 dragstart 事件\n * @param image - 拖拽快照(离屏克隆元素 + 相对原行的抓取偏移);提供时幽灵影为整行截图\n */\n function start(\n key: string,\n event: DragEvent,\n image?: { el: Element; offsetX: number; offsetY: number },\n ) {\n draggingKey.value = key;\n if (event.dataTransfer) {\n event.dataTransfer.effectAllowed = \"move\";\n event.dataTransfer.setData(\"text/plain\", key);\n // 快照在 dragstart 内同步截取,早于 Vue 异步应用源行半透明类 → 幽灵影为不透明整行\n if (image) event.dataTransfer.setDragImage(image.el, image.offsetX, image.offsetY);\n }\n }\n\n /**\n * 悬停(行 dragover):持续 preventDefault 才允许 drop——**含被拖行占位自身**\n * (实时让位后光标恰停在占位上,不 preventDefault 则真实浏览器拒绝 drop)。\n * @param key - 悬停行主键\n * @param event - 原生 dragover 事件\n * @returns 是否接收让位(同源行返回 false:允许 drop 但不移动预览序)\n */\n function over(key: string, event: DragEvent): boolean {\n if (!draggingKey.value) return false;\n event.preventDefault();\n if (event.dataTransfer) event.dataTransfer.dropEffect = \"move\";\n return key !== draggingKey.value;\n }\n\n /**\n * 落位(行 drop):仅成功落位返回结果(取消路径走 end,不返回)。\n * 实时让位后被拖行占位恰在光标下,落在自身占位是有效提交(toKey = fromKey),\n * 最终序由组件层预览序决定;无预览时同源落位由组件层 from === to 守卫为空操作。\n * @param key - 落位行主键\n * @param event - 原生 drop 事件\n * @returns 源/目标行主键;无起拖状态时 undefined\n */\n function drop(key: string, event: DragEvent): { fromKey: string; toKey: string } | undefined {\n const fromKey = draggingKey.value;\n draggingKey.value = undefined;\n if (!fromKey) return undefined;\n event.preventDefault();\n return { fromKey, toKey: key };\n }\n\n /** 拖拽结束(把手 dragend,含取消路径):仅清理状态,不产生落位结果 */\n function end() {\n draggingKey.value = undefined;\n }\n\n return { draggingKey, start, over, drop, end };\n}\n\n/**\n * 整行拖拽快照:深克隆 tr 包进离屏临时 table(border-separate + 完整边框)。\n * border-collapse 下边框几何归属 table 而非 tr,直接截 tr 会缺上/左边框;\n * 克隆逐格复制实测宽度保证列宽一致。调用方负责在 drop/dragend 时 remove()。\n * @param tr - 源行元素\n * @returns 离屏快照 table(已挂 body,fixed 定位移出视口)\n */\nexport function createRowSnapshot(tr: HTMLElement): HTMLElement {\n const clone = tr.cloneNode(true) as HTMLElement;\n const srcCells = tr.querySelectorAll(\"td\");\n const cloneCells = clone.querySelectorAll(\"td\");\n srcCells.forEach((td, index) => {\n const cell = cloneCells[index];\n if (cell) cell.style.width = `${td.offsetWidth}px`;\n });\n const tbody = document.createElement(\"tbody\");\n tbody.appendChild(clone);\n const table = document.createElement(\"table\");\n table.className = \"border-separate border-spacing-0 border border-border bg-background\";\n table.style.position = \"fixed\";\n table.style.left = \"-9999px\";\n table.style.top = \"0\";\n table.style.tableLayout = \"fixed\";\n table.style.width = `${tr.offsetWidth}px`;\n table.appendChild(tbody);\n document.body.appendChild(table);\n return table;\n}\n"
|
|
84
97
|
},
|
|
85
98
|
{
|
|
86
99
|
"path": "table-render/useTableRender.ts",
|
|
87
100
|
"type": "registry:lib",
|
|
88
101
|
"target": "components/ui/table-render/useTableRender.ts",
|
|
89
|
-
"content": "import type { ColumnDef, RowSelectionState } from \"@tanstack/vue-table\";\nimport { computed, onMounted, reactive, readonly, ref, shallowRef, toValue, watch } from \"vue\";\nimport type { Ref } from \"vue\";\nimport {\n getCoreRowModel,\n getExpandedRowModel,\n getPaginationRowModel,\n getSortedRowModel,\n useVueTable,\n} from \"@tanstack/vue-table\";\nimport type {\n DataRecord,\n SortableOptions,\n TableRenderDefinition,\n TableSelectionOptions,\n TreeOptions,\n UseTableRenderOptions,\n} from \"./types\";\nimport type { FormRenderDefinition } from \"../form-render\";\n\nconst DEFAULT_PAGE_SIZE_OPTS = [10, 20, 50, 100];\n\n/**\n * 数值配置防御:受控 getter(组件层)与数值配置(defineTable 层)同字段共存时只认数字\n * @param value - 待判定的配置值\n * @returns 值为数字时原样返回,否则返回 undefined\n */\nfunction numericOption(value: unknown): number | undefined {\n return typeof value === \"number\" ? value : undefined;\n}\n\n/**\n * DEV 兜底提示:生产构建静默,只留可读的降级行为(R1–R7)\n * @param message - 提示文本\n */\nfunction warn(message: string) {\n if (import.meta.env.DEV) console.warn(`[tu-design] <TableRender> ${message}`);\n}\n\n/**\n * 表格数据内核:TanStack 无头引擎组装 + 1-based 对外投影 + 实例动作。\n *\n * 状态真相源是 TanStack 引擎(pageIndex 为 0-based),\n * `page`/`sort` 是对外的 1-based 只读投影,由 watch 同步。\n * @param options - 表格配置:列定义、数据源(静态 data 或服务端 onLoad)、分页排序、\n * 行选择、树形、列显隐、搜索表单等\n * @returns 表格渲染定义(含只读投影与实例动作),供 TableRender 组件消费\n */\nexport function useTableRender<T extends DataRecord>(\n options: UseTableRenderOptions<T>,\n): TableRenderDefinition<T> {\n const columns = options.columns;\n // 传入 onLoad 即服务端模式:分页/排序交由数据源,引擎不做本地加工\n const serverMode = typeof options.onLoad === \"function\";\n\n if (columns.length === 0) warn(\"columns 为空,表格将没有表头。\");\n if (serverMode && options.data !== undefined) {\n warn(\"onLoad 与 data 不能同时传入,已按 onLoad(服务端模式)处理。\");\n }\n\n // ---- 受控模式(v-model,D11) ------------------------------------------------\n // 约定:options 字段传入(非 undefined)即受控;受控值经 watch 同步进 TanStack,\n // 内部交互仍走既有动作路径(emit 由组件负责)。等值守卫防「父回写 → 同步 → 回弹」循环。\n const controlledPageIndex = () => toValue(options.pageIndex);\n const controlledPageSize = () => toValue(options.pageSize);\n const controlledSort = () => toValue(options.sort);\n const controlledSelectedKeys = () => toValue(options.selectedKeys);\n const controlledVisibleKeys = () => toValue(options.visibleKeys);\n\n // ---- 树形数据(T 系列) ------------------------------------------------------\n // 唯一解析点:无效配置 warn 并忽略;解析结果回传供组件读取 indentSize\n let tree: TreeOptions | undefined;\n if (options.tree !== undefined) {\n if (typeof options.tree !== \"object\" || options.tree === null) {\n warn(\"tree 必须是对象配置,已忽略。\");\n } else if (\n options.tree.childrenKey !== undefined &&\n typeof options.tree.childrenKey !== \"string\"\n ) {\n warn(\"tree.childrenKey 必须是字符串,已忽略。\");\n } else {\n tree = options.tree;\n }\n }\n const childrenKey = tree?.childrenKey ?? \"children\";\n\n // ---- 搜索表单(FormRender 联动) -------------------------------------------\n // any:FormRenderDefinition 对 T 不变,DataRecord 版拒收具体 defineForm<Q> 结果(见 types.ts)\n let search: FormRenderDefinition<any> | undefined;\n\n /**\n * search 唯一装配入口:静态模式 / 缺 form·items 时 DEV 警告并忽略\n * @param next - 待装配的搜索表单定义,undefined 表示移除\n */\n function applySearch(next: FormRenderDefinition<any> | undefined) {\n if (next === undefined) {\n search = undefined;\n return;\n }\n if (!serverMode) {\n warn(\"search 仅服务端模式生效(未传 onLoad),已忽略。\");\n search = undefined;\n return;\n }\n if (!next.form || !Array.isArray(next.items)) {\n warn(\"search 缺少 form 或 items,已忽略。\");\n search = undefined;\n return;\n }\n search = next;\n }\n\n applySearch(options.search);\n\n /**\n * 拆分式/组件级装配口:definition 未配置 search 时由 TableRender 回填 prop(对齐 setRowKey)\n * @param next - 待回填的搜索表单定义\n */\n function setSearch(next: FormRenderDefinition<any> | undefined) {\n if (search || !next) return;\n applySearch(next);\n }\n\n const page = reactive({\n pageIndex: 1,\n pageSize: controlledPageSize() ?? numericOption(options.pageSize) ?? 10,\n total: 0,\n pageSizeOpts: options.pageSizeOpts ?? DEFAULT_PAGE_SIZE_OPTS,\n });\n // defaultSort:静态模式进 TanStack 初始 sorting,服务端模式进首载 sort 参数\n const defaults = columns.filter((column) => column.defaultSort !== undefined);\n if (defaults.length > 1) {\n warn(`多列 defaultSort 仅首列 \"${defaults[0].key}\" 生效,其余已忽略。`);\n }\n if (defaults[0] && defaults[0].sortable !== true) {\n warn(`列 \"${defaults[0].key}\" 的 defaultSort 需要同时开启 sortable,已忽略。`);\n }\n const sorted = defaults.find((column) => column.sortable === true);\n\n // 初始值合并:受控初值优先于 defaultSort / pageSize 配置(避免 mount 后二次跳转与重复 load)\n const initialSort = controlledSort();\n const sort = ref<SortableOptions | undefined>(\n initialSort ?? (sorted ? { key: sorted.key, direction: sorted.defaultSort! } : undefined),\n );\n const loading = ref(false);\n const error = ref<Error | undefined>(undefined);\n const rows = shallowRef<T[]>([]);\n\n // ---- 行选择(S 系列) ------------------------------------------------------\n // 字符串简写 → 对象(S2)\n const rawSelection = options.rowSelection;\n const selectionConfig: TableSelectionOptions<T> | undefined =\n rawSelection === undefined\n ? undefined\n : typeof rawSelection === \"string\"\n ? { type: rawSelection }\n : rawSelection;\n // rowKey 由 defineTable 配置或 TableRender setup 时回填(S1);就绪前选择不可用\n const rowKey = ref(options.rowKey);\n const selectionEnabled = computed(() => selectionConfig !== undefined && !!rowKey.value);\n const selectedKeys = ref(new Set<string | number>()) as Ref<Set<string | number>>;\n const selectionRows = shallowRef<T[]>([]);\n /** key → 最近一次出现的行对象;跨页选中行由此返回快照(S6) */\n const selectionSnapshot = new Map<string, T>();\n /** 选中但当前数据中不存在的 key(reserveOnPageChange 语义,S12) */\n const dirtyKeys = new Set<string>();\n /** 受控选择状态:单一真相源,onRowSelectionChange 只通知不落盘(避免 setRowSelection 回环) */\n const rowSelectionState = ref<RowSelectionState>({});\n\n function selectionEmitSafe() {\n // 选择集变化 → 替换新 Set 触发依赖(S7);rows 从快照解析(含跨页)\n const keys = new Set<string | number>();\n for (const key of Object.keys(rowSelectionState.value))\n if (rowSelectionState.value[key]) keys.add(key);\n selectedKeys.value = keys;\n selectionRows.value = [...keys].map(\n (key) => selectionSnapshot.get(String(key)) ?? ({ [rowKey.value!]: key } as T),\n );\n }\n\n /**\n * 选中集写入的唯一入口:赋受控 state + 重建对外投影\n * @param next - TanStack 行选择状态(row id → 是否选中)\n */\n function applyRowSelection(next: RowSelectionState) {\n rowSelectionState.value = next;\n selectionEmitSafe();\n }\n\n /**\n * 行主键 → TanStack row id;rowKey 缺失时退化为索引(仅非选择场景可达,S1)\n * @param record - 行记录\n * @param index - 行索引(rowKey 缺失时的退化 id 来源)\n * @returns 稳定的行标识字符串\n */\n function rowIdOf(record: T, index: number): string {\n const key = rowKey.value;\n const value = key ? record[key] : undefined;\n return value === undefined || value === null ? `index-${index}` : String(value);\n }\n\n /** 数据窗口变化时刷新快照中已存在 key 的行对象(S6:后写覆盖) */\n function refreshSnapshot() {\n const key = rowKey.value;\n if (!key) return;\n let collisionWarned = false;\n for (const record of rows.value) {\n const value = record[key];\n if (value === undefined || value === null) continue;\n const id = String(value);\n if (selectionSnapshot.has(id) && !collisionWarned && import.meta.env.DEV) {\n // S11:撞 key 属数据问题,只提示一次\n if (selectionSnapshot.get(id) !== record) {\n collisionWarned = true;\n warn(`rowKey \"${key}\" 存在重复值,行选择快照以后出现的记录为准。`);\n }\n }\n selectionSnapshot.set(id, record);\n dirtyKeys.delete(id);\n }\n // 选中行对象可能刚被刷新:重建投影\n if (selectedKeys.value.size > 0) selectionEmitSafe();\n }\n\n // ---- 引擎组装 -------------------------------------------------------------\n const table = useVueTable({\n get data() {\n return rows.value;\n },\n getRowId: (originalRow, index) => rowIdOf(originalRow, index),\n // 树形:子行走 childrenKey(空数组与缺字段都视为叶子);展开模型接入后\n // getRowModel() 返回「父行 + 可见子行」的扁平序列,行带 depth/toggleExpanded\n getSubRows: (originalRow) => {\n const children = (originalRow as DataRecord)[childrenKey];\n return Array.isArray(children) ? children : [];\n },\n getExpandedRowModel: getExpandedRowModel(),\n columns: columns.map<ColumnDef<T>>((column) => ({\n accessorKey: column.key,\n header: column.title,\n enableSorting: column.sortable === true,\n })),\n initialState: {\n // 排序从投影初值构造(覆盖 defaultSort 与受控 sort 两种来源)\n sorting: sort.value ? [{ id: sort.value.key, desc: sort.value.direction === \"desc\" }] : [],\n // 初始 pageSize 须进 TanStack(此前只写对外投影,静态模式初始 pageSize≠10 不生效);\n // 受控初值优先(组件层受控 getter 未传时返回 undefined,须防御性取数值配置)\n pagination: {\n pageIndex: Math.max(0, (controlledPageIndex() ?? 1) - 1),\n pageSize: controlledPageSize() ?? numericOption(options.pageSize) ?? 10,\n },\n // defaultExpandAll:true = 全部展开;否则全收起(TanStack expanded 空对象)\n expanded: tree?.defaultExpandAll === true ? true : {},\n },\n getCoreRowModel: getCoreRowModel(),\n getPaginationRowModel: getPaginationRowModel(),\n getSortedRowModel: getSortedRowModel(),\n manualPagination: serverMode,\n manualSorting: serverMode,\n get state() {\n return { rowSelection: rowSelectionState.value };\n },\n enableRowSelection: selectionConfig?.selectable\n ? (row) => selectionConfig.selectable!(row.original)\n : selectionConfig !== undefined,\n enableMultiRowSelection: selectionConfig?.type !== \"radio\",\n onRowSelectionChange: (updater) => {\n const prev = rowSelectionState.value;\n const next = typeof updater === \"function\" ? updater(prev) : updater;\n // S4:radio 且 cancelable: false 时,解绑结果为空集则保持原状\n if (\n selectionConfig?.type === \"radio\" &&\n selectionConfig.cancelable === false &&\n !Object.keys(next).some((key) => next[key])\n ) {\n return;\n }\n applyRowSelection(next);\n },\n });\n\n watch(\n () => table.getState().pagination,\n (pagination) => {\n if (page.pageIndex === pagination.pageIndex + 1 && page.pageSize === pagination.pageSize)\n return;\n page.pageIndex = pagination.pageIndex + 1;\n page.pageSize = pagination.pageSize;\n },\n { immediate: true },\n );\n\n watch(\n () => table.getState().sorting,\n (sorting) => {\n const next: SortableOptions | undefined = sorting[0]\n ? { key: sorting[0].id, direction: sorting[0].desc ? \"desc\" : \"asc\" }\n : undefined;\n // 仅在语义发散时回写:toggleSort 已同步落值,等价对象回写会触发多余的重复加载\n if (sort.value?.key === next?.key && sort.value?.direction === next?.direction) return;\n sort.value = next;\n },\n { immediate: true },\n );\n\n // 静态数据源:ref/getter 会自动跟随;普通数组为快照,可用 reload() 重同步\n function syncData() {\n const data = toValue(options.data);\n if (data !== undefined && !Array.isArray(data)) {\n warn(\"data 必须是数组,已按空表处理。\");\n }\n // 复制出新引用:就地修改同一个普通数组时 shallowRef 不会触发,行模型会停留在旧快照\n rows.value = Array.isArray(data) ? [...data] : [];\n page.total = rows.value.length;\n }\n\n watch(() => toValue(options.data), syncData, { immediate: true });\n\n function setPageIndex(pageIndex: number) {\n table.setPageIndex(Math.max(0, pageIndex - 1));\n }\n\n function setPageSize(pageSize: number) {\n table.setPageSize(pageSize);\n // TanStack 容量变更后停在最后一页(pageCount-1),R9 要求回到首页\n table.setPageIndex(0);\n }\n\n /** 排序应用的唯一管线:服务端模式归位第 1 页(R8)+ 投影落值 + TanStack setSorting。\n * 受控 sort 的外部同步与此共用(直接 setSorting 会漏服务端重载)\n * @param next - 目标排序(key + direction),undefined 表示取消排序\n */\n function applySort(next: SortableOptions | undefined) {\n // 服务端模式按新排序取数,必须先归位到首页(R8)\n if (serverMode && page.pageIndex !== 1) setPageIndex(1);\n // 同步落值:对外投影不能等 watcher(emit 需要立即读到新排序)\n sort.value = next;\n table.setSorting(next ? [{ id: next.key, desc: next.direction === \"desc\" }] : []);\n }\n\n /**\n * 排序三态:无 → asc → desc → 取消;非 sortable 列为空操作(R8)\n * @param key - 目标列 key\n */\n function toggleSort(key: string) {\n if (!columns.some((column) => column.key === key && column.sortable === true)) return;\n\n const current = sort.value;\n const direction =\n current?.key !== key ? \"asc\" : current.direction === \"asc\" ? \"desc\" : undefined;\n\n applySort(direction ? { key, direction } : undefined);\n }\n\n // 服务端模式:请求序号守卫,乱序返回的旧响应直接丢弃(R6)\n let requestId = 0;\n\n async function load() {\n const id = ++requestId;\n loading.value = true;\n // 下一次 load 开始时清除上一次的错误(无论该 load 是否为当前请求)\n error.value = undefined;\n try {\n await options.onLoad?.({\n // 事件/取数时机读取是安全的(form.state 非响应式但同步);浅拷贝避免调用方改写真值\n form: search ? { ...search.form.state.values } : {},\n page: {\n pageIndex: page.pageIndex,\n pageSize: page.pageSize,\n total: page.total,\n pageSizeOpts: page.pageSizeOpts,\n },\n sort: sort.value,\n update: (data, total) => {\n if (id !== requestId) return;\n rows.value = Array.isArray(data) ? data : [];\n // total 缺省时保留旧值(R10)\n if (typeof total === \"number\") page.total = total;\n },\n });\n } catch (err) {\n // 乱序旧请求的失败直接丢弃(R6 同款守卫)\n if (id === requestId) {\n const normalized = err instanceof Error ? err : new Error(String(err));\n error.value = normalized;\n console.error(\"[tu-design] <TableRender> onLoad 执行失败:\", normalized);\n }\n } finally {\n if (id === requestId) loading.value = false;\n }\n }\n\n // 服务端模式下分页/排序变化即重取数;同一 tick 内多次变更只触发一次\n watch(\n () => (serverMode ? [page.pageIndex, page.pageSize, sort.value] : null),\n () => {\n void load();\n },\n );\n\n // ---- 受控同步(D11):外部变更 → TanStack -------------------------------------\n // 各 watch 均带语义等值守卫:内部先行(动作已生效)或父回写回弹时跳过,\n // 严禁死循环与重复 onLoad(load watch 绑定投影,投影等值守卫兜底)。\n // pageIndex 受控(1-based;最小归 1)\n watch(controlledPageIndex, (next) => {\n if (next === undefined || page.pageIndex === next) return;\n table.setPageIndex(Math.max(0, next - 1));\n });\n\n // pageSize 受控:同步容量;pageIndex 未受控时保持 R9 归位第 1 页(两方都受控由父层联动)\n watch(controlledPageSize, (next) => {\n if (next === undefined || page.pageSize === next) return;\n table.setPageSize(next);\n if (controlledPageIndex() === undefined) table.setPageIndex(0);\n });\n\n // sort 受控:经 applySort 管线(服务端归位 + 重载不漏);不可排序列警告并忽略\n watch(controlledSort, (next) => {\n if (next === undefined && sort.value === undefined) return;\n if (\n next &&\n sort.value &&\n next.key === sort.value.key &&\n next.direction === sort.value.direction\n ) {\n return;\n }\n if (next && !columns.some((c) => c.key === next.key && c.sortable === true)) {\n warn(`sort 受控值指向不可排序列 \"${next.key}\",已忽略。`);\n return;\n }\n applySort(next);\n });\n\n // selectedKeys 受控:经 setSelection 写入(S5 selectable 过滤 / S12 待定 key 语义继承)\n watch(\n controlledSelectedKeys,\n (next) => {\n if (next === undefined) return;\n const current = selectedKeys.value;\n // 语义等值(内容而非引用):内部勾选先行或父回写回弹时跳过,防 Set 重建触发的事件回环\n if (next.length === current.size && next.every((key) => current.has(key))) return;\n setSelection(next);\n },\n { immediate: true },\n );\n\n // ---- 列显隐(column visibility,R20–R24) -------------------------------------\n // 统一投影:受控初值 > defaultVisibleKeys(拆分式/聚合式 R26) > 全部可见。\n // 列显隐只动本 ref——不触发 onLoad、不重置 pageIndex/sort/selectedKeys(R25)。\n let emptyVisibleWarned = false;\n\n /**\n * 规范化:未知 key 静默忽略、按 columns 原序、空数组钳制为首列(R24,warn 一次)\n * @param keys - 目标可见列 key 列表(任意顺序,可含未知 key)\n * @returns 规范化后的可见列 key 列表(columns 原序)\n */\n function normalizeVisibleKeys(keys: readonly string[]): string[] {\n const known = columns.filter((column) => keys.includes(column.key)).map((column) => column.key);\n if (known.length > 0) return known;\n if (columns.length > 0) {\n if (!emptyVisibleWarned) {\n warn(\"可见列不能为空,已钳制为首列可见。\");\n emptyVisibleWarned = true;\n }\n return [columns[0]!.key];\n }\n return [];\n }\n\n function sameVisibleKeys(a: readonly string[], b: readonly string[]): boolean {\n return a.length === b.length && a.every((key, index) => key === b[index]);\n }\n\n const parsedDefaultVisibleKeys = (() => {\n const raw = toValue(options.defaultVisibleKeys) ?? options.columnVisibility?.defaultVisibleKeys;\n return raw ? normalizeVisibleKeys(raw) : undefined;\n })();\n\n const visibleKeysInternal = ref<string[]>(\n controlledVisibleKeys()\n ? normalizeVisibleKeys(controlledVisibleKeys()!)\n : (parsedDefaultVisibleKeys ?? columns.map((column) => column.key)),\n );\n\n /**\n * 列显隐动作(面板交互/程序化):规范化后更新统一投影\n * @param keys - 目标可见列 key 列表\n */\n function setVisibleKeys(keys: string[]) {\n visibleKeysInternal.value = normalizeVisibleKeys(keys);\n }\n\n // visibleKeys 受控:外部变更同步投影(规范化后语义等值跳过,防回弹)\n watch(controlledVisibleKeys, (next) => {\n if (next === undefined) return;\n const normalized = normalizeVisibleKeys(next);\n if (sameVisibleKeys(normalized, visibleKeysInternal.value)) return;\n visibleKeysInternal.value = normalized;\n });\n\n onMounted(() => {\n if (serverMode && (options.autoLoad ?? true)) void load();\n // S1:rowKey 在 defineTable 阶段可能尚未就绪(聚合式由 TableRender 回填),挂载时终审\n if (selectionConfig && !rowKey.value) {\n warn(\"rowSelection 需要有效的 rowKey 字段,已禁用行选择。\");\n }\n });\n\n function reload(resetPage = false) {\n if (serverMode) {\n // 归位由分页 watch 触发重载;页码本就为首页时直接重载(避免双请求)\n if (resetPage && page.pageIndex !== 1) setPageIndex(1);\n else void load();\n return;\n }\n if (resetPage) setPageIndex(1);\n syncData();\n }\n\n // ---- 行选择动作与联动(S 系列) -------------------------------------------\n\n /**\n * 程序化设置选中集;不存在的 key 保留进入 dirtyKeys(S12);不可选行被过滤(对齐 S5)\n * @param keys - 目标选中行的 key 列表(整体替换现有选中集)\n */\n function setSelection(keys: Array<string | number>) {\n const next: RowSelectionState = {};\n for (const key of keys) {\n const row = selectionSnapshot.get(String(key));\n // 快照中存在的行按 selectable 谓词过滤;待定 key(尚无行对象)无法判定的不拦\n if (row && selectionConfig?.selectable && !selectionConfig.selectable(row)) continue;\n next[String(key)] = true;\n if (!row) dirtyKeys.add(String(key));\n }\n applyRowSelection(next);\n }\n\n function clearSelection() {\n applyRowSelection({});\n }\n\n function toggleRowSelected(key: string, checked: boolean) {\n // S4:radio 且 cancelable: false 时,交互解绑最后一个选中为空操作\n if (!checked && selectionConfig?.type === \"radio\" && selectionConfig.cancelable === false) {\n return;\n }\n if (!checked) {\n const { [key]: _removed, ...rest } = rowSelectionState.value;\n applyRowSelection(rest);\n return;\n }\n // radio:单选互斥(S4);checkbox:累加\n const next =\n selectionConfig?.type === \"radio\"\n ? { [key]: true }\n : { ...rowSelectionState.value, [key]: true };\n applyRowSelection(next);\n }\n\n /**\n * 拆分式装配口:TableRender setup 时回传组件 rowKey(S1)\n * @param key - 行主键字段名\n */\n function setRowKey(key: string | undefined) {\n if (rowKey.value === key) return;\n rowKey.value = key;\n // 聚合式下数据窗口早于 rowKey 就绪(pre-flush 先于子组件 setup),补建快照\n refreshSnapshot();\n }\n\n // 数据窗口变化(翻页或数据替换):刷新快照;reserveOnPageChange: false 时清空选中(S6)\n watch([rows, () => page.pageIndex], () => {\n refreshSnapshot();\n if (selectionConfig && selectionConfig.reserveOnPageChange === false) clearSelection();\n });\n\n return {\n columns,\n table,\n page: readonly(page),\n sort: readonly(sort),\n loading: readonly(loading),\n error: readonly(error),\n reload,\n toggleSort,\n setPageIndex,\n setPageSize,\n selection: {\n get value(): T[] {\n return selectionRows.value;\n },\n get enabled(): boolean {\n return selectionEnabled.value;\n },\n get type(): \"radio\" | \"checkbox\" {\n return selectionConfig?.type ?? \"checkbox\";\n },\n get width(): number {\n return selectionConfig?.width ?? 48;\n },\n },\n selectedKeys: selectedKeys as Readonly<Ref<Set<string | number>>>,\n setSelection,\n clearSelection,\n toggleRowSelected,\n // getter 而非快照:setSearch 由 TableRender 在 setup 回填,读取须反映最新值\n get search() {\n return search;\n },\n setSearch,\n // 纯配置透传(渲染层消费;不支持运行时切换)\n virtual: options.virtual,\n height: options.height,\n tree,\n // 列显隐(R20–R24):统一投影 + 动作 + 重置基准\n visibleKeys: readonly(visibleKeysInternal),\n setVisibleKeys,\n defaultVisibleKeys: parsedDefaultVisibleKeys,\n columnVisibility: options.columnVisibility,\n setRowKey,\n };\n}\n"
|
|
102
|
+
"content": "import type { ColumnDef, RowSelectionState } from \"@tanstack/vue-table\";\nimport { computed, onMounted, reactive, readonly, ref, shallowRef, toValue, watch } from \"vue\";\nimport type { Ref } from \"vue\";\nimport { flattenColumns } from \"./columns\";\nimport {\n getCoreRowModel,\n getExpandedRowModel,\n getPaginationRowModel,\n getSortedRowModel,\n useVueTable,\n} from \"@tanstack/vue-table\";\nimport type {\n DataRecord,\n SortableOptions,\n TableDraggableOptions,\n TableDragSortPayload,\n TableRenderDefinition,\n TableSelectionOptions,\n TreeOptions,\n UseTableRenderOptions,\n} from \"./types\";\nimport type { FormRenderDefinition } from \"../form-render\";\n\nconst DEFAULT_PAGE_SIZE_OPTS = [10, 20, 50, 100];\n\n/**\n * 数值配置防御:受控 getter(组件层)与数值配置(defineTable 层)同字段共存时只认数字\n * @param value - 待判定的配置值\n * @returns 值为数字时原样返回,否则返回 undefined\n */\nfunction numericOption(value: unknown): number | undefined {\n return typeof value === \"number\" ? value : undefined;\n}\n\n/**\n * DEV 兜底提示:生产构建静默,只留可读的降级行为\n * @param message - 提示文本\n */\nfunction warn(message: string) {\n if (import.meta.env.DEV) console.warn(`[tu-design] <TableRender> ${message}`);\n}\n\n/**\n * 表格数据内核:TanStack 无头引擎组装 + 1-based 对外投影 + 实例动作。\n *\n * 状态真相源是 TanStack 引擎(pageIndex 为 0-based),\n * `page`/`sort` 是对外的 1-based 只读投影,由 watch 同步。\n * @param options - 表格配置:列定义、数据源(静态 data 或服务端 onLoad)、分页排序、\n * 行选择、树形、列显隐、搜索表单等\n * @returns 表格渲染定义(含只读投影与实例动作),供 TableRender 组件消费\n */\nexport function useTableRender<T extends DataRecord>(\n options: UseTableRenderOptions<T>,\n): TableRenderDefinition<T> {\n const columnTree = options.columns;\n const columns = flattenColumns(options.columns);\n // 传入 onLoad 即服务端模式:分页/排序交由数据源,引擎不做本地加工\n const serverMode = typeof options.onLoad === \"function\";\n\n if (columns.length === 0) warn(\"columns 为空,表格将没有表头。\");\n if (serverMode && options.data !== undefined) {\n warn(\"onLoad 与 data 不能同时传入,已按 onLoad(服务端模式)处理。\");\n }\n\n // ---- 受控模式(v-model) ------------------------------------------------\n // 约定:options 字段传入(非 undefined)即受控;受控值经 watch 同步进 TanStack,\n // 内部交互仍走既有动作路径(emit 由组件负责)。等值守卫防「父回写 → 同步 → 回弹」循环。\n const controlledPageIndex = () => toValue(options.pageIndex);\n const controlledPageSize = () => toValue(options.pageSize);\n const controlledSort = () => toValue(options.sort);\n const controlledSelectedKeys = () => toValue(options.selectedKeys);\n const controlledVisibleKeys = () => toValue(options.visibleKeys);\n\n // ---- 树形数据(T 系列) ------------------------------------------------------\n // 唯一解析点:无效配置 warn 并忽略;解析结果回传供组件读取 indentSize\n let tree: TreeOptions | undefined;\n if (options.tree !== undefined) {\n if (typeof options.tree !== \"object\" || options.tree === null) {\n warn(\"tree 必须是对象配置,已忽略。\");\n } else if (\n options.tree.childrenKey !== undefined &&\n typeof options.tree.childrenKey !== \"string\"\n ) {\n warn(\"tree.childrenKey 必须是字符串,已忽略。\");\n } else {\n tree = options.tree;\n }\n }\n const childrenKey = tree?.childrenKey ?? \"children\";\n\n // ---- 搜索表单(FormRender 联动) -------------------------------------------\n // any:FormRenderDefinition 对 T 不变,DataRecord 版拒收具体 defineForm<Q> 结果(见 types.ts)\n let search: FormRenderDefinition<any> | undefined;\n\n /**\n * search 唯一装配入口:静态模式 / 缺 form·items 时 DEV 警告并忽略\n * @param next - 待装配的搜索表单定义,undefined 表示移除\n */\n function applySearch(next: FormRenderDefinition<any> | undefined) {\n if (next === undefined) {\n search = undefined;\n return;\n }\n if (!serverMode) {\n warn(\"search 仅服务端模式生效(未传 onLoad),已忽略。\");\n search = undefined;\n return;\n }\n if (!next.form || !Array.isArray(next.items)) {\n warn(\"search 缺少 form 或 items,已忽略。\");\n search = undefined;\n return;\n }\n search = next;\n }\n\n applySearch(options.search);\n\n /**\n * 拆分式/组件级装配口:definition 未配置 search 时由 TableRender 回填 prop(对齐 setRowKey)\n * @param next - 待回填的搜索表单定义\n */\n function setSearch(next: FormRenderDefinition<any> | undefined) {\n if (search || !next) return;\n applySearch(next);\n }\n\n const page = reactive({\n pageIndex: 1,\n pageSize: controlledPageSize() ?? numericOption(options.pageSize) ?? 10,\n total: 0,\n pageSizeOpts: options.pageSizeOpts ?? DEFAULT_PAGE_SIZE_OPTS,\n });\n // defaultSort:静态模式进 TanStack 初始 sorting,服务端模式进首载 sort 参数\n const defaults = columns.filter((column) => column.defaultSort !== undefined);\n if (defaults.length > 1) {\n warn(`多列 defaultSort 仅首列 \"${defaults[0].key}\" 生效,其余已忽略。`);\n }\n if (defaults[0] && defaults[0].sortable !== true) {\n warn(`列 \"${defaults[0].key}\" 的 defaultSort 需要同时开启 sortable,已忽略。`);\n }\n const sorted = defaults.find((column) => column.sortable === true);\n\n // 初始值合并:受控初值优先于 defaultSort / pageSize 配置(避免 mount 后二次跳转与重复 load)\n const initialSort = controlledSort();\n const sort = ref<SortableOptions | undefined>(\n initialSort ?? (sorted ? { key: sorted.key, direction: sorted.defaultSort! } : undefined),\n );\n const loading = ref(false);\n const error = ref<Error | undefined>(undefined);\n const rows = shallowRef<T[]>([]);\n\n // ---- 行拖拽排序(draggable) ------------------------------------------------\n // 唯一解析点:与 tree/virtual 互斥(warn 并忽略);解析结果回传供组件渲染把手列。\n // 排序激活/rowKey 记录级缺失是动态守卫,由组件渲染层判定(把手置灰)。\n let draggableConfig: TableDraggableOptions<T> | undefined;\n if (options.draggable !== undefined && options.draggable !== false) {\n if (tree) {\n warn(\"draggable 与 tree 不能同时启用,已忽略 draggable。\");\n } else if (options.virtual === true) {\n warn(\"draggable 与 virtual 不能同时启用,已忽略 draggable。\");\n } else {\n const config = options.draggable === true ? {} : options.draggable;\n if (config.width !== undefined && typeof config.width !== \"number\") {\n warn(\"draggable.width 必须是数字,已按默认 32 处理。\");\n delete config.width;\n }\n draggableConfig = config;\n if (sort.value !== undefined) {\n warn(\"draggable 与初始排序(defaultSort/受控 sort)同时配置,排序激活期间拖拽不可用。\");\n }\n }\n }\n\n // ---- 行选择(S 系列) ------------------------------------------------------\n // 字符串简写 → 对象\n const rawSelection = options.rowSelection;\n const selectionConfig: TableSelectionOptions<T> | undefined =\n rawSelection === undefined\n ? undefined\n : typeof rawSelection === \"string\"\n ? { type: rawSelection }\n : rawSelection;\n // rowKey 由 defineTable 配置或 TableRender setup 时回填;就绪前选择不可用\n const rowKey = ref(options.rowKey);\n const selectionEnabled = computed(() => selectionConfig !== undefined && !!rowKey.value);\n const selectedKeys = ref(new Set<string | number>()) as Ref<Set<string | number>>;\n const selectionRows = shallowRef<T[]>([]);\n /** key → 最近一次出现的行对象;跨页选中行由此返回快照 */\n const selectionSnapshot = new Map<string, T>();\n /** 选中但当前数据中不存在的 key(reserveOnPageChange 语义) */\n const dirtyKeys = new Set<string>();\n /** 受控选择状态:单一真相源,onRowSelectionChange 只通知不落盘(避免 setRowSelection 回环) */\n const rowSelectionState = ref<RowSelectionState>({});\n\n function selectionEmitSafe() {\n // 选择集变化 → 替换新 Set 触发依赖;rows 从快照解析(含跨页)\n const keys = new Set<string | number>();\n for (const key of Object.keys(rowSelectionState.value))\n if (rowSelectionState.value[key]) keys.add(key);\n selectedKeys.value = keys;\n selectionRows.value = [...keys].map(\n (key) => selectionSnapshot.get(String(key)) ?? ({ [rowKey.value!]: key } as T),\n );\n }\n\n /**\n * 选中集写入的唯一入口:赋受控 state + 重建对外投影\n * @param next - TanStack 行选择状态(row id → 是否选中)\n */\n function applyRowSelection(next: RowSelectionState) {\n rowSelectionState.value = next;\n selectionEmitSafe();\n }\n\n /**\n * 行主键 → TanStack row id;rowKey 缺失时退化为索引(仅非选择场景可达)\n * @param record - 行记录\n * @param index - 行索引(rowKey 缺失时的退化 id 来源)\n * @returns 稳定的行标识字符串\n */\n function rowIdOf(record: T, index: number): string {\n const key = rowKey.value;\n const value = key ? record[key] : undefined;\n return value === undefined || value === null ? `index-${index}` : String(value);\n }\n\n /** 数据窗口变化时刷新快照中已存在 key 的行对象(后写覆盖) */\n function refreshSnapshot() {\n const key = rowKey.value;\n if (!key) return;\n let collisionWarned = false;\n for (const record of rows.value) {\n const value = record[key];\n if (value === undefined || value === null) continue;\n const id = String(value);\n if (selectionSnapshot.has(id) && !collisionWarned && import.meta.env.DEV) {\n // 撞 key 属数据问题,只提示一次\n if (selectionSnapshot.get(id) !== record) {\n collisionWarned = true;\n warn(`rowKey \"${key}\" 存在重复值,行选择快照以后出现的记录为准。`);\n }\n }\n selectionSnapshot.set(id, record);\n dirtyKeys.delete(id);\n }\n // 选中行对象可能刚被刷新:重建投影\n if (selectedKeys.value.size > 0) selectionEmitSafe();\n }\n\n // ---- 引擎组装 -------------------------------------------------------------\n const table = useVueTable({\n get data() {\n return rows.value;\n },\n getRowId: (originalRow, index) => rowIdOf(originalRow, index),\n // 树形:子行走 childrenKey(空数组与缺字段都视为叶子);展开模型接入后\n // getRowModel() 返回「父行 + 可见子行」的扁平序列,行带 depth/toggleExpanded\n getSubRows: (originalRow) => {\n const children = (originalRow as DataRecord)[childrenKey];\n return Array.isArray(children) ? children : [];\n },\n getExpandedRowModel: getExpandedRowModel(),\n columns: columns.map<ColumnDef<T>>((column) => ({\n accessorKey: column.key,\n header: column.title,\n enableSorting: column.sortable === true,\n })),\n initialState: {\n // 排序从投影初值构造(覆盖 defaultSort 与受控 sort 两种来源)\n sorting: sort.value ? [{ id: sort.value.key, desc: sort.value.direction === \"desc\" }] : [],\n // 初始 pageSize 须进 TanStack(此前只写对外投影,静态模式初始 pageSize≠10 不生效);\n // 受控初值优先(组件层受控 getter 未传时返回 undefined,须防御性取数值配置)\n pagination: {\n pageIndex: Math.max(0, (controlledPageIndex() ?? 1) - 1),\n pageSize: controlledPageSize() ?? numericOption(options.pageSize) ?? 10,\n },\n // defaultExpandAll:true = 全部展开;否则全收起(TanStack expanded 空对象)\n expanded: tree?.defaultExpandAll === true ? true : {},\n },\n getCoreRowModel: getCoreRowModel(),\n getPaginationRowModel: getPaginationRowModel(),\n getSortedRowModel: getSortedRowModel(),\n manualPagination: serverMode,\n manualSorting: serverMode,\n get state() {\n return { rowSelection: rowSelectionState.value };\n },\n enableRowSelection: selectionConfig?.selectable\n ? (row) => selectionConfig.selectable!(row.original)\n : selectionConfig !== undefined,\n enableMultiRowSelection: selectionConfig?.type !== \"radio\",\n onRowSelectionChange: (updater) => {\n const prev = rowSelectionState.value;\n const next = typeof updater === \"function\" ? updater(prev) : updater;\n // radio 且 cancelable: false 时,解绑结果为空集则保持原状\n if (\n selectionConfig?.type === \"radio\" &&\n selectionConfig.cancelable === false &&\n !Object.keys(next).some((key) => next[key])\n ) {\n return;\n }\n applyRowSelection(next);\n },\n });\n\n watch(\n () => table.getState().pagination,\n (pagination) => {\n if (page.pageIndex === pagination.pageIndex + 1 && page.pageSize === pagination.pageSize)\n return;\n page.pageIndex = pagination.pageIndex + 1;\n page.pageSize = pagination.pageSize;\n },\n { immediate: true },\n );\n\n watch(\n () => table.getState().sorting,\n (sorting) => {\n const next: SortableOptions | undefined = sorting[0]\n ? { key: sorting[0].id, direction: sorting[0].desc ? \"desc\" : \"asc\" }\n : undefined;\n // 仅在语义发散时回写:toggleSort 已同步落值,等价对象回写会触发多余的重复加载\n if (sort.value?.key === next?.key && sort.value?.direction === next?.direction) return;\n sort.value = next;\n },\n { immediate: true },\n );\n\n // 静态数据源:ref/getter 会自动跟随;普通数组为快照,可用 reload() 重同步\n function syncData() {\n const data = toValue(options.data);\n if (data !== undefined && !Array.isArray(data)) {\n warn(\"data 必须是数组,已按空表处理。\");\n }\n // 复制出新引用:就地修改同一个普通数组时 shallowRef 不会触发,行模型会停留在旧快照\n rows.value = Array.isArray(data) ? [...data] : [];\n page.total = rows.value.length;\n }\n\n watch(() => toValue(options.data), syncData, { immediate: true });\n\n function setPageIndex(pageIndex: number) {\n table.setPageIndex(Math.max(0, pageIndex - 1));\n }\n\n function setPageSize(pageSize: number) {\n table.setPageSize(pageSize);\n // TanStack 容量变更后停在最后一页(pageCount-1),需回到首页\n table.setPageIndex(0);\n }\n\n /** 排序应用的唯一管线:服务端模式归位第 1 页+ 投影落值 + TanStack setSorting。\n * 受控 sort 的外部同步与此共用(直接 setSorting 会漏服务端重载)\n * @param next - 目标排序(key + direction),undefined 表示取消排序\n */\n function applySort(next: SortableOptions | undefined) {\n // 服务端模式按新排序取数,必须先归位到首页\n if (serverMode && page.pageIndex !== 1) setPageIndex(1);\n // 同步落值:对外投影不能等 watcher(emit 需要立即读到新排序)\n sort.value = next;\n table.setSorting(next ? [{ id: next.key, desc: next.direction === \"desc\" }] : []);\n }\n\n /**\n * 排序三态:无 → asc → desc → 取消;非 sortable 列为空操作\n * @param key - 目标列 key\n */\n function toggleSort(key: string) {\n if (!columns.some((column) => column.key === key && column.sortable === true)) return;\n\n const current = sort.value;\n const direction =\n current?.key !== key ? \"asc\" : current.direction === \"asc\" ? \"desc\" : undefined;\n\n applySort(direction ? { key, direction } : undefined);\n }\n\n /**\n * 页内重排(drag-sort 唯一管线):from/to 为页内 0-based 索引。\n * 静态模式按对象身份定位全量位置后 splice(页内索引 → 全量映射不依赖裸索引 arithmetic,\n * 行对象与 rows.value 同引用);服务端模式 rows.value 即当前页数据,只算新序不落盘。\n * @param from - 源行页内索引\n * @param to - 目标行页内索引(拖拽落位行;源行移除后插入该原位)\n * @returns drag-sort 载荷;守卫不通过或索引无效时 undefined\n */\n function reorderRows(from: number, to: number): TableDragSortPayload<T> | undefined {\n if (!draggableConfig || sort.value !== undefined) return undefined;\n const pageRows = table.getRowModel().rows.map((row) => row.original);\n if (from === to || from < 0 || to < 0 || from >= pageRows.length || to >= pageRows.length) {\n return undefined;\n }\n const record = pageRows[from]!;\n const next = [...pageRows];\n next.splice(from, 1);\n next.splice(to, 0, record);\n if (!serverMode) {\n const all = [...rows.value];\n const target = pageRows[to]!;\n all.splice(all.indexOf(record), 1);\n const targetIndex = all.indexOf(target);\n // 下移插在目标之后、上移插在目标之前(与页内 splice 语义一致)\n all.splice(from < to ? targetIndex + 1 : targetIndex, 0, record);\n rows.value = all;\n }\n return { from, to, record, rows: next };\n }\n\n // 服务端模式:请求序号守卫,乱序返回的旧响应直接丢弃\n let requestId = 0;\n\n async function load() {\n const id = ++requestId;\n loading.value = true;\n // 下一次 load 开始时清除上一次的错误(无论该 load 是否为当前请求)\n error.value = undefined;\n try {\n await options.onLoad?.({\n // 事件/取数时机读取是安全的(form.state 非响应式但同步);浅拷贝避免调用方改写真值\n form: search ? { ...search.form.state.values } : {},\n page: {\n pageIndex: page.pageIndex,\n pageSize: page.pageSize,\n total: page.total,\n pageSizeOpts: page.pageSizeOpts,\n },\n sort: sort.value,\n update: (data, total) => {\n if (id !== requestId) return;\n rows.value = Array.isArray(data) ? data : [];\n // total 缺省时保留旧值\n if (typeof total === \"number\") page.total = total;\n },\n });\n } catch (err) {\n // 乱序旧请求的失败直接丢弃(同款竞态守卫)\n if (id === requestId) {\n const normalized = err instanceof Error ? err : new Error(String(err));\n error.value = normalized;\n console.error(\"[tu-design] <TableRender> onLoad 执行失败:\", normalized);\n }\n } finally {\n if (id === requestId) loading.value = false;\n }\n }\n\n // 服务端模式下分页/排序变化即重取数;同一 tick 内多次变更只触发一次\n watch(\n () => (serverMode ? [page.pageIndex, page.pageSize, sort.value] : null),\n () => {\n void load();\n },\n );\n\n // ---- 受控同步:外部变更 → TanStack -------------------------------------\n // 各 watch 均带语义等值守卫:内部先行(动作已生效)或父回写回弹时跳过,\n // 严禁死循环与重复 onLoad(load watch 绑定投影,投影等值守卫兜底)。\n // pageIndex 受控(1-based;最小归 1)\n watch(controlledPageIndex, (next) => {\n if (next === undefined || page.pageIndex === next) return;\n table.setPageIndex(Math.max(0, next - 1));\n });\n\n // pageSize 受控:同步容量;pageIndex 未受控时保持归位第 1 页(两方都受控由父层联动)\n watch(controlledPageSize, (next) => {\n if (next === undefined || page.pageSize === next) return;\n table.setPageSize(next);\n if (controlledPageIndex() === undefined) table.setPageIndex(0);\n });\n\n // sort 受控:经 applySort 管线(服务端归位 + 重载不漏);不可排序列警告并忽略\n watch(controlledSort, (next) => {\n if (next === undefined && sort.value === undefined) return;\n if (\n next &&\n sort.value &&\n next.key === sort.value.key &&\n next.direction === sort.value.direction\n ) {\n return;\n }\n if (next && !columns.some((c) => c.key === next.key && c.sortable === true)) {\n warn(`sort 受控值指向不可排序列 \"${next.key}\",已忽略。`);\n return;\n }\n applySort(next);\n });\n\n // selectedKeys 受控:经 setSelection 写入(selectable 过滤 / 待定 key 语义继承)\n watch(\n controlledSelectedKeys,\n (next) => {\n if (next === undefined) return;\n const current = selectedKeys.value;\n // 语义等值(内容而非引用):内部勾选先行或父回写回弹时跳过,防 Set 重建触发的事件回环\n if (next.length === current.size && next.every((key) => current.has(key))) return;\n setSelection(next);\n },\n { immediate: true },\n );\n\n // ---- 列显隐(column visibility) -------------------------------------\n // 统一投影:受控初值 > defaultVisibleKeys(拆分式/聚合式) > 全部可见。\n // 列显隐只动本 ref——不触发 onLoad、不重置 pageIndex/sort/selectedKeys。\n let emptyVisibleWarned = false;\n\n /**\n * 规范化:未知 key 静默忽略、按 columns 原序、空数组钳制为首列(warn 一次)\n * @param keys - 目标可见列 key 列表(任意顺序,可含未知 key)\n * @returns 规范化后的可见列 key 列表(columns 原序)\n */\n function normalizeVisibleKeys(keys: readonly string[]): string[] {\n const known = columns.filter((column) => keys.includes(column.key)).map((column) => column.key);\n if (known.length > 0) return known;\n if (columns.length > 0) {\n if (!emptyVisibleWarned) {\n warn(\"可见列不能为空,已钳制为首列可见。\");\n emptyVisibleWarned = true;\n }\n return [columns[0]!.key];\n }\n return [];\n }\n\n function sameVisibleKeys(a: readonly string[], b: readonly string[]): boolean {\n return a.length === b.length && a.every((key, index) => key === b[index]);\n }\n\n const parsedDefaultVisibleKeys = (() => {\n const raw = toValue(options.defaultVisibleKeys) ?? options.columnVisibility?.defaultVisibleKeys;\n return raw ? normalizeVisibleKeys(raw) : undefined;\n })();\n\n const visibleKeysInternal = ref<string[]>(\n controlledVisibleKeys()\n ? normalizeVisibleKeys(controlledVisibleKeys()!)\n : (parsedDefaultVisibleKeys ?? columns.map((column) => column.key)),\n );\n\n /**\n * 列显隐动作(面板交互/程序化):规范化后更新统一投影\n * @param keys - 目标可见列 key 列表\n */\n function setVisibleKeys(keys: string[]) {\n visibleKeysInternal.value = normalizeVisibleKeys(keys);\n }\n\n // visibleKeys 受控:外部变更同步投影(规范化后语义等值跳过,防回弹)\n watch(controlledVisibleKeys, (next) => {\n if (next === undefined) return;\n const normalized = normalizeVisibleKeys(next);\n if (sameVisibleKeys(normalized, visibleKeysInternal.value)) return;\n visibleKeysInternal.value = normalized;\n });\n\n onMounted(() => {\n if (serverMode && (options.autoLoad ?? true)) void load();\n // rowKey 在 defineTable 阶段可能尚未就绪(聚合式由 TableRender 回填),挂载时终审\n if (selectionConfig && !rowKey.value) {\n warn(\"rowSelection 需要有效的 rowKey 字段,已禁用行选择。\");\n }\n });\n\n function reload(resetPage = false) {\n if (serverMode) {\n // 归位由分页 watch 触发重载;页码本就为首页时直接重载(避免双请求)\n if (resetPage && page.pageIndex !== 1) setPageIndex(1);\n else void load();\n return;\n }\n if (resetPage) setPageIndex(1);\n syncData();\n }\n\n // ---- 行选择动作与联动(S 系列) -------------------------------------------\n\n /**\n * 程序化设置选中集;不存在的 key 保留进入 dirtyKeys;不可选行被过滤\n * @param keys - 目标选中行的 key 列表(整体替换现有选中集)\n */\n function setSelection(keys: Array<string | number>) {\n const next: RowSelectionState = {};\n for (const key of keys) {\n const row = selectionSnapshot.get(String(key));\n // 快照中存在的行按 selectable 谓词过滤;待定 key(尚无行对象)无法判定的不拦\n if (row && selectionConfig?.selectable && !selectionConfig.selectable(row)) continue;\n next[String(key)] = true;\n if (!row) dirtyKeys.add(String(key));\n }\n applyRowSelection(next);\n }\n\n function clearSelection() {\n applyRowSelection({});\n }\n\n function toggleRowSelected(key: string, checked: boolean) {\n // radio 且 cancelable: false 时,交互解绑最后一个选中为空操作\n if (!checked && selectionConfig?.type === \"radio\" && selectionConfig.cancelable === false) {\n return;\n }\n if (!checked) {\n const { [key]: _removed, ...rest } = rowSelectionState.value;\n applyRowSelection(rest);\n return;\n }\n // radio:单选互斥;checkbox:累加\n const next =\n selectionConfig?.type === \"radio\"\n ? { [key]: true }\n : { ...rowSelectionState.value, [key]: true };\n applyRowSelection(next);\n }\n\n /**\n * 拆分式装配口:TableRender setup 时回传组件 rowKey\n * @param key - 行主键字段名\n */\n function setRowKey(key: string | undefined) {\n if (rowKey.value === key) return;\n rowKey.value = key;\n // 聚合式下数据窗口早于 rowKey 就绪(pre-flush 先于子组件 setup),补建快照\n refreshSnapshot();\n }\n\n // 数据窗口变化(翻页或数据替换):刷新快照;reserveOnPageChange: false 时清空选中\n watch([rows, () => page.pageIndex], () => {\n refreshSnapshot();\n if (selectionConfig && selectionConfig.reserveOnPageChange === false) clearSelection();\n });\n\n return {\n columns,\n columnTree,\n table,\n page: readonly(page),\n sort: readonly(sort),\n loading: readonly(loading),\n error: readonly(error),\n reload,\n toggleSort,\n setPageIndex,\n setPageSize,\n selection: {\n get value(): T[] {\n return selectionRows.value;\n },\n get enabled(): boolean {\n return selectionEnabled.value;\n },\n get type(): \"radio\" | \"checkbox\" {\n return selectionConfig?.type ?? \"checkbox\";\n },\n get width(): number {\n return selectionConfig?.width ?? 48;\n },\n },\n selectedKeys: selectedKeys as Readonly<Ref<Set<string | number>>>,\n setSelection,\n clearSelection,\n toggleRowSelected,\n // getter 而非快照:setSearch 由 TableRender 在 setup 回填,读取须反映最新值\n get search() {\n return search;\n },\n setSearch,\n // 纯配置透传(渲染层消费;不支持运行时切换)\n virtual: options.virtual,\n height: options.height,\n tree,\n draggable: draggableConfig,\n reorderRows,\n // 列显隐:统一投影 + 动作 + 重置基准\n visibleKeys: readonly(visibleKeysInternal),\n setVisibleKeys,\n defaultVisibleKeys: parsedDefaultVisibleKeys,\n columnVisibility: options.columnVisibility,\n setRowKey,\n };\n}\n"
|
|
90
103
|
}
|
|
91
104
|
]
|
|
92
105
|
}
|