jetpack库_通过新的Jetpack WindowManager库支持新的外形尺寸

Posted by Kenneth Ford and Andrii Kulian

肯尼斯·福特(Kenneth Ford)和安德里·库里安(Andrii Kulian)发布

WindowManager is a recent addition to Android Jetpack that aims to help application developers support new device form factors and provide a common API surface for different Window Manager features on both old and new platform versions. The initial release is aimed at foldable devices, and future versions will be extended to support more display types and window features.

WindowManager是Android Jetpack的最新功能 ，旨在帮助应用程序开发人员支持新的设备尺寸，并为新旧平台版本上的各种Window Manager功能提供通用的API表面。 初始版本面向可折叠设备，将来的版本将扩展为支持更多的显示类型和窗口功能。

我为什么需要它？ (Why would I need it?)

New foldable devices are appearing on the market that provide a set of unique hardware features. Optimizing your app for these new devices and form-factors allow you to bring a differentiating experience and allow your users to take full advantage of whatever device they are on.

新的可折叠设备出现在市场上，它们提供了一组独特的硬件功能。 针对这些新设备和外形优化应用程序可让您带来与众不同的体验，并让您的用户充分利用他们所使用的任何设备。

For example, the Samsung Galaxy Z Flip is a clamshell type of device which supports both folded and partially folded states (referred to by Samsung as Flex mode).The app can optimize its layout when the device is in the partially folded state and separate its controls on the bottom from the rest of the content on the top.

例如，三星Galaxy Z Flip是翻盖式设备，支持折叠和部分折叠状态(三星称为Flex模式 )。当设备处于部分折叠状态时，该应用可以优化其布局并将其分开控件位于底部，其余内容位于顶部。

Users can set the phone somewhere flat, like on a table, and use the bottom half of the screen to navigate and interact with the app.

用户可以将手机放在平坦的地方(例如在桌子上)，然后使用屏幕的下半部分导航和与应用交互。

The goal of the Jetpack WindowManager library is to provide a single API surface for different types of foldable devices coming to the market, so that application developers could target entire categories of devices instead of a single model.

Jetpack WindowManager库的目标是为上市的不同类型的可折叠设备提供单个API表面，以便应用程序开发人员可以针对整个设备类别而不是单个模型。

In version 1.0.0, the library provides information about two physical properties of foldable devices — display features and device state.

在版本1.0.0中 ，该库提供有关可折叠设备的两个物理属性的信息-显示功能和设备状态。

显示功能 (Display features)

A single display panel or a multi-display configuration may have different features that create disruptions in the continuous screen surface. Examples of these can be folds, hinges, curved areas, or cutouts. If there are such disruptions within the application window, the layout and placement of the content in the window can be adapted to avoid such areas, or to take advantage of them and use it as a natural separator.

单个显示面板或多个显示配置可能具有不同的功能，这些功能会在连续的屏幕表面产生干扰。 这些示例可以是折叠，铰链，弯曲区域或切口。 如果应用程序窗口中存在此类中断，则可以调整内容在窗口中的布局和位置，以避免此类区域，或者利用它们的优势并将其用作自然分隔符。

Each display feature area can be characterized by its bounding rectangle in the window coordinate space and its type. The rectangle will indicate the physical bounds of the feature. The type of the feature will help to define how to treat it. For example, some features can create physical separations and/or non-interactive areas (e.g. hinge between two display panels, display cutout), while others can serve as logical separators (e.g. fold).

每个显示特征区域都可以通过其在窗口坐标空间中的边界矩形及其类型来表征。 矩形将指示要素的物理范围。 功能的类型将有助于定义如何对待它。 例如，某些功能部件可以创建物理分隔和/或非交互式区域(例如，两个显示面板之间的铰链，显示切口)，而其他功能部件可以用作逻辑分隔符(例如，折叠)。

public class DisplayFeature {private Rect mRect;private @Type int mType;...
}

The first version of the support library includes only two types of features: TYPE_FOLD and TYPE_HINGE.

支持库的第一个版本仅包含两种类型的功能： TYPE_FOLD和TYPE_HINGE 。

@IntDef({// A fold on the screen without a physical gap.TYPE_FOLD,// A physical separation with a hinge that allows two display // panels to fold.TYPE_HINGE, 
})
public @interface Type{}

For TYPE_FOLD specifically the bounding rectangle is expected to be zero-high (0, y, width, y) or zero-wide (x, 0, x, height). This indicates that there is no inaccessible region, but it still reports the position on screen.

特别是对于TYPE_FOLD ，边界矩形应为零高(0，y，宽度，y)或零宽(x，0，x，高度)。 这表明没有不可访问的区域，但是它仍然报告屏幕上的位置。

设备状态 (Device states)

Depending on the hinge hardware design different foldable devices can have several intermediate states: closed, partially opened, fully opened (flat surface), or flipped. Using the library, apps can provide different functions depending on these device states. These states are defined as different postures:

取决于铰链硬件设计，不同的可折叠设备可以具有几种中间状态：关闭，部分打开，完全打开(平坦表面)或翻转。 使用该库，应用程序可以根据这些设备状态提供不同的功能。 这些状态定义为不同的姿势：

