Skeleton

실제 콘텐츠를 불러오는 동안 해당 영역의 레이아웃 형태를 임시로 보여줍니다. 데이터가 로딩되고 있음을 직관적으로 인지할 수 있도록 돕고, 콘텐츠가 갑자기 나타날 때 발생할 수 있는 화면 깜빡임을 방지합니다.

enum Skeleton

Overview

데이터 로딩 중에 UI의 구조를 미리 보여주는 스켈레톤 뷰를 제공합니다. 텍스트, 사각형, 원형 등 다양한 형태의 스켈레톤 로딩 플레이스홀더를 지원합니다.

텍스트 스켈레톤은 Typography.Variant의 lineHeight를 기반으로 줄 수를 자동 계산하고, 첫 줄은 100%, 나머지는 가변 길이로 표시합니다.

// 자동 텍스트 스켈레톤 (variant 기반 자동 계산)
Text("콘텐츠")
    .skeleton(isPresented: isLoading, kind: .text(variant: .body1))

// 이미지를 위한 원형 스켈레톤 사용
Image(systemName: "person.circle")
    .skeleton(isPresented: isLoading, kind: .circle)

// 커스텀 스켈레톤 뷰 사용
contentView
    .skeleton(isPresented: isLoading) {
        Skeleton.SkeletonView(.rectangle(cornerRadius: 8))
            .color(.semantic(.surfaceNeutralSecondary))
            .opacity(0.7)
    }

Topics

Structures

struct Kind

스켈레톤 요소의 종류를 지정하는 구조체입니다.

  • Overview

    다양한 콘텐츠 유형에 맞게 적절한 스켈레톤 형태를 선택할 수 있습니다. 텍스트 스켈레톤은 Typography.Variant의 lineHeight를 기반으로 줄 수와 길이를 자동 계산합니다.

    // 자동 텍스트 스켈레톤 (variant 기반 자동 계산)
Skeleton.Kind.text(variant: .body1)

// 둥근 모서리 사각형 스켈레톤
Skeleton.Kind.rectangle(cornerRadius: 8)

// 원형 스켈레톤 (프로필 이미지 등에 적합)
Skeleton.Kind.circle

Instance Properties

var isCircle: Bool

원형 종류인지 여부

var isRectangle: Bool

사각형 종류인지 여부

var isText: Bool

텍스트 종류인지 여부

Type Properties

static var circle: Kind

원형 스켈레톤

Type Methods

static func rectangle(cornerRadius: CGFloat) -> Kind

사각형 모양의 스켈레톤을 생성합니다.

  • Parameters

    ParameterDescription
    cornerRadius모서리 둥글기, 생략하면 기본값으로 3 적용

  • Return Value

    사각형 스켈레톤 Kind

static func text(variant: Typography.Variant, alignment: Align, cornerRadius: CGFloat) -> Kind

텍스트 줄을 나타내는 스켈레톤을 생성합니다.

  • Parameters

    ParameterDescription
    variant텍스트의 타이포그래피 변형. lineHeight를 기준으로 줄 수를 자동 계산합니다
    alignment텍스트 정렬 방식, 생략하면 기본값으로 .leading 적용
    cornerRadius모서리 둥글기, 생략하면 기본값으로 3 적용

  • Return Value

    텍스트 스켈레톤 Kind

  • Discussion

    variant의 lineHeight를 기반으로 뷰 높이에 맞는 줄 수를 자동 계산하고, 첫 줄은 100%, 나머지는 가변 길이로 표시합니다.

struct SkeletonView

스켈레톤 로딩 UI를 표시하는 뷰입니다.

  • Overview

    지정된 형태(텍스트, 사각형, 원형)에 따라 적절한 스켈레톤 UI를 렌더링합니다. 색상, 투명도 등을 커스터마이징할 수 있습니다.

    텍스트 스켈레톤의 자동 계산:

    • variant.lineHeight를 기준으로 뷰 높이를 나누어 최적의 줄 수를 계산합니다.
    • 첫 줄 100%, 중간 줄 6590%, 마지막 줄 4055% 비율로 자동 생성합니다.
    // variant 기반 자동 모드
Skeleton.SkeletonView(.text(variant: .body1))
    .color(.gray)
    .opacity(0.8)

Initializers

init(Kind)

스켈레톤 뷰를 초기화합니다.

  • Parameters

    ParameterDescription
    kind표시할 스켈레톤의 종류

Instance Properties

var body: some View

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

Instance Methods

func color(SwiftUI.Color) -> Skeleton.SkeletonView

스켈레톤 뷰의 색상을 설정합니다.

  • Parameters

    ParameterDescription
    color적용할 색상

  • Return Value

    수정된 SkeletonView 인스턴스

func opacity(CGFloat) -> Skeleton.SkeletonView

스켈레톤 뷰의 투명도를 설정합니다.

  • Parameters

    ParameterDescription
    opacity적용할 투명도 (0.0 ~ 1.0)

  • Return Value

    수정된 SkeletonView 인스턴스

Enumerations

enum Align

스켈레톤 요소의 정렬 방식을 지정하는 열거형입니다.

  • Overview

    텍스트 스켈레톤에서 각 라인의 정렬 방식을 지정할 때 사용됩니다.

    Skeleton.Kind.text(alignment: .center, lineNumber: 2)

Enumeration Cases

case center

중앙 정렬

case leading

좌측 정렬

case trailing

우측 정렬

Associated Extensions

extension View
func skeleton<V>(isPresented: Bool, skeletonView: () -> V) -> some View

현재 뷰에 커스텀 스켈레톤 로딩 UI를 적용합니다.

  • Parameters

    ParameterDescription
    isPresented스켈레톤 표시 여부를 제어하는 불리언 값
    skeletonView커스텀 스켈레톤 뷰를 생성하는 클로저

  • Return Value

    스켈레톤 기능이 적용된 뷰

func skeleton(isPresented: Bool, kind: Skeleton.Kind, color: SwiftUI.Color?, opacity: CGFloat?, size: CGSize?) -> some View

현재 뷰에 미리 정의된 스켈레톤 로딩 UI를 적용합니다.

  • Parameters

    ParameterDescription
    isPresented스켈레톤 표시 여부를 제어하는 불리언 값
    kind스켈레톤 종류 (텍스트, 사각형, 원형 등)
    color스켈레톤 색상, 생략하면 기본값으로 nil 적용 (.semantic(.surfaceNeutralSecondary) 사용)
    opacity스켈레톤 투명도, 생략하면 기본값으로 nil 적용
    size스켈레톤 크기 (지정하지 않으면 원본 뷰 크기를 사용), 생략하면 기본값으로 nil 적용

  • Return Value

    스켈레톤 기능이 적용된 뷰

© 2026 Wanted Lab, Inc.