Skeleton#

데이터 로딩 중에 콘텐츠 레이아웃을 미리 표시하는 스켈레톤 컴포넌트입니다. 사용자에게 로딩 상태를 시각적으로 전달합니다.

Live Preview#

class SkeletonDefaultExample extends StatefulComponent {
  const SkeletonDefaultExample({super.key});

  @override
  State<SkeletonDefaultExample> createState() => _SkeletonDefaultExampleState();
}

class _SkeletonDefaultExampleState extends State<SkeletonDefaultExample> {
  @override
  Component build(BuildContext context) {
    return div(classes: 'flex flex-col gap-${CoreSpace.scale.space8}', [
      Skeleton(width: '200px', height: '20px'),
      Skeleton(width: '150px', height: '20px'),
      Skeleton(width: '180px', height: '20px'),
    ]);
  }
}

class SkeletonDefaultExample extends StatefulWidget {
  const SkeletonDefaultExample({super.key});

  @override
  State<SkeletonDefaultExample> createState() => _SkeletonDefaultExampleState();
}

class _SkeletonDefaultExampleState extends State<SkeletonDefaultExample> {
  @override
  Widget build(BuildContext context) {
    return const Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      spacing: CoreSpace.space8,
      children: [
        Skeleton(width: 200, height: 20),
        Skeleton(width: 150, height: 20),
        Skeleton(width: 180, height: 20),
      ],
    );
  }
}

class SkeletonCircleExample extends StatefulComponent {
  const SkeletonCircleExample({super.key});

  @override
  State<SkeletonCircleExample> createState() => _SkeletonCircleExampleState();
}

class _SkeletonCircleExampleState extends State<SkeletonCircleExample> {
  @override
  Component build(BuildContext context) {
    return Skeleton.circle(size: '48px');
  }
}

class SkeletonCircleExample extends StatefulWidget {
  const SkeletonCircleExample({super.key});

  @override
  State<SkeletonCircleExample> createState() => _SkeletonCircleExampleState();
}

class _SkeletonCircleExampleState extends State<SkeletonCircleExample> {
  @override
  Widget build(BuildContext context) {
    return const Skeleton.circle(size: 48);
  }
}

class SkeletonTextExample extends StatefulComponent {
  const SkeletonTextExample({super.key});

  @override
  State<SkeletonTextExample> createState() => _SkeletonTextExampleState();
}

class _SkeletonTextExampleState extends State<SkeletonTextExample> {
  @override
  Component build(BuildContext context) {
    return Skeleton.text(
      skeletonStyle: const CoreSkeletonStyle(lines: 3),
    );
  }
}

class SkeletonTextExample extends StatefulWidget {
  const SkeletonTextExample({super.key});

  @override
  State<SkeletonTextExample> createState() => _SkeletonTextExampleState();
}

