ArrangementView en SwiftUI : styles split et overlay sur iPhone Duo

Beaucoup d'écrans sont en réalité deux vues qui vont ensemble : un lecteur et sa file d'attente, une conversation et ses photos, un podcast et sa transcription. Sur un iPhone classique, vous les empilez. Sur l'écran interne de l'iPhone Duo, vous les voulez côte à côte, et lorsque quelqu'un plie l'appareil à moitié, aucune des deux vues ne doit chevaucher le pli. ArrangementView en SwiftUI est la réponse d'Apple à ce problème. Ce guide explique ce que fait ce conteneur, ses deux styles, le fonctionnement du dimensionnement autour de la charnière et les cas où il vaut mieux choisir NavigationSplitView.

ArrangementView, ses styles et ses modificateurs de dimensionnement sont indiqués dans la documentation d'Apple comme disponibles à partir d'iOS 27.1, et il vous faut Xcode 27.1 pour compiler l'expérience iPhone Duo complète. Ces API sont nouvelles : certains détails peuvent changer d'une version à l'autre. Tout ce qui suit provient de la documentation d'Apple, du Tech Talk Strike a pose with adaptive layouts on iPhone Duo et des publications du développeur iOS Sarun Wongpatcharapakorn (@sarunw). Nous n'avons pas exécuté ce code sur un appareil réel.

Qu'est-ce qu'ArrangementView en SwiftUI ?

ArrangementView est un conteneur qui contient exactement deux vues, une principale et une secondaire, et les dispose pour vous. Dans le Tech Talk, Apple décrit les arrangements comme une nouvelle couche située entre les conteneurs de navigation et les conteneurs de contenu.

Les règles qui pilotent un arrangement s'appuient sur trois données : la size class horizontale et verticale de la vue, son rapport d'aspect et l'activation éventuelle de régions de division. Sur l'iPhone Duo, la région de division est le pli. À partir de ces données, l'arrangement décide si chaque vue apparaît et quel cadre elle reçoit. C'est la différence essentielle avec un HStack ou un VStack : une pile affiche toujours tous ses enfants, alors qu'un arrangement peut masquer la vue secondaire quand la place manque. Un ingénieur d'Apple a confirmé sur les forums développeurs que ce repli est un comportement attendu.

UIKit propose le même concept avec UIArrangementViewController, qui prend un view controller principal et un view controller secondaire. Cet article se concentre sur SwiftUI.

Comment ajouter une ArrangementView à mon app ?

Vous créez un arrangement avec deux closures finales et le placez dans un conteneur de navigation. Voici la structure utilisée par Apple dans le Tech Talk :

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

La première closure est la vue principale, et la closure secondary: est la vue secondaire. Les schémas de Sarun les appellent « First View » et « Secondary View », ce qui revient au même.

L'emplacement compte. ArrangementView ne fournit aucune navigation propre : la navigation l'entoure, elle ne se trouve pas à l'intérieur. La documentation d'Apple recommande aussi d'éviter de placer un arrangement dans une scroll view, une liste, une grille ou une navigation split view, et d'éviter de placer une navigation split view ou une tab view dans un arrangement.

Pour choisir un style, appliquez arrangementViewStyle(_:). Vous pouvez aussi limiter les axes utilisés par un arrangement :

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

Pour tout axe que vous excluez, l'arrangement n'affiche que la vue principale.

Split ou overlay : quel style d'ArrangementView choisir ?

Il existe deux styles. Le style par défaut correspond à split, et overlay est l'alternative. Ils se comportent de la même façon dans certaines positions et très différemment dans d'autres. Les termes ci-dessous suivent l'appareil : fermé signifie que vous utilisez l'écran externe, à moitié ouvert signifie partiellement plié sur l'écran interne, et ouvert signifie à plat.

Sarun résume split ainsi : il « essaie de placer chaque vue côte à côte », et s'il n'y a pas assez de place, seule la première vue s'affiche. Overlay « empile les deux vues la plupart du temps », et en position pliée les deux vues se placent côte à côte avec la First View à droite, soit l'inverse de split. La documentation d'Apple décrit le même placement : en position pliée paysage, overlay place la vue secondaire au début (leading) et la vue principale à la fin (trailing). Pour inverser cela, appliquez overlayArrangementEdge(.leading) à la vue principale.

La recommandation d'Apple pour choisir est simple. Utilisez split pour une relation principal-détail où aucune vue ne doit être recouverte, comme un podcast et sa transcription. Utilisez overlay lorsqu'il y a un premier plan et un arrière-plan clairs, comme des commandes de lecture par-dessus une vidéo. Si votre mise en page actuelle est un HStack ou un VStack, split est le choix naturel. Si c'est un ZStack, utilisez overlay.

Dans un arrangement overlay, une vue peut lire sa position dans l'empilement et adapter sa présentation. Le Tech Talk fait passer une vue en forme réduite lorsque la valeur est supérieure à zéro :

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

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

ControlsPanel représente ici votre propre vue.

Comment fonctionne splitArrangementLayoutRatio sur l'iPhone Duo ?

Par défaut, un arrangement split donne la même taille aux deux vues. Pour changer cela, appliquez splitArrangementLayoutRatio(_:) à l'une d'elles. Il prend un CGFloat optionnel compris entre zéro et un. Voici l'exemple d'Apple :

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

