此页面由 Cloud Translation API 翻译。

Compose Material 3 自适应

API 参考文档
androidx.compose.material3.adaptive

使用 Material 3 自适应库创建自适应界面，这些界面会根据当前的窗口配置（如窗口大小类别或设备姿态）自动调整。该库同时提供默认的脚手架实现和必要的基础组件可组合项，以便您创建自己的自定义体验。

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2025 年 7 月 2 日	1.1.0	-	-	1.2.0-alpha08

声明依赖项

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

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

Groovy

dependencies {
    implementation "androidx.compose.material3.adaptive:adaptive:1.2.0-alpha08"
    implementation "androidx.compose.material3.adaptive:adaptive-layout:1.2.0-alpha08"
    implementation "androidx.compose.material3.adaptive:adaptive-navigation:1.2.0-alpha08"
}

Kotlin

dependencies {
    implementation("androidx.compose.material3.adaptive:adaptive:1.2.0-alpha08")
    implementation "androidx.compose.material3.adaptive:adaptive-layout:1.2.0-alpha08"
    implementation "androidx.compose.material3.adaptive:adaptive-navigation:1.2.0-alpha08"
}

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

反馈

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

创建新问题

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

Compose Material 3 自适应版本 1.2

版本 1.2.0-alpha08

2025 年 7 月 2 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha08。版本 1.2.0-alpha08 中包含这些提交内容。

版本 1.2.0-alpha07

2025 年 6 月 18 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha07。版本 1.2.0-alpha07 中包含这些提交内容。

API 变更

使 currentWindowAdaptiveInfo() 函数支持大号和超大号窗口宽度尺寸类别，并将 calculatePosture() 和 currentWindowDpSize() 函数提升为稳定版。(I92e97)

版本 1.2.0-alpha06

2025 年 5 月 20 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha06。版本 1.2.0-alpha06 中包含这些提交内容。

新功能

默认窗格支架指令计算函数现在支持 L 和 XL 窗口宽度大小类别。

API 变更

使 Modifier.paneExpansionDraggable 提供默认无障碍语义，并将相关 API 升级为稳定版。(Idb818)
支持使用悬浮窗格进行拖动调整大小 (Idadd3)
支持悬浮窗格的遮罩 (I9b091)

版本 1.2.0-alpha05

2025 年 5 月 7 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha05。版本 1.2.0-alpha05 中包含这些提交内容。

新功能

Material3 自适应布局现在支持悬浮自适应策略，可以将窗格变成浮动弹出式窗口。

API 变更

使当前窗口大小函数支持多平台 (Ie4172)
为悬浮窗格引入了窗格动作 (Ic9dc3)
为自适应引入了悬浮策略 (I1ba7c)

bug 修复

修复了自适应示例中协程作用域的使用问题 (7631016)

版本 1.2.0-alpha04

2025 年 4 月 23 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha04。版本 1.2.0-alpha04 中包含这些提交内容。

新功能

现在，ListDetailPaneScaffold 和 SupportingPaneScaffold 可提供重排策略，用于在单窗格布局设置下重排关联的窗格。

API 变更

向 PaneScaffoldScope 添加了可保存的状态持有者 (Id9299)
引入了用于自适应的重排策略 (I75c6a)

bug 修复

修复了窗格在首次过渡时不进行动画处理的 bug。(Ib0415)
修复了首选高度无法正常运行的问题。(I1913b)
修复了支架指令未正确更新的 bug。(0403ab)

版本 1.2.0-alpha03

2025 年 4 月 9 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha03。版本 1.2.0-alpha03 中包含这些提交内容。

bug 修复

修复了拖动控柄在单窗格布局中错误显示的问题。(806e443 )

依赖项更新

此库现在以 Kotlin 2.0 语言级别为目标，并且需要 KGP 2.0.0 或更高版本。(Idb6b5)

版本 1.2.0-alpha02

2025 年 3 月 26 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha02。版本 1.2.0-alpha02 中包含这些提交内容。

版本 1.2.0-alpha01

2025 年 3 月 12 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha01。版本 1.2.0-alpha01 中包含这些提交内容。

API 变更

引入 PaneScaffoldScope.preferredHeight 修饰符，供开发者提供窗格首选高度，该高度将与我们即将推出的新自适应策略一起应用。（I957dd、b/220960090）
将 ComponentOverride 类型重命名为 Override，并将 ComponentOverrideContext 类型重命名为 OverrideScope。(Id973c)
重命名了一些组件替换方法。(I222b3)

