ScrollArea#

아무 child 나 스크롤 가능한 뷰포트로 감싸고 슬림한 디자인 시스템 스크롤바를 입히는 래퍼입니다. 엣지를 그라데이션으로 가리는 FadeScroll 과 달리 콘텐츠를 그대로 보여주고, 오버플로는 스크롤바로만 알립니다. Flutter / Web 동일 API 입니다.

Live Preview#

class ScrollAreaDefaultExample extends StatelessComponent {
  const ScrollAreaDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return div(
      styles: Styles(raw: {'width': '260px'}),
      [
        ScrollArea(
          scrollAreaStyle: const CoreScrollAreaStyle(maxHeight: 180),
          child: div(
            classes: 'flex flex-col gap-${CoreSpace.scale.space8}',
            [
              for (var i = 1; i <= 20; i += 1) Text('스크롤 항목 $i').bodyMedium,
            ],
          ),
        ),
      ],
    );
  }
}

class ScrollAreaDefaultExample extends StatelessWidget {
  const ScrollAreaDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 260,
      child: ScrollArea(
        scrollAreaStyle: const CoreScrollAreaStyle(maxHeight: 180),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          spacing: CoreSpace.space8,
          children: [
            for (var i = 1; i <= 20; i += 1) Text('스크롤 항목 $i').bodyMedium,
          ],
        ),
      ),
    );
  }
}

class ScrollAreaChainExample extends StatelessComponent {
  const ScrollAreaChainExample({super.key});

  @override
  Component build(BuildContext context) {
    return div(
      styles: Styles(raw: {'width': '260px'}),
      [
        ScrollArea(
          child: div(
            classes: 'flex flex-col gap-${CoreSpace.scale.space8}',
            [
              for (var i = 1; i <= 20; i += 1) Text('스크롤 항목 $i').bodyMedium,
            ],
          ),
        ).withStyle(
          const CoreScrollAreaStyle(
            height: CoreSpace.space192,
            maxHeight: CoreSpace.space192,
            scrollbarStyle: CoreScrollbarStyle(
              thumbColor: CoreColor.token(CoreColors.primary),
              thumbRadius: CoreBorderRadius.all(CoreRadius.radius9999),
              thickness: CoreStrokeWidth.stroke8,
            ),
          ),
        ),
      ],
    );
  }
}

class ScrollAreaChainExample extends StatelessWidget {
  const ScrollAreaChainExample({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 260,
      child:
          ScrollArea(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              spacing: CoreSpace.space8,
              children: [
                for (var i = 1; i <= 20; i += 1) Text('스크롤 항목 $i').bodyMedium,
              ],
            ),
          ).withStyle(
            const CoreScrollAreaStyle(
              height: CoreSpace.space192,
              maxHeight: CoreSpace.space192,
              scrollbarStyle: CoreScrollbarStyle(
                thumbColor: CoreColor.token(CoreColors.primary),
                thumbRadius: CoreBorderRadius.all(CoreRadius.radius9999),
                thickness: CoreStrokeWidth.stroke8,
              ),
            ),
          ),
    );
  }
}

사용법#

// Flutter / Web 동일
ScrollArea(
  scrollAreaStyle: const CoreScrollAreaStyle(maxHeight: 180),
  child: Column(
    children: [for (var i = 0; i < 20; i += 1) Text('Item $i')],
  ),
)

빠른 오버라이드 (Chain)#

이미 만든 ScrollArea 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다.

class ScrollAreaChainExample extends StatelessWidget {
  const ScrollAreaChainExample({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 260,
      child:
          ScrollArea(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              spacing: CoreSpace.space8,
              children: [
                for (var i = 1; i <= 20; i += 1) Text('스크롤 항목 $i').bodyMedium,
              ],
            ),
          ).withStyle(
            const CoreScrollAreaStyle(
              height: CoreSpace.space192,
              maxHeight: CoreSpace.space192,
              scrollbarStyle: CoreScrollbarStyle(
                thumbColor: CoreColor.token(CoreColors.primary),
                thumbRadius: CoreBorderRadius.all(CoreRadius.radius9999),
                thickness: CoreStrokeWidth.stroke8,
              ),
            ),
          ),
    );
  }
}

class ScrollAreaChainExample extends StatelessComponent {
  const ScrollAreaChainExample({super.key});

