ArrangementView in SwiftUI: Split vs. Overlay auf dem iPhone Duo

Viele Bildschirme bestehen eigentlich aus zwei zusammengehörigen Views: ein Player und seine Warteschlange, eine Unterhaltung und ihre Fotos, ein Podcast und sein Transkript. Auf einem normalen iPhone stapeln Sie sie. Auf dem inneren Display des iPhone Duo möchten Sie sie nebeneinander haben, und wenn jemand das Gerät halb faltet, sollte keine der beiden Views über dem Knick liegen. ArrangementView in SwiftUI ist Apples Antwort auf dieses Problem. Dieser Leitfaden erklärt, was sie tut, welche zwei Stile es gibt, wie die Größenberechnung rund um das Scharnier funktioniert und wann Sie besser zu NavigationSplitView greifen.

ArrangementView, ihre Stile und die Modifier zur Größensteuerung sind in Apples Dokumentation als verfügbar ab iOS 27.1 aufgeführt, und Sie benötigen Xcode 27.1, um für das volle iPhone-Duo-Erlebnis zu bauen. Diese APIs sind neu, Details können sich also zwischen Releases ändern. Alles Folgende stammt aus Apples Dokumentation, dem Tech Talk Strike a pose with adaptive layouts on iPhone Duo und Beiträgen des iOS-Entwicklers Sarun Wongpatcharapakorn (@sarunw). Wir haben diesen Code nicht selbst auf Hardware ausgeführt.

Was ist ArrangementView in SwiftUI?

ArrangementView ist ein Container, der genau zwei Views enthält, eine primäre und eine sekundäre, und sie für Sie anordnet. Im Tech Talk beschreibt Apple Arrangements als neue Ebene, die zwischen Navigationscontainern und Inhaltscontainern liegt.

Die Regeln, nach denen eine Arrangement arbeitet, lesen drei Eingaben: die horizontale und vertikale Size Class der View, ihr Seitenverhältnis und ob Teilungsregionen aktiv sind. Auf dem iPhone Duo ist die Teilungsregion die Faltkante. Aus diesen Eingaben entscheidet die Arrangement, ob jede View erscheint und welchen Frame sie erhält. Das ist der zentrale Unterschied zu einem HStack oder VStack: Ein Stack zeigt immer jedes Kind, eine Arrangement kann dagegen die sekundäre View ausblenden, wenn kein Platz ist. Ein Apple-Ingenieur hat in den Entwicklerforen bestätigt, dass dieses Zusammenklappen erwartetes Verhalten ist.

UIKit kennt dasselbe Konzept in UIArrangementViewController, der einen primären und einen sekundären View Controller aufnimmt. Dieser Beitrag konzentriert sich auf SwiftUI.

Wie füge ich meiner App eine ArrangementView hinzu?

Sie erstellen eine Arrangement mit zwei Trailing Closures und platzieren sie in einem Navigationscontainer. Diese Form verwendet Apple im Tech Talk:

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

Die erste Closure ist die primäre View, die Closure secondary: die sekundäre. Saruns Diagramme nennen sie „First View“ und „Secondary View“, was dasselbe meint.

Die Platzierung ist wichtig. ArrangementView bringt keine eigene Navigation mit, die Navigation gehört also um sie herum, nicht in sie hinein. Apples Dokumentation rät außerdem davon ab, eine Arrangement in eine Scroll View, Liste, ein Grid oder eine Navigation Split View zu setzen, und ebenso davon, eine Navigation Split View oder Tab View in eine Arrangement zu setzen.

Um einen Stil zu wählen, wenden Sie arrangementViewStyle(_:) an. Sie können auch die Achsen einschränken, die eine Arrangement verwendet:

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

Für jede ausgelassene Achse zeigt die Arrangement nur die primäre View.

Split oder Overlay: Welchen ArrangementView-Stil sollte ich verwenden?

Es gibt zwei Stile. Der Standardstil wird zu Split aufgelöst, Overlay ist die Alternative. In manchen Haltungen verhalten sie sich gleich, in anderen sehr unterschiedlich. Die Begriffe unten richten sich nach dem Gerät: Zugeklappt bedeutet, dass Sie das äußere Display nutzen, halb geöffnet bedeutet teilweise gefaltet auf dem inneren Display, und aufgeklappt bedeutet flach.

