让您的应用支持折叠状态

展开后的大显示屏和独特的折叠状态为可折叠设备带来了全新的用户体验。要让您的应用支持折叠状态，请使用 Jetpack WindowManager 库，它提供了一个 API 接口，用于处理可折叠设备的窗口功能，例如折叠和铰链。当您的应用支持折叠状态时，它可以调整布局以避免将重要内容放置在折叠或铰链区域，并利用折叠和铰链作为自然分隔符。

了解设备是否支持桌面模式或书本模式等配置，可以指导您决定是否支持不同的布局或提供特定功能。

窗口信息

Jetpack WindowManager 中的 WindowInfoTracker 接口公开了窗口布局信息。该接口的 windowLayoutInfo() 方法返回一个 WindowLayoutInfo 数据流，用于向您的应用告知可折叠设备的折叠状态。WindowInfoTracker#getOrCreate() 方法创建一个 WindowInfoTracker 实例。

WindowManager 支持使用 Kotlin 流和 Java 回调收集 WindowLayoutInfo 数据。

Kotlin 流

要开始和停止 WindowLayoutInfo 数据收集，您可以使用可重启的、感知生命周期的协程，其中 repeatOnLifecycle 代码块在生命周期至少处于 STARTED 状态时执行，并在生命周期处于 STOPPED 状态时停止。当生命周期再次处于 STARTED 状态时，代码块的执行会自动重启。在以下示例中，代码块收集并使用了 WindowLayoutInfo 数据

class DisplayFeaturesActivity : AppCompatActivity() {

    private lateinit var binding: ActivityDisplayFeaturesBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        binding = ActivityDisplayFeaturesBinding.inflate(layoutInflater)
        setContentView(binding.root)

        lifecycleScope.launch(Dispatchers.Main) {
            lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
                WindowInfoTracker.getOrCreate(this@DisplayFeaturesActivity)
                    .windowLayoutInfo(this@DisplayFeaturesActivity)
                    .collect { newLayoutInfo ->
                        // Use newLayoutInfo to update the layout.
                    }
            }
        }
    }
}

Java 回调

androidx.window:window-java 依赖项中包含的回调兼容层使您无需使用 Kotlin 流即可收集 WindowLayoutInfo 更新。该工件包含 WindowInfoTrackerCallbackAdapter 类，该类可适配 WindowInfoTracker 以支持注册（和取消注册）回调，从而接收 WindowLayoutInfo 更新，例如

public class SplitLayoutActivity extends AppCompatActivity {

    private WindowInfoTrackerCallbackAdapter windowInfoTracker;
    private ActivitySplitLayoutBinding binding;
    private final LayoutStateChangeCallback layoutStateChangeCallback =
            new LayoutStateChangeCallback();

   @Override
   protected void onCreate(@Nullable Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);

       binding = ActivitySplitLayoutBinding.inflate(getLayoutInflater());
       setContentView(binding.getRoot());

       windowInfoTracker =
                new WindowInfoTrackerCallbackAdapter(WindowInfoTracker.getOrCreate(this));
   }

   @Override
   protected void onStart() {
       super.onStart();
       windowInfoTracker.addWindowLayoutInfoListener(
                this, Runnable::run, layoutStateChangeCallback);
   }

   @Override
   protected void onStop() {
       super.onStop();
       windowInfoTracker
           .removeWindowLayoutInfoListener(layoutStateChangeCallback);
   }

   class LayoutStateChangeCallback implements Consumer<WindowLayoutInfo> {
       @Override
       public void accept(WindowLayoutInfo newLayoutInfo) {
           SplitLayoutActivity.this.runOnUiThread( () -> {
               // Use newLayoutInfo to update the layout.
           });
       }
   }
}

RxJava 支持

如果您已在使用 RxJava（2 或 3 版），您可以利用一些工件，这些工件使您能够使用 Observable 或 Flowable 来收集 WindowLayoutInfo 更新，而无需使用 Kotlin 流。

androidx.window:window-rxjava2 和 androidx.window:window-rxjava3 依赖项提供的兼容层包含 WindowInfoTracker#windowLayoutInfoFlowable() 和 WindowInfoTracker#windowLayoutInfoObservable() 方法，这些方法使您的应用能够接收 WindowLayoutInfo 更新，例如

