Top navigation

앱과 모바일 웹의 최상단에 위치하는 주요 탐색 요소입니다. 사용자가 서비스의 핵심 섹션과 기능에 빠르게 접근할 수 있도록 돕습니다.

@MainActor struct TopNavigation

Overview

제목, 뒤로가기, 추가 액션 버튼 등을 포함할 수 있으며, 다양한 외관 스타일을 지원합니다. 스크롤 시 배경색과 구분선의 불투명도가 자동으로 조절됩니다.

TopNavigation(scrollOffset: 0)
.variant(.normal)
.backgroundColor(.white)
.title("제목")
.leadingContent { /* 왼쪽 영역 컴포넌트 */ }
.trailingContents(
    { /* 컴포넌트1 */ },
    { /* 컴포넌트2 */ }
)

TopNavigation(scrollOffset: 0)
.variant(.floating)
.backgroundColor(.white)
.titleView { /* 제목 컴포넌트 */ }
.leadingContent { /* 왼쪽 영역 컴포넌트 */ }
.trailingContents(
    { /* 컴포넌트1 */ },
    { /* 컴포넌트2 */ }
)

Topics

Structures

struct LeadingButton

내비게이션 바의 왼쪽(leading) 영역에 위치하는 기본 버튼입니다.

  • Overview

    뒤로가기, 아이콘 버튼, 텍스트 버튼 등의 다양한 형태를 제공합니다.

    LeadingButton(
    .back { dismiss() }
)

    버튼이 없을 경우에는 투명한 공간을 차지하여 레이아웃이 유지됩니다.

Initializers

init(Resource.Leading?)

내비게이션 바의 왼쪽(leading) 영역에 위치하는 기본 버튼을 초기화합니다.

  • Parameters

    ParameterDescription
    action버튼 액션

Instance Properties

var body: some View

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

struct TrailingIconButton

내비게이션 바의 오른쪽(trailing)에 위치하는 아이콘 버튼입니다.

  • Overview

    푸시 뱃지 등을 옵션으로 설정할 수 있습니다.

    TrailingIconButton(
    icon: .bell,
    showPushBadge: true
) {
    // 버튼 액션
}
.disabled(true)

    Note

    비활성화는 SwiftUI 표준 disabled(_:)를 사용합니다.

Initializers

init(icon: Icon, showPushBadge: Bool, action: () -> Void)

내비게이션 바의 오른쪽(trailing)에 위치하는 아이콘 버튼을 초기화합니다.

  • Parameters

    ParameterDescription
    icon아이콘 버튼의 아이콘
    showPushBadgePushBadge의 노출 여부, 생략하면 기본값으로 false 적용
    action아이콘 버튼 클릭시 동작할 액션

Instance Properties

var body: some View

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

struct TrailingTextButton

내비게이션 바의 오른쪽(trailing)에 위치하는 텍스트 버튼입니다.

  • Overview

    TrailingTextButton(text: "확인") {
    // 버튼 액션
}
.disabled(isFormInvalid)

    Note

    비활성화는 SwiftUI 표준 disabled(_:)를 사용합니다.

Initializers

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

내비게이션 바의 오른쪽(trailing)에 위치하는 텍스트 버튼을 초기화합니다.

  • Parameters

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

Instance Properties

var body: some View

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

Initializers

init(scrollOffset: CGFloat?)

TopNavigation을 초기화합니다.

  • Parameters

    ParameterDescription
    scrollOffset스크롤 오프셋 값. 생략하면 ScreenScaffold가 내려 주는 값을 씁니다. 스캐폴드 밖에서 생략하면 최상단(0)으로 봅니다

Instance Properties

var body: some View

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

Instance Methods

func backgroundColor(SwiftUI.Color) -> TopNavigation

내비게이션 바의 배경색을 설정합니다.

  • Parameters

    ParameterDescription
    backgroundColor배경색

  • Return Value

    수정된 내비게이션 바 인스턴스

