列表窗口化架构¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 治理契约 | 无。每个使用方的记录负责人们在长列表中看到和听到的内容;本记录只负责由哪个模块计算窗口。 |
| 系统行为 | 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:DateInputPR1),保留其自身的窗格窗口,因此不在此模块范围内。 - INV2 — 该模块是私有的。 该模块不是公共 API:它不从任何公共入口导出;其他 Astryx 包只能通过 Core 的
./internal/*子路径访问它(spec:AST-017FR21)。在 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