@IntDef({POSTURE_UNKNOWN,POSTURE_CLOSED,POSTURE_HALF_OPENED,POSTURE_OPENED,POSTURE_FLIPPED
})
public @interface Posture{}

Each device can report any subset of the postures defined above depending on their hardware and desired UX

每个设备都可以报告上面定义的姿势的任何子集，具体取决于它们的硬件和所需的用户体验

如何使用？ (How do I use it?)

To add a dependency on Window Manager, you must add the Google Maven repository to your project.

要添加对Window Manager的依赖关系，必须将Google Maven存储库添加到项目中。

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

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

dependencies {implementation "androidx.window:window:1.0.0-alpha01"
}

Let’s say you’d like to split the UI of your app like Google Duo on foldable devices. Generally, it would make sense to do so in cases when the physical configuration and state of the device creates a logical separation for the user. For example, the Galaxy Z Flip creates such logical separation when it is in “Flex” or “half-folded” mode. Therefore, you need to know the position of the fold within the app window and the state of the device.

假设您想在可折叠设备上拆分Google Duo等应用的用户界面。 通常，在设备的物理配置和状态为用户造成逻辑隔离的情况下，这样做是有意义的。 例如，Galaxy Z Flip在“ Flex”或“对折”模式下会产生这种逻辑上的分离。 因此，您需要知道折叠在应用程序窗口中的位置以及设备的状态。

First, obtain an instance of androidx.window.WindowManager from an Activity.

首先，从Activity获取androidx.window.WindowManager的实例。

var windowManager = WindowManager(this /* context */, null /* windowBackend */)

Notice the parameters here.

注意此处的参数。

First, the context is used to initialize and connect the instance of WindowManager to a visual entity on the screen. So it must be a visual Context, which means either Activity or a ContextWrapper around one.

首先，上下文用于初始化WindowManager的实例并将其连接到屏幕上的可视实体。 因此，它必须是可视的Context ，这意味着Activity或ContextWrapper围绕一个。

Second, the window backend is the provider of the information for the support library. Passing null here would mean that the default device information would be used, and the library would report no display features and unknown device state when the app runs on a regular phone. However, you can also pass a custom implementation of androidx.window.WindowBackend to emulate any kind of foldable device out there without access to the physical hardware. We show an example of this in our sample application.

其次，窗口后端是支持库信息的提供者。 在此处传递null表示将使用默认设备信息，并且当应用程序在常规手机上运行时，该库将不报告任何显示功能和未知的设备状态。 不过，您也可以传递androidx.window.WindowBackend的自定义实现，以模拟任何类型的可折叠设备，而无需访问物理硬件。 我们在示例应用程序中显示了一个示例。

Since it only makes sense to separate the UI when there is a logical hardware separation, there are two cases to do so:

由于只有在逻辑上存在硬件分离时才需要分离UI，因此有两种情况：

1. Either the type of the display feature is TYPE_HINGE and there is always a physical separation within the activity window.

   显示功能的类型为TYPE_HINGE并且活动窗口内始终存在物理分隔。

2. Or the type of the display feature is Type_Fold, and the state of the screen is not flat (e.g. not POSTURE_OPENED). For the Galaxy Z Flip specifically, we’ll be interested in POSTURE_HALF_OPENED.

   或者显示功能的类型为Type_Fold ，并且屏幕状态不平坦(例如，不是POSTURE_OPENED )。 特别是对于Galaxy Z Flip，我们将对POSTURE_HALF_OPENED感兴趣。

For the case of the fold we’ll need to learn about the device posture changes, so we’ll need to register a DeviceState change listener:

对于折叠的情况，我们需要了解设备状态变化，因此我们需要注册一个DeviceState变化侦听器：

windowManager.registerDeviceStateChangeCallback(mainThreadExecutor /* Executor */,callback /* Consumer<DeviceState> */)

In the callback you can change the device state and update the UI if needed.

在回调中，您可以更改设备状态并根据需要更新UI。

Lastly, we’ll need to get the actual display features that are located within the activity window.

最后，我们需要获取活动窗口中的实际显示功能。

val displayFeatures = windowManager.windowLayoutInfo.displayFeatures

Depending on how your activity handles (or doesn’t handle) configuration changes, you may need to ask it at different points of the Activity lifecycle. Asking for it on the layout for the window decor view will make sure that it’s always up to date after activity state changes:

根据您的活动处理(或不处理)配置更改的方式，您可能需要在“活动”生命周期的不同时间询问它。 在窗口装饰视图的布局上要求它，以确保在活动状态更改后它始终是最新的：

window.decorView.doOnLayout {val displayFeatures =windowManager.windowLayoutInfo.displayFeatures...
}

Note that the positions of display features are calculated relative to the activity window coordinate space. Therefore, it can only be provided after the activity is attached to the window. Requesting the information before that will throw an Exception.

请注意，显示要素的位置是相对于活动窗口坐标空间计算的。 因此，只能在将活动附加到窗口之后才能提供。 在此之前请求信息将引发异常。

We strongly suggest exploring the demo application for the library. It also contains examples of computing the position of display features in the view hierarchy, and an example of a layout that automatically splits the content if a dividing display feature is found.

我们强烈建议探索该库的演示应用程序 。 它还包含计算显示要素在视图层次结构中的位置的示例，以及一个布局示例，如果找到划分的显示要素， 该布局将自动拆分内容 。