func leadingContent<V>(() -> V) -> TopNavigation

내비게이션 영역의 왼쪽(leadingContent) 영역에 표시할 뷰를 설정합니다.

  • Parameters

    ParameterDescription
    contentleadingContent 영역에 표시할 뷰를 반환하는 클로저

  • Return Value

    수정된 인스턴스를 반환합니다.

  • Discussion

    주로 아이콘이나 취소 버튼 등을 배치할 수 있으며, ViewBuilder를 통해 정의됩니다.

func searchField(placeholder: String?, searchTerm: Binding<String>, focused: Binding<Bool>?, onSubmit: (() -> Void)?, onTextChange: ((String) -> Void)?, onFocusChange: ((Bool) -> Void)?) -> TopNavigation

검색 필드의 속성과 동작을 설정합니다. variant가 .search일 때만 적용됩니다.

  • Parameters

    ParameterDescription
    placeholder검색 필드에 표시할 플레이스홀더 텍스트, 생략하면 기본값으로 nil 적용
    searchTerm검색어 바인딩 변수
    focused검색 필드의 포커스 상태 바인딩 변수, 생략하면 기본값으로 nil 적용
    onSubmit검색어 제출 시 호출될 클로저, 생략하면 기본값으로 nil 적용
    onTextChange검색어 텍스트 변경 시 호출될 클로저, 생략하면 기본값으로 nil 적용
    onFocusChange검색 필드 포커스 변경 시 호출될 클로저, 생략하면 기본값으로 nil 적용

  • Return Value

    수정된 인스턴스를 반환합니다.

func title(String) -> TopNavigation

텍스트 기반 타이틀을 설정합니다.

  • Parameters

    ParameterDescription
    text타이틀에 표시할 문자열

  • Return Value

    수정된 내비게이션 바 인스턴스

  • Discussion

    Note

    titleView(_:)와 함께 사용될 경우 이 메서드로 설정된 텍스트만 표시됩니다.

func titleView<V>(() -> V) -> TopNavigation

내비게이션 영역의 타이틀 뷰를 설정합니다.

  • Parameters

    ParameterDescription
    content표시할 타이틀 뷰를 반환하는 클로저

  • Return Value

    수정된 인스턴스를 반환합니다.

  • Discussion

    타이틀에는 텍스트 또는 커스텀 뷰를 사용할 수 있으며, ViewBuilder를 통해 정의됩니다.

    Note

    Title(:)와 함께 사용될 경우 title(:) 메서드로 설정된 텍스트만 표시됩니다.

func trailingContents((() -> any View)...) -> TopNavigation

내비게이션 영역의 오른쪽(trailing) 영역에 표시할 뷰들을 설정합니다.

  • Parameters

    ParameterDescription
    contentsTrailing 영역에 표시할 뷰들을 반환하는 클로저들

  • Return Value

    수정된 인스턴스를 반환합니다.

  • Discussion

    최대 3개까지의 뷰를 클로저를 , 로 구분하여 전달할 수 있으며, 각 클로저는 다양한 타입의 View를 반환할 수 있습니다 (any View). 내부적으로는 모든 View를 AnyView로 타입을 지운 후 렌더링합니다.

func trailingContents([() -> any View]) -> TopNavigation

내비게이션 영역의 오른쪽(trailing) 영역에 표시할 뷰들을 설정합니다.

  • Parameters

    ParameterDescription
    contentsTrailing 영역에 표시할 뷰들을 반환하는 클로저 배열

  • Return Value

    수정된 인스턴스를 반환합니다.

  • Discussion

    최대 3개까지의 뷰를 클로저 배열로 전달할 수 있으며, 각 클로저는 다양한 타입의 View를 반환할 수 있습니다 (any View). 내부적으로는 모든 View를 AnyView로 타입을 지운 후 렌더링합니다.

func variant(Variant) -> TopNavigation