Compose Material3 自适应版本 1.1

版本 1.1.0

2025 年 3 月 12 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0。版本 1.1.0 中包含这些提交内容。

自 1.0.0 以来的重要变更

ListDetailPaneScaffold 和 SupportingPaneScaffold 现在支持窗格展开功能 - 用户可以拖动来更改双窗格布局的默认窗格拆分，开发者也可以通过更改新引入的 PaneExpansionState 在运行时更改窗格拆分。
NavigableListDetailPaneScaffold 和 NavigableSupportingPaneScaffold 现已支持默认的预测性返回。您还可以使用 ThreePaneScaffoldPredictiveBackHandler 通过您自己的三窗格支架实现提供预测性返回支持。
您现在可以通过向 AnimatedPane 提供不同的 EnterTransition 和 ExitTransition，自定义窗格切换期间的窗格运动。

版本 1.1.0-rc01

2025 年 2 月 26 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-rc01。版本 1.1.0-rc01 中包含这些提交内容。

bug 修复

停用三窗格支架预测性返回缩放 (ab6fd0b)

版本 1.1.0-beta02

2025 年 2 月 12 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-beta02。版本 1.1.0-beta02 中包含这些提交内容。

API 变更

更改了 MutableThreePaneScaffoldState 动画函数中 isPredictiveBackInProgress 的设置方式，以保持状态一致性。(Idc97f)

bug 修复

为与库的其余部分保持一致，NavigableListDetailPaneScaffold 和 NavigableSupportingPaneScaffold 的默认返回行为已更改为 PopUntilScaffoldValueChange。(I873f0)
设置窗格支架的正确无障碍遍历顺序。(67d030)
修复了窗格内容状态未保存的问题。(88b0ff)
支持替代无障碍操作来代替拖动。(28266d)
在当前窗格分屏发生变化后，宣布新的分屏。(0c3a80)

版本 1.1.0-beta01

2025 年 1 月 29 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-beta01。版本 1.1.0-beta01 中包含这些提交内容。

API 变更

引入了工厂函数，用于分别从开头和结尾创建偏移类型的窗格展开锚点。(I2eb21)
密封 PaneMotion 接口并移除其默认过渡方法。(Ifc4c7)
引入了用于获取当前锚点和动画显示到锚点的 API。(Icf95d)
引入了用于窗格展开的无障碍功能 API (Icc669)
将 PaneScaffoldParentData.preferredWidth 的类型更改为 DP。(Id98ee)

版本 1.1.0-alpha09

2025 年 1 月 15 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha09。版本 1.1.0-alpha09 中包含这些提交内容。

API 变更

添加并使用新的实验性注释 ExperimentalMaterial3AdaptiveComponentOverrideApi。(Id45aa)
隐藏 ThreePaneScaffoldHorizontalOrder.toLtrOrder。(I6f8d2)
ThreePaneScaffoldPredictiveBackHandler 已设为公开。（I1a995、b/370543873）
向 ThreePaneScaffoldState 添加了 isPredictiveBackInProgress 属性。（I1a995、b/370543873）
为 AnimatedPane 创建替换机制，以支持不同设备类型的旁加载实现。(Id7622)

bug 修复

修复了当稳定方向没有锚点时出现的问题。(df8257d)

版本 1.1.0-alpha08

2024 年 12 月 12 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha08。版本 1.1.0-alpha08 中包含这些提交内容。

API 变更

引入 currentWindowDpSize 函数。（I99125、b/296300441）
公开了 PaneScaffoldParentData 和 ThreePaneScaffoldHorizontalOrder.toLtrOrder() (I2d6b7)
移除 PaneScaffoldMotionScope 并将其转换为 PaneScaffoldTransitionScope 下的字段。此外，将其重命名为 PaneScaffoldMotionDataProvider，并移除对 PaneMotionData 底层数据结构的访问权限，而是提供用于访问数据的 getter 和循环方法。(Id8884)
为 ThreePaneScaffold 创建替换机制，以支持不同设备类型的旁加载实现。(I5280f)
将窗格展开状态默认设为 null（Ia65f8、b/376394520）

版本 1.1.0-alpha07