L'arrangement dimensionne d'abord la vue dont la layoutPriority est la plus élevée, en utilisant son ratio. Si ce ratio demande plus que l'espace restant, la vue reçoit l'espace restant à la place. Si les ratios laissent de l'espace inutilisé, la vue la plus prioritaire s'agrandit pour le remplir. Apple documente aussi des modificateurs associés pour les ratios minimum, idéal et maximum, des tailles explicites avec splitArrangementLayoutSize, ainsi que splitArrangementFixedLayoutSize.

Il existe une exception importante. Sarun indique que sur un iPhone Duo à moitié ouvert, splitArrangementLayoutRatio est ignoré et la séparation se place toujours sur la charnière, moitié-moitié. C'est logique : une répartition 30/70 placerait le bord d'un panneau en travers du pli. Concevez votre ratio pour l'écran à plat et attendez-vous à une répartition égale lorsque l'appareil est plié. Nous n'avons pas trouvé ce comportement dans la documentation d'Apple : considérez-le comme un comportement observé sous iOS 27.2.

Une répartition égale ne signifie pas des panneaux de taille égale. Dans le schéma de Sarun d'un appareil à moitié ouvert en paysage, chaque moitié de l'écran mesure 475 points, et la barre d'état occupe 84 points le long du bord droit. Le panneau secondaire est donc plus étroit. Disposez toujours le contenu selon la taille fournie plutôt que de supposer que les deux panneaux sont identiques.

Pour comprendre comment le pli lui-même est signalé, consultez comment les régions réservées décrivent le pli de l'iPhone Duo.

Quelles size classes reçoit chaque panneau d'une ArrangementView ?

Chaque panneau d'un arrangement reçoit ses propres size classes, souvent différentes de celles de la fenêtre. Sarun les a mesurées sous iOS 27.2. H correspond à l'horizontale et V à la verticale.

Deux règles en découlent. D'abord, l'axe de séparation passe en compact : côte à côte, chaque panneau reçoit une largeur compact, et empilés, chaque panneau reçoit une hauteur compact. Ensuite, sur l'écran interne, à moitié ouvert ou ouvert, les panneaux reçoivent les mêmes size classes qu'une ArrangementView sur iPad.

Un panneau situé sur un écran interne de largeur regular peut donc tout de même signaler une size class horizontale compact. Concevez chaque panneau pour qu'il réagisse à son propre environnement, et ne lisez pas les traits de la fenêtre depuis l'intérieur. Pour les valeurs au niveau de la fenêtre, consultez les size classes de l'iPhone Duo.

Vous pouvez aussi lire directement la direction de séparation. La valeur d'environnement splitArrangementAxis vaut .horizontal ou .vertical dans un arrangement split et nil en dehors. L'exemple d'Apple l'utilise pour changer la disposition interne d'un panneau :

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

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

Lorsque la vue secondaire est masquée, ses commandes disparaissent avec elle. Sur les forums, un ingénieur d'Apple a suggéré de donner à la vue essentielle une layoutPriority plus élevée pour que ce soit elle qui reste affichée. Vous pouvez aussi prévoir un bouton ou une feuille qui donne accès au contenu secondaire dans cet état.

ArrangementView ou NavigationSplitView : quand utiliser l'un ou l'autre ?

Ils résolvent des problèmes différents et ne sont pas conçus pour être imbriqués.

Utilisez NavigationSplitView lorsque les vues sont des niveaux de navigation, comme une liste d'e-mails et l'e-mail sélectionné. Les recommandations de design d'Apple indiquent que les split views s'étendent sur l'écran interne, se replient en un seul panneau sur l'écran externe et s'ajustent d'elles-mêmes au pli. Si votre app en utilise déjà une, vous n'aurez peut-être pas besoin d'ArrangementView du tout.

Utilisez ArrangementView pour deux vues qui partagent le même écran, au sein d'une même destination. Une vidéo et ses commandes, une recette et son minuteur, ou un plateau de jeu et sa feuille de score s'y prêtent parfaitement. Un modèle issu des recommandations de design d'Apple pour l'iPhone Duo est la position sur table : le contenu qui gagne à être vu à distance va sur la moitié relevée, et les commandes sur la moitié posée à plat. Des jeux comme ceux de notre page Built for the Fold montrent la force de cette disposition.

En UIKit, le même conseil s'applique à UISplitViewController et UIArrangementViewController. Sur les forums, un évangéliste d'Apple a précisé qu'Apple ne recommande pas d'intégrer un UINavigationController dans un UIArrangementViewController.

À retenir

• ArrangementView, nouveau dans iOS 27.1, dispose une vue principale et une vue secondaire selon les size classes, le rapport d'aspect et le pli. Contrairement à une pile, il peut masquer la vue secondaire.
• Split garde les deux vues dans des espaces séparés et n'affiche que la principale quand il ne peut pas diviser. Overlay les superpose sur un écran à plat et les sépare au niveau du pli, avec la principale à la fin.
• splitArrangementLayoutRatio façonne la disposition à plat. Sur un iPhone Duo à moitié ouvert, Sarun indique qu'il est ignoré et que la séparation se place sur la charnière.
• Chaque panneau reçoit ses propres size classes, et l'axe de séparation passe en compact. Lisez l'environnement à l'intérieur de chaque panneau.
• Placez ArrangementView dans un conteneur de navigation, jamais dans une liste, une scroll view ou une NavigationSplitView.

Ensuite, découvrez comment réagir à la charnière elle-même avec les états de charnière de l'iPhone Duo et onHingeChange, ou suivez la checklist de préparation de votre app pour l'iPhone Duo.