ScrollableClient#

고정 크기 뷰포트 안에서 2D 스크롤을 제공하고, 매 스크롤 프레임마다 현재 offset / viewportSize를 builder 콜백에 전달하는 컴포넌트입니다. Table의 가로/세로 고정 셀이나 가상화 레이아웃처럼 스크롤 위치에 따라 렌더링을 조정해야 하는 서브트리에 최적화되어 있습니다.

Live Preview#

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

  @override
  Component build(BuildContext context) {
    final cs = context.theme.colorScheme;
    return div(
      [
        ScrollableClient(
          diagonalDragBehavior: CoreDiagonalDragBehavior.free,
          builder: (context, offset, viewportSize, child) {
            return div(
              [
                Text(
                  'Offset: ${offset.dx.toStringAsFixed(1)}, '
                  '${offset.dy.toStringAsFixed(1)}',
                ),
                Gap.space8(),
                Text(
                  'Viewport: ${viewportSize.width.toStringAsFixed(0)} × '
                  '${viewportSize.height.toStringAsFixed(0)}',
                ),
                Gap.space16(),
                Text(
                  'Drag or scroll to move around this 1200 × 560 content.',
                ),
              ],
              classes:
                  'flex flex-col bg-${cs.surfaceContainer} text-${CoreTextStyles.bodyMedium.name} text-${cs.onSurface} rounded-${CoreRadius.scale.radius16} p-${CoreSpace.scale.space16}',
              styles: Styles(
                raw: const {
                  'width': '${1200 / 16}rem',
                  'height': '${560 / 16}rem',
                },
              ),
            );
          },
        ),
      ],
      styles: Styles(
        raw: const {
          'height': '${320 / 16}rem',
          'width': '100%',
          'min-width': '0',
        },
      ),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    return SizedBox(
      height: 320,
      child: ScrollableClient(
        diagonalDragBehavior: CoreDiagonalDragBehavior.free,
        builder: (context, offset, viewportSize, child) {
          return Container(
            width: 1200,
            height: 560,
            padding: const EdgeInsets.all(CoreSpace.space16),
            decoration: BoxDecoration(
              color: theme.colorScheme.surfaceContainer.toValue(),
              borderRadius: BorderRadius.circular(CoreRadius.radius16),
            ),
            child: DefaultTextStyle.merge(
              style: theme.typography.bodyMedium.toValue(theme: theme).copyWith(
                color: theme.colorScheme.onSurface.toValue(),
              ),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                mainAxisSize: MainAxisSize.min,
                children: [
                  Text(
                    'Offset: ${offset.dx.toStringAsFixed(1)}, '
                    '${offset.dy.toStringAsFixed(1)}',
                  ),
                  const Gap.space8(),
                  Text(
                    'Viewport: ${viewportSize.width.toStringAsFixed(0)} × '
                    '${viewportSize.height.toStringAsFixed(0)}',
                  ),
                  const Gap.space16(),
                  const Text(
                    'Drag or scroll to move around this 1200 × 560 content.',
                  ),
                ],
              ),
            ),
          );
        },
      ),
    );
  }
}

사용 시기 (When to Use)#

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

• 가로/세로 동시 스크롤이 필요한 고정 크기 영역을 만들 때
• 현재 스크롤 오프셋을 기준으로 자식을 다르게 렌더링해야 할 때 (예: 테이블의 frozen 헤더/컬럼, 가상화된 리스트)
• Web/Flutter 양쪽에 동일한 builder 인터페이스로 스크롤 영역을 재사용하고 싶을 때

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

• SingleChildScrollView / <div overflow:auto>로 충분한 단방향 스크롤: 그냥 네이티브 스크롤 컨테이너를 쓰는 게 더 가볍습니다
• 리사이저블 레이아웃이 필요: Resizable

기본 사용법 (Basic Usage)#

SizedBox(
  height: CoreSpace.space256,
  child: ScrollableClient(
    diagonalDragBehavior: CoreDiagonalDragBehavior.free,
    builder: (context, offset, viewportSize, child) {
      return Card(
        cardStyle: const CoreCardStyle(
          sizing: CoreCardSizing.fixed,
          width: 720,
          height: 560,
        ),
        child: /* content */,
      );
    },
  ),
)