  @override
  Component build(BuildContext context) {
    return div(
      styles: Styles(raw: {'width': '260px'}),
      [
        ScrollArea(
          child: div(
            classes: 'flex flex-col gap-${CoreSpace.scale.space8}',
            [
              for (var i = 1; i <= 20; i += 1) Text('스크롤 항목 $i').bodyMedium,
            ],
          ),
        ).withStyle(
          const CoreScrollAreaStyle(
            height: CoreSpace.space192,
            maxHeight: CoreSpace.space192,
            scrollbarStyle: CoreScrollbarStyle(
              thumbColor: CoreColor.token(CoreColors.primary),
              thumbRadius: CoreBorderRadius.all(CoreRadius.radius9999),
              thickness: CoreStrokeWidth.stroke8,
            ),
          ),
        ),
      ],
    );
  }
}

Props#

CoreScrollAreaStyle 필드#

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

✅ Do#

ScrollArea(
  scrollAreaStyle: const CoreScrollAreaStyle(maxHeight: 240),
  child: Column(children: [for (final item in items) Text(item)]),
)

❌ Don't#

// ❌ 넘침을 알릴 다른 수단 없이 스크롤바만 숨김
ScrollArea(
  showScrollbar: false,
  scrollAreaStyle: const CoreScrollAreaStyle(maxHeight: 180),
  child: longContent,
)

접근성 (Accessibility)#

역할 (Semantics)#

양 플랫폼 모두 역할을 내보내지 않습니다. Flutter 는 SingleChildScrollView 에 Scrollbar 를 합성하고 ConstrainedBox 로 감쌀 뿐 Semantics 노드를 만들지 않으며, Web 은 합성된 Scrollbar 가 그리는 overflow-* 클래스가 붙은 <div> 하나만 내보내고 role / aria-* 는 하나도 붙이지 않습니다(호출자가 넘긴 attributes 는 그대로 통과).

즉 "여기가 스크롤되는 영역"이라는 사실 자체가 보조기술에 전달되지 않습니다. 영역 이름이 필요하면 소비자가 직접 붙여야 합니다 — Web 은 attributes 로 role="region" · aria-label 을, Flutter 는 바깥에 자기 Semantics 를 감싸는 방식입니다.

키보드#

이 컴포넌트가 해석하는 키는 없습니다. Flutter 에서 방향키 · Page · Home · End 로 스크롤되는 것은 SingleChildScrollView 안의 프레임워크 Scrollable 이 주는 동작이고, Web 에서는 브라우저가 주는 동작입니다 — 그리고 Web 쪽은 스크롤 컨테이너가 포커스를 받았을 때만 동작합니다(아래 제약 참조). Web 의 onKeyDown / onKeyUp 은 호출자가 넘긴 핸들러를 루트에 연결하는 통과 슬롯일 뿐, 컴포넌트가 채우는 값이 아닙니다.

포커스#

포커스를 받지 않습니다. 양 플랫폼 모두 FocusNode / Focus / tabindex 가 없고 포커스 링도 그리지 않습니다. 탭 순서에 등장하지 않으며, 포커스를 가두거나 되돌리지도 않습니다 — 콘텐츠 안의 포커스 가능한 요소는 각자의 동작을 그대로 유지합니다.

스크린 리더#

영역 자체에는 이름이 없습니다 — Flutter 는 프레임워크 Scrollable 이 기여하는 스크롤 액션이, Web 은 이름 없는 <div> 안쪽 콘텐츠가 읽힙니다.

showScrollbar 가 켜져 있으면 합성된 Scrollbar 가 스크롤 위치를 0–100 퍼센트로 안내합니다 (Web role="scrollbar" + aria-valuenow, Flutter slider Semantics). 남은 분량 자체는 어느 쪽에서도 안내되지 않습니다.

알려진 제약#

• Web 스크롤 컨테이너에 tabindex 가 없어 키보드만 쓰는 사용자가 이 영역을 스크롤할 수 있는지가 전적으로 브라우저 동작에 달려 있습니다. 키보드로 확실히 스크롤시키려면 소비자가 attributes 로 tabindex="0" 과 role="region" · aria-label 을 직접 넣어야 합니다.
• showScrollbar: false 는 넘침을 알리는 유일한 시각 단서를 없애면서 대체 어포던스를 제공하지 않습니다 — 콘텐츠가 더 있다는 사실이 시각적으로도 음성으로도 드러나지 않습니다.
• controller 는 Flutter 전용이라 크로스 플랫폼 프로그래매틱 스크롤 경로가 없습니다. "특정 항목으로 스크롤" 같은 동작을 양 플랫폼에서 동일하게 제공하려면 소비자 쪽에서 플랫폼별로 구현해야 합니다.

reduced motion · 고대비 · 최소 터치 타겟 등 컴포넌트를 가로지르는 축은 전역 접근성 축에서 다룹니다.