跳转至

动画布局系统规范

{
  "paths": ["packages/core/src/**"]
}

意图

当区域内的某个元素改变尺寸时,该元素及其之后的内容不是跳变,而是以同一个共享动效一起动画,使用主题的曲线令牌,并由其 character 和 tempo 计时。应用在每个区域选择启用一次;没有它时,一切不变,除非某个组件的记录规定对其自身变化进行动画(FR2)。

非目标

  • 区域之外的内容,以及另一个文档或 iframe 中的内容。
  • 滑动(glide)如何产生,这由 architecture:react-component-runtime INV12 负责。

公开契约

const scrollRef = useRef(null);
const animatedLayout = useAnimatedLayout({containerRef: scrollRef});
<ScrollableArea ref={scrollRef} label="Project">
  <TreeList items={items} animatedLayout={animatedLayout} />
  <p>Notes</p>
</ScrollableArea>;

需求

  • FR1 — 一个 hook、一个句柄、一个 prop。 useAnimatedLayout({containerRef}) 返回一个不透明的 animatedLayout 句柄,没有公开方法或字段。该句柄的类型携带一个可选的、类型为 never 的 phantom 品牌成员,因此包中的句柄与 swizzled 副本的句柄匹配(spec:AST-110 FR3);它在运行时从不出现,也不提供任何可读或可设置的内容。应用将其传递给一个尺寸会改变的组件,通过该组件的 animatedLayout prop;或者当组件是 hook 时,通过该 hook 的 animatedLayout 选项,并由该组件报告每一次变化。containerRef 指明区域;ScrollableArea 不会注册自身,应用传入它已经给 ScrollableArea 的 ref,该 ref 会到达原生滚动视口。每个采用该机制的组件的记录都会记录其 animatedLayout prop 或选项。
  • FR2 — 没有句柄,一切不变。 没有句柄的组件保持其原有行为:被改变的元素按照其自身记录的规定显示其变化,其后的内容立即就位。AppShell 的内容区域和 SideNav rail 在侧边导航折叠或展开时动画其自身变化,LayoutPanel 渲染的可调整大小窗格也动画其自身的折叠和展开,正如它们的记录所述(component:AppShell FR17、component:SideNav FR6、component:Resizable FR8、component:LayoutPanel FR7)。在粗指针下,没有来自应用的句柄的 TreeList 会在树内动画其自身的展开和折叠(component:TreeList FR8)。
  • FR3 — 变化之后的内容在区域内滑动。 对于持有句柄的组件所报告的任何变化——例如一个 disclosure 被打开、内容加载进来、消息出现、或插入/移除条目——该组件在区域内所推移的内容会从旧位置移动到新位置,而不是跳变:包括其后的兄弟元素,以及其布局变化所移动的前方兄弟元素(居中、末端对齐或 space-between 的行,或 order),以及其布局变化所移动的自身祖先(居中的列),在直到区域为止的每一层祖先级别,且绝不越过区域。只有当元素的布局矩形发生变化且它位于区域的可见部分时,该元素才会移动。哪些元素会移动见“覆盖范围”一节。被推移的内容可以混合 Astryx 组件和普通应用元素,且它们都无需选择启用。同一区域中的多个变化,无论是否嵌套,都会组合:每个元素只移动一次,按它的总变化量移动。区域绝不会因为滑动而滚动。
  • FR4 — 在主题曲线令牌上的一个共享动效。 被改变的元素播放自身动画——进入、退出或调整大小——而其后的内容随之移动。两者播放相同的动效,因此计时由中央统一控制,绝不由每个组件决定:主题的移动曲线 --ease-move,时长 --duration-medium,它们遵循主题的 character 和 tempo(spec:AST-108 FR1、FR2)。滑动使用曲线令牌,绝不用弹簧,也没有任何 character 或选项会为它播放平台测量的曲线(spec:AST-094 FR45)。手势释放时会按释放速度稳定到 spec:AST-094 的弹簧;曲线令牌则控制没有手势释放的滑动。两者在同一帧开始,Reduce Motion 同时作用于两者,如 design:reduced-motion DR1–DR3 所要求:在粗主指针下使用交叉淡入淡出,否则立即变化。
  • FR5 — 所有指针。 滑动适用于所有指针,包括鼠标:它消除了使用精细指针的人也会看到的布局跳变,因此它是 spec:AST-017 FR59 下的一个具名精细指针变更,采纳该机制的拉取请求需展示精细指针的前后证据。
  • FR6 — 准入。 两个其他方面完全相同的页面,其区别在于尺寸变化后的内容是滑动还是跳变,以及由哪个容器作为边界——这些只有调用者知道(spec:AST-002 FR1、FR5)。该句柄是配置,而不是渲染槽位;没有其他 API 承担此工作;它也不是一个视觉布尔值。
  • FR7 — 文档。 该 hook 的文档内容为:“返回一个句柄,用于传给尺寸会变化的组件,例如 TreeList 或 Collapsible。当该组件改变尺寸时,它以及 containerRef 内其后的内容将以同一个共享动效一起动画,该动效遵循主题的运动令牌和 tempo。fixed 元素和处于粘住状态的 sticky 元素保持不动,滑动绝不会滚动区域,并且 Reduce Motion 得到尊重。”
  • FR8 — 两个元素可以在原位互换。 一个区域可以将一个元素与另一个元素在同一位置互换,例如用骨架屏替换其内容:两者重叠,因此区域永远不会为空;短暂的显示延迟可防止快速加载时闪烁出第一个元素;方向则承载向前或向后的页面变化。该互换共享 FR4 的同一个动效。在减少动态效果下,它遵循 design:reduced-motion DR1–DR3:在粗主指针下仅进行不透明度交叉淡入淡出,否则立即变化。层退出沿用层运行时的退出副本(architecture:layer-runtime INV14)。互换还可以将区域的旧内容保持为一个临时副本,该副本是惰性的,并对辅助技术隐藏,同时新内容进入,并在互换结束时移除该副本(architecture:component-style-authoring INV7);AppShell 的内容区域在侧边导航折叠或展开时会这样做(component:AppShell FR17),SideNav rail 在折叠或展开期间也会保持其旧状态(component:SideNav FR6)。该互换是内部的;hook 的公开契约不变。

  • FR9 — 共享边缘揭示。 一个区域可以从其一条边缘揭示或隐藏某个元素:默认是块末边缘,也可以是块首、行内首或行内末边缘,例如面板在内容旁收起。该揭示会在变化前后测量元素的盒子,正如 FR3 测量任何变化一样;元素的移动边缘与该边缘一侧的内容会在 FR4 的同一次运动中移动,无论该内容是在元素之后还是之前(末端面板的 LayoutContent 位于面板之前),因此边缘旁的内容随之滑动,不会出现空隙。在块边缘形式中,元素自身的子元素在该运动下滑动,位于其内容盒上部件进入一侧的静止裁剪下方,从而它们从移动边缘进入和离开;如果元素自身带有文本、有无法通过平移移动的子元素,或者有自身绘制或生成的盒子,则它会保留随边缘移动的裁剪。可选的双状态形式会像 FR8 的交换那样持有元素的旧状态,而元素则随着其移动边缘旁内容的滑动而移动;从显示状态反转时,从当前位置开始。在 Reduce Motion 下,它遵循 design:reduced-motion:在粗略主指针下遵循 DR2,否则遵循 DR3。Core 中的每一次边缘揭示都是这一个:

    • Collapsible、TreeList 和 Table 的行展开保持其块末形式(component:Collapsible、component:TreeList、component:Table FR15)。
    • SideNav 轨道通过其行内边缘以双状态形式隐藏和揭示,并且只保留其自身的标签和图标淡入淡出效果(component:SideNav FR6)。
    • LayoutPanel 渲染的可调整大小窗格,每次收起或打开时,通过面向其 ResizeHandle 的边缘隐藏和揭示,旁边的 LayoutContent 在同一次运动中移动(component:Resizable FR8、component:LayoutPanel FR7)。只有抬起会关闭窗格,其隐藏会以抬起的释放速度稳定下来(FR4);重新打开已收起窗格的拖动不会播放任何动画,因为指针驱动着边缘。调用方仅按 useResizable 的大小渲染的窗格不会显示揭示,因为 Core 从不持有该元素;同样,给定配置对象形式的 LayoutPanel,或手动构建的、不是由 useResizable 返回的 ResizableProps 对象,也不会显示揭示;该 hook 自身的 props 通过 resizable 传递时则会滑动。

      当 LayoutPanel 渲染的可调整大小窗格收起且焦点在其中时,焦点会移动到其 ResizeHandle(即再次打开它的控件),并且收起的窗格在打开前是惰性的且对辅助技术隐藏,无论使用哪种调整大小控制器(component:LayoutPanel AR2);打开时不会移动焦点。此焦点规则仅涵盖收起窗格:SideNav 轨道遵循自己的记录,Collapsible、TreeList 和 Table 的行展开保持其记录中的行为。边缘揭示是内部的:useAnimatedLayout 的公开契约不变,且不添加任何 prop 或选项。