Web에서도 동일한 생성자로 사용합니다 — 단 builder의 offset은 ({double dx, double dy}) 레코드, viewportSize는 ({double width, double height}) 레코드입니다.

Props / Parameters#

위 기본값들은 테마 오버라이드 대상이 아닙니다 — CoreScrollableClientTheme 은 chrome style 슬롯만 나르고, 이 behaviour 기본값은 CoreScrollableClientContract 의 static const 로 살아서 Flutter/Web resolver 가 같은 값을 읽습니다 (clipBehavior 만 각 플랫폼의 hardEdge 상수).

Flutter 전용#

CoreScrollableClientStyle 필드#

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

✅ Do#

ScrollableClient(
  child: staticHeader,
  builder: (context, offset, viewportSize, child) {
    return Column(children: [child!, /* offset 기반 콘텐츠 */]);
  },
)

❌ Don't#

// ❌ 오프셋과 무관한 콘텐츠를 builder 안에서 매번 생성
ScrollableClient(
  builder: (context, offset, viewportSize, child) {
    return Column(children: [ExpensiveStaticHeader(), /* ... */]);
  },
)

✅ Do#

ScrollableClient(
  mainAxis: CoreAxis.horizontal,
  diagonalDragBehavior: CoreDiagonalDragBehavior.free,
  builder: (context, offset, viewportSize, child) => canvasContent,
)

❌ Don't#

// ❌ 대각선 드래그가 필요한데 diagonalDragBehavior 를 지정하지 않음
ScrollableClient(
  builder: (context, offset, viewportSize, child) => canvasContent,
)

접근성 (Accessibility)#

포인터로만 조작되던 뷰포트를 보조 기술과 키보드에 노출한다.

• 이름과 역할 — 뷰포트는 그룹으로 선언되고 이름을 갖는다. Web은 role="group" + aria-label, Flutter는 같은 CoreSemanticRole.group을 CoUISemantics로 emit한다. 이름은 semanticLabel이 없으면 현재 로케일의 scrollableClientLabel에서 온다 — 이름 없는 영역은 스크린 리더가 아무것도 읽지 않기 때문에 폴백이 필요하다.
• 키보드 스크롤 — 화살표(한 줄) · PageUp/PageDown(뷰포트의 80%) · Home/End(세로 양 끝). 키 이름과 이동량은 양 플랫폼이 같은 Core 함수 (resolveScrollableKeyIntent)를 읽으므로 갈라질 수 없다. 끝에 닿아 더 움직일 수 없는 키는 소비하지 않는다 — 브라우저가 네이티브 overflow: auto 박스에서 하는 스크롤 체이닝과 같다. Flutter의 기본 ScrollAction은 가장 가까운 Scrollable(2D에서는 항상 안쪽 가로축)만 찾아 다른 축에 0을 돌려주므로 여기서 두 축을 직접 라우팅한다.
• 포커스 표시 — 뷰포트가 탭 순서에 들어가므로(WCAG 2.4.7) 키보드로 들어왔을 때 링이 보인다. Web은 :focus-visible scoped rule, Flutter는 onShowFocusHighlight + FocusOutline. 포인터로 누른 경우에는 링이 뜨지 않는다 — 두 메커니즘 모두 같은 CoreFocusOutlineStyle 슬롯에서 값을 읽는다.
• 호출자가 이긴다 — attributes로 넘긴 role / aria-label / tabindex(Web)는 위 기본값을 덮는다. 콘텐츠가 키를 직접 소유하는 캔버스류는 tabindex: '-1'로 뷰포트를 탭 순서에서 빼면 된다.
• 스크롤바는 네이티브 OS 스크롤바 + CoUI onSurface 틴트로 렌더링되어 사용자 설정(감추기/포커스 색)이 반영됩니다.
• keyboardDismissBehavior: CoreKeyboardDismissBehavior.onDrag로 설정하면 드래그 스크롤이 시작될 때 document.activeElement(Web) / 현재 포커스된 FocusScope(Flutter)가 해제되어 모바일에서 소프트 키보드가 닫힙니다.

관련 컴포넌트#

• Table — ScrollableClient와 함께 가상화/frozen 셀 구현
• Resizable — 사용자 지정 분할 패널