Compose Animation

Compose Animation

用户指南 代码示例

API 参考文档
androidx.compose.animation
androidx.compose.animation.core

在 Jetpack Compose 应用中构建动画，丰富用户的体验。

最近更新时间	当前稳定版	下一候选版本	Beta 版	Alpha 版
2020 年 9 月 16 日	-	-	-	1.0.0-alpha03

结构

Compose 由 androidx 中的 7 个 Maven 组 ID 构成。每个组都包含一套特定用途的功能，并各有专属的版本说明。

下表介绍了各个组及指向其版本说明的链接。

组	说明
compose	使用描述界面形状和数据依赖项的可组合函数，以编程方式定义界面。
compose.animation	在 Jetpack Compose 应用中构建动画，丰富用户的体验。
compose.foundation	使用现成可用的构建块编写 Jetpack Compose 应用，还可扩展 Foundation 以构建您自己的设计系统元素。
compose.material	使用现成可用的 Material Design 组件构建 Jetpack Compose UI。这是更高层级的 Compose 入口点，旨在提供与 www.material.io 上描述的组件一致的组件。
compose.runtime	Compose 的编程模型和状态管理的基本构建块，以及 Compose 编译器插件所针对的核心运行时。
compose.ui	与设备互动所需的 Compose UI 的基本组件，包括布局、绘图和输入。
ui	使用 Jetpack Compose 库。

声明依赖项

如需添加 Compose 的依赖项，您必须将 Google Maven 代码库添加到项目中。如需了解详情，请参阅 Google 的 Maven 代码库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

dependencies {
    implementation "androidx.compose.animation:animation:1.0.0-alpha09"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerVersion "1.4.21"
        kotlinCompilerExtensionVersion "1.0.0-alpha09"
    }
}

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
    kotlinOptions {
        jvmTarget = "1.8"
        freeCompilerArgs += ["-Xallow-jvm-ir-dependencies"]
    }
}

如需详细了解依赖项，请参阅添加构建依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对库的改进有某些建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 1.0.0

版本 1.0.0-alpha03

2020 年 9 月 16 日

发布了 androidx.compose.animation:animation:1.0.0-alpha03 和 androidx.compose.animation:animation-core:1.0.0-alpha03。版本 1.0.0-alpha03 中包含这些提交内容。

问题修复

• gravity 在布局 API 中用到时被一致地重命名为 align 或 alignment。（I2421a、b/164077038）

版本 1.0.0-alpha02

2020 年 9 月 2 日

发布了 androidx.compose.animation:animation:1.0.0-alpha02 和 androidx.compose.animation:animation-core:1.0.0-alpha02。版本 1.0.0-alpha02 中包含这些提交内容。

API 变更

• 添加了 ManualFrameClock.hasAwaiters，用于检查是否有任何内容在等待来自相应时钟的帧；在运行需要 ManualFrameClock 的测试时，runWithManualClock 可用于替代 runBlocking；TestUiDispatcher.Main 可让您轻松访问测试中的主界面调度程序。

  例如：

  @Test
  fun myTest() = runWithManualClock { clock ->
      // set some compose content
      withContext(TestUiDispatcher.Main) {
          clock.advanceClock(1000L)
      }
      if (clock.hasAwaiters) {
          println("The clock has awaiters")
      } else {
          println("The clock has no more awaiters")
      }
  }
  

  （I0a85b、b/161247083）

问题修复

• 弃用了 onPreCommit；onCommit 的功用现在与 onPreCommit 相同。

  现在，onCommit 和 onActive 在已提交的组成部分变更的同一 Choreographer 帧中运行，而不是在下一个 Choreographer 帧开始处运行。(I70403)

版本 1.0.0-alpha01

2020 年 8 月 26 日

发布了 androidx.compose.animation:animation:1.0.0-alpha01 和 androidx.compose.animation:animation-core:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容。

版本 0.1.0-dev

版本 0.1.0-dev17

2020 年 8 月 19 日