覆盖范围

区域内移动的内容,每种情况及其测试:

情况 行为 测试
变化元素之后的常规流块级兄弟节点,在直至该区域的每一祖先层级上 在其矩形发生变化时移动 嵌套的变化元素,在三个层级上有块级兄弟节点
带有 display: contents 的元素 没有盒子;其子元素会代替它占据位置 一个包含两个子元素的后续 display: contents 包装器
绝对定位或固定定位的元素 被跳过并占据其最终位置;移动元素的绝对定位子元素会随其一起移动 各一个,以及在移动行上的一个绝对定位徽标
处于绝对定位、固定定位、stuck、sticky 或 top-layer(顶层)祖先元素内的变更内容 只有变更之后的内容会移动;该祖先元素、其内部的祖先元素以及变更之前的兄弟元素都占据其最终位置 在底部停靠面板中,一个包围变更的卡片上方的页眉,以及一个包围变更的底部粘住 sticky 页脚
sticky 元素 未粘住时处于文档流中,因此当其矩形区域发生变化时会移动;粘住时会占据其最终位置 在其粘住点上方和下方的 sticky 页眉
浮动元素 当其矩形区域发生变化时移动 变更元素之后的一个浮动元素
变更元素之后的 Flex 和 grid 项,包括 wrap 和 row 方向 当其矩形发生变化时移动 一个换行的 flex 行和一个不发生移动的 row 方向相邻元素
变更元素之前的兄弟元素及其每一层的祖先 当其矩形发生变化时移动:居中的行、末端对齐或 space-between 的行、居中的列,或可见部分附近兄弟元素中的 order 会使它们移动 一个居中的行、一个 space-between 行、一个末端对齐的行、一个居中的列,以及一个通过 order 放置的兄弟元素
隐藏、display: none 或零尺寸的元素 跳过 变更元素之后每种各一个
位于区域可见部分之外的变更元素 不播放动画,直接占据其最终位置 一个长列表,首屏上方和下方都有变更的行
位于缩放或变换的祖先元素之下的元素 按其布局变化移动,并根据祖先元素的缩放比例进行校正 缩放面板内部的一个移动行
Portal 与顶层内容 绝不移动 从后续某行打开的 popover
已在移动的元素 保持其正在进行中的运动,并将新的移动叠加到该运动中 两个相隔 100 ms 的变更
嵌套区域 运动在变更组件所持有的手柄区域处停止;内部区域作为一个整体在外层区域内移动 区域中的区域,在内层区域中发生变更
打开或关闭明细行之后的表格行 行会滑动;关闭的明细行立即隐藏,并在其后的行向上滑动时保持其空间。绘制列线的表格(component:Table FR15)不会滑动:它及其后续内容会立即就位 在带有固定列的表格中,以及在带有列线的表格中,一个明细行的打开和关闭
沿任一轴的边缘显示或隐藏 内容从块末端边缘(默认)、块起始边缘或内联边缘显示或隐藏;可选的双状态形式会在交换时保持旧状态,并使元素随其移动边缘旁边的内容一起滑动;移动边缘一侧的内容在元素之前或之后移动;可调整大小的 LayoutPanel 窗格在折叠和打开时;折叠中的 LayoutPanel 窗格内部的焦点移动到其 ResizeHandle(FR9) 动效布局浏览器测试,覆盖块末端显示与隐藏、块起始显示与隐藏(一个面板在其后的内容上方打开)、内联起始与内联结束的显示与隐藏(一个结束面板,其 LayoutContent 位于其之前)、双状态形式、LayoutPanel 窗格通过切换、Enter 键和拖拽越过阈值进行折叠与打开,以及焦点离开已隐藏窗格(待定)