class _SkeletonTextExampleState extends State<SkeletonTextExample> {
  @override
  Widget build(BuildContext context) {
    return const Skeleton.text(
      skeletonStyle: CoreSkeletonStyle(lines: 3),
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• API 요청이나 비동기 데이터 로딩 중에 콘텐츠의 대략적인 형태를 미리 보여줄 때
• 목록 항목, 카드, 텍스트 블록 등 콘텐츠 레이아웃이 예측 가능할 때
• 로딩 중에 레이아웃 점프(layout shift)를 방지하고 싶을 때

대신 다른 컴포넌트를 사용하세요:

• Loading: 콘텐츠 구조를 예측할 수 없거나 단순히 진행 중임만 표시할 때
• EmptyState: 데이터가 없는 상태를 안내할 때 (로딩이 끝난 후)

기본 사용법 (Basic Usage)#

// 기본 직사각형 스켈레톤
Skeleton(
  width: 200,
  height: 20,
)

// 원형 스켈레톤 (아바타)
Skeleton.circle(size: 48)

// 텍스트 스켈레톤 (여러 줄)
Skeleton.text(
  skeletonStyle: CoreSkeletonStyle(lines: 3),
)

// 카드 스켈레톤 조합
Column(
  crossAxisAlignment: CrossAxisAlignment.start,
  children: [
    Skeleton(
      width: double.infinity,
      height: 200,
      skeletonStyle: CoreSkeletonStyle(
        borderRadius: CoreBorderRadius.all(CoreRadius.radius12),
      ),
    ),
    SizedBox(height: 12),
    Skeleton.text(
      skeletonStyle: CoreSkeletonStyle(lines: 2),
    ),
    SizedBox(height: 8),
    Skeleton(width: 100, height: 16),
  ],
)

// 기본 직사각형 스켈레톤 (CSS 크기값 사용)
Skeleton(width: '200px', height: '20px')

// 원형 스켈레톤 (아바타)
Skeleton.circle(size: '48px')

// 텍스트 스켈레톤 (여러 줄)
Skeleton.text(
  skeletonStyle: const CoreSkeletonStyle(lines: 3),
)

// 카드 스켈레톤 조합
div([
  Skeleton(
    width: '100%',
    height: '200px',
    skeletonStyle: const CoreSkeletonStyle(
      borderRadius: CoreBorderRadius.all(CoreRadius.radius16),
    ),
  ),
  div([
    Skeleton(width: '70%', height: '20px'),
    Skeleton(width: '50%', height: '16px'),
  ]),
])

Props / Parameters#

Skeleton (Flutter) / Skeleton (Web)#

CoreSkeletonStyle 필드#

Skeleton.circle 팩토리#

변형 (Variants)#

rectangular#

기본 직사각형 형태입니다.

Skeleton(width: 300, height: 150, variant: CoreSkeletonVariant.rectangular)

text#

텍스트 줄을 흉내 내는 여러 줄 형태입니다.

Skeleton.text(lines: 4, lastLineWidth: 0.6)

circular#

아바타나 원형 요소를 위한 형태입니다.

Skeleton.circle(size: 56)

동작 스펙 (Behavior)#

인터랙션#

• Skeleton은 인터랙티브 요소가 아닙니다.

상태 전환#

• 로딩 시작: 스켈레톤 표시 (shimmer 애니메이션 시작)
• 로딩 완료: 실제 콘텐츠로 교체 (AnimatedSwitcher 사용 권장)

애니메이션#

• shimmer 효과: 왼쪽에서 오른쪽으로 흘러가는 빛나는 반짝임 1.5s 무한 반복
• 색상: 베이스 색상 → 약간 밝은 색상 → 베이스 색상

사용 가이드라인 (Usage Guidelines)#

✅ Do#

// 실제 카드와 동일한 구조의 스켈레톤
Widget buildSkeletonCard() {
  return CouiCard(
    child: Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Skeleton(width: double.infinity, height: 180, borderRadius: 8),
        SizedBox(height: 12),
        Row(children: [
          Skeleton.circle(size: 40),
          SizedBox(width: 8),
          Expanded(child: Skeleton.text(lines: 2)),
        ]),
        SizedBox(height: 8),
        Skeleton(width: 80, height: 14),
      ],
    ),
  );
}

❌ Don't#

// ❌ 오류 발생 후에도 스켈레톤 유지
if (isLoading || hasError) {
  return Skeleton.text(lines: 5); // 오류 상태에서도 스켈레톤
}

✅ Do#

// 목록 스켈레톤: 실제 개수가 아닌 적당한 수 표시
if (isLoading) {
  return Column(
    children: List.generate(4, (index) => Padding(
      padding: EdgeInsets.only(bottom: 12),
      child: SkeletonListItem(),
    )),
  );
}

❌ Don't#

// ❌ 스켈레톤과 로딩 스피너 동시 표시
Stack(
  children: [
    Skeleton.text(lines: 5),
    Center(child: CouiLoading()), // 중복
  ],
)

✅ Do#

// 실제 카드와 동일한 구조의 Skeleton
Skeleton(
  child: Column(
    children: [
      SkeletonBox(width: double.infinity, height: 200),  // 이미지
      Gap(12),
      SkeletonBox(width: 200, height: 20),  // 제목
      Gap(8),
      SkeletonBox(width: double.infinity, height: 60),  // 설명
    ],
  ),
)

❌ Don't#

// ❌ 데이터 로드 완료 후에도 Skeleton 유지
Widget build(BuildContext context) {
  return Skeleton(  // 항상 Skeleton 표시
    child: DataContent(data: loadedData),
  );
}

접근성 (Accessibility)#

키보드 인터랙션#

해당 없음. Skeleton은 인터랙티브 요소가 아닙니다.

스크린 리더#

• Flutter: Semantics(label: '로딩 중', liveRegion: true)로 로딩 상태 알림
• Web: role="progressbar", aria-label="콘텐츠 로딩 중" 자동 적용

터치 타겟#

해당 없음. 표시 전용 요소.

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• Loading: 콘텐츠 구조를 예측할 수 없는 로딩 상태 표시
• EmptyState: 로딩 완료 후 데이터가 없는 상태 처리
• Avatar: Skeleton.circle()을 아바타 로딩 자리 표시자로 사용

조합 예제#

// 완전한 로딩 → 빈 상태 → 콘텐츠 패턴
Widget buildUserList() {
  if (isLoading) {
    // 스켈레톤으로 로딩 표시
    return Column(
      children: List.generate(4, (_) => Padding(
        padding: EdgeInsets.only(bottom: 12),
        child: Row(children: [
          Skeleton.circle(size: 48),
          SizedBox(width: 12),
          Expanded(child: Skeleton.text(lines: 2, lastLineWidth: 0.6)),
        ]),
      )),
    );
  }

  if (users.isEmpty) {
    return CouiEmptyState(
      icon: Icon(Icons.people_outline, size: 48),
      title: '사용자가 없습니다',
    );
  }

  return ListView.builder(
    itemCount: users.length,
    itemBuilder: (context, index) => UserListTile(user: users[index]),
  );
}