# web-admin 列表表体内嵌滚动(视口填满)Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 让 web-admin 主列表在视口内表体内嵌滚动:表头固定、横滚条贴在表体可视区底,分页始终可见且距内容区底 10px。 **Architecture:** 抽出纯函数 `calcListTableViewportHeight`;composable `useListTableViewportHeight` 测量 `#app-content` 底、表顶、分页高并绑定 `ListTable`/`el-table` 的 `:height`;先接模板页与 bx 样板,再文档/OpenSpec,最后按模块批推。 **Tech Stack:** Vue 3 · `@vueuse/core` · Element Plus `el-table` height · TypeScript · `tsx` 脚本单测 **Spec:** `docs/superpowers/specs/2026-09-01-web-admin-list-table-viewport-scroll-design.md` **Demo:** `docs/list-table-scroll-demo.html` --- ## File map | File | Responsibility | |------|----------------| | `web-admin/src/composables/listTableViewportHeight.ts` | 纯函数:高度公式 + 默认常量 | | `web-admin/scripts/check-list-table-viewport-height.ts` | 无浏览器依赖的公式断言(tsx) | | `web-admin/src/composables/useListTableViewportHeight.ts` | 测量 DOM、resize/观察、返回 `tableHeight` + `recalc` | | `web-admin/src/views/demo/unit/index.vue` | 模板样板页接入 | | `web-admin/src/views/bx/reimburse/apply/index.vue` | ListTable + wrap 样板接入 | | `web-admin/src/styles/bx/index.scss` | 澄清 `.table-scroll` 与 EP height 模式不双滚 | | `docs/web-admin-ui-spec-fresh-mint.md` §7.6 | 规范改为视口填满策略 | | `docs/list-table-scroll-demo.html` | Demo 文案对齐「分页下 10px」 | | `openspec/.../ui-conventions/spec.md` | 新增 SHALL | | 后续批处理列表页 | 同构接入(Task 6 清单) | --- ### Task 1: 纯函数高度公式 + 脚本单测 **Files:** - Create: `web-admin/src/composables/listTableViewportHeight.ts` - Create: `web-admin/scripts/check-list-table-viewport-height.ts` - [ ] **Step 1: 写失败断言脚本(文件尚不存在时应无法通过)** 创建 `web-admin/scripts/check-list-table-viewport-height.ts`: ```ts import assert from 'node:assert/strict' import { LIST_TABLE_VIEWPORT_BOTTOM_GAP, LIST_TABLE_VIEWPORT_MIN_HEIGHT, calcListTableViewportHeight } from '../src/composables/listTableViewportHeight' assert.equal(LIST_TABLE_VIEWPORT_BOTTOM_GAP, 10) assert.equal(LIST_TABLE_VIEWPORT_MIN_HEIGHT, 240) // contentBottom=1000, tableTop=200, pager=48 → 1000-200-48-10 = 742 assert.equal( calcListTableViewportHeight({ contentViewportBottom: 1000, tableTop: 200, pagerHeight: 48 }), 742 ) // 无分页 assert.equal( calcListTableViewportHeight({ contentViewportBottom: 800, tableTop: 100, pagerHeight: 0 }), 690 ) // 过矮时夹到 minHeight assert.equal( calcListTableViewportHeight({ contentViewportBottom: 400, tableTop: 300, pagerHeight: 48, minHeight: 240, bottomGap: 10 }), 240 ) // 自定义 min / gap assert.equal( calcListTableViewportHeight({ contentViewportBottom: 1000, tableTop: 100, pagerHeight: 40, minHeight: 100, bottomGap: 16 }), 844 ) console.log('check-list-table-viewport-height: ok') ``` - [ ] **Step 2: 跑脚本确认失败** Run: ```bash cd web-admin && pnpm exec tsx scripts/check-list-table-viewport-height.ts ``` Expected: 失败(模块不存在 / 无法解析) - [ ] **Step 3: 实现纯函数** 创建 `web-admin/src/composables/listTableViewportHeight.ts`: ```ts /** 分页底边到内容区底的默认空隙(px) */ export const LIST_TABLE_VIEWPORT_BOTTOM_GAP = 10 /** 表体动态高度下限(px),避免筛选展开时表被压没 */ export const LIST_TABLE_VIEWPORT_MIN_HEIGHT = 240 export type CalcListTableViewportHeightInput = { /** 主内容滚动容器可视底边(如 #app-content.getBoundingClientRect().bottom) */ contentViewportBottom: number /** 表格锚点顶边(同坐标系,通常 getBoundingClientRect().top) */ tableTop: number /** 分页条实际高度;无分页传 0 */ pagerHeight: number minHeight?: number bottomGap?: number } /** * 计算列表表体应设置的 height,使「表 + 分页」落在内容视口内,且分页下方留 bottomGap。 * tableHeight = floor(contentBottom - tableTop - pagerHeight - bottomGap),再与 minHeight 取大。 */ export function calcListTableViewportHeight( input: CalcListTableViewportHeightInput ): number { const minHeight = input.minHeight ?? LIST_TABLE_VIEWPORT_MIN_HEIGHT const bottomGap = input.bottomGap ?? LIST_TABLE_VIEWPORT_BOTTOM_GAP const raw = Math.floor( input.contentViewportBottom - input.tableTop - input.pagerHeight - bottomGap ) if (!Number.isFinite(raw)) return minHeight return Math.max(raw, minHeight) } ``` - [ ] **Step 4: 再跑脚本确认通过** Run: ```bash cd web-admin && pnpm exec tsx scripts/check-list-table-viewport-height.ts ``` Expected: 打印 `check-list-table-viewport-height: ok` - [ ] **Step 5: Commit** ```bash git add web-admin/src/composables/listTableViewportHeight.ts \ web-admin/scripts/check-list-table-viewport-height.ts git commit -m "$(cat <<'EOF' feat(web-admin): add list table viewport height formula Pure calc keeps pagination visible with a 10px bottom gap for main list scroll UX. EOF )" ``` --- ### Task 2: composable `useListTableViewportHeight` **Files:** - Create: `web-admin/src/composables/useListTableViewportHeight.ts` - [ ] **Step 1: 实现 composable** 创建 `web-admin/src/composables/useListTableViewportHeight.ts`: ```ts import { nextTick, onBeforeUnmount, onMounted, ref, unref, watch, type Ref } from 'vue' import { useEventListener, useResizeObserver } from '@vueuse/core' import { LIST_TABLE_VIEWPORT_BOTTOM_GAP, LIST_TABLE_VIEWPORT_MIN_HEIGHT, calcListTableViewportHeight } from '@/composables/listTableViewportHeight' export type UseListTableViewportHeightOptions = { /** 表格锚点(包住 ListTable/el-table 的元素,不含分页) */ tableEl: Ref | (() => HTMLElement | null | undefined) /** 分页条根节点;无分页可省略 */ pagerEl?: Ref | (() => HTMLElement | null | undefined) /** 可选:ListTable / el-table 组件实例,高度变化后调用 doLayout */ tableRef?: Ref minHeight?: number bottomGap?: number /** 主内容滚动根;默认 #app-content */ scrollRootSelector?: string /** 为 false 时不自动监听(隐藏 Tab 可用) */ enabled?: Ref | boolean } function resolveEl( source?: Ref | (() => HTMLElement | null | undefined) ): HTMLElement | null { if (!source) return null if (typeof source === 'function') return source() ?? null return unref(source) ?? null } export function useListTableViewportHeight(options: UseListTableViewportHeightOptions) { const tableHeight = ref(LIST_TABLE_VIEWPORT_MIN_HEIGHT) const minHeight = options.minHeight ?? LIST_TABLE_VIEWPORT_MIN_HEIGHT const bottomGap = options.bottomGap ?? LIST_TABLE_VIEWPORT_BOTTOM_GAP const scrollRootSelector = options.scrollRootSelector ?? '#app-content' const isEnabled = () => { const e = options.enabled if (e === undefined) return true return !!unref(e) } const recalc = () => { if (!isEnabled()) return if (typeof window === 'undefined') return const table = resolveEl(options.tableEl) if (!table) return const root = (document.querySelector(scrollRootSelector) as HTMLElement | null) ?? null const contentViewportBottom = root ? root.getBoundingClientRect().bottom : window.innerHeight const tableTop = table.getBoundingClientRect().top const pager = resolveEl(options.pagerEl) const pagerHeight = pager ? Math.ceil(pager.getBoundingClientRect().height) : 0 const next = calcListTableViewportHeight({ contentViewportBottom, tableTop, pagerHeight, minHeight, bottomGap }) if (next !== tableHeight.value) { tableHeight.value = next } nextTick(() => { const inst = options.tableRef ? unref(options.tableRef) : null if (inst && typeof inst.doLayout === 'function') { inst.doLayout() } }) } let raf = 0 const scheduleRecalc = () => { if (raf) cancelAnimationFrame(raf) raf = requestAnimationFrame(() => { raf = 0 recalc() }) } onMounted(() => { nextTick(scheduleRecalc) }) onBeforeUnmount(() => { if (raf) cancelAnimationFrame(raf) }) useEventListener(window, 'resize', scheduleRecalc) // 观察表锚点与分页尺寸变化(筛选展开会改变 tableTop) useResizeObserver( () => resolveEl(options.tableEl), () => scheduleRecalc() ) useResizeObserver( () => resolveEl(options.pagerEl), () => scheduleRecalc() ) useResizeObserver( () => document.querySelector(scrollRootSelector) as HTMLElement | null, () => scheduleRecalc() ) if (options.enabled !== undefined && typeof options.enabled !== 'boolean') { watch(options.enabled, () => scheduleRecalc()) } return { tableHeight, recalc: scheduleRecalc } } ``` - [ ] **Step 2: 类型检查(抽查无报错)** Run: ```bash cd web-admin && pnpm exec vue-tsc --noEmit 2>&1 | head -n 40 ``` Expected: 与本次新文件相关无新增错误(若仓库已有历史错误,确认不含 `useListTableViewportHeight` / `listTableViewportHeight`) - [ ] **Step 3: Commit** ```bash git add web-admin/src/composables/useListTableViewportHeight.ts git commit -m "$(cat <<'EOF' feat(web-admin): add useListTableViewportHeight composable Measure content viewport, table top, and pager to drive el-table height. EOF )" ``` --- ### Task 3: 接入模板样板页 `demo/unit` **Files:** - Modify: `web-admin/src/views/demo/unit/index.vue` - [ ] **Step 1: 模板增加锚点 ref,绑定 height** 在 `list-body` 内,用 wrap 只包住表格(分页保持为兄弟节点)。将: ```vue