ArrangementView en SwiftUI: estilo split vs overlay en iPhone Duo

Muchas pantallas son en realidad dos vistas que van juntas: un reproductor y su cola, una conversación y sus fotos, un podcast y su transcripción. En un iPhone normal las apilas. En la pantalla interior de iPhone Duo las quieres lado a lado, y cuando alguien pliega el dispositivo a medias, ninguna vista debería quedar sobre el pliegue. ArrangementView en SwiftUI es la respuesta de Apple a ese problema. Esta guía explica qué hace, los dos estilos, cómo funciona el dimensionado alrededor de la bisagra y cuándo conviene usar NavigationSplitView en su lugar.

La documentación de Apple indica que ArrangementView, sus estilos y los modificadores de tamaño están disponibles en iOS 27.1 y posteriores, y necesitas Xcode 27.1 para compilar la experiencia completa de iPhone Duo. Estas API son nuevas, así que los detalles pueden cambiar entre versiones. Todo lo que sigue procede de la documentación de Apple, del Tech Talk Strike a pose with adaptive layouts on iPhone Duo y de publicaciones del desarrollador de iOS Sarun Wongpatcharapakorn (@sarunw). No hemos ejecutado este código en hardware.

¿Qué es ArrangementView en SwiftUI?

ArrangementView es un contenedor que contiene exactamente dos vistas, una principal y una secundaria, y las distribuye por ti. En el Tech Talk, Apple describe las disposiciones (arrangements) como una nueva capa situada entre los contenedores de navegación y los contenedores de contenido.

Las reglas que gobiernan una disposición leen tres entradas: la clase de tamaño horizontal y vertical de la vista, su proporción y si hay alguna región de división activa. En iPhone Duo, la región de división es el pliegue. A partir de esas entradas, la disposición decide si cada vista aparece y qué marco recibe. Esa es la diferencia clave con un HStack o un VStack: una pila siempre muestra todos sus hijos, pero una disposición puede ocultar la vista secundaria cuando no hay espacio. Un ingeniero de Apple confirmó en los foros de desarrolladores que este colapso es el comportamiento esperado.

UIKit tiene el mismo concepto en UIArrangementViewController, que recibe un view controller principal y uno secundario. Este artículo se centra en SwiftUI.

¿Cómo añado un ArrangementView a mi app?

Creas una disposición con dos closures finales y la colocas dentro de un contenedor de navegación. Esta es la estructura que usa Apple en el Tech Talk:

var body: some View {
    NavigationStack {
        ArrangementView {
            PlayerView()
        } secondary: {
            UpNextView()
        }
    }
}

El primer closure es la vista principal, y el closure secondary: es la secundaria. Los diagramas de Sarun las llaman "First View" y "Secondary View", que es lo mismo.

La ubicación importa. ArrangementView no ofrece navegación propia, así que la navegación va alrededor, no dentro. La documentación de Apple también dice que evites poner una disposición dentro de un scroll view, una lista, una cuadrícula o un navigation split view, y que evites poner un navigation split view o un tab view dentro de una disposición.

Para elegir un estilo, aplica arrangementViewStyle(_:). También puedes limitar los ejes que usa una disposición:

ArrangementView {
    NowPlayingView()
} secondary: {
    LyricsView()
}
.arrangementViewStyle(.split.axes(.horizontal))

En cualquier eje que excluyas, la disposición muestra solo la vista principal.

Split vs overlay: ¿qué estilo de ArrangementView debo usar?

Hay dos estilos. El estilo por defecto se resuelve como split, y overlay es la alternativa. Se comportan igual en algunas posturas y de forma muy distinta en otras. Los términos siguientes se refieren al dispositivo: cerrado significa que usas la pantalla exterior, medio abierto significa parcialmente plegado en la pantalla interior y abierto significa plano.

Sarun resume split así: "intentará poner cada vista lado a lado", y si no hay espacio suficiente, solo se muestra la primera vista. Overlay "apila las dos vistas la mayor parte del tiempo", y en un pliegue las dos quedan lado a lado con First View a la derecha, lo contrario que split. La documentación de Apple describe la misma colocación: en una postura plegada en horizontal, overlay pone la vista secundaria al inicio y la principal al final. Para invertirlo, aplica overlayArrangementEdge(.leading) a la vista principal.

La pauta de Apple para elegir es sencilla. Usa split para una relación principal-detalle en la que ninguna vista deba quedar tapada, como un podcast y su transcripción. Usa overlay cuando haya un primer plano y un fondo claros, como controles de reproducción sobre un vídeo. Si tu diseño actual es un HStack o un VStack, split es el equivalente natural. Si es un ZStack, usa overlay.

En una disposición overlay, una vista puede leer su posición en la pila y cambiar su presentación. El Tech Talk cambia una vista a una forma contraída cuando el valor es mayor que cero:

struct PlayerControls: View {
    @Environment(\.overlayArrangementZIndex)
    private var zIndex: Int

    var body: some View {
        ControlsPanel(isCollapsed: zIndex > 0)
    }
}

ControlsPanel representa tu propia vista.

¿Cómo funciona splitArrangementLayoutRatio en iPhone Duo?

Por defecto, una disposición split da el mismo tamaño a ambas vistas. Para cambiarlo, aplica splitArrangementLayoutRatio(_:) a una de ellas. Recibe un CGFloat opcional entre cero y uno. Este es el ejemplo de Apple:

