Communitygithub.com

ComeOnOliver/skillshub

リファレンス — SwiftUI アダプティブレイアウト API 完全ガイド。ViewThatFits、AnyLayout、Layout プロトコル、onGeometryChange、GeometryReader、サイズクラス、iOS 26 ウィンドウ API を網羅

skillshub とは?

このスキルは、SwiftUI アダプティブレイアウトに特化した包括的な API リファレンスです。ViewThatFits、AnyLayout、Layout プロトコル、onGeometryChange、GeometryReader、Safe Area Padding、サイズクラス、iOS 26 のウィンドウ関連 API など、iOS 16+ 以降の主要なレイアウトツールを実用的なコード例と共に解説します。開発者は、条件分岐や GeometryReader の過剰使用によるパフォーマンス低下やレイアウトループのリスクを回避しながら、真にアダプティブでアニメーション可能な UI を構築できます。Claude Code、Cursor、Codex などの AI エージェント向けに設計されており、各 API の基本的な使い方から、キャッシュ機構、LayoutValueKey、セーフエリアの考慮まで、現実の開発現場で即座に利用できる知識が詰まっています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-swiftui-layout-ref

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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
}

動作の仕組み

  1. 各子ビューに fixedSize() を適用
  2. 理想サイズを利用可能スペースに対して計測
  3. 最初に収まった子ビューを返す
  4. どれも収まらなければ最後の子ビューにフォールバック

制限事項

  • どのバリアントが選択されたかを公開しない
  • バリアント間のアニメーションは不可(代わりに 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 との比較

アスペクトonGeometryChangeGeometryReader
レイアウトへの影響なし貪欲(スペースを埋める)
評価タイミングレイアウト後レイアウト中
使用目的副作用レイアウト計算
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 の哲学に合致)
  • 自動セーフエリア認識
  • 優れたパフォーマンス(余分なレイアウトパスなし)
  • 型安全なエッジ指定

現実世界での影響

…[翻訳のため省略]

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

関連スキル