跳转至

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:OverflowList DEC-1 涵盖时序。如果在同步渲染后立即读取结果的测试,需要先等待一个微任务,例如使用 await act(async () => {})。

消费者迁移说明属于消费者文档和发布说明。

所有权边界

拥有

  • 提交后 hook 何时测量,以及其结果何时生效。
  • 哪些 resize 报告会触发该 hook 重新测量。
  • 每个列表为其观察的每个元素记录的大小。

不拥有 / 非目标

  • 适配计算、折叠顺序、minVisibleItems 和 maxVisibleItems、行以及指示器:component:OverflowList FR2 和 FR4,以及它们所验证的 computeOverflow 辅助函数。
  • 哪些 resize 结果会晚一帧绘制:component:OverflowList PR1。
  • 共享 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:OverflowList PR2)。
  • 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