跳转至

列表窗口化架构

契约概览

领域 契约
治理契约 无。每个使用方的记录负责人们在长列表中看到和听到的内容;本记录只负责由哪个模块计算窗口。
系统行为 Core 中有一个共享的内部窗口化模块负责长列表窗口化。该模块不是公共 API(INV1、INV2)。
最终用户影响 长 Table 通过该模块进行窗口化。Selector 渲染每个选项、Chat 渲染每条消息,直到它们采用该模块;此后每个窗口化列表的行为都相同。
构建者影响 需要窗口化长列表的 Core 组件应调用这一个模块,而不是自行构建。在 OQ1 开放期间,不存在公共窗口化 hook。
兼容性/就绪状态 增量且内部。模块位于 packages/core/src/virtualization/(当前状态影响)。Table 已获批准的虚拟化 hook 保持其公共形态。
审查检查 拒绝 Core 中出现第二个窗口化实现、模块的公共导出,或为采用该模块而改变 Table 的公共虚拟化形态。
治理规则 DEC-1。

此表是审查投影;下文正文具有权威性。

目的

Core 中的长列表只渲染人们可以看到的行。本记录为这项工作指定一个唯一负责人,从而使每个需要窗口化列表的组件共享一个实现,而不是各自维护自己的实现。

系统模型

窗口化列表渲染覆盖其可见滚动视口的行,外加每侧边缘之外的少量行,并将其滚动范围设置为完整列表的大小。共享窗口化模块计算渲染哪些行以及滚动范围在何处结束。每个使用方各自记录其窗口化时机、渲染内容,以及如何向辅助技术暴露完整列表。

该模块可在任一滚动轴上对列表进行窗口化。在块轴上,所有行共享同一间距。在行内轴上,每个项目有自己的宽度。使用方指定其固定项目在每侧边缘所覆盖的视口空间,模块只为它们之间的空间进行规划。模块将行内滚动位置读取为距行内起点的距离,因此从右到左的列表也以相同方式窗口化。在两个轴上,一个共享的焦点岛将焦点项目保持挂在窗口之外。

使用方:

  • Table 的行虚拟化,由 module:Table/useTableRowsVirtualization 提供。
  • Table 的列虚拟化,由 module:Table/useTableColumnsVirtualization 提供,作用于行内轴。
  • Selector 的选项列表。
  • Chat 的消息列表。

边界与不变量

  • INV1 — Core 中只有一个窗口化模块。 在 @astryxdesign/core 中,一个共享的内部模块负责长列表窗口化。需要窗口化长列表的组件使用该模块,且不保留自己的窗口化实现。按页吸附的窗格滚动器,例如由 DateInput 和 DateTimeInput 共享的触摸日历 MonthScroller(monthGeometry.ts 中的 paneWindow,component:DateInput PR1),保留其自身的窗格窗口,因此不在此模块范围内。
  • INV2 — 该模块是私有的。 该模块不是公共 API:它不从任何公共入口导出;其他 Astryx 包只能通过 Core 的 ./internal/* 子路径访问它(spec:AST-017 FR21)。在 OQ1 开放期间,此约束仍然有效。
  • INV3 — 使用方保持其公共形态。 采用该模块不会改变任何使用方的公共 API。module:Table/useTableRowsVirtualization 保持其已获批准的公共形态,并在内部使用该模块。

当前状态影响

  • 模块位于 packages/core/src/virtualization/。 其他包只能通过 @astryxdesign/core/internal/virtualization 访问它。Table 的行虚拟化由 module:Table/useTableRowsVirtualization 提供,并使用该模块。Selector 在打开时渲染每个选项,Chat 渲染每条消息。

变更耦合

当某项变更新增或修改 Core 列表中的窗口化、虚拟化或已渲染行的计算,或者导出窗口化符号时,请依据本记录进行审查。

所属代码

  • packages/core/src/virtualization/ — 该模块。
  • packages/core/src/internal/virtualization.ts — 供其他包使用的私有入口。
  • module:Table/useTableRowsVirtualization — Table 的公共虚拟化 hook,是一个使用方。
  • module:Table/useTableColumnsVirtualization — Table 的公共列虚拟化 hook,是行内轴上的一个使用方。
  • packages/core/src/Selector/ — 一个使用方。
  • packages/core/src/Chat/ — 一个使用方。

决策规格

DEC-1 — 一个共享的私有窗口化模块

参考: architecture:list-windowing/DEC-1 决策者: cixzhang,2026-11-06 贡献者: humbertovirtudes,2026-11-08

一个共享的私有窗口化模块在 Core 中负责长列表窗口化;仅为规格层面的决定。在 OQ1 开放期间,该模块保持私有。

开放问题

  • OQ1 — 窗口化模块是公开的(hook)还是仅内部使用? 尚未决定。在决定之前,该模块保持私有(INV2)。

验证

不变量 证据 失败信号
INV1 packages/core/src/virtualization/useListWindow.test.tsx;对每个进行窗口化的 Core 列表的审查 某个 Core 组件在该模块之外保留了自己的窗口化实现
INV2 对每个包入口点的公共导出审查;该模块仅从 ./internal/virtualization 导出 该模块或仅由其使用的类型可从公共入口点访问
INV3 拉取请求中 useTableRowsVirtualization 及每个使用者的 API 差异 采用该模块会改变使用者的公共 props、类型或导出

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx