Fallback view

화면에 표시할 데이터가 없을 때 사용자에게 현재 상황을 알려주는 요소입니다. 단순히 비어있음을 알리는 것을 넘어, 다음에 무엇을 해야 할지 안내하는 메시지와 액션 버튼을 함께 제공하여 사용 흐름이 끊기지 않도록 돕습니다.

@MainActor struct FallbackView

Overview

데이터 없음, 검색 결과 없음(Empty) 뿐 아니라 404/네트워크 오류 등의 상태를 시각적으로 표현하고 사용자에게 적절한 안내/복구 액션을 제공합니다. 제목, 설명, 버튼 요소를 조합하여 다양한 상황에 맞는 대체(Fallback) 화면을 구성할 수 있습니다.

// 기본 사용법
FallbackView(
    description: "검색 결과가 없습니다."
)

// 버튼 1개를 사용한 예시
FallbackView(
    title: "데이터가 없습니다.",
    description: "새로운 항목을 추가해 보세요."
)
.buttonActionArea(
    .single(.init(text: "추가하기", action: { addItem() }))
)

// 버튼 2개를 가로로 배치한 예시
FallbackView(
    title: "불러올 수 없어요.",
    description: "네트워크 상태를 확인해 주세요."
)
.buttonActionArea(
    .horizontal(
        main: .init(text: "다시 시도", action: { retry() }),
        alternative: .init(text: "홈으로", action: { goHome() })
    )
)

// 상하 여백을 좁게 적용한 예시
FallbackView(
    description: "검색 결과가 없습니다."
)
.padding(.compact)

Topics

Initializers

init(title: String?, description: String)

FallbackView 컴포넌트를 초기화합니다.

  • Parameters

    ParameterDescription
    title강조되어 표시할 제목, 생략하면 기본값으로 nil 적용
    description상황을 설명하는 텍스트

  • Discussion

    원하는 레이아웃을 구성하기 위해 제목을 선택적으로 제공할 수 있습니다. 설명은 필수이며, 제목과 설명 모두 최대 2줄로 표시되고 넘치는 텍스트는 말줄임 처리됩니다.

    하단 버튼 영역과 상하 여백은 buttonActionArea(_:), padding(_:) 수정자로 구성합니다.

Instance Properties

var body: some View

뷰의 내용과 동작을 정의합니다.

Instance Methods

func buttonActionArea(ButtonActionArea?) -> FallbackView

하단 버튼 영역의 구성을 설정합니다.

  • Parameters

    ParameterDescription
    buttonActionArea하단 버튼 영역의 구성, nil을 전달하면 버튼을 표시하지 않음

  • Return Value

    수정된 FallbackView 인스턴스

func padding(Padding) -> FallbackView

콘텐츠 영역의 상하 여백 크기를 설정합니다.

  • Parameters

    ParameterDescription
    padding콘텐츠 영역의 상하 여백 크기

  • Return Value

    수정된 FallbackView 인스턴스

  • Discussion

    콘텐츠는 상위 뷰의 세로 중앙에 배치되며, 이 여백은 상위 뷰가 충분히 크지 않을 때 확보할 최소 여백입니다.

Enumerations

enum ButtonActionArea

하단 버튼 영역의 버튼 구성과 배치를 정의합니다.

  • Overview

    버튼은 항상 Assistive 색상의 외곽선(outlined) 스타일로 표시됩니다.

Structures

struct ButtonInfo

버튼에 표시할 텍스트와 탭 시 실행할 액션을 정의하는 구조체입니다.

Initializers
init(text: String, action: () -> Void)

버튼 정보를 초기화합니다.

  • Parameters

    ParameterDescription
    text버튼에 표시할 텍스트
    action버튼 탭 시 실행할 액션

Enumeration Cases

case horizontal(main: ButtonInfo, alternative: ButtonInfo)

버튼 2개를 가로로 배치합니다. 대체 버튼이 왼쪽, 주 버튼이 오른쪽에 표시됩니다.

  • Parameters

    ParameterDescription
    main주 버튼 정보
    alternative대체 버튼 정보
case single(ButtonInfo)

버튼 1개를 배치합니다.

  • Parameters

    ParameterDescription
    buttonInfo버튼 정보
case vertical(main: ButtonInfo, alternative: ButtonInfo)

버튼 2개를 세로로 배치합니다. 주 버튼이 위, 대체 버튼이 아래에 표시됩니다.

  • Parameters

    ParameterDescription
    main주 버튼 정보
    alternative대체 버튼 정보
enum Padding

콘텐츠 영역의 상하 여백 크기를 정의합니다.

Enumeration Cases

case compact

좁은 여백(80)을 적용합니다. 화면 일부 영역만 대체할 때 사용합니다.

case normal

기본 여백(160)을 적용합니다. 화면 전체를 대체할 때 사용합니다.

Relationships

Conforms To

Swift.Sendable

SwiftUICore.View

© 2026 Wanted Lab, Inc.