2024 年 11 月 13 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha07。版本 1.1.0-alpha07 中包含这些提交内容。

API 变更

移除了自适应库中的拖动手柄实现，并鼓励人们使用其 M3 版本。同时，引入一个修饰符，以向提供的拖动手柄可组合项提供窗格展开拖动功能。此外，还需隐藏 DraggableState 作为实现细节，以便日后根据需要进行更改。(Ib50cd)
根据 UXR 反馈，将窗格运动自定义的入口点从 scaffold 函数移至 AnimatedPane。(I10f72)
引入了对窗格展开的快速滑动支持和自定义动画规范。（Ie207d、b/362584341）

bug 修复

修复了取消时出现的预测性返回问题。（36a3e0a）、（b/369899645）

版本 1.1.0-alpha06

2024 年 10 月 30 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha06。版本 1.1.0-alpha06 中包含这些提交内容。

API 变更

在 PaneScaffoldTransitionScope.motionProgress 中添加了 FloatRange。(Iac0dd)
将可导航 scaffold 中的导航器参数类型更改为泛型。(I1da6e)

版本 1.1.0-alpha05

2024 年 10 月 16 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha05。版本 1.1.0-alpha05 中包含这些提交内容。

API 变更

引入动画规范类，以确保更一致的运动行为和未来的可扩展性。(I2d3cc)
提供运动类型，并将 PaneMotionData 中的 currentXXXXX 重命名为 originXXXX。(I7c61a)

版本 1.1.0-alpha04

2024 年 10 月 2 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha04。版本 1.1.0-alpha04 中包含这些提交内容。

新功能

向 NavigableListDetailPaneScaffold 和 NavigableSupportingPaneScaffold 添加了预测性返回支持。（I4dc21、b/359616816）

API 变更

为 ThreePaneScaffoldNavigator 添加了 ThreePaneScaffoldState。导航方法已设为 suspend，以支持带动画的导航。添加了 seekBack 以支持部分导航状态（例如预测性返回）。（I5a651、b/359616816）
添加了 MutableThreePaneScaffoldState 以控制 scaffold 值之间的过渡。现有的 ThreePaneScaffoldState 已设为只读。(Idb3c6)
公开了默认窗格运动实现 (I95a7b)
支持设置窗格展开状态的初始锚点（Ie41b3、b/362350560）

bug 修复

强制执行拖动手柄的最小触摸目标大小为 48x48dp（7ce6635、b/366018217）
在配置更改后恢复锚定位置（3c9fc6b、b/362353672）

版本 1.1.0-alpha03

2024 年 9 月 18 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha03。版本 1.1.0-alpha03 中包含这些提交内容。

版本 1.1.0-alpha02

2024 年 9 月 4 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha02。版本 1.1.0-alpha02 中包含这些提交内容。

新功能

制造商可以自定义动态效果 (I0bf9c)、(I80e66)，以便在自适应脚手架状态发生变化时更改默认动态效果。开发者可以从一组默认的进入和退出过渡效果中进行选择，也可以通过新的运动范围提供的信息实现纯自定义过渡效果。
实现了窗格展开拖动手柄的淡入淡出动画 (46e3c69)
使记住的 PaneExpansionState 可保存 (61ff76f)

API 变更

向脚手架添加了缺失的窗格展开 API (Ic5bc0)
ThreePaneScaffoldDestinationItem.content 已重命名为 contentKey。rememberListDetailPaneScaffoldNavigator 和 rememberSupportingPaneScaffoldNavigator 的默认类型实参已从 Nothing 更改为 Any。(I58749)
将 ThreePaneScaffoldState 标记为稳定 (I64aec)
使拖动手柄参数具有作用域 (Ic0aa2)

版本 1.1.0-alpha01

2024 年 8 月 21 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha01。版本 1.1.0-alpha01 中包含这些提交内容。

新功能

引入了对自适应 scaffold 的窗格展开支持。

API 变更

向公众推出了窗格展开 API (I301d6)
引入了 ThreePaneScaffoldState 来控制窗格值过渡。添加了接受此状态的 ListDetailPaneScaffold 和 SupportingPaneScaffold 过载。(I5db3b)
引入了窗格展开键和密钥提供程序接口 (Id621f)

bug 修复

修复了存在排除的铰链时分区计算错误的问题。(9dfd483)

Compose Material3 Adaptive 版本 1.0

版本 1.0.0

2024 年 9 月 4 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0。版本 1.0.0 中包含这些提交内容。

1.0.0 的主要功能

单行可组合函数 currentWindowSize()、collectFoldingFeaturesAsState() 和 currentWindowAdaptiveInfo()，用于获取所需的窗口信息以调整应用，例如窗口大小和折叠功能。
ListDetailPaneScaffold 和 SupportingPaneScaffold，以提供两种 Material3 规范布局，它们会根据不同的窗口配置自动调整自身。这两个支架还可完全自定义，以满足创作者的不同需求。
ThreePaneScaffoldNavigator 及其相关的记忆函数 rememberListDetailPaneScaffoldNavigator() 和 rememberSupportingPaneScaffoldNavigator()，以便在自适应脚手架中提供导航解决方案，与非自适应世界中常见的每次一个目的地的设置相比，该解决方案可以同时显示多个导航目的地。
更改自适应脚手架状态时的默认内置 Material 3 动画。

版本 1.0.0-rc01

2024 年 8 月 21 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

bug 修复

修复了存在排除的铰链时分区计算错误的问题。(9dfd483)

版本 1.0.0-beta04

2024 年 6 月 26 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-beta04。版本 1.0.0-beta04 中包含这些提交内容。

bug 修复

修复了以下问题：当铰链边界更新时，布局未相应更新。(71e9cf1)

版本 1.0.0-beta03

2024 年 6 月 12 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-beta03。版本 1.0.0-beta03 中包含这些提交内容。

bug 修复

修复了 beta02 中因依赖项解析不正确而导致的崩溃。

版本 1.0.0-beta02

2024 年 5 月 29 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-beta02。版本 1.0.0-beta02 中包含这些提交内容。

版本 1.0.0-beta01

2024 年 5 月 14 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-beta01。版本 1.0.0-beta01 中包含这些提交内容。

版本 1.0.0-alpha12

2024 年 5 月 1 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha12。版本 1.0.0-alpha12 中包含这些提交内容。

API 变更

向 HingeInfo 添加了 isFlat 信息（Ie0516、b/333784198）
使自适应 API 不再处于实验阶段 (I1d038)
将自适应布局 API 设为非实验性 (Id23df)
将 BackNavigationBehavior 从枚举更改为值类 (Id8757)

bug 修复

将过渡分数更改为 lambda (I6f5a9)
修复了 SizeTracker 的初始状态问题 (18326a9)
在 Posture 等值检查中包含铰链列表 (6687137)

版本 1.0.0-alpha11

2024 年 4 月 17 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha11。版本 1.0.0-alpha11 中包含这些提交内容。

API 变更

使范围接口处于密封状态。(Iefa57)
引入 AnimatedPaneScope。（I62d73、b/332750742）
使 AdaptStrategy 密封且稳定。(Ia28b2)
引入了 PaneScaffoldDirective 的复制方法。(I9291f)
将 ThreePaneScaffoldScope 标记为实验性。(I9d527)
提供易于使用的支持导航的框架 API。（I263f0、b/321010778）

版本 1.0.0-alpha10

2024 年 4 月 3 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha10。版本 1.0.0-alpha10 中包含这些提交内容。

API 变更

使默认首选宽度具有自适应性和可自定义性。(Ic3abc)
重命名了脚手架指令计算函数。(I10855)
从 scaffold API 中移除了内边距和边衬区。(I786f8)
添加了不含泛型类型的导航器记忆方法。(I607c3)

版本 1.0.0-alpha09

2024 年 3 月 20 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha09。版本 1.0.0-alpha09 中包含这些提交内容。

API 变更

向 ThreePaneScaffoldScope 添加了状态转换字段。(I3d917)
重新排序了支架参数。(I4dff5)
提供 AnimatedPane 修饰符参数的默认值。(I77dd7)

bug 修复

将分隔器大小纳入窗格动作。(a3174ca)

版本 1.0.0-alpha08

2024 年 3 月 6 日

发布了 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha08。版本 1.0.0-alpha08 中包含这些提交内容。

新功能

实现切换窗格时的延迟滑动效果。(I1a38e)

API 变更

移除了 ThreePaneScaffoldState 接口。(I63f23)

版本 1.0.0-alpha07

2024 年 2 月 21 日