class RxActivity: AppCompatActivity {

    private lateinit var binding: ActivityRxBinding

    private var disposable: Disposable? = null
    private lateinit var observable: Observable<WindowLayoutInfo>

   @Override
   protected void onCreate(@Nullable Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);

       binding = ActivitySplitLayoutBinding.inflate(getLayoutInflater());
       setContentView(binding.getRoot());

        // Create a new observable.
        observable = WindowInfoTracker.getOrCreate(this@RxActivity)
            .windowLayoutInfoObservable(this@RxActivity)
   }

   @Override
   protected void onStart() {
       super.onStart();

        // Subscribe to receive WindowLayoutInfo updates.
        disposable?.dispose()
        disposable = observable
            .observeOn(AndroidSchedulers.mainThread())
            .subscribe { newLayoutInfo ->
            // Use newLayoutInfo to update the layout.
        }
   }

   @Override
   protected void onStop() {
       super.onStop();

        // Dispose of the WindowLayoutInfo observable.
        disposable?.dispose()
   }
}

可折叠显示屏的功能

Jetpack WindowManager 的 WindowLayoutInfo 类将显示窗口的功能作为 DisplayFeature 元素的列表提供。

FoldingFeature 是一种 DisplayFeature 类型，提供有关可折叠显示屏的信息，包括以下内容

state：设备的折叠状态，FLAT 或 HALF_OPENED
orientation：折叠或铰链的方向，HORIZONTAL 或 VERTICAL
occlusionType：折叠或铰链是否遮挡了显示屏的一部分，NONE 或 FULL
isSeparating：折叠或铰链是否创建了两个逻辑显示区域，true 或 false

处于 HALF_OPENED 状态的可折叠设备始终报告 isSeparating 为 true，因为屏幕被分成了两个显示区域。此外，在应用横跨两个屏幕的双屏设备上，isSeparating 也始终为 true。

从 DisplayFeature 继承的 FoldingFeature 的 bounds 属性表示折叠功能（如折叠或铰链）的边界矩形。边界可用于在屏幕上相对于该功能定位元素

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    ...
    lifecycleScope.launch(Dispatchers.Main) {
        lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
            // Safely collects from WindowInfoTracker when the lifecycle is
            // STARTED and stops collection when the lifecycle is STOPPED.
            WindowInfoTracker.getOrCreate(this@MainActivity)
                .windowLayoutInfo(this@MainActivity)
                .collect { layoutInfo ->
                    // New posture information.
                    val foldingFeature = layoutInfo.displayFeatures
                        .filterIsInstance<FoldingFeature>()
                        .firstOrNull()
                    // Use information from the foldingFeature object.
                }

        }
    }
}

Java

private WindowInfoTrackerCallbackAdapter windowInfoTracker;
private final LayoutStateChangeCallback layoutStateChangeCallback =
                new LayoutStateChangeCallback();

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    ...
    windowInfoTracker =
            new WindowInfoTrackerCallbackAdapter(WindowInfoTracker.getOrCreate(this));
}

@Override
protected void onStart() {
    super.onStart();
    windowInfoTracker.addWindowLayoutInfoListener(
            this, Runnable::run, layoutStateChangeCallback);
}

@Override
protected void onStop() {
    super.onStop();
    windowInfoTracker.removeWindowLayoutInfoListener(layoutStateChangeCallback);
}

class LayoutStateChangeCallback implements Consumer<WindowLayoutInfo> {
    @Override
    public void accept(WindowLayoutInfo newLayoutInfo) {
        // Use newLayoutInfo to update the Layout.
        List<DisplayFeature> displayFeatures = newLayoutInfo.getDisplayFeatures();
        for (DisplayFeature feature : displayFeatures) {
            if (feature instanceof FoldingFeature) {
                // Use information from the feature object.
            }
        }
    }
}

桌面模式

使用 FoldingFeature 对象中包含的信息，您的应用可以支持桌面模式等姿态，即手机放在表面上，铰链处于水平位置，可折叠屏幕半开。

桌面模式为用户提供了无需手持手机即可操作手机的便利。桌面模式非常适合观看媒体、拍照和进行视频通话。

使用 FoldingFeature.State 和 FoldingFeature.Orientation 来确定设备是否处于桌面模式

Kotlin

