diff --git a/docs/UpperTable-大列表滚动性能优化方案.md b/docs/UpperTable-大列表滚动性能优化方案.md new file mode 100644 index 00000000..522cbee2 --- /dev/null +++ b/docs/UpperTable-大列表滚动性能优化方案.md @@ -0,0 +1,201 @@ +# UpperTable 大列表滚动性能优化方案 + +> 状态:方案评审中(未实施) +> 日期:2026-08-28 +> 组件:`src/components/UpperTable/index.vue` +> 涉及页面:订单管理、波次管理(waveOrder)等所有使用 UpperTable 的大数据列表 + +--- + +## 1. 背景与问题 + +列表在展示大量数据(如每页 200~500 条)时,**滚动查看存在明显视觉卡顿**,用户反馈"用起来不舒服"。 + +**关键现象**:任务管理器 / 性能面板显示 **CPU 与内存占用并不高**,但滚动时画面明显掉帧、卡顿。这说明问题**不在 JS 计算密集度,而在渲染管线与组件渲染规模**,需要针对"滚动时主线程被长任务阻塞"这一根因定位。 + +## 2. 现状分析 + +### 2.1 UpperTable 已具备的能力 + +| 能力 | 说明 | +|---|---| +| 行级虚拟滚动 | `virtualThreshold=80` 时启用,仅渲染可视窗口行 + 缓冲行(`virtualBufferRows=12`),上下用 spacer 行撑高 | +| 滚动驱动 | 监听 `.el-scrollbar__wrap` 的 scroll 事件(rAF 节流),更新 `virtualScrollTop` 后重算渲染窗口 | +| 列配置 | `enableColumnConfig` + `tableId` 支持用户自定义列显示/排序/固定,配置存 localStorage | +| 服务端分页 | 各页面通过 `pagination` 驱动,pageSize 可到 200/500 | + +### 2.2 虚拟滚动实现方式(关键) + +当前为 **"spacer 撑高 + 窗口替换"** 模式: + +``` +tableRenderData = [顶部spacer(高=startIndex*行高)] + [可视窗口行] + [底部spacer] +``` + +- 行高按 `tableSize` **硬编码假设**:large=49 / default=41 / small=33 +- 滚动时通过**替换渲染的行集合**来更新可视窗口 +- 无 transform 位移跟随、无 `will-change` / `contain` 合成层优化 + +### 2.3 各页面使用情况(以实测页面为例) + +- **订单管理 - 待处理订单**:35 列,每页最多 500 条 +- **波次管理 - 团购波次**:22 列 + 左/右固定列(波次号 left、操作 right)+ 选择列 + +## 3. 实测诊断数据(DevTools 实测,待处理订单页) + +### 3.1 表格规模与组件数量 + +| 指标 | 值 | +|---|---| +| 总列数 | 35 | +| 总数据量 | 约 515 行(滚动高度 17016px ÷ 33px 行高)| +| 虚拟滚动渲染行数 | 43 行(可视 ~19 + 缓冲 24)——**虚拟滚动正常生效** | +| 单元格总数 | 43 × 35 = **1505 个** | +| **el-tag 组件** | **440 个**(同步/复核/储位/快递/打印/拣货/打包/拦截/锁定 等状态列)| +| **el-tooltip 组件** | **1540 个**(`show-overflow-tooltip` 对全列默认开启)| +| 固定列 | 无(此页)| + +### 3.2 滚动性能实测 + +| 测试 | 平均耗时 | 最大耗时 | +|---|---|---| +| 单步滚动 20px(**不跨行**,窗口不变)| **141ms** | 304ms | +| 单步滚动 100px(跨行)| **144ms** | 253ms | + +> 帧预算为 16.7ms,实测每次滚动卡 141~860ms,是帧预算的 **8~50 倍**。 + +### 3.3 长任务分析(决定性证据) + +1.5 秒连续滚动,`PerformanceObserver` 捕获 longtask: + +``` +7 个长任务,总阻塞 2785ms,单个最长 862ms(全部为 self 页面脚本) +``` + +### 3.4 结论:根因不是 paint,而是 JS 组件树过重 + +| 证据 | 指向 | +|---|---| +| 长任务全部为 `self` 脚本,且高达 862ms | JS 逻辑/组件渲染,**非** paint/composite | +| **不跨行滚动(20px)同样卡 141ms** | 卡顿不来自虚拟滚动"窗口替换",而来自 el-table 每次滚动都要驱动大量组件更新 | +| 虚拟滚动已将行数降至 43,但仍卡 | 每行 35 列 × 每列 tooltip + 状态列 tag = **43 行也要 diff 1505 单元格 / 约 1980 个组件** | + +**为什么 CPU 不高却卡**:不是持续高占用,而是**滚动瞬间的渲染尖峰**(700ms+ 长任务阻塞主线程 → 掉帧)。CPU 平均占用不高,但瞬时峰值阻塞了渲染。 + +## 4. 根因排序 + +| 优先级 | 根因 | 影响 | +|---|---|---| +| ★★★ | `show-overflow-tooltip` 全列默认开启 → **每单元格一个 el-tooltip 组件(1540 个)** | 组件树最大头,滚动时 diff 成本极高 | +| ★★★ | 状态列大量使用 `el-tag`(440 个)| 第二大组件源 | +| ★★☆ | 列数过多(订单管理 35 列)| 线性放大所有成本 | +| ★★☆ | 虚拟滚动"窗口替换"式重渲染(无 transform 位移)| 滚动跨行时整块重渲染 | +| ★☆☆ | 行高硬编码假设,可能与实际不符(如操作列按钮换行)| 内容跳变/错位 | +| ★☆☆ | 固定列复制表(waveOrder 页)| paint 面积放大,属次要叠加 | + +## 5. 优化方案(按收益/成本排序) + +### 方案 ①:收窄 `show-overflow-tooltip`(P0,最优先) + +**目标**:把 1540 个 tooltip 组件降为几十个。 + +**做法**: +- `UpperTable` 默认值从"全列开启"改为"默认关闭,仅按需开启" +- 在 `UpperTable/index.vue` 中调整 `:show-overflow-tooltip` 的默认判定 +- 各页面列配置只对**需要看全内容的列**显式开启(如订单号、物流单号、买家留言、商品快照等) + +**预期收益**:组件树规模降一个量级,滚动重渲染成本显著下降。这是**成本最低、收益最大**的一步。 + +**改动范围**: +- `src/components/UpperTable/index.vue`(默认值逻辑) +- 各页面 `columns` 配置(订单管理、波次管理等,按需显式开启) + +### 方案 ②:状态列 `el-tag` → 纯文本 + CSS 颜色(P0) + +**目标**:把 440 个 el-tag 组件降为文本节点。 + +**做法**: +- 状态列(同步/复核/储位/快递/打印/拣货/打包/拦截/锁定 等)由 `` 改为 `` + 状态色 class +- 保留视觉区分(颜色圆点/着色文字),不损失可读性 + +**预期收益**:440 个组件 → 0,进一步降低组件树。 + +**注意**:涉及多个页面模板,改动面较广,需逐页确认状态色映射。 + +### 方案 ③:虚拟滚动改造为 transform 位移模式(P1) + +**目标**:减少"窗口替换"式整块重渲染,滚动更平滑。 + +**做法**(业界标准做法,react-window / vue-virtual-scroller 原理): +- 保持固定行窗口,用 `transform: translateY(offset)` 让内容连续跟随滚动条 +- 仅在越过行边界时替换窗口,并用 transform 补平偏移,消除跳变 +- 可选加 `will-change: transform` / `contain` 合成层优化 + +**预期收益**:滚动跨行时不再整块重渲染;配合 ①② 后接近原生滚动体验。 + +**风险**:改动 `UpperTable` 内部核心,需回归测试列配置/选择/拖拽等功能。 + +### 方案 ④:默认列数收敛(P1) + +**目标**:减少列数 = 线性减少组件与重渲染成本。 + +**做法**:利用现有"字段设置"能力,把 35 列的大表**默认只显示核心列**,用户按需自行开启更多列。 + +**预期收益**:不改变功能,但显著降低默认渲染成本。 + +### 方案 ⑤:长期评估 `el-table-v2`(P2) + +**做法**:Element Plus 官方虚拟表格,自带高效渲染与固定列支持;逐步替换 `UpperTable` 内部实现。 + +**成本**:高(需适配列配置/选择/拖拽等既有能力),仅在前述方案仍不足时考虑。 + +## 6. 实施建议与验证 + +### 6.1 建议顺序 + +``` +第一步:方案①(收窄 tooltip)—— 小改动,验证根因 + ↓ 浏览器实测:滚动长任务是否从 700ms 级降到几十 ms +第二步:方案②(el-tag 文本化)—— 进一步降组件树 + ↓ 复测 +第三步:方案③(transform 位移虚拟化) +第四步:方案④(默认列收敛,可随时做) +``` + +### 6.2 验证方法(DevTools) + +1. Performance 面板录制滚动过程 +2. 查看 `PerformanceObserver` 的 longtask:**目标是滚动时无 >50ms 长任务** +3. 单步滚动耗时:**目标从 141ms 降到 <30ms** +4. 配合 `Rendering → Paint Flashing` 确认 paint 范围(waveOrder 固定列页) + +### 6.3 复测工具(可在浏览器 Console 执行) + +```js +// 长任务监控 +const longtasks = []; +const obs = new PerformanceObserver(list => { + for (const e of list.getEntries()) longtasks.push(Math.round(e.duration)); +}); +obs.observe({ entryTypes: ['longtask'] }); +// 滚动 1.5s 后查看 +// obs.disconnect(); console.log(longtasks); +``` + +## 7. 风险与注意事项 + +1. **tooltip 收窄的影响**:`show-overflow-tooltip` 关闭后,超长内容不再自动显示 tooltip 提示。需对关键列(订单号/留言/商品快照等)显式保留,避免信息不可见。 +2. **el-tag 文本化**:需保持状态色的可读性,避免用户混淆。 +3. **虚拟滚动改造**(方案③)影响面大,必须回归: + - 行选择/全选、行点击高亮 + - 列配置(拖拽排序、固定、显示/隐藏) + - 复制按钮、二维码、tooltip 交互 + - 分页切换、数据刷新后的滚动位置 +4. **行高**:方案③ 之前建议先锁定行高(操作按钮禁止换行、单元格单行),否则 transform 位移会错位。 +5. **waveOrder 固定列页**:固定列复制表是独立 paint 层,若 ①② 之后仍有卡顿,再单独评估减少固定列或 content-visibility。 + +## 8. 参考资料 + +- 组件:`src/components/UpperTable/index.vue` +- 页面示例:`src/views/order/orderManagement/`、`src/views/order/waveOrder/` +- 列配置示例:`src/views/order/waveOrder/config/wave-config.ts` diff --git a/src/api/order/order.ts b/src/api/order/order.ts index fff747c7..dbf8e76b 100644 --- a/src/api/order/order.ts +++ b/src/api/order/order.ts @@ -29,6 +29,8 @@ export type WaveBatchListWhere = { express_assignment_status?: 'unassigned' | 'partially_assigned' | 'assigned' /** 英文枚举:unprinted | partially_printed | printed */ print_assignment_status?: 'unprinted' | 'partially_printed' | 'printed' + /** 英文枚举:unpicked | partially_picked | picked */ + pick_assignment_status?: 'unpicked' | 'partially_picked' | 'picked' /** 中文:未分配 | 部分分配 | 已分配 */ storage_assignment_status?: string /** 0 普通波次,1 管理后台策略任务,2 PDA 策略任务 */ diff --git a/src/components/BatchReceivingPrintDialog.vue b/src/components/BatchReceivingPrintDialog.vue index 8134b116..24000b2f 100644 --- a/src/components/BatchReceivingPrintDialog.vue +++ b/src/components/BatchReceivingPrintDialog.vue @@ -39,6 +39,21 @@ + + 距底部留白(mm) + +
- {{ field.label }} +
{ + const rows: any[] = Array.isArray(table.rows) ? table.rows : [] + for (const r of rows) { + const f = Number(r.fontSize) + if (Number.isFinite(f) && f > 0) return f + } + return 0 + })() + const cellFontSizeMm = + options.cellFontSizeMm ?? (tableRowFontSizePt > 0 ? tableRowFontSizePt * 0.3528 : 3) - // 截止线:参数优先;否则取表格之后最近的 text 元素 top(如备注位置) + // 截止线(表格下方切割位置): + // 1) cutlineTop 参数优先; + // 2) 其次 bottomMargin(距页面底部留白,cutlineTop = page_height - bottomMargin,供用户手动调整); + // 3) 否则取表格之后最近的 text 元素 top(如备注位置),无则回退为 table 自身高度。 const optionCutline = options.cutlineTop + const pageHeight = Number(template?.page_height) || 210 let cutlineTop: number - if (optionCutline === undefined || optionCutline === null) { + if (optionCutline !== undefined && optionCutline !== null) { + cutlineTop = optionCutline + } else if (options.bottomMargin !== undefined && options.bottomMargin !== null) { + cutlineTop = pageHeight - options.bottomMargin + } else { const afterTexts = content .filter(el => el !== table && el?.type === 'text' && Number(el.top) > tableTop) .map(el => Number(el.top)) .filter(n => Number.isFinite(n)) .sort((a, b) => a - b) cutlineTop = afterTexts.length > 0 ? (afterTexts[0] as number) : tableTop + (Number(table.height) || 75) - } else { - cutlineTop = optionCutline } - const usableH = cutlineTop - tableTop - headerH - - // 第一遍:按实际行高动态切分(不按固定行数) - const pageRowSets: any[][] = [] - let curRows: any[] = [] - let curH = 0 - for (const detail of details) { - const rowH = estimateRowHeight(detail, table, cellFontSizeMm, perLineHeight) - if (curRows.length > 0 && curH + rowH > usableH) { - pageRowSets.push(curRows) - curRows = [] - curH = 0 + // 「距底部留白(bottomMargin)」以页面模板底边(page_height)为参照:bottomMargin=0 时表格可用到页面底边, + // 用户可参照底边向上调整留白值,使表格上移直到不再遮挡底部元素(页码/备注/签名等)。 + // 这样不依赖任何模板特有参数,不同模板设计、不同页面尺寸都通用。 + /** 根据截止线计算表格可用高度(含防御:截止线过小时回退为距页面底部 20mm 留白) */ + const computeUsableH = (cut: number) => { + let h = cut - tableTop - headerH + if (h < perLineHeight * 2) { + h = pageHeight - 20 - tableTop - headerH } - curRows.push(detail) - curH += rowH + return Math.max(perLineHeight, h) } - if (curRows.length > 0 || pageRowSets.length === 0) { - pageRowSets.push(curRows) + + /** 按可用高度动态切分明细(不按固定行数) */ + const splitRows = (usableHeight: number) => { + const sets: any[][] = [] + let cur: any[] = [] + let curH = 0 + for (const detail of details) { + const rowH = estimateRowHeight(detail, table, cellFontSizeMm, perLineHeight) + if (cur.length > 0 && curH + rowH > usableHeight) { + sets.push(cur) + cur = [] + curH = 0 + } + cur.push(detail) + curH += rowH + } + if (cur.length > 0 || sets.length === 0) { + sets.push(cur) + } + return sets } + // 按「截止线(= 页面底边 - bottomMargin)」切分;bottomMargin=0 时表格可延伸到页面底边 + const pageRowSets = splitRows(computeUsableH(cutlineTop)) + // 第二遍:生成每页模板内容与数据 const total = pageRowSets.length const result: PrintPageItem[] = [] diff --git a/src/views/order/orderManagement/config/order-common-config.ts b/src/views/order/orderManagement/config/order-common-config.ts index 80841e6e..24e81829 100644 --- a/src/views/order/orderManagement/config/order-common-config.ts +++ b/src/views/order/orderManagement/config/order-common-config.ts @@ -714,6 +714,20 @@ function lookupTranslationTable(table: Record | undefined, field return undefined } +/** 将 el-tag 的 type 映射为轻量状态文本的颜色 class(方案②:减少 el-tag 组件,提升大列表滚动性能) */ +export function getStatusTextClass(tagType?: string) { + const t = String(tagType || 'info') + const map: Record = { + primary: 'ut-status-text--primary', + success: 'ut-status-text--success', + warning: 'ut-status-text--warning', + info: 'ut-status-text--info', + danger: 'ut-status-text--danger', + error: 'ut-status-text--danger' + } + return `ut-status-text ${map[t] || 'ut-status-text--info'}` +} + export function getTagType(field: string, value: any) { if (field === 'is_urgency') { const y = normalizeUrgencyValue(value) @@ -1752,7 +1766,7 @@ export const reviewColums = applyOrderListCopyActions([ { prop: 'delivery_order_code', label: '发货单号', width: '170' }, { prop: 'wave_no', label: '波次号', width: '170' }, { prop: 'order_flag', label: '订单标记', minWidth: '260' }, - { prop: 'shop_nick', label: '店铺名称', width: '140' }, + { prop: 'shop_nick', label: '店铺名称', width: '140', showOverflowTooltip: true }, orderStoreRemarkColumn, { prop: 'sys_platform_name', label: '平台编码', width: '100' }, { prop: 'source_order_codes', label: '平台交易单号', width: '140' }, @@ -1922,16 +1936,16 @@ export const pendingAvailableFields = [ export const pendingCloums = [ { prop: 'id', label: '订单ID', width: '80' }, orderWaveIndexColumn, - { prop: 'delivery_order_code', label: '外部订单号', width: '170' ,fixed: 'left'}, - { prop: 'wave_no', label: '波次号', width: '170' }, + { prop: 'delivery_order_code', label: '外部订单号', width: '170', fixed: 'left', showOverflowTooltip: true }, + { prop: 'wave_no', label: '波次号', width: '170', showOverflowTooltip: true }, { prop: 'order_flag', label: '订单标记', minWidth: '260' }, - { prop: 'shop_nick', label: '店铺名称', width: '140' }, + { prop: 'shop_nick', label: '店铺名称', width: '140', showOverflowTooltip: true }, orderStoreRemarkColumn, { prop: 'sys_platform_name', label: '平台编码', width: '100' }, { prop: 'name', label: '收件人', width: '110' }, { prop: 'mobile', label: '电话', width: '120' }, { prop: 'buyer_message', label: '买家留言', minWidth: '180' }, - { prop: 'seller_message', label: '卖家留言', minWidth: '180' }, + { prop: 'seller_message', label: '卖家留言', minWidth: '180', showOverflowTooltip: true }, { prop: 'is_urgency', label: '是否紧急', width: '100' }, { prop: 'sync_status', label: '同步状态', width: '100' }, { prop: 'storage_status', label: '储位状态', width: '100' }, @@ -1940,7 +1954,7 @@ export const pendingCloums = [ { prop: 'pack_status', label: '打包状态', width: '100' }, { prop: 'intercept_status', label: '拦截状态', width: '100', tag: true }, { prop: 'lock_status', label: '锁定状态', width: '100' }, - { prop: 'express_numbers', label: '快递单号', width: '160', formatter: waybillCodesFormatter }, + { prop: 'express_numbers', label: '快递单号', width: '160', formatter: waybillCodesFormatter, showOverflowTooltip: true }, { prop: 'items_count', label: '商品种类', width: '100' }, { prop: 'items_total', label: '商品总数', width: '100' }, { prop: 'items_weight', label: '商品重量(g)', width: '110' }, @@ -1949,9 +1963,9 @@ export const pendingCloums = [ { prop: 'pay_time', label: '支付时间', width: '160', formatter: orderTimeFormatter }, { prop: 'place_order_time', label: '下单时间', width: '165', formatter: orderTimeFormatter }, { prop: 'create_channel', label: '来源', width: '120' }, - { prop: 'source_order_codes', label: '平台交易单号', width: '140' }, + { prop: 'source_order_codes', label: '平台交易单号', width: '140', showOverflowTooltip: true }, { prop: 'logistics_name', label: '快递', width: '120' }, - { prop: 'remark', label: '留言', width: '160' }, + { prop: 'remark', label: '留言', width: '160', showOverflowTooltip: true }, ] /** 列表字段显示名(以待处理订单 pendingCloums 为准,含动态插入列) */ diff --git a/src/views/order/orderManagement/pendingOrder.vue b/src/views/order/orderManagement/pendingOrder.vue index 3baecfa0..549c5425 100644 --- a/src/views/order/orderManagement/pendingOrder.vue +++ b/src/views/order/orderManagement/pendingOrder.vue @@ -58,66 +58,63 @@ @selection-change="onSelectionChange" >