ArrangementView {
    ConversationView()
        .splitArrangementLayoutRatio(0.3)
} secondary: {
    PhotosView()
}
.arrangementViewStyle(.split.axes(.horizontal))

La disposición dimensiona primero la vista con mayor layoutPriority, usando su proporción. Si esa proporción pide más que el espacio restante, la vista recibe el espacio restante. Si las proporciones dejan espacio sin ocupar, la vista de mayor prioridad crece para llenarlo. Apple también documenta modificadores relacionados para proporciones mínima, ideal y máxima, tamaños explícitos con splitArrangementLayoutSize y splitArrangementFixedLayoutSize.

Hay una excepción importante. Sarun informa de que en un iPhone Duo medio abierto, splitArrangementLayoutRatio se ignora y la división siempre queda sobre la bisagra, mitad y mitad. Tiene sentido: una división 30/70 pondría el borde de un panel sobre el pliegue. Diseña tu proporción para la pantalla plana y espera una división a partes iguales cuando el dispositivo esté plegado. No hemos encontrado este comportamiento descrito en la documentación de Apple, así que tómalo como comportamiento observado en iOS 27.2.

Una división a partes iguales no significa paneles del mismo tamaño. En el diagrama de Sarun de un dispositivo medio abierto en horizontal, cada mitad de la pantalla mide 475 puntos, y la barra de estado ocupa 84 puntos a lo largo del borde derecho. Como resultado, el panel secundario queda más estrecho. Distribuye siempre según el tamaño que recibes, en lugar de suponer que los dos paneles coinciden.

Para saber cómo se informa del propio pliegue, consulta cómo describen las regiones reservadas el pliegue de iPhone Duo.

¿Qué clases de tamaño recibe cada panel de ArrangementView?

Cada panel de una disposición recibe sus propias clases de tamaño, y a menudo difieren de las de la ventana. Sarun las midió en iOS 27.2. H es horizontal y V es vertical.

De aquí salen dos reglas. Primera: el eje de división pasa a compact; lado a lado da a cada panel un ancho compact, y apiladas da a cada panel un alto compact. Segunda: en la pantalla interior, medio abierta o abierta, los paneles reciben las mismas clases de tamaño que un ArrangementView en iPad.

Así, un panel situado en una pantalla interior de ancho regular puede seguir informando de una clase de tamaño horizontal compact. Construye cada panel para que responda a su propio entorno y no leas los traits de la ventana desde dentro. Para los valores a nivel de ventana, consulta clases de tamaño en iPhone Duo.

También puedes leer directamente la dirección de la división. El valor de entorno splitArrangementAxis es .horizontal o .vertical dentro de una disposición split y nil fuera de ella. El ejemplo de Apple lo usa para cambiar el diseño interno de un panel:

struct DetailsView: View {
    @Environment(\.splitArrangementAxis) var axis

    var body: some View {
        let layout: AnyLayout = axis == .horizontal
            ? AnyLayout(VStackLayout())
            : AnyLayout(HStackLayout())
        layout {
            Artwork()
            Metadata()
        }
    }
}

Cuando la vista secundaria está oculta, sus controles se van con ella. En los foros, un ingeniero de Apple sugirió dar a la vista esencial una layoutPriority más alta para que sea la que permanezca. También puede interesarte un botón o una hoja que dé acceso al contenido secundario en ese estado.

ArrangementView vs NavigationSplitView: ¿cuándo usar cada uno?

Resuelven problemas distintos y no están pensados para anidarse.

Usa NavigationSplitView cuando las vistas son niveles de navegación, como una lista de correos y el correo seleccionado. Las pautas de diseño de Apple dicen que las split views se expanden en la pantalla interior, se contraen a un solo panel en la exterior y se ajustan al pliegue por sí solas. Si tu app ya usa una, puede que no necesites ArrangementView en absoluto.

Usa ArrangementView para dos vistas que conviven en la misma pantalla, dentro de un mismo destino. Un vídeo y sus controles, una receta y su temporizador, o un tablero de juego y su marcador encajan bien. Un patrón de las pautas de diseño de Apple para iPhone Duo es la postura de mesa: el contenido que se beneficia de verse a distancia va en la mitad erguida y los controles en la mitad apoyada. Juegos como los de nuestra página Built for the Fold muestran lo potente que puede ser ese diseño.

En UIKit, el mismo consejo se aplica a UISplitViewController y UIArrangementViewController. En los foros, un evangelista de Apple señaló que Apple no recomienda incrustar un UINavigationController dentro de un UIArrangementViewController.

Conclusiones clave

• ArrangementView, nuevo en iOS 27.1, distribuye una vista principal y una secundaria usando las clases de tamaño, la proporción y el pliegue. A diferencia de una pila, puede ocultar la vista secundaria.
• Split mantiene ambas vistas en espacios separados y muestra solo la principal cuando no puede dividir. Overlay las superpone en una pantalla plana y las separa en el pliegue, con la principal al final.
• splitArrangementLayoutRatio define el diseño en plano. En un iPhone Duo medio abierto, Sarun informa de que se ignora y la división queda sobre la bisagra.
• Cada panel recibe sus propias clases de tamaño, y el eje de división pasa a compact. Lee el entorno dentro de cada panel.
• Pon ArrangementView dentro de un contenedor de navegación, nunca dentro de una lista, un scroll view o un NavigationSplitView.

A continuación, aprende a reaccionar a la propia bisagra en estados de la bisagra de iPhone Duo y onHingeChange, o repasa la lista de comprobación para preparar tu app para iPhone Duo.