fun isTableTopPosture(foldFeature : FoldingFeature?) : Boolean {
    contract { returns(true) implies (foldFeature != null) }
    return foldFeature?.state == FoldingFeature.State.HALF_OPENED &&
            foldFeature.orientation == FoldingFeature.Orientation.HORIZONTAL
}

Java

boolean isTableTopPosture(FoldingFeature foldFeature) {
    return (foldFeature != null) &&
           (foldFeature.getState() == FoldingFeature.State.HALF_OPENED) &&
           (foldFeature.getOrientation() == FoldingFeature.Orientation.HORIZONTAL);
}

一旦您知道设备处于桌面模式，请相应地更新您的应用布局。对于媒体应用，这通常意味着将播放器放在折叠区域上方，并将控件和补充内容放在下方，以实现免提观看或收听体验。

在 Android 15（API 级别 35）及更高版本中，您可以调用同步 API 来检测设备是否支持桌面模式，无论设备当前状态如何。

该 API 提供设备支持的姿态列表。如果该列表包含桌面模式，您可以拆分应用布局以支持该姿态，并对桌面模式和全屏布局的应用界面运行 A/B 测试。

Kotlin

if (WindowSdkExtensions.getInstance().extensionsVersion >= 6) {
    val postures = WindowInfoTracker.getOrCreate(context).supportedPostures
    if (postures.contains(TABLE_TOP)) {
        // Device supports tabletop posture.
   }
}

Java

if (WindowSdkExtensions.getInstance().getExtensionVersion() >= 6) {
    List<SupportedPosture> postures = WindowInfoTracker.getOrCreate(context).getSupportedPostures();
    if (postures.contains(SupportedPosture.TABLETOP)) {
        // Device supports tabletop posture.
    }
}

示例

MediaPlayerActivity 应用：了解如何使用 Media3 Exoplayer 和 WindowManager 创建支持折叠状态的视频播放器。
使用 Jetpack WindowManager 优化可折叠设备上的相机应用 Codelab：了解如何为摄影应用实现桌面模式。在屏幕上半部分（折叠区域上方）显示取景器，在下半部分（折叠区域下方）显示控件。

书本模式

另一个独特的可折叠功能是书本模式，即设备半开且铰链垂直。书本模式非常适合阅读电子书。借助在大型可折叠屏幕上像装订书籍一样打开的两页布局，书本模式捕捉了阅读真实书籍的体验。

如果您想在免提拍照时捕捉不同的纵横比，它也可以用于摄影。

使用与桌面模式相同的技术实现书本模式。唯一的区别是代码应检查折叠功能方向是垂直而不是水平

Kotlin

fun isBookPosture(foldFeature : FoldingFeature?) : Boolean {
    contract { returns(true) implies (foldFeature != null) }
    return foldFeature?.state == FoldingFeature.State.HALF_OPENED &&
            foldFeature.orientation == FoldingFeature.Orientation.VERTICAL
}

Java

boolean isBookPosture(FoldingFeature foldFeature) {
    return (foldFeature != null) &&
           (foldFeature.getState() == FoldingFeature.State.HALF_OPENED) &&
           (foldFeature.getOrientation() == FoldingFeature.Orientation.VERTICAL);
}

窗口尺寸变化

由于设备配置更改，应用的显示区域可能会发生变化，例如设备折叠或展开、旋转或在多窗口模式下调整窗口大小。

Jetpack WindowManager WindowMetricsCalculator 类使您能够检索当前和最大窗口指标。与 API 级别 30 中引入的平台 WindowMetrics 类似，WindowManager WindowMetrics 提供窗口边界，但该 API 向后兼容至 API 级别 14。

请参阅使用窗口尺寸类别。

其他资源

示例

Jetpack WindowManager：如何使用 Jetpack WindowManager 库的示例
Jetcaster：Compose 的桌面模式实现

Codelab

了解可折叠设备

支持可折叠显示模式

让您的应用支持折叠状态 使用收藏夹保持井井有条 根据您的偏好保存内容并进行分类。

窗口信息

Kotlin 流

Java 回调

RxJava 支持

可折叠显示屏的功能

Kotlin

Java

桌面模式

Kotlin

Java

Kotlin

Java

示例

书本模式

Kotlin

Java

窗口尺寸变化

其他资源

示例

Codelab

让您的应用支持折叠状态