Sarun fasst Split so zusammen: Der Stil „versucht, jede View nebeneinander zu platzieren“, und wenn nicht genug Platz ist, erscheint nur die erste View. Overlay „stapelt die beiden Views meistens“, und in einer Faltung liegen die beiden nebeneinander mit der First View rechts, also umgekehrt wie bei Split. Apples Dokumentation beschreibt dieselbe Platzierung: In einer gefalteten Querformat-Haltung setzt Overlay die sekundäre View an die führende und die primäre View an die nachgestellte Seite. Um das umzukehren, wenden Sie overlayArrangementEdge(.leading) auf die primäre View an.

Apples Empfehlung für die Wahl ist einfach. Verwenden Sie Split für eine Haupt-Detail-Beziehung, bei der keine View verdeckt werden soll, etwa ein Podcast und sein Transkript. Verwenden Sie Overlay, wenn es einen klaren Vorder- und Hintergrund gibt, etwa Wiedergabesteuerung über einem Video. Ist Ihr aktuelles Layout ein HStack oder VStack, passt Split am natürlichsten. Ist es ein ZStack, verwenden Sie Overlay.

In einer Overlay-Arrangement kann eine View ihre Stapelposition auslesen und ihre Darstellung anpassen. Der Tech Talk schaltet eine View in eine eingeklappte Form, wenn der Wert größer als null ist:

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

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

ControlsPanel steht stellvertretend für Ihre eigene View.

Wie funktioniert splitArrangementLayoutRatio auf dem iPhone Duo?

Standardmäßig gibt eine Split-Arrangement beiden Views die gleiche Größe. Um das zu ändern, wenden Sie splitArrangementLayoutRatio(_:) auf eine von ihnen an. Der Modifier nimmt einen optionalen CGFloat zwischen null und eins. Das ist Apples Beispiel:

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

Die Arrangement bemisst zuerst die View mit der höchsten layoutPriority anhand ihres Verhältnisses. Verlangt dieses Verhältnis mehr als den verbleibenden Platz, erhält die View stattdessen den verbleibenden Platz. Lassen die Verhältnisse Platz ungenutzt, wächst die View mit höherer Priorität, um ihn zu füllen. Apple dokumentiert außerdem verwandte Modifier für minimale, ideale und maximale Verhältnisse, explizite Größen mit splitArrangementLayoutSize sowie splitArrangementFixedLayoutSize.

Es gibt eine wichtige Ausnahme. Sarun berichtet, dass splitArrangementLayoutRatio auf einem halb geöffneten iPhone Duo ignoriert wird und die Teilung immer auf dem Scharnier liegt, halb und halb. Das ist logisch: Eine 30/70-Teilung würde die Kante eines Bereichs über den Knick legen. Gestalten Sie Ihr Verhältnis für das flache Display und rechnen Sie mit einer gleichmäßigen Teilung, wenn das Gerät gefaltet ist. Wir konnten dieses Verhalten nicht in Apples Dokumentation finden, betrachten Sie es also als beobachtetes Verhalten in iOS 27.2.

Gleichmäßige Teilung bedeutet nicht gleich große Bereiche. In Saruns Diagramm eines halb geöffneten Geräts im Querformat ist jede Displayhälfte 475 Punkte breit, und die Statusleiste belegt 84 Punkte entlang der rechten Kante. Der sekundäre Bereich fällt dadurch schmaler aus. Layouten Sie immer für die Größe, die Sie erhalten, statt anzunehmen, dass beide Bereiche gleich sind.

Wie die Faltkante selbst gemeldet wird, erfahren Sie unter wie Reserved Regions die Faltkante des iPhone Duo beschreiben.

Welche Size Classes erhält jeder Bereich einer ArrangementView?

Jeder Bereich einer Arrangement erhält eigene Size Classes, und diese weichen oft von denen des Fensters ab. Sarun hat sie unter iOS 27.2 gemessen. H steht für horizontal und V für vertikal.