내비게이션 바의 스타일(Variant)을 설정합니다.

  • Parameters

    ParameterDescription
    variant적용할 내비게이션 스타일

  • Return Value

    수정된 내비게이션 바 인스턴스

  • Discussion

    .normal, .display, .search, .floating 중 하나의 스타일을 지정할 수 있으며, 스타일에 따라 내비게이션의 외형과 정렬 방식 등이 달라집니다.

Enumerations

enum Resource

TopNavigation의 좌/우에 표시될 요소들의 Namespace입니다.

  • Overview

    슬롯마다 쓸 수 있는 요소가 다르므로 슬롯별로 타입을 나눠 두었습니다.

Enumerations

enum Leading

내비게이션 바 좌측(leading)에 표시할 요소입니다.

  • Overview

    뒤로가기 버튼, 아이콘 버튼, 텍스트 버튼을 지원합니다.

    TopNavigation()
    .leadingContent { /* ... */ }
Enumeration Cases
case back(action: () -> Void)

뒤로가기 버튼

  • Parameters

    ParameterDescription
    action뒤로가기 버튼 클릭시 동작할 액션
case icon(Icon, action: () -> Void)

아이콘 버튼

  • Parameters

    ParameterDescription
    icon표시할 아이콘
    action아이콘 버튼 클릭시 동작할 액션
case text(String, action: () -> Void)

텍스트 버튼

  • Parameters

    ParameterDescription
    text버튼에 표시할 텍스트
    action텍스트 버튼 클릭시 동작할 액션
enum Trailing

내비게이션 바 우측(trailing)에 표시할 요소입니다.

  • Overview

    아이콘 버튼과 텍스트 버튼을 지원합니다.

    TopNavigation()
    .trailingContents(
        { TopNavigation.TrailingIconButton(icon: .search) { /* ... */ } },
        { TopNavigation.TrailingTextButton(text: "완료") { /* ... */ } }
    )
Operators
static func == (TopNavigation.Resource.Trailing, TopNavigation.Resource.Trailing) -> Bool

두 개의 Trailing 인스턴스를 비교합니다.

  • Parameters

    ParameterDescription
    lhs비교할 첫 번째 Trailing 인스턴스
    rhs비교할 두 번째 Trailing 인스턴스

  • Return Value

    두 인스턴스가 같은지 여부

Enumeration Cases
case icon(Icon, disable: Bool, showPushBadge: Bool, action: () -> Void)

icon 형태의 Action입니다.

  • Parameters

    ParameterDescription
    icon아이콘 버튼의 아이콘
    disable버튼 비활성화 여부, 생략하면 기본값으로 false 적용
    showPushBadgePushBadge의 노출 여부, 생략하면 기본값으로 false 적용
    action아이콘 클릭시 동작할 액션
case text(String, disable: Bool, action: () -> Void)

text 형태의 Action입니다.

  • Parameters

    ParameterDescription
    text텍스트 버튼의 텍스트
    disable버튼 비활성화 여부, 생략하면 기본값으로 false 적용
    action텍스트 클릭시 동작할 액션
Instance Methods
func hash(into: inout Hasher)

해시 값을 생성합니다.

  • Parameters

    ParameterDescription
    hasher해시 값을 생성할 해시 값
enum Variant

TopNavigation의 외관을 결정하는 열거형입니다.

  • Overview

    내비게이션 바의 다양한 레이아웃과 시각적 스타일을 정의합니다.

    TopNavigation
    .variant(.floating)
    .titleView { ... }

Enumeration Cases

case display

타이틀이 크게 표시되는 내비게이션 바 스타일

case floating

플로팅 내비게이션 바 스타일

  • Discussion

    스크롤 오프셋이 0(스크롤이 최상단)일 때는 배경이 없고, 스크롤하면 그라디언트 블러 배경이 나타납니다.

case normal

기본 내비게이션 바 스타일

case search

검색 내비게이션 바 스타일

Relationships

Conforms To

Swift.Sendable

SwiftUICore.View

© 2026 Wanted Lab, Inc.