不在覆盖范围内,每一项都立即到达其最终位置:

  • 区域之外的内容,以及另一个文档或 iframe 中的内容;
  • 内联文本和其他非替换型行内内容,它们无法应用 transform;
  • 浮动元素旁边段落内重排的文本;
  • 应用自身通过其 transform 移动的元素;
  • 一个正在关闭的元素,其空间不会被任何末尾外边距释放(一个在隐藏时其轨道或间距发生变化的网格项,或一个设置了其行高的 flex-row 项):它会立即隐藏,且没有退出动画,其后的内容会立即到达最终位置,但表格明细行(Coverage)除外;
  • 一个锚定弹出层,与某个移动中的元素绑定,层锚定会将其保持原位(architecture:layer-runtime);
  • 一个由 order 或网格放置(grid-row、grid-column、命名区域或密集打包)从区域可见部分加一个视口(若变化尺寸更大,则为该尺寸)之外的文档顺序中带入视野的项目,而遍历无法到达该项目。

当前状态影响

  • 目前还没有 Core 组件采用 animatedLayout;TreeList、Collapsible 和 Table 的行展开(component:Table FR15)是首批采用者,它们的文档将加入 animatedLayout 句柄。
  • Core 新增 useAnimatedLayout 导出项及其文档(FR7)。
  • architecture:react-component-runtime INV12 产生滑动效果。
  • architecture:react-component-runtime INV12 也新增了原地交换(FR8);目前尚无组件使用这种交换。
  • INV12 还产生边缘显现(FR9)。SideNav 的轨道裁剪和滑动效果将从 SideNav 自身代码迁入其中;目前会跳变的可调整大小的 LayoutPanel 的折叠与展开也将采用它;LayoutPanel 的文档说明折叠会滑动。
  • 每个正在运行的、移动了可命中测试元素的 translate 的滑动效果,都会将其报告给 motion/presentation.ts,正如动画器的移动那样。惰性副本或正在关闭的元素不会被报告。因此,在 iOS WebKit 上,手势宿主处理的触摸会送达手指下方绘制的内容(spec:AST-094 FR11、FR19)。实现差距:在 iOS WebKit 上,一个没有手势处理、点击滑动中途元素的普通点击,仍会送达滑动前该位置原有的内容,直到滑动结束(滑动效果最多持续主题的移动时长)。
  • 每个变更的运动会促使引擎再一次解析其元素,具体是在运动被绘制到接近其末端的第一帧时:即半像素或半个百分点之内,或不透明度或指示器转动的 0.005 之内。WebKit 可能会用上次解析出的值来绘制合成器动画的最后一帧,以及跨越其末端的长任务的每一帧;这一帧会显示运动的末端。该机制覆盖滑动效果、退出动画及其各部分、显现效果的各部分以及指示器的过渡。Reduce Motion 下的淡出则不会得到这种处理:WebKit 会在其末端绘制最终值。实现差距:在该帧之前开始的长任务仍会显示上次解析出的值;而一个只在最后一个关键帧(线性曲线,或陡峭曲线上的长移动)接近末端的运动,则不会得到这样的解析。复查条件:在每次 WebKit 发布时重新测量;一旦 WebKit 能以最终值绘制已结束的合成器动画,请移除这些解析。

验证

契约 验证 代表性状态 变异或失败预期
FR1, FR2 有句柄和无句柄的单元测试与浏览器测试 TreeList 上有句柄;无句柄;一个 ScrollableArea ref 出现带公共成员的句柄、无句柄时行为发生变化,或 ScrollableArea 自行注册失败
FR3, Coverage 每个 Coverage 行一项的真实浏览器测试 每个 Coverage 行;Astryx 与普通内容混合;一帧内两处变更;一个在列表中途滚动的区域 元素行为与其所在行不一致、同一帧内元素被移动两次、超出区域的内容发生移动,或区域滚动失败
FR4 在粗粒度指针和细粒度指针下,启用与未启用 Reduce Motion 的真实浏览器帧捕获 在每种 character 下的已变更元素及其可见跟随者,以及在 tempo 为 0.75 和 1.5 时;一个以释放速度关闭 LayoutPanel 的上提手势 从不同帧开始、读取不同运动设置、组件使用自身计时、滑动忽略主题的 character 或 tempo、在没有手势释放时为滑动使用弹簧或实测曲线,或 Reduce Motion 只应用于其中一个而非另一个,均失败
FR5 在每个采用该效果的拉取请求中,提供来自组件 Storybook story 的精细指针前后证据 鼠标位于每个采用组件上 鼠标下缺少滑动,或采用该效果的拉取请求没有该证据,失败
FR8 交换的单元测试,以及其采用者的真实浏览器证明 快速加载、慢速加载、前进和后退页面变更、Reduce Motion 交换期间出现空白区域、快速加载时闪现占位符、Reduce Motion 下产生移动、由它播放图层退出动画,或公共导出失败
FR9 展开效果的测量单元测试,以及每个采用者的真实浏览器帧捕获 Collapsible 打开;SideNav rail 折叠与展开;起始和结束 LayoutPanel 通过切换、Enter、展开箭头、受控更改以及超过阈值的上提进行折叠和打开;拖拽重新打开窗格;仅使用 hook 的窗格;折叠窗格内部聚焦;Reduce Motion 移动边缘旁边出现间隙、一次 rail 折叠产生两个动画、在重新打开窗格的拖拽过程中发生展开、在仅使用 hook 的窗格上发生展开、焦点留在隐藏窗格内、隐藏窗格可通过 Tab 到达,或公共导出失败

决策日志

DEC-1 — 每个区域一个选择加入的句柄;变更后的内容滑动

Reference: spec:AST-105/DEC-1 Decider: cixzhang, 2026-10-25

无论何种指针,当上方某个内容改变尺寸时,内容的跳变都会让人失去方向感。应用为每个区域向尺寸发生变化的组件传入一个句柄,从而使选择加入显式化,并且无需包装器即可组合;组件只在其记录声明的位置对自身的变更进行动画处理(FR2;component:SideNav/DEC-2);变更后的内容与已变更元素在同一个共享运动角色上滑动,且只在该区域内部、仅在其可见处滑动。

已否决:将后续内容包裹在元素中,并为每个后续元素选择加入。

DEC-2 — 滑动播放主题的 curve tokens

参考: spec:AST-105/DEC-2 决策者: cixzhang,2026-11-04

滑动与任何其他移动一样,是一种动作,因此它采用主题的移动曲线和时长;设置了 character 或 tempo 的主题,会在所有指针下让滑动随其余动效一同变化。用于展开或折叠内容的点按不携带速度,因此紧随其后的滑动播放 curve tokens,绝不会是弹簧(spec:AST-094 FR45)。手势松开时,会以松开速度在 spec:AST-094 的弹簧上落定;curve tokens 则支配那些不由手势松开触发的滑动。

已否决:将实测弹簧作为滑动;以及平台实测的选择加入机制,例如单独的 character。

DEC-3 — 滑动采用中等时长

参考: spec:AST-105/DEC-3 决策者: cixzhang,2026-11-06

滑动在 --duration-medium 期间播放,即主题中等时长的中值:Neutral 主题中为 300 ms,无主题时为 410 ms,两者均按 tempo 缩放。Collapsible、TreeList、Table 的行展开、AppShell 的内容区域以及 List 共用这一时长,作为一个统一的动效。

已否决:--duration-medium-min。

开放问题

无。

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