Daraus ergeben sich zwei Regeln. Erstens wird die Teilungsachse compact: Nebeneinander erhält jeder Bereich eine kompakte Breite, gestapelt eine kompakte Höhe. Zweitens erhalten die Bereiche auf dem inneren Display, halb geöffnet oder aufgeklappt, dieselben Size Classes wie eine ArrangementView auf dem iPad.

Ein Bereich auf einem inneren Display mit regulärer Breite kann also trotzdem eine kompakte horizontale Size Class melden. Bauen Sie jeden Bereich so, dass er auf seine eigene Umgebung reagiert, und lesen Sie nicht die Traits des Fensters aus seinem Inneren. Die Werte auf Fensterebene finden Sie unter Size Classes auf dem iPhone Duo.

Sie können die Teilungsrichtung auch direkt auslesen. Der Environment-Wert splitArrangementAxis ist innerhalb einer Split-Arrangement .horizontal oder .vertical und außerhalb nil. Apples Beispiel nutzt ihn, um das innere Layout eines Bereichs umzuschalten:

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

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

Wenn die sekundäre View ausgeblendet ist, verschwinden ihre Steuerelemente mit ihr. In den Foren schlug ein Apple-Ingenieur vor, der wesentlichen View eine höhere layoutPriority zu geben, damit sie diejenige ist, die erhalten bleibt. Möglicherweise möchten Sie in diesem Zustand auch eine Schaltfläche oder ein Sheet anbieten, das den sekundären Inhalt erreichbar macht.

ArrangementView oder NavigationSplitView: Wann verwende ich was?

Sie lösen unterschiedliche Probleme und sind nicht dafür gedacht, ineinander verschachtelt zu werden.

Verwenden Sie NavigationSplitView, wenn die Views Navigationsebenen sind, etwa eine Liste von E-Mails und die ausgewählte E-Mail. Laut Apples Design-Richtlinien erweitern sich Split Views auf dem inneren Display, klappen auf dem äußeren Display zu einem einzelnen Bereich zusammen und passen sich selbstständig an die Faltkante an. Wenn Ihre App bereits eine verwendet, brauchen Sie ArrangementView möglicherweise gar nicht.

Verwenden Sie ArrangementView für zwei Views, die auf demselben Bildschirm innerhalb eines Ziels leben. Ein Video und seine Steuerung, ein Rezept und sein Timer oder ein Spielbrett und seine Punktetafel passen gut. Ein Muster aus Apples Design-Richtlinien für iPhone Duo ist die Tabletop-Haltung: Inhalte, die aus der Entfernung gut sichtbar sein sollen, kommen auf die aufgestellte Hälfte, Steuerelemente auf die flach liegende Hälfte. Spiele wie die auf unserer Seite Built for the Fold zeigen, wie stark dieses Layout sein kann.

In UIKit gilt derselbe Rat für UISplitViewController und UIArrangementViewController. In den Foren merkte ein Apple-Evangelist an, dass Apple nicht empfiehlt, einen UINavigationController in einen UIArrangementViewController einzubetten.

Das Wichtigste in Kürze

• ArrangementView, neu in iOS 27.1, ordnet eine primäre und eine sekundäre View anhand von Size Classes, Seitenverhältnis und Faltkante an. Anders als ein Stack kann sie die sekundäre View ausblenden.
• Split hält beide Views in getrennten Bereichen und zeigt nur die primäre, wenn keine Teilung möglich ist. Overlay legt sie auf einem flachen Display übereinander und trennt sie an der Faltkante, mit der primären auf der nachgestellten Seite.
• splitArrangementLayoutRatio formt das flache Layout. Auf einem halb geöffneten iPhone Duo wird es laut Sarun ignoriert, und die Teilung liegt auf dem Scharnier.
• Jeder Bereich erhält eigene Size Classes, und die Teilungsachse wird compact. Lesen Sie das Environment innerhalb jedes Bereichs.
• Setzen Sie ArrangementView in einen Navigationscontainer, niemals in eine Liste, Scroll View oder NavigationSplitView.

Erfahren Sie als Nächstes, wie Sie auf das Scharnier selbst reagieren, unter Scharnierzustände des iPhone Duo und onHingeChange, oder arbeiten Sie die Checkliste zur iPhone-Duo-Vorbereitung Ihrer App durch.