模板库卡片列表接入虚拟滚动

- 用 workspace 已有的 react-window@1.8.11 的 FixedSizeGrid：只渲染可视行 + 2 行 overscan，1000 条不再一次性挂 1000 个卡片节点 - 新增 templateLibraryGrid.ts 纯函数布局契约（列数/列宽/行高/行数/按行切分），单测覆盖 - 卡片抽成 memo 化的 TemplateCard；筛选条件变化时把滚动位置复位到顶部 - 筛选区（运行时/标签）改为可独立滚动区块，标签膨胀不再挤压卡片区 - 页面回归改用固定视口：断言 1000 条只渲染 ≤40 张卡、滚动高度按 250 行计算 - 技术方案补虚拟滚动契约说明
2026-09-17 16:36:04 +08:00
parent 19e9dea45c
commit 066d0fe6f9
8 changed files with 573 additions and 152 deletions
@@ -97,6 +97,14 @@ AGC_TEMPLATE_LIBRARY_SYNTHETIC_COUNT=300 AGC_DEV_CARGO_FEATURES=template-library

 ### 1000 条实测结论

+### 卡片列表虚拟滚动（react-window）
+
+- 列表改用 workspace 里已有的 `react-window@1.8.11` 的 `FixedSizeGrid`（`react-arborist` 已在用同一版本，不引入新包；类型来自 devDependency `@types/react-window`）。
+- 布局契约收在纯函数 `templateLibraryGrid.ts`（单测覆盖）：列数 = `floor((容器宽 + gap) / (最小卡宽 + gap))`、列宽 = 容器宽 / 列数、行高 = `卡片宽 × 9/16 + 文字区 150 + gap`；`buildTemplateRows` 按行切分并在行尾补 `null` 占位。
+- 卡片抽成 `TemplateCard`（`memo`），网格只渲染可视行 + 2 行 overscan；筛选条件（关键词/标签/运行时/仅看已下载）变化时把滚动位置复位到顶部，避免"从筛选切回全量后停在空白处"。
+- 筛选区（运行时/标签）改成可独立滚动的区块（`max-h-[24vh]`），标签数量随库量增长时不再把卡片区挤出窗口。
+- 回归：`templateLibraryGrid.test.ts` 覆盖列数/行高/行数/切行；页面测试用固定视口断言「1000 条只渲染 ≤ 40 张卡片，滚动高度仍按 250 行计算」。
+
 - 页面能正常渲染 1000 张卡片（头部显示「共 1000 个模板 · 已下载 335 个」），并且滚动容器生效（窗口高度压到 430px 时右侧出现滚动条，页面内容被裁切而不是溢出到窗口外）。
 - 需要后续收口的两点（本次未改）：① 标签筛选条随库量膨胀——1000 条时聚合出 35 个标签、占三行；② 一次性渲染 1000 个卡片节点并触发 1000 次封面请求。建议标签只展示 Top N + 「更多」，卡片列表加分页或虚拟滚动。
 - 前端回归：1000 条渲染 + 已安装过滤（334）/标签过滤（50）/关键词过滤数量自洽，见 `apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx`。