发布了 androidx.compose.animation:animation:0.1.0-dev17 和 androidx.compose.animation:animation-core:0.1.0-dev17。版本 0.1.0-dev17 中包含这些提交内容。

新功能

API 变更

• Offset 已成为内联类 (Iaec70)
• IntOffset 现已成为内联类 (Iac0bf)
• IntSize 现已成为内联类 (I2bf42)

• AnimatedVisibilty 可组合项可为子项内容的出现和消失添加动画效果。

  引入了 EnterTransition 和 ExitTransition，用于与 AnimatedVisibilty 可组合项结合使用，以提供 3 种不同类型的出现和消失动画：淡入淡出、滑动和展开/收缩内容。将不同类型的动画结合使用，可以实现定制程度更高的外观和风格。(Idda11)

• 弃用了 PxBounds，改为使用 Rect。使用 PxBounds 的所有情况都更新为使用 Rect，并添加了适当的弃用/替换注释，以辅助迁移。（I37038、b/162627058）

问题修复

• PlacementScope.placeAbsolute() 已重命名为 PlacementScope.place()，以前的 PlacementScope.place() 已重命名为 PlacementScope.placeRelative()。因此，PlacementScope.place() 方法将不再自动在从右到左的上下文中镜像位置。如果需要执行此镜像，请改用 PlacementScope.placeRelative()。（I873ac、b/162916675）
• 为清楚起见，现在弃用了 state { ... } 可组合项，改为对 remember { mutableStateOf(...) } 的显式调用。这样可减少管理状态所需的整体 API Surface 及概念数量，且与类属性委托的 by mutableStateOf() 模式相一致。(Ia5727)

版本 0.1.0-dev16

2020 年 8 月 5 日

发布了 androidx.compose.animation:animation:0.1.0-dev16 和 androidx.compose.animation:animation-core:0.1.0-dev16。版本 0.1.0-dev16 中包含这些提交内容。

API 变更

• 现在可通过 Foo.VectorConverter 访问用于转换内置单位的内置矢量转换器。例如 Dp.VectorConverter、Color.VectorConverter、Float.VectorConverter 等 (I3e273)
• 支持在 Modifier.animateContentSize() 中使用结束监听器，以便监听器在尺寸有变化的动画播放完毕后能够收到通知，并得知动画的开始/结束尺寸。(I277b2)
• 新增了 animateContentSize 修饰符，用于为其子修饰符的布局尺寸变化添加动画效果 (Ieffdc)

• 添加了 MonotonicFrameAnimationClock，让您能够将 MonotonicFrameClock 用作 AnimationClockObservable，以消除基于协程的新时钟与仍使用基于回调的旧时钟的 API 之间的差异。

  现在，ManualAnimationClock 的 MonotonicFrameClock 等效项是 ManualFrameClock。（I111c7、b/161247083）

问题修复

• 更新了 API 对从右到左布局的支持。添加了 LayoutDirectionAmbient，可用于读取和更改布局方向。移除了 Modifier.rtl 和 Modifier.ltr。(I080b3)
• 要求为 transitionDefinition 明确指定类型 T。(I1aded)
• foundation.shape.corner 软件包已扁平化为 foundation.share（I46491、b/161887429）
• 已弃用 Modifier.plus，现在改用 Modifier.then。“Then”能够更明确地指出先后执行顺序，同时还禁止输入会破坏链且降低可读性的 Modifier.padding().background() + anotherModifier（Iedd58、b/161529964）
• Modifier.drawBackground 已重命名为 Modifier.background (I13677)

版本 0.1.0-dev15

2020 年 7 月 22 日

发布了 androidx.compose.animation:animation:0.1.0-dev15 和 androidx.compose.animation:animation-core:0.1.0-dev15。版本 0.1.0-dev15 中包含这些提交内容。

依赖项更新

• 如需使用 Compose 的 0.1.0-dev15 版本，您需要根据上面的声明依赖项部分给出的新代码段来更新依赖项。

API 变更

