Jetpack WindowManager permite que los desarrolladores de aplicaciones admitan nuevos factores de forma de dispositivos y entornos multiventana.
Las extensiones de WindowManager (extensiones) son un módulo de habilitación de la plataforma de Android que
habilita una variedad de funciones de WindowManager de Jetpack. El módulo se implementa
en AOSP en frameworks/base/libs/WindowManager/Jetpack
y se envían en dispositivos compatibles con las funciones de WindowManager.
Distribución del módulo de extensiones
Las extensiones se compilan en una biblioteca .jar
y se colocan en system_ext
en un dispositivo si las extensiones están habilitadas en el archivo makefile del dispositivo.
Para habilitar las extensiones en un dispositivo, agrega lo siguiente al dispositivo del producto makefile:
$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)
De esta manera, habilitarás androidx.window.extensions
y androidx.window.sidecar
del dispositivo y configura la propiedad persist.wm.extensions.enabled
.
Si incluyes estos paquetes en el archivo makefile, también se colocan declaraciones en
etc/permissions/
, para que estén disponibles para los procesos de la aplicación. Por lo general, el
módulos se cargan y se ejecutan como parte del proceso de la aplicación en
cuando lo usa la biblioteca WindowManager de Jetpack, lo que hace que su
operación similar al código del framework del cliente, como se muestra a continuación
figura:
El módulo androidx.window.extensions
es el módulo de extensiones actual en
y el desarrollo activo. El módulo androidx.window.sidecar
es un módulo heredado
para brindar compatibilidad con las primeras versiones de Jetpack WindowManager
pero el sidecar ya no se mantiene de forma activa.
En la siguiente figura, se muestra la lógica para determinar el uso de
androidx.window.extensions
o androidx.window.sidecar
.
androidx.window.extensions
o androidx.window.sidecar
.
Módulos de extensiones
Las extensiones proporcionan funciones de renderización en ventanas para dispositivos plegables con pantalla grande y que admiten la renderización en ventanas en pantallas externas. Las áreas de características incluyen lo siguiente:
Las implementaciones de OEM de extensiones pueden proporcionar componentes nulos o
implementaciones de stub o predeterminadas de los métodos del
WindowExtensions
si el hardware del dispositivo no admite las funciones correspondientes
a menos que la función se solicite específicamente
Documento de definición de compatibilidad (CDD) 7.1.1.1.
Extensiones y APIs de Jetpack
El módulo de extensiones de WindowManager brinda su propia superficie de API, además de
las APIs de la plataforma pública. El módulo Extensiones se desarrolla públicamente en un
para no desarrolladores androidx.window.extensions
biblioteca de Jetpack para que Jetpack WindowManager
(androidx.window
)
poder vincularlo en el tiempo de compilación. Por lo general, la plataforma de la API de Extensions
proporciona APIs de nivel inferior.
Las APIs que proporcionan las Extensiones están pensadas para que las use Jetpack. Solo la biblioteca de WindowManager. Las APIs de Extensions no están diseñadas para que las llamen desarrolladores de aplicaciones directamente. No se debe agregar la biblioteca de Extensions como dependencia de una aplicación en el archivo de compilación de Gradle para garantizar funcionalidad. Evita compilar previamente la biblioteca de Extensions en una aplicación directamente; en su lugar, confía en la carga del tiempo de ejecución para evitar que se cargue una combinación de clases de extensiones precompiladas y proporcionadas por el entorno de ejecución.
Jetpack WindowManager (androidx.window
) se debe agregar como una aplicación
y proporciona las APIs públicas orientadas al desarrollador, incluidas aquellas
para las funciones de extensiones de WindowManager. La biblioteca de WindowManager
carga extensiones en el proceso de la aplicación y une el nivel
Extensiones las APIs a abstracciones de nivel más alto y más enfocadas
interfaces. Las APIs de Jetpack WindowManager siguen los estándares de la
de aplicaciones para Android y están diseñados para brindar
a través de la integración correcta con bases de código que usan otras apps
bibliotecas.
Versiones y actualizaciones de las extensiones
El módulo de extensiones se puede actualizar junto con la plataforma de Android de forma anual o actualizaciones trimestrales. Las actualizaciones trimestrales permiten que el nivel de API de Extensions aumenta entre las actualizaciones de la API de la plataforma de Android, lo que permite una iteración y lo que les da a los OEM la oportunidad de agregar el acceso oficial a la API a las nuevas funciones cerca del lanzamiento del hardware.
En la siguiente tabla, se enumeran las androidx.window.extensions
versiones de la API para
diferentes versiones de Android.
Versión de la plataforma de Android | Nivel de API de Extensions para WindowManager | Versión de la API de androidx.window.extensions |
---|---|---|
Android 15 | 6 | 1.5.0 (próximamente) |
QPR3 para Android 14 | 5 | 1.4.0 (próximamente) |
QPR1 para Android 14 | 4 | 1.3.0 |
Android 14 | 3 | 1.2.0 |
QPR3 para Android 13 | 2 | 1.1.0 |
Android 13 | 1 | 1.0.0 |
Android 12L | 1 | 1.0.0 |
El nivel de API de Extensions (columna central) aumenta cada vez que hay una además de la superficie de API estable existente (columna derecha).
Compatibilidad con versiones anteriores y posteriores
Jetpack WindowManager controla la complejidad de lidiar con el nivel de API frecuente la evolución rápida de APIs y la retrocompatibilidad. Cuando el código de la biblioteca se ejecuta en el proceso de aplicación, la biblioteca comprueba el estado de Extensiones y proporciona acceso a las funciones según el nivel de API declarado a nivel de organización.
Para proteger una aplicación de fallas en el tiempo de ejecución, WindowManager también realiza una comprobación de reflejo de Java en tiempo de ejecución de las APIs de Extensions disponibles de acuerdo con el nivel de API de Extensions declarado. Si no hay coincidencia, WindowManager puede inhabilitar el uso de Extensiones (de forma parcial o total) e informar la funciones como no disponibles para la app.
Las extensiones de WindowManager se implementan como un módulo system_ext
que usa
para llamar al núcleo de WindowManager,
DeviceStateManager
,
y otros servicios del sistema en la implementación de las funciones de Extensiones.
Es posible que no se mantenga la compatibilidad con las versiones previas al lanzamiento de Extensiones
antes del lanzamiento trimestral o anual correspondiente de la plataforma de Android con
en la que se finalizan las versiones. Puedes consultar el historial completo de las APIs de Extensions
que se encuentra en la rama de la versión
Archivos de texto de la API de window:extensions:extensions
.
Las versiones más nuevas de las extensiones deben seguir funcionando con las versiones anteriores de Se compila WindowManager en aplicaciones para mantener la compatibilidad con versiones posteriores. Para asegúrate de que cualquier versión nueva de la API de Extensions solo agrega nuevas APIs y no quita los más antiguos. Como resultado, las aplicaciones con versiones anteriores de WindowManager pueden seguir usando las APIs de Extensiones anteriores donde se compilaron las apps y defenderte.
La verificación del CTS garantiza que cualquier versión declarada de las APIs de Extensions en todas las APIs de esa versión y de las anteriores están presentes y funcionan.
Rendimiento
El módulo Extensions se almacena en caché en cargadores de clase del sistema que no son de bootclasspath de forma predeterminada a partir de Android 14 (nivel de API 34), por lo que no hay un impacto en el rendimiento debido a la carga del módulo en la memoria durante el inicio de la app. El uso de funciones de módulos individuales puede tener una ligera influencia en las características de rendimiento de las apps cuando se realizan llamadas de IPC adicionales entre el cliente y el servidor.
Módulos
Incorporación de actividades
La Incorporación de actividades proporciona un conjunto de funciones que permiten que las aplicaciones organicen presentación de la ventana de actividad dentro de los límites de la aplicación principal. Esta incluye mostrar dos actividades simultáneamente en una diseño de varios paneles, que facilita la optimización de pantallas grandes para versiones heredadas aplicaciones.
El componente de incorporación de actividades debe estar disponible en todos los dispositivos que tengan un
pantalla integrada de un tamaño igual o superior a sw600 dp
.
La incorporación de actividades también debe habilitarse en dispositivos compatibles con pantallas externas
externas, ya que la aplicación podría mostrarse en un tamaño más grande cuando
se conectan durante el tiempo de ejecución.
Configuración del dispositivo
No se necesita ninguna configuración de dispositivo específica, salvo habilitar las extensiones. como se describe en Distribución del módulo de extensiones sección. Tiene sentido habilitar las extensiones en todos los dispositivos que admitan modo multiventana. Es probable que las versiones futuras de Android creen extensiones que se requieren en configuraciones comunes de dispositivos portátiles y de pantalla grande.
Información del diseño de la ventana
El componente de información de diseño de ventana identifica la posición y el estado de la bisagra en un dispositivo plegable cuando la bisagra cruza una ventana de la aplicación. La información de diseño de ventanas permite que las aplicaciones respondan y muestren imágenes optimizadas en el modo de mesa en dispositivos plegables. Consulta Cómo hacer que tu app funcione en dispositivos plegables para conocer los detalles de uso.
Dispositivos Android plegables que incluyen una bisagra que se conecta por separado o
las áreas de los paneles de visualización continua deben hacer que la información sobre la bisagra
disponible para las aplicaciones a través de WindowLayoutComponent
.
La posición de la bisagra y los límites deben informarse en relación con la aplicación
ventana identificada por un Context
pasado a la API. Si la ventana de la aplicación
no se cruzan con los de la bisagra, la bisagra
DisplayFeature
no se deben informar. También es aceptable no informar sobre las características de la pantalla
cuando su posición podría no ser informada de manera confiable, como cuando una aplicación
El usuario puede mover la ventana libremente en el modo multiventana.
modo letterbox de compatibilidad.
Para las funciones plegables,
se deben informar las actualizaciones de estado cuando la posición de la bisagra cambia entre los
en estados estables. De forma predeterminada, en un estado de pantalla plana, la API debe informar
FoldingFeature.State.FLAT
Si el hardware del dispositivo se puede dejar en un estado estable en modo semiplegado, el
La API debe informar FoldingFeature.State.HALF_OPENED
.
No hay un estado cerrado en la API, ya que, en ese caso, la ventana de la aplicación
no sería visible o no cruzaría los límites de la bisagra.
Configuración del dispositivo
Para admitir la implementación de la función de plegado, los OEM deben hacer lo siguiente:
Configura los estados del dispositivo en
device_state_configuration.xml
que usaráDeviceStateManagerService
ConsultaDeviceStateProviderImpl.java
para referencia.Si las implementaciones predeterminadas de
DeviceStateProvider
oDeviceStatePolicy
no son adecuadas para el dispositivo, se puede usar una implementación personalizada.Habilita el módulo Extensiones como se describe en el Distribución del módulo de extensiones.
Especifica la ubicación de las características de la pantalla en el
com.android.internal.R.string.config_display_features
. recurso de cadenas (generalmente enframeworks/base/core/res/res/values/config.xml
en la superposición del dispositivo).El formato esperado para la cadena es el siguiente:
<type>-[<left>,<top>,<right>,<bottom>]
El
type
puede serfold
ohinge
. Valores paraleft
,top
,right
ybottom
son coordenadas de píxeles enteros en el espacio de coordenadas de la pantalla en la orientación natural de la pantalla. La cadena de configuración puede contener varios los componentes de la pantalla separados por punto y coma.Por ejemplo:
<!-- Jetpack WindowManager display features --> <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
Define la asignación entre los identificadores de estado del dispositivo interno que se usan en
DeviceStateManager
y las constantes de estado público enviadas a los desarrolladores encom.android.internal.R.array.config_device_state_postures
El formato esperado para cada entrada es el siguiente:
<device_specific_state_identifier>:<Jetpack WindowManager state identifier>
Los identificadores de estado admitidos son los siguientes:
COMMON_STATE_NO_FOLDING_FEATURES = 1
: El estado no tiene atributos de plegado para . Por ejemplo, puede ser el estado cerrado del típico modo de plegado dispositivo con la pantalla principal en la parte interior.COMMON_STATE_HALF_OPENED = 2
: La función de plegado está semiabierta.COMMON_STATE_FLAT = 3
: La función plegable es plana. Por ejemplo, puede ser el estado abierto de un dispositivo plegable típico con la pantalla principal en el lado interno.COMMON_STATE_USE_BASE_STATE = 1000
: En Android 14, un valor que se puede usar para emular estados en los que el estado de la bisagra se deriva mediante el estado de base, como se define enCommonFoldingFeature.java
Consulta
DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int)
para obtener más información.Por ejemplo:
<!-- Map of System DeviceState supplied by DeviceStateManager to WindowManager posture.--> <string-array name="config_device_state_postures" translatable="false"> <item>0:1</item> <!-- CLOSED : COMMON_STATE_NO_FOLDING_FEATURES --> <item>1:2</item> <!-- HALF_OPENED : COMMON_STATE_HALF_OPENED --> <item>2:3</item> <!-- OPENED : COMMON_STATE_FLAT --> <item>3:1</item> <!-- REAR_DISPLAY : COMMON_STATE_NO_FOLDING_FEATURES --> <item>4:1000</item> <!-- CONCURRENT : COMMON_STATE_USE_BASE_STATE --> </string-array>
Área de la ventana
El componente de área de ventana proporciona un conjunto de funciones que brindan a las aplicaciones acceso a pantallas y áreas de visualización adicionales en algunos dispositivos dispositivos multipantalla.
El modo de pantalla posterior permite que una aplicación muestre la IU de vista previa de la cámara en la pantalla cubierta de un dispositivo plegable para permitir el uso de la cámara del dispositivo principal selfies y videos. Los dispositivos que tienen un navegador (tal como lo define el CDD de Android en términos de atributos como el tamaño, la densidad y posibilidades de navegación disponibles) cubren una pantalla que se alinea con el dispositivo trasero las cámaras deben proporcionar acceso al modo de pantalla posterior.
En Android 14, el modo de pantalla doble permite que las aplicaciones que se ejecutan en la pantalla interior de un dispositivo plegable muestren contenido adicional en la pantalla de la portada frente a otros usuarios. Por ejemplo, la pantalla de portada puede mostrar la vista previa de la cámara a la persona a la que se le toma una foto o se graba.
Configuración del dispositivo
Para admitir la implementación de la función de plegado, los OEM deben hacer lo siguiente:
Configura los estados del dispositivo en
device_state_configuration.xml
que usaráDeviceStateManagerService
ConsultaDeviceStateProviderImpl.java
para obtener más información.Si la implementación predeterminada de
DeviceStateProvider
oDeviceStatePolicy
no es adecuada para el dispositivo, se puede usar una implementación personalizada.En el caso de los dispositivos plegables que admiten el modo abierto o plano, especifica la opción identificadores de estado en
com.android.internal.R.array.config_openDeviceStates
.En el caso de los dispositivos plegables que admiten este estado, enumera las correspondientes identificadores de estado en
com.android.internal.R.array.config_foldedDeviceStates
.Para dispositivos plegados que admiten un estado de medio plegado (la bisagra está semiabierta) como una laptop), enumera los estados correspondientes en
com.android.internal.R.array.config_halfFoldedDeviceStates
Para dispositivos compatibles con el modo de pantalla posterior:
- Enumera los estados correspondientes en
com.android.internal.R.array.config_rearDisplayDeviceStates
paraDeviceStateManager
. - Especifica la dirección física de la pantalla posterior en
com.android.internal.R.string.config_rearDisplayPhysicalAddress
. - Especifica el identificador de estado en
com.android.internal.R.integer.config_deviceStateRearDisplay
que usarán las extensiones. - Agrega el identificador de estado en
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests
para que esté disponible para las aplicaciones.
- Enumera los estados correspondientes en
En Android 14, para dispositivos que admiten el modo de pantalla doble (simultáneo), haz lo siguiente:
- Establece
com.android.internal.R.bool.config_supportsConcurrentInternalDisplays
entrue
. - Especifica la dirección física de la pantalla posterior en
com.android.internal.R.config_deviceStateConcurrentRearDisplay
. - Especifica el identificador de estado en
com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay
que usarán las Extensiones si el identificador está destinado a estar disponible para las aplicaciones. - Agrega el identificador de estado en
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests
para que esté disponible para las aplicaciones.
- Establece
Verificación
Los OEMs deben verificar sus implementaciones para garantizar el comportamiento esperado en común. reales. Las pruebas de CTS con Jetpack WindowManager están disponibles para los OEM para probar implementaciones.
Pruebas del CTS
Para ejecutar las pruebas del CTS, consulta Cómo ejecutar pruebas del CTS. El CTS
las pruebas relacionadas con Jetpack WindowManager están en cts/tests/framework/base/windowmanager/jetpack/
.
El nombre del módulo de prueba es CtsWindowManagerJetpackTestCases
.
Pruebas de WindowManager
Para descargar las pruebas de WindowManager de Jetpack, sigue las
Instrucciones para Android Jetpack
Las pruebas se encuentran en la biblioteca de Windows, en el módulo window:window
: window/window/src/androidTest/
.
Para ejecutar las pruebas de dispositivos para el módulo window:window
desde la línea de comandos, haz lo siguiente:
lo siguiente:
- Conecta un dispositivo que tenga habilitadas las opciones para desarrolladores y la depuración por USB.
- Permite que la computadora depure el dispositivo.
- Abre un shell en el directorio raíz del repositorio de androidx.
- Cambia el directorio a
framework/support
. - Ejecuta el siguiente comando:
./gradlew window:window:connectedAndroidTest
. - Analiza los resultados.
Para ejecutar las pruebas desde Android Studio, haz lo siguiente:
- Abre Android Studio.
- Conecta un dispositivo que tenga habilitadas las opciones para desarrolladores y la depuración por USB.
- Permite que la computadora depure el dispositivo.
- Navega a una prueba dentro de la biblioteca de Window del módulo de Window.
- Abre una clase de prueba y realiza la ejecución usando las flechas verdes en el lado derecho de la Editor.
Como alternativa, puedes crear una configuración en Android Studio para ejecutar una prueba una clase de prueba o todas las pruebas de un módulo.
Los resultados se pueden analizar de forma manual si observas el resultado de la shell. Algunos las pruebas se omiten si el dispositivo no cumple con ciertas suposiciones. Los resultados son guardado en una ubicación estándar, y los analistas pueden escribir una secuencia de comandos para automatizar el análisis de los resultados.