SwiftUI レイアウト API リファレンス
SwiftUI アダプティブレイアウトツールの包括的な API リファレンスです。判断ガイダンスとアンチパターンについては、axiom-swiftui-layout スキルを参照してください。
概要
このリファレンスでは、アダプティブインターフェースを構築するためのすべての SwiftUI レイアウト API をカバーしています。
- ViewThatFits — 自動バリアント選択(iOS 16+)
- AnyLayout — 型消去されたアニメーション対応レイアウト切り替え(iOS 16+)
- Layout プロトコル — カスタムレイアウトアルゴリズム(iOS 16+)
- onGeometryChange — 効率的なジオメトリ読み取り(iOS 16+ にバックポート)
- GeometryReader — レイアウトフェーズでのジオメトリアクセス(iOS 13+)
- セーフエリアパディング — .safeAreaPadding() vs .padding()(iOS 17+)
- サイズクラス — トレイトベースの適応
- iOS 26 ウィンドウ API — 自由形式ウィンドウ、メニューバー、リサイズアンカー
ViewThatFits
子ビューを順に評価し、利用可能なスペースに最初に収まるものを表示します。
基本的な使い方
ViewThatFits {
// 第一候補
HStack {
icon
title
Spacer()
button
}
// 第二候補
HStack {
icon
title
button
}
// フォールバック
VStack {
HStack { icon; title }
button
}
}
軸指定
// 水平方向の適合のみを考慮
ViewThatFits(in: .horizontal) {
wideVersion
narrowVersion
}
// 垂直方向の適合のみを考慮
ViewThatFits(in: .vertical) {
tallVersion
shortVersion
}
動作の仕組み
- 各子ビューに
fixedSize()を適用 - 理想サイズを利用可能スペースに対して計測
- 最初に収まった子ビューを返す
- どれも収まらなければ最後の子ビューにフォールバック
制限事項
- どのバリアントが選択されたかを公開しない
- バリアント間のアニメーションは不可(代わりに AnyLayout を使用)
- すべてのバリアントを計測する(複雑なビューの場合はパフォーマンスに注意)
AnyLayout
型消去されたレイアウトコンテナ。レイアウト間のアニメーション遷移を可能にします。
基本的な使い方
struct AdaptiveView: View {
@Environment(\.horizontalSizeClass) var sizeClass
var layout: AnyLayout {
sizeClass == .compact
? AnyLayout(VStackLayout(spacing: 12))
: AnyLayout(HStackLayout(spacing: 20))
}
var body: some View {
layout {
ForEach(items) { item in
ItemView(item: item)
}
}
.animation(.default, value: sizeClass)
}
}
利用可能なレイアウトタイプ
AnyLayout(HStackLayout(alignment: .top, spacing: 10))
AnyLayout(VStackLayout(alignment: .leading, spacing: 8))
AnyLayout(ZStackLayout(alignment: .center))
AnyLayout(GridLayout(alignment: .leading, horizontalSpacing: 10, verticalSpacing: 10))
カスタム条件
// Dynamic Type に基づく
@Environment(\.dynamicTypeSize) var typeSize
var layout: AnyLayout {
typeSize.isAccessibilitySize
? AnyLayout(VStackLayout())
: AnyLayout(HStackLayout())
}
// ジオメトリに基づく
@State private var isWide = true
var layout: AnyLayout {
isWide
? AnyLayout(HStackLayout())
: AnyLayout(VStackLayout())
}
条件付きビューよりも使うべき理由
// ❌ ビューのIDが失われ、アニメーションしない
if isCompact {
VStack { content }
} else {
HStack { content }
}
// ✅ IDを保持し、スムーズなアニメーション
let layout = isCompact ? AnyLayout(VStackLayout()) : AnyLayout(HStackLayout())
layout { content }
Layout プロトコル
配置を完全に制御できるカスタムレイアウトコンテナを作成します。
基本的なカスタムレイアウト
struct FlowLayout: Layout {
var spacing: CGFloat = 8
func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) -> CGSize {
let sizes = subviews.map { $0.sizeThatFits(.unspecified) }
return calculateSize(for: sizes, in: proposal.width ?? .infinity)
}
func placeSubviews(in bounds: CGRect, proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) {
var point = bounds.origin
var lineHeight: CGFloat = 0
for subview in subviews {
let size = subview.sizeThatFits(.unspecified)
if point.x + size.width > bounds.maxX {
point.x = bounds.origin.x
point.y += lineHeight + spacing
lineHeight = 0
}
subview.place(at: point, proposal: .unspecified)
point.x += size.width + spacing
lineHeight = max(lineHeight, size.height)
}
}
}
// 使用例
FlowLayout(spacing: 12) {
ForEach(tags) { tag in
TagView(tag: tag)
}
}
キャッシュ付き
struct CachedLayout: Layout {
struct CacheData {
var sizes: [CGSize] = []
}
func makeCache(subviews: Subviews) -> CacheData {
CacheData(sizes: subviews.map { $0.sizeThatFits(.unspecified) })
}
func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout CacheData) -> CGSize {
// 再計測せずに cache.sizes を使用
}
}
レイアウト値
// カスタムレイアウト値を定義
struct Rank: LayoutValueKey {
static let defaultValue: Int = 0
}
extension View {
func rank(_ value: Int) -> some View {
layoutValue(key: Rank.self, value: value)
}
}
// レイアウト内で読み取り
func placeSubviews(...) {
let sorted = subviews.sorted { $0[Rank.self] < $1[Rank.self] }
}
onGeometryChange
レイアウトの副作用なしに効率的にジオメトリを読み取ります。iOS 16+ にバックポートされています。
基本的な使い方
@State private var size: CGSize = .zero
var body: some View {
content
.onGeometryChange(for: CGSize.self) { proxy in
proxy.size
} action: { newSize in
size = newSize
}
}
特定の値の読み取り
// 幅のみ
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.size.width
} action: { width in
columnCount = max(1, Int(width / 150))
}
// 座標空間内のフレーム
.onGeometryChange(for: CGRect.self) { proxy in
proxy.frame(in: .global)
} action: { frame in
globalFrame = frame
}
// アスペクト比
.onGeometryChange(for: Bool.self) { proxy in
proxy.size.width > proxy.size.height
} action: { isWide in
self.isWide = isWide
}
座標空間
// 名前付き座標空間
ScrollView {
content
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.frame(in: .named("scroll")).minY
} action: { offset in
scrollOffset = offset
}
}
.coordinateSpace(name: "scroll")
GeometryReader との比較
| アスペクト | onGeometryChange | GeometryReader |
|---|---|---|
| レイアウトへの影響 | なし | 貪欲(スペースを埋める) |
| 評価タイミング | レイアウト後 | レイアウト中 |
| 使用目的 | 副作用 | レイアウト計算 |
| iOS バージョン | 16+(バックポート) | 13+ |
GeometryReader
レイアウトフェーズ中にジオメトリ情報を提供します。貪欲なサイズ設定のため控えめに使用してください。
基本的な使い方(制約付き)
// ✅ GeometryReader は常に制約を付ける
GeometryReader { proxy in
let width = proxy.size.width
HStack(spacing: 0) {
Rectangle().frame(width: width * 0.3)
Rectangle().frame(width: width * 0.7)
}
}
.frame(height: 100) // 必須の制約
GeometryProxy プロパティ
GeometryReader { proxy in
// コンテナサイズ
let size = proxy.size // CGSize
// セーフエリアインセット
let insets = proxy.safeAreaInsets // EdgeInsets
// 座標空間内のフレーム
let globalFrame = proxy.frame(in: .global)
let localFrame = proxy.frame(in: .local)
let namedFrame = proxy.frame(in: .named("container"))
}
よくあるパターン
// 比例サイズ設定
GeometryReader { geo in
VStack {
header.frame(height: geo.size.height * 0.2)
content.frame(height: geo.size.height * 0.8)
}
}
// オフセットによる中央揃え
GeometryReader { geo in
content
.position(x: geo.size.width / 2, y: geo.size.height / 2)
}
よくある間違いの回避
// ❌ VStack 内で制約なし
VStack {
GeometryReader { ... } // すべてのスペースを占有
Button("Next") { } // 見えなくなる
}
// ✅ 制約付き
VStack {
GeometryReader { ... }
.frame(height: 200)
Button("Next") { }
}
// ❌ レイアウトループの原因
GeometryReader { geo in
content
.frame(width: geo.size.width) // 無限ループの可能性
}
セーフエリアパディング
SwiftUI はコンテンツの周囲のスペーシングを処理するための2つの主要なアプローチを提供します: .padding() と .safeAreaPadding()。いつどちらを使うべきかを理解することは、ノッチ、Dynamic Island、ホームインジケーターがあるデバイスで適切なレイアウトを実現するために重要です。
重要な違い
// ❌ 間違い - セーフエリアを無視し、コンテンツがノッチ/ホームインジケーターに被る
ScrollView {
content
}
.padding(.horizontal, 20)
// ✅ 正しい - セーフエリアを尊重し、その外側にパディングを追加
ScrollView {
content
}
.safeAreaPadding(.horizontal, 20)
重要な洞察: .padding() はビューの端から固定のスペーシングを追加します。.safeAreaPadding() はセーフエリアインセットの外側にスペーシングを追加します。
それぞれを使うべき場合
.padding() を使う場合
- コンテナ内の兄弟ビュー間にスペーシングを追加するとき
- どこでも一貫した内部スペーシングを作成するとき
- List や Form など、すでにセーフエリアを尊重するビューを扱うとき
- macOS で装飾的なスペーシングを追加するとき(セーフエリアの懸念なし)
VStack(spacing: 0) {
header
.padding(.horizontal, 16) // ✅ 内部スペーシング
Divider()
content
.padding(.horizontal, 16) // ✅ 内部スペーシング
}
.safeAreaPadding() を使う場合(iOS 17+)
- 画面端まで広がる全幅コンテンツにマージンを追加するとき
- 適切なインセットを備えたエッジツーエッジのスクロールを実装するとき
- セーフエリア認識が必要なカスタムコンテナを作成するとき
- Liquid Glass やフルスクリーンマテリアルを扱うとき
// ✅ カスタムパディング付きエッジツーエッジリスト
List(items) { item in
ItemRow(item)
}
.listStyle(.plain)
.safeAreaPadding(.horizontal, 20) // セーフエリアの外側に20pt追加
// ✅ 適切なマージン付きフルスクリーンコンテンツ
ZStack {
Color.blue.ignoresSafeArea()
VStack {
content
}
.safeAreaPadding(.all, 16) // ノッチ、ホームインジケーターを尊重
}
プラットフォームの可用性
iOS 17+、iPadOS 17+、macOS 14+、axiom-visionOS 1.0+
それ以前の iOS バージョンでは、手動でセーフエリアを処理します:
// iOS 13-16 フォールバック
GeometryReader { geo in
content
.padding(.horizontal, 20 + geo.safeAreaInsets.leading)
}
または条件付きコンパイル:
if #available(iOS 17, *) {
content.safeAreaPadding(.horizontal, 20)
} else {
content.padding(.horizontal, 20)
.padding(.leading, safeAreaInsets.leading)
}
エッジ固有の使用法
// 上部のみ(ステータスバー/ノッチの下)
.safeAreaPadding(.top, 8)
// 下部のみ(ホームインジケーターの上)
.safeAreaPadding(.bottom, 16)
// 水平(セーフエリアの左右)
.safeAreaPadding(.horizontal, 20)
// すべてのエッジ
.safeAreaPadding(.all, 16)
// 個別のエッジ
.safeAreaPadding(EdgeInsets(top: 8, leading: 20, bottom: 16, trailing: 20))
よくあるパターン
エッジツーエッジ ScrollView
ScrollView {
LazyVStack(spacing: 12) {
ForEach(items) { item in
ItemCard(item)
}
}
}
.safeAreaPadding(.horizontal, 16) // 端 + セーフエリアからのコンテンツインセット
.safeAreaPadding(.vertical, 8)
フルスクリーン背景と安全なコンテンツ
ZStack {
// 背景はエッジツーエッジに広がる
LinearGradient(...)
.ignoresSafeArea()
// コンテンツはセーフエリア + カスタムパディングを尊重
VStack {
header
Spacer()
content
Spacer()
footer
}
.safeAreaPadding(.all, 20)
}
ネストされたパディング(組み合わせアプローチ)
// 外側: デバイスインセット用のセーフエリアパディング
VStack(spacing: 0) {
content
}
.safeAreaPadding(.horizontal, 16) // セーフエリアの外側
// 内側: 内部スペーシング用の通常パディング
VStack {
Text("Title")
.padding(.bottom, 8) // 内部スペーシング
Text("Subtitle")
}
判断木
コンテンツは画面端まで広がりますか?
├─ YES → .safeAreaPadding() を使用
│ ├─ スクロール可能ですか? → .safeAreaPadding(.horizontal/.vertical)
│ └─ フルスクリーンですか? → .safeAreaPadding(.all)
│
└─ NO(List/Form のような安全なコンテナ内に収まっている)
└─ 内部スペーシングには .padding() を使用
視覚的デバッグ
// セーフエリアパディングの可視化(iOS 17+)
content
.safeAreaPadding(.horizontal, 20)
.background(.red.opacity(0.2)) // パディング領域を表示
.border(.blue) // コンテンツ境界を表示
手動セーフエリア処理からの移行
// ❌ 旧: 手動計算(iOS 13-16)
GeometryReader { geo in
content
.padding(.top, geo.safeAreaInsets.top + 16)
.padding(.bottom, geo.safeAreaInsets.bottom + 16)
.padding(.horizontal, 20)
}
// ✅ 新: .safeAreaPadding()(iOS 17+)
content
.safeAreaPadding(.vertical, 16)
.safeAreaPadding(.horizontal, 20)
関連 API
.safeAreaInset(edge:) - セーフエリアを縮小する永続的なコンテンツを追加:
ScrollView {
content
}
.safeAreaInset(edge: .bottom) {
// これによりセーフエリアが REDUCE され、コンテンツはその下にスクロールする
toolbarButtons
.padding()
.background(.ultraThinMaterial)
}
.ignoresSafeArea() - セーフエリアを完全に無効化:
Color.blue
.ignoresSafeArea() // 絶対的な画面端まで広がる
なぜ重要か
iOS 17 以前: 開発者は GeometryReader を使って手動でセーフエリアインセットを計算しなければならず、以下の問題を引き起こしていました:
- 冗長なコード
- パフォーマンスのオーバーヘッド(GeometryReader は余分なレイアウトパスを強制)
- 間違いが起こりやすい(すべてのエッジをチェックし忘れる)
iOS 17+: .safeAreaPadding() が提供するもの:
- 宣言的 API(SwiftUI の哲学に合致)
- 自動セーフエリア認識
- 優れたパフォーマンス(余分なレイアウトパスなし)
- 型安全なエッジ指定
現実世界での影響
…[翻訳のため省略]