• Transition API 已更改为返回 TransitionState，而不是将 TransitionState 传递给子级。这使该 API 与 animate() API 更加一致。(I24e38)
• 为淡入淡出添加了修饰符参数（I87cfe、b/159706180）
• 在顶级 API 中使用 AnimationSpec 而非 AnimationBuilder 来阐明静态动画规范的概念
  • 改进了过渡 DSL：在创建补间动画、弹性动画等 AnimationSpec 时无需再指定 lambda 要求，而是直接接受构造函数参数。
  • 提高了 AnimationSpec 的整体易用性：开放构造函数，而不是依赖于构建器
  • 将关键帧和补间动画的时长和延迟时间改为了 Int 类型的值。这样就能消除不必要的类型转换和方法重载（同时支持 Long 和 Int 两种数据类型）。(Ica0b4)
• 将使用的 IntPx 替换为了 Int。将 IntPxPosition 替换为了 IntOffset。将 IntPxSize 替换为了 IntSize。(Ib7b44)
• 为了整合用于表示大小信息的类的数量，我们对 Size 类（而非 PxSize）的使用进行了标准化。这样即可获得内联类的优势，即利用一个 long 值封装 2 个浮点数值，用于表示以浮点数表示的宽度和高度。(Ic0191)
• 为了整合用于表示位置信息的类的数量，我们对 Offset 类（而非 PxPosition）的使用进行了标准化。这样即可获得内联类的优势，即利用一个 long 值封装 2 个浮点数值，用于表示以浮点数表示的 x 轴和 y 轴偏移量。(I3ad98)
• 我们进行了大规模的重构工作，其中包括替换了各种 Compose 类中对 Px 类的使用，从而仅依赖于 Dp 和基元类型来处理像素参数 (I086f4)
• 为 Dp、Px、Size、Position、Bounds、PxPosition、PxSize、PxBounds、IntPx、IntPxSize、IntPxPosition、IntPxBounds 和 AnimationVector 添加了对 animate() 的支持 (Ib7518)
• 淡入淡出现在接受可选的 AnimationBuilder 参数，以允许配置动画 (I6d6e0)
• 将 API 中使用的所有可为 null 的 Color 替换为非 null 值，并使用 Color.Unset 代替 null (Iabaa7)
• 移除了 ValueHolder 类。重构了 AnimatedValue 和 AnimatedFloat 类，使动画值字段抽象化，以便子类可以发现值更新。
  • 为 AnimatedValue、AnimatedFloat 等添加了模型类。
  • 添加了一组新的轻量级 @Composable API，用于在值之间添加动画。(I79530)
• Ambient API 重大更改。如需了解详情，请参阅日志和 Ambient<T> 文档（I4c7ee、b/143769776）
• 新的重复模式：Reverse。当动画在 RepeatableSpec 或 VectorizedRepeatableSpec 中重复时，此模式会返回上一次迭代。(Ibe0f5)
• ManualAnimationClock 增加了 API 内容：hasObservers: Boolean 和构造函数参数 dispatchOnSubscribe: Boolean (Iaa134)
• 添加了 API 以在 AnimatedFloat 中获取最小/最大边界 (Icd9cc)

问题修复

