useOverflow 模块契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 无变化。useOverflow(itemCount, options) 返回 containerRef、measureRef、visibleCount、hasOverflow、rows 和 rowHeight。 |
| 行为 | 该 hook 会在某次 commit 挂载或更改其列表时进行测量,并且在该 commit 中的每个列表都会在 commit 之后的微任务中、绘制之前进行测量。当浏览器报告的大小与某个列表上次测量时的大小一致时,该 hook 不会对该列表测量任何内容。 |
| 最终用户影响 | 包含许多溢出容器的页面会在每个 commit 中为所有这些容器只布局一次;容器所观察的父级变窄时,它总是会折叠到新的宽度。 |
| 构建者影响 | 在同步渲染的同一任务中读取结果的调用方,需要先等待一个微任务。component:OverflowList PR1 关于 resize 时序的说明同样适用于直接调用方。 |
| 兼容性/就绪状态 | 记录已发布行为;没有 API、默认值或 DOM 变更。权威级别:draft。FR3 差距:记录的盒可以与报告的盒存在差异,而实际尺寸并未变化,因为 hook 记录的是父级取整后的 clientWidth 减去其 padding,以及测量副本的 getBoundingClientRect() 盒(在 observeSelf 下还包括列表自身的盒),而祖先元素的 zoom、scale、skew 或 rotation 会改变这些盒(translation 不会,旋转四分之一圈只会交换宽高,FR3 仍然匹配)。该列表随后会针对该报告再次测量,当结果未改变时,它不会渲染任何内容。ORD1 没有测试。 |
| 评审检查 | 拒绝在 commit 内部进行测量;拒绝在帧绘制之后才落地、且 component:OverflowList PR1 不允许的结果;拒绝一个列表与另一个列表共享的已测尺寸记录。 |
| 治理规则 | component:OverflowList FR7、ORD3、PR1、PR2 和 DEC-1;architecture:public-component-api。 |
此表是评审投影;下文正文具有权威性。
意图¶
useOverflow 是 OverflowList 背后的公共测量核心。应用也可以直接调用它来构建自己的溢出布局。它测量列表子元素的隐藏副本,并报告有多少可以放入。这份记录只约束一个语义切片:hook 何时测量,以及其结果何时落地。适配性计算、折叠顺序、数量限制和指示器仍由 component:OverflowList 负责。
兼容性与迁移¶
- 已发布的默认值保持不变:
yes。该记录描述当前的main。 - 兼容性类别:记录已发布的行为;无 API、默认值或 DOM 变更。
- 迁移决定:
component:OverflowListDEC-1 涵盖时序。如果在同步渲染后立即读取结果的测试,需要先等待一个微任务,例如使用await act(async () => {})。
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 提交后 hook 何时测量,以及其结果何时生效。
- 哪些 resize 报告会触发该 hook 重新测量。
- 每个列表为其观察的每个元素记录的大小。
不拥有 / 非目标
- 适配计算、折叠顺序、
minVisibleItems和maxVisibleItems、行以及指示器:component:OverflowListFR2 和 FR4,以及它们所验证的computeOverflow辅助函数。 - 哪些 resize 结果会晚一帧绘制:
component:OverflowListPR1。 - 共享 resize observer 自身的交付:
utils/sharedResizeObserver。
公共 API 与概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 所有者 | 稳定性 |
|---|---|---|---|---|---|
| results | visibleCount, hasOverflow, rows, rowHeight |
上次测量时列表中可容纳的内容 | 所有项目、一行、0 |
module:OverflowList/useOverflow |
stable |
| refs | containerRef, measureRef |
可见列表及其隐藏的测量副本;绑定任意一个都会开始观察 | none | module:OverflowList/useOverflow |
stable |
| observed box | observeSelf(列表的边框盒),observeParent(父元素的内容宽度) |
测量为可用宽度读取的尺寸 | observeSelf |
component:OverflowList |
stable |
| measured size | 每个列表、每个被观察元素 | 列表上次测量所依据的尺寸:列表及其测量副本的边框盒,或父元素的内容宽度 | 首次测量前为 none | module:OverflowList/useOverflow |
stable |
行为契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 在提交(commit)挂载列表或其测量副本、或更改项目数量或某个选项之后,该 hook 会在提交后的一个微任务中进行测量,与该提交中的其他每个列表一起。每个列表读取其尺寸,然后一次渲染应用所有结果,均发生在帧绘制之前。结果在提交内部不会改变。 | component:OverflowList FR7 和 DEC-1 |
| FR2 | 当 resize 报告包含该列表尚未为该元素记录的尺寸时(FR3),该列表会在同样类型的微任务中重新测量,与这次交付所报告的每个列表一起。其结果会在帧绘制之前渲染,除非 component:OverflowList PR1 将其延迟一帧渲染。 |
component:OverflowList PR1 |
| FR3 | 列表会为其观察的每个元素记录上次测量所依据的盒。后续报告若在 0.01 px 范围内与该记录匹配,则不会对该列表进行测量;边框盒的匹配不考虑宽度和高度顺序,因为报告给出的是逻辑尺寸,而记录是物理尺寸。任何其他报告都会触发测量。使用 observeParent 时,记录是父元素的内容宽度,因此仅父元素内边距变化仍会触发测量。每个列表保留自己的记录,因此一个列表会测量它自身未测量过的尺寸,即使同一父元素上的另一个列表已经测量过该尺寸。 |
当前源码和测试 |
转换与优先级顺序¶
- ORD1 — 先提交,后调整大小。 若一个提交和一个调整大小报告在同一微任务中命名了同一个列表,则以提交测量(FR1)的方式测量一次。
性能与资源¶
- PR1 — 每次提交一次布局。 在同一提交中挂载或更改的列表会在提交后一次性读取它们的尺寸(
component:OverflowListPR2)。 - PR2 — 已记录尺寸不测量。 与记录(FR3)匹配的报告不测量任何内容。这是该 Hook 唯一跳过的测量:任何其他报告——包括浏览器在某个结果改变了所观察盒子后的首次报告,以及 FR3 缺口中的情况——都会再次测量,并在结果未变化时不渲染任何内容。
无障碍契约¶
此 Hook 不拥有任何无障碍语义。
设计关系¶
此 Hook 不拥有任何视觉表现。
父级与系统关系¶
component:OverflowList拥有聚合行为、折叠规则以及其折叠和onOverflowChange的时机(FR7、PR1)。- 本记录拥有 Hook 自身的测量时机及其测量尺寸记录,
OverflowList和直接调用者共享这些记录。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1, PR1 | useOverflow.test.ts “在提交后测量该提交的每个列表,然后仅渲染每个结果一次” |
同一提交中的两个列表 | 若在提交内部进行测量,或在两个列表的尺寸读取之间进行渲染,则失败。 |
| FR2 | useOverflow.test.ts “测量一次传递所报告的每个列表,然后渲染一次”,以及“在绘制前渲染”和“在绘制后渲染”两种情况 |
一次传递对应两个列表;单行和多行折叠 | 若某个调整大小结果在其对应情况下于错误时机渲染,或一次传递导致第二次渲染,则失败。 |
| FR3, PR2 | useOverflow.test.ts “对于列表所测量尺寸的报告不测量任何内容”、“当被观察父元素的内容盒发生变化而其边框盒未变化时再次测量”,以及“当两个列表位于同一父元素下且只有其中一个测量了新宽度时,分别对两个列表进行测量” |
相同尺寸报告;仅 padding 变化的父元素;同一父元素下的两个列表 | 若针对相同尺寸报告进行测量、跳过 padding 变化,或记录在列表之间共享,则失败。 |
| ORD1 | 无。缺口:没有测试覆盖在同一微任务中命名同一列表的提交和调整大小报告。 | 同一微任务中的一次提交和一个调整大小报告 | 若一个调整大小测量替代了挂起的提交测量,将不会被注意到。 |
决策日志¶
无记录。时机决策见 component:OverflowList DEC-1。
开放问题¶
无。
内容边界¶
本记录不重复消费者签名或示例、父级的聚合协议或排序、当前审计结果、实现步骤,或族系、设计、系统规则。它链接到它们的权威所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx