尺寸过渡
包住尺寸会变化的内容——变长的消息、多了一行的分区、少了一行的面板——并以一段连贯的动画把自身尺寸带到内容的新尺寸,使排在它后面的内容平滑移动而不是突然跳动,同时它所固定的那条边保持不动。
- 类别
- 容器
- 令牌
comp.size-transition- 层级
- 基础
- Web
tanrei-size-transitionclock_loader_40 - SwiftUI
TanreiSizeTransitionradio_button_unchecked - Jetpack Compose
TanreiSizeTransitionradio_button_unchecked - Flutter
TanreiSizeTransitionradio_button_unchecked - React Native
SizeTransitionradio_button_unchecked
生成自 docs/status/status.json, specs/size-transition.spec.json
随段落变化的块,以及随文字变化的行内盒子
季度报告已经完成。与上一版相比,新增了三个部分:成本、人员和下一季度的计划。
当里面的内容改变尺寸时,盒子会从当前显示的尺寸,以一段连贯的动画过渡到新的尺寸。布局中排在它后面的内容也会随之移动,而不会在一帧之内跳过去。它自身不绘制任何东西:没有背景、边框、圆角和内边距。
Web 和 React 的示例展示的是当前的规格。SwiftUI、Compose、Flutter 和 React Native 尚在计划中:它们还没有提供尺寸过渡。
<tanrei-size-transition>
<div id="details"></div>
</tanrei-size-transition>
<p>详情变化时,下面的所有内容都会平滑移动。</p>
<!-- 停靠在底部:向上增长,最后一行保持不动。 -->
<tanrei-size-transition anchor="end">
<div id="draft"></div>
</tanrei-size-transition>
<script type="module">
import '@tanrei/web/components/size-transition';
const box = document.querySelector('tanrei-size-transition');
box.addEventListener('settle', (event) => console.log(event.detail.height));
document.querySelector('#details').textContent = longerText; // 平滑移动,不会跳动
</script>import { SizeTransition } from '@tanrei/react';
<SizeTransition onSettle={(event) => setHeight(event.detail.height)}>
{expanded ? <FullDetails /> : <Summary />}
</SizeTransition>
<SizeTransition axis="inline">
<span>{saving ? '正在保存…' : '已保存'}</span>
</SizeTransition>固定的边:start(默认)、end 和 center
start:第一行保持不动,新的行出现在它下面。
end:最后一行始终贴着盒子的底边,新的行出现在它上面。
center:两条边各移动变化量的一半。
构成
构成
block 之上。| 部件 | 说明 |
|---|---|
1 box | The size transition itself: a box with no look of its own, laid out where it stands, whose size along its axis is the one that moves. It clips what lies beyond it while it moves. |
2 content | Whatever the product puts in it, laid out at its own natural size and fixed to the box's anchor edge. It is measured, never scaled or stretched. |
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
axis | block | inline | both | "block" | Which of its sizes follows the content. block: its height in a horizontal writing mode (the size across lines); its width is the layout's. inline: its width (the size along a line); its height is the layout's. both: both sizes. |
anchor | start | end | center | "start" | Which edge stays still while the box grows or shrinks. start: the block-start edge (the top) for block, the inline-start edge for inline, so that a growing box uncovers what is new below or after and never moves the first line. end: the opposite edges, for a box docked at its container's end that grows upward (a composer above the keyboard). center: both edges move by half. |
duration | number | null | How long one change takes, in milliseconds, used as given for every distance. Null, the default, takes the system's answer, which grows with the distance moved (SZT-3). Set it only where one place needs another tempo than every other size transition of the product. |
disabled | boolean | false | Makes the box follow its content's size at once, without a motion: for a change the person should not watch (a list replaced by a search's results) or a stretch of time in which the content changes at every frame. |
插槽
| 插槽 | 说明 |
|---|---|
default | The content whose size the box follows. Any content: text, a list, another component. |
事件
| 事件 | 说明 |
|---|---|
settle | The box's size has come to rest after a change, by a motion or at once: emitted once per change, after the last frame, with the box's new width and height in the platform's layout units. A motion that is turned round or retargeted (SZT-2) emits once, at its final rest. |
状态
行为
以 EARS 形式写成的需求。每个平台的实现都按这些 ID 逐条测试。需求原文取自规格文件,原样以英文呈现。
| ID | 需求 |
|---|---|
SZT-1 | WHEN the size transition is first drawn THE size transition SHALL take its content's size along its axis in its first frame, without a motion, as every component draws its first frame at rest (MOT-3); content that arrives or changes before that frame is drawn is part of the first frame. |
SZT-2 | WHEN its content's size along its axis changes after the first frame THE size transition SHALL move its own size in the layout, at every frame, from the size it shows to the new one, over the duration SZT-3 gives with comp.size-transition.motion.easing, so that what stands after it moves with it; WHEN the content changes again during the motion THE size transition SHALL go on from the size then shown towards the newest size as one motion, never jumping to the old target or restarting from the old size (MOT-2). |
SZT-3 | WHILE duration is null THE size transition SHALL take the duration of a change from the distance its size moves: comp.size-transition.motion.duration for a distance of up to comp.size-transition.motion.distance-step, plus comp.size-transition.motion.duration-step for each further distance-step begun, and never more than comp.size-transition.motion.duration-max; WHILE duration is a number THE size transition SHALL take that many milliseconds for every distance, 0 meaning at once. The duration of a retargeted motion SHALL be computed from the distance between the size shown and the newest size. |
SZT-4 | WHILE its size differs from its content's THE size transition SHALL clip what lies beyond its box and keep the content fixed to the edge anchor names, mirrored for inline in a right-to-left layout: WHILE anchor is start a growing box SHALL uncover what is new at its block-end (or inline-end) edge and never move its first line, WHILE anchor is end it SHALL uncover what is new at its start edge, the content moving with its end edge, and WHILE anchor is center both edges SHALL move by half the change. |
SZT-5 | WHILE it moves THE size transition SHALL scroll nothing — neither itself nor its content nor an ancestor — to bring a part of the content into view, also WHILE an element inside it has focus, and SHALL leave focus, the caret and a selection where they are (MOT-5). |
SZT-6 | WHEN its content's size changes because the room the layout gives it changed — the window or a pane was resized or turned, the text size changed, the layout direction changed — THE size transition SHALL take the new size at once, so that it never lags behind a person resizing the window; and WHILE a size transition inside its content is moving THE size transition SHALL follow its content at every frame, so that two nested motions move as one and do not compound. |
SZT-7 | WHERE motion is reduced THE size transition SHALL take every new size at once, as size changes are made where motion is reduced (MOT-6), and SHALL still emit settle once per change. |
SZT-8 | WHILE disabled is true THE size transition SHALL follow its content's size at once; WHEN disabled becomes true during a motion THE size transition SHALL take the newest size at once and emit settle. |
SZT-9 | WHILE the size transition is not drawn — hidden, outside a view that is shown, or in an app in the background — THE size transition SHALL take every new size at once, and WHEN it is drawn again it SHALL show its content's size without a motion. |
SZT-10 | THE size transition SHALL expose nothing of its own to assistive technology — no role, no name, no state — and SHALL NOT be a focus stop: its content is read and reached as if the box were not there, including content that the box clips during a motion. |
SZT-11 | WHEN its size has come to rest after a change, by a motion or at once, THE size transition SHALL emit settle exactly once, after the last frame, with its new width and height; it SHALL emit nothing WHEN its content changes without changing its size along its axis. |
SZT-12 | THE size transition SHALL draw nothing of its own — no color, edge, shadow, corner or padding — and SHALL take, on the axes it does not follow, the size its layout gives it; WHILE axis is both it SHALL follow the content's width and height together in one motion of one duration, computed from the larger of the two distances (SZT-3). |
SZT-13 | THE size transition SHALL take its layout direction from where it is used and SHALL have no direction setting of its own; WHEN axis or anchor names a value it does not define THE size transition SHALL use the default value and in debug builds report the unknown value; WHILE duration is a negative number or not a finite number THE size transition SHALL treat it as null and in debug builds report it. |
各平台名称对照
对等并不意味着 API 完全相同。同一份契约,由各平台以自己的惯用方式表达。
| 规格 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| 组件 | tanrei-size-transition | TanreiSizeTransition | TanreiSizeTransition | TanreiSizeTransition | SizeTransition |
axis · 属性 | axis | axis | axis | axis | axis |
anchor · 属性 | anchor | anchor | anchor | anchor | anchor |
duration · 属性 | duration | duration | durationMillis | duration | duration |
disabled · 属性 | disabled | isDisabled | enabled | disabled | disabled |
settle · 事件 | settle | onSettle | onSettle | onSettle | onSettle |
| 备注 | <tanrei-size-transition axis="block" anchor="start">…</tanrei-size-transition>, built on the package's size-motion primitive (AnimatedSize). The shadow root holds a box and, in it, a wrapper around the slot at its natural size. A resize observer of the wrapper sees a change of the content's size after layout and before the frame is painted; the box then moves from the size the last frame drew to the new one in pixels, with a CSS transition, clipped with overflow: clip (never hidden, which lets a focused descendant scroll the box). The box is a flex container that justifies the wrapper to the anchor's edge (flex-start, flex-end, center), so that the content is laid out at its own size and overflows the edge that moves; justification follows the direction, so the inline axis mirrors in right-to-left. interpolate-size: allow-keywords is not used: it is experimental and not Baseline. SZT-6: a change of the window's size, of the box's own inline size (the room it is given, for axis block), of its font size or of its direction is applied at once, as is any change while a size transition in its content carries data-resizing (the host carries it while it moves). settle is a CustomEvent that does not bubble, whose detail is { width, height } in CSS pixels; a run that is retargeted ends with the run that replaced it. duration is a number property, the duration attribute parsed as the tooltip's delays are (an empty attribute is not a number). The host is display: block (axis inline or both: display: inline-block), as large as the box. | A container view that measures its content with a geometry reader and animates its frame with withAnimation on the measured size, .clipped(), aligned by anchor; reduced motion from accessibilityReduceMotion. | A Box with Modifier.animateContentSize(animationSpec, alignment) and clipToBounds(); enabled is the inverse of disabled. The spec of SZT-3 is computed from the measured distance before each animation. | Built on AnimatedSize with alignment from anchor and clipBehavior: Clip.hardEdge; the duration of SZT-3 is set from the size the child reports before the animation starts. | A View that measures its child with onLayout and animates its own height or width with Reanimated, overflow: 'hidden' (React Native has no clip distinction). |
令牌
| 令牌 | 引用 | 解析值(浅色) |
|---|---|---|
--tanrei-comp-size-transition-motion-distance-step | sys.space.space800 | 64px |
--tanrei-comp-size-transition-motion-duration | sys.motion.role.resize.default | 300ms |
--tanrei-comp-size-transition-motion-duration-max | sys.motion.role.resize.large | 400ms |
--tanrei-comp-size-transition-motion-duration-step | sys.motion.duration.short1 | 50ms |
--tanrei-comp-size-transition-motion-easing | sys.motion.easing.spatial | cubic-bezier(0.2, 0, 0, 1) |
测试样例
作为基准的渲染结果。所有平台都以相同的 ID 为每个样例截取快照,以便相互比较。
block
{} inline
axis: inline anchor-end
anchor: end anchor-center
anchor: center both
axis: both rtl-inline
axis: inline direction: rtl 生成自 specs/size-transition.spec.json, tokens/comp/size-transition.tokens.json, design/tokens/
用尺寸过渡包住你自己的、会在用户注视时改变尺寸的内容:换到第二行的回复草稿、被替换成全文的摘要、出现在你自建输入框下方的错误提示、文字变长的状态标签。不包住的话,下面的所有内容都会在一帧之内跳动,用户会找不到自己读到了哪里。
Tanrei 自己的组件已经会为自身的尺寸变化添加动画,例如会变高的文本输入、会展开的消息条(snackbar)、会打开的折叠面板。不需要为此再用尺寸过渡包住它们。
如果要按用户的操作整体展开或收起一个分区,请使用折叠面板:展开和收起是它的职责。尺寸过渡不会展开或收起任何东西,它只是跟随里面的内容。
时间随距离增长。在默认系统中,64 像素以内的变化需要 300 ms。距离每再增加 64 像素(不足 64 像素也算一份),就再加 50 ms,最长 400 ms。这样,大的变化放在小的变化旁边不会显得仓促,很远的变化也不会让人久等。只有当某一处需要与产品中其他尺寸过渡不同的节奏时,才设置 duration。设为 0 时变化立即生效。
| 轴 | 用于 |
|---|---|
| Block(默认) | 高度会变化的内容:段落、列表、多出一行的分区。宽度由布局决定。 |
| Inline | 宽度会变化的标签:状态文字、计数、按钮上的文字。宽度与内容相同。 |
| Both | 宽度和高度一起变化的小盒子,例如换到第二行的徽标。两者以同一段动画移动。 |
| 固定的边 | 用于 |
|---|---|
| Start(默认) | 大多数内容。第一行从不移动,新的内容出现在它后面。 |
| End | 停靠在容器末端的内容,例如键盘上方的消息输入框。最后一行保持原位,盒子向开头一侧增长。 |
| Center | 位于所在空间正中的内容,例如空面板正中的提示。 |
- 只包住会变化的内容。用它包住整个页面,所有东西都会同时移动。
- 当内容每一帧都在变化时(例如用户正在里面拖动某样东西),以及对于不需要让用户看到过程的变化(例如列表被替换成搜索结果),使用
disabled。 - 需要在变化之后测量或滚动时,等待
settle:它会在最后一帧之后到达,且只到达一次。
- 不要用它让内容淡入或淡出。它只移动尺寸,淡入淡出应由内容自己负责。
- 不要用尺寸过渡包住已经会为自身尺寸添加动画的 Tanrei 组件。
- 不要指望它在指标上消除布局偏移。浏览器仍然会把因布局变化而移动的元素计算在内。它消除的是用户看到的跳动。
- 角色
none (a generic container that exposes nothing of its own)- 标注
- The size transition names nothing and is not named; its content keeps its own names, roles and order.
- 最小目标
- 即使外观尺寸更小,点击区域也满足最小目标尺寸。 minimum 36px · pointer 36px · spacing 8px · touch 36px
键盘操作
| 按键 | 动作 |
|---|
备注
- It takes no input, so it has no target of its own; its content keeps its own hit areas.
- A size change is a motion in the sense of WCAG 2.3.3 (animation from interactions): where motion is reduced it happens at once (SZT-7). The opacity of the content is never changed by this component.
- Content that the box clips while it moves stays in the reading and focus order: a person who tabs into it during the motion reaches it, and nothing scrolls to show it (SZT-5) — the motion ends within comp.size-transition.motion.duration-max.
- Browsers count an element moved by a layout change as a layout shift unless a person's input preceded it within a short window. Moving what follows over a motion does not remove it from that count; it removes the jump a person sees. Measure layout shift in a product's own pages.
生成自 specs/size-transition.spec.json, tokens/sys/measure.tokens.json
- 它不向辅助技术公开任何属于自己的东西:没有角色、没有名称、没有状态,也从不成为焦点停留点。里面的内容被读出和到达的方式,就像这个盒子不存在一样。
- 动画过程中被盒子裁切的内容仍然留在朗读顺序和焦点顺序中。在动画过程中按 Tab 进入的人可以到达它,而且在默认系统中动画会在 400 ms 内结束。
- 动画过程中不会滚动任何东西:盒子、里面的内容和页面都不会。焦点、光标和选区都保持原位。
- 在请求减弱动态效果时,所有尺寸变化都立即生效。
settle仍然每次变化到达一次。 - 布局给它的空间发生变化时——窗口尺寸改变、文字大小或方向改变——会立即生效,因此盒子不会落后于正在调整窗口大小的用户。
- 未知的
axis或anchor,以及为负数或不是数字的duration,都会在调试构建中报告。
- 重要的变化要由你自己告知:用实时区域,或用户会看到的通知。尺寸过渡只移动尺寸,什么也不说。
- 保持内容自身的名称、角色和顺序正确。尺寸过渡不会添加任何东西。