• runOnIdleCompose 已重命名为 runOnIdle (I83607)
• 多个测试 API 已重命名，变得更为直观。所有 findXYZ API 均已重命名为 onNodeXYZ。所有 doXYZ API 均已重命名为 performXYZ。(I7f164)
• 引入了低级别无状态动画 API。这些 API (I63bf7)
• Recompose 可组合项已不再属于有效抽象。大多数重新组合都应由 MutableState 分配促成。在此之外，建议您使用 invalidate 函数来触发对当前范围的重新组合。(Ifc992)
• 我们进行了大规模的重构工作，其中包括替换了各种 Compose 类中对 Px 类的使用，从而仅依赖于 Dp 和基元类型来处理像素参数。删除了整个 Px 类 (I3ff33)
• 我们进行了大规模的重构工作，其中包括替换了各种 Compose 类中对 Px 类的使用，从而仅依赖于 Dp 和基元类型来处理像素参数 (Id3434)
• 淡入淡出现在可以将 null 用作初始值（Iad6a4、b/155947711）
• 我们进行了大规模的重构工作，其中包括替换了各种 Compose 类中对 Px 类的使用，从而仅依赖于 Dp 和基元类型来处理像素参数 (I19d02)
• 整合了 CanvasScope 实现，因此现在只有 DrawScope 和 ContentDrawScope。CanvasScope 已重命名为 DrawScope。更新了 DrawScope 以实现密度界面并提供 LayoutDirection。删除了 ContentDrawScope 中的 DrawScope 子类。Painter 和 PainterModifier 已更新，不再由自身保留 RTL 属性，因为 DrawScope 已提供此信息，无需手动提供 (I1798e)
• 更新了公开画布的更高级别的 Compose API，改为公开 CanvasScope。这样一来，用户便无需再维护自己的渲染对象。对于仍需要访问画布的使用方，可以使用 drawCanvas 扩展程序方法，该方法提供回调以向底层画布发出绘制命令。(I80afd)
• 分别向 Row 和 Column 添加了 verticalGravity 和 horizontalGravity 参数。(I7dc5a)
• ui-text 模块已重命名为 ui-text-core (I57dec)
• 改进了 DrawModifier API：
  • 确定了 draw() ContentDrawScope 的接收器范围
  • 移除了 draw() 上的所有参数
  • DrawScope 的接口与之前的 CanvasScope 接口相同
  • ContentDrawScope 具有 drawContent() 方法（Ibaced、b/152919067）
• runOnIdleCompose 和 runOnUiThread 现在是全局函数，而不是 ComposeTestRule 上的方法。(Icbe8f)
• [Mutable]State 属性委托运算符移到了扩展程序，以支持 Kotlin 1.4 属性委托优化。调用方必须添加 import 才能继续使用 by state { ... } 或 by mutableStateOf(...)。(I5312c)
• 已弃用 ColoredRect，现改用 Box(Modifier.preferredSize(width, height).drawBackground(color))。（I499fa、b/152753731）
• 将修饰符以及运算符替换成了出厂扩展函数 (I225e4)
• 弃用了 Center 可组合项。应使用 LayoutSize.Fill + LayoutAlign.Center 修饰符或应用了适当修饰符的某个 Box 或 Stack 可组合项替换 (Idf5e0)
• LayoutFlexible 已重命名为 LayoutWeight。“tight”参数已重命名为“fill”。(If4738)
• Opacity 可组合函数已替换为 drawOpacity 修饰符。(I5fb62)
• 现在，使用 AndroidComposeTestRule 的测试会在组合根目录处提供一个动画时钟，该时钟可以手动暂停、恢复和快进。(Id54c5)
• 支持 LayoutPadding 修饰符中从右向左的方向 (I9e8da)
• Density 和 DensityScope 合并到了一个接口中。现在，您可以使用 DensityAmbient.current 代替 ambientDensity()。只需 with(density) 便可代替 withDensity(density) (I11cb1)
• 为各种内联类类型添加了复制方法，包括：
  • Offset
  • Size
  • Radius
  • Motion
  • TransformOrigin
  • 弃用了 Size.copy 伴生对象方法，改为使用实例复制方法（Ife290、b/159905651）
• androidx.compose.ViewComposer 移到了 androidx.ui.node.UiComposer。移除了 androidx.compose.Emittable，它与 ComponentNode 重复。移除了 androidx.compose.ViewAdapters，它们不再是受支持的用例。已弃用 Compose.composeInto，请改为使用 setContent 或 setViewContent。已弃用 Compose.disposeComposition，改用 setContent 返回的 Composition 的 dispose 方法。androidx.compose.Compose.subcomposeInto 已移到 androidx.ui.core.subcomposeInto。ComponentNode#emitInsertAt 已重命名为 ComponentNode#insertAt。ComponentNode#emitRemoveAt 已重命名为 ComponentNode#removeAt。ComponentNode#emitMode 已重命名为 ComponentNode#move (Idef00)