Extensiones de WindowManager

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:

Figura 1: Extensiones de WindowManager cargadas en la app proceso similar al código de la plataforma.

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.

Figura 2: Árbol de decisión para acceder 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 Consulta DeviceStateProviderImpl.java para referencia.

    Si las implementaciones predeterminadas de DeviceStateProvider o DeviceStatePolicy 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 en frameworks/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 ser fold o hinge. Valores para left, top, right y bottom 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 en com.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 en CommonFoldingFeature.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 Consulta DeviceStateProviderImpl.java para obtener más información.

    Si la implementación predeterminada de DeviceStateProvider o DeviceStatePolicy 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 para DeviceStateManager.
    • 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.

  • 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 en true.
    • 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.

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:

  1. Conecta un dispositivo que tenga habilitadas las opciones para desarrolladores y la depuración por USB.
  2. Permite que la computadora depure el dispositivo.
  3. Abre un shell en el directorio raíz del repositorio de androidx.
  4. Cambia el directorio a framework/support.
  5. Ejecuta el siguiente comando: ./gradlew window:window:connectedAndroidTest.
  6. Analiza los resultados.

Para ejecutar las pruebas desde Android Studio, haz lo siguiente:

  1. Abre Android Studio.
  2. Conecta un dispositivo que tenga habilitadas las opciones para desarrolladores y la depuración por USB.
  3. Permite que la computadora depure el dispositivo.
  4. Navega a una prueba dentro de la biblioteca de Window del módulo de Window.
  5. 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.