ResponsiveGrid#

지정된 columns 개의 균등 너비 셀에 자식을 그리드로 배치합니다. responsive: true 일 때 CoreBreakpoint에 맞춰 컬럼 수가 자동 감소합니다 (기본: md 이하 1열, lg 이하 2열, lg 이상 columns열). GridItem으로 감싸 colSpan/rowSpan을 적용하면 여러 셀을 차지합니다.

Live Preview#

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

  @override
  Component build(BuildContext context) {
    final cs = context.colorScheme;
    final textClass = 'text-${CoreTextStyles.bodyMedium.name} text-${cs.onSurface}';
    return ResponsiveGrid(
      columns: 3,
      cellSpacing: CoreSpace.space16,
      children: [
        for (var i = 1; i <= 5; i += 1)
          Card(
            cardStyle: const CoreCardStyle(padding: CoreEdgeInsets.all(CoreSpace.space16)),
            child: div([Text('Item $i')], classes: textClass),
          ),
      ],
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    final textStyle = theme.typography.bodyMedium.toValue(theme: theme).copyWith(
      color: theme.colorScheme.onSurface.toValue(),
    );
    return ResponsiveGrid(
      columns: 3,
      cellSpacing: CoreSpace.space16,
      children: [
        for (var i = 1; i <= 5; i += 1)
          Card(
            cardStyle: const CoreCardStyle(
              padding: CoreEdgeInsets.all(CoreSpace.space16),
            ),
            child: Text('Item $i', style: textStyle),
          ),
      ],
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    final cs = context.colorScheme;
    final textClass = 'text-${CoreTextStyles.bodyMedium.name} text-${cs.onSurface}';
    const cardStyle = CoreCardStyle(
      padding: CoreEdgeInsets.all(CoreSpace.space16),
    );
    return ResponsiveGrid(
      columns: 4,
      cellSpacing: CoreSpace.space16,
      responsive: false,
      children: [
        GridItem(
          colSpan: 2,
          child: Card(
            cardStyle: cardStyle,
            child: div(
              [Text('Spans 2 cols')],
              classes: textClass,
            ),
          ),
        ),
        Card(
          cardStyle: cardStyle,
          child: div([Text('Cell')], classes: textClass),
        ),
        Card(
          cardStyle: cardStyle,
          child: div([Text('Cell')], classes: textClass),
        ),
        GridItem(
          rowSpan: 2,
          child: Card(
            cardStyle: cardStyle,
            child: div(
              [Text('Spans 2 rows')],
              classes: textClass,
            ),
          ),
        ),
        Card(
          cardStyle: cardStyle,
          child: div([Text('Cell')], classes: textClass),
        ),
        Card(
          cardStyle: cardStyle,
          child: div([Text('Cell')], classes: textClass),
        ),
        Card(
          cardStyle: cardStyle,
          child: div([Text('Cell')], classes: textClass),
        ),
      ],
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    final textStyle = theme.typography.bodyMedium.toValue(theme: theme).copyWith(
      color: theme.colorScheme.onSurface.toValue(),
    );
    const cardStyle = CoreCardStyle(
      padding: CoreEdgeInsets.all(CoreSpace.space16),
    );
    return ResponsiveGrid(
      columns: 4,
      cellSpacing: CoreSpace.space16,
      responsive: false,
      children: [
        GridItem(
          colSpan: 2,
          child: Card(
            cardStyle: cardStyle,
            child: Text('Spans 2 cols', style: textStyle),
          ),
        ),
        Card(
          cardStyle: cardStyle,
          child: Text('Cell', style: textStyle),
        ),
        Card(
          cardStyle: cardStyle,
          child: Text('Cell', style: textStyle),
        ),
        GridItem(
          rowSpan: 2,
          child: Card(
            cardStyle: cardStyle,
            child: Text('Spans 2 rows', style: textStyle),
          ),
        ),
        Card(
          cardStyle: cardStyle,
          child: Text('Cell', style: textStyle),
        ),
        Card(
          cardStyle: cardStyle,
          child: Text('Cell', style: textStyle),
        ),
        Card(
          cardStyle: cardStyle,
          child: Text('Cell', style: textStyle),
        ),
      ],
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    final cs = context.colorScheme;
    final textClass = 'text-${CoreTextStyles.bodyMedium.name} text-${cs.onSurface}';
    return ResponsiveGrid(
      children: [
        for (var i = 1; i <= 5; i += 1)
          Card(
            cardStyle: const CoreCardStyle(
              padding: CoreEdgeInsets.all(CoreSpace.space16),
            ),
            child: div([Text('Item $i')], classes: textClass),
          ),
      ],
    ).withStyle(
      const CoreResponsiveGridStyle(
        columns: 2,
        cellSpacing: CoreSpace.space24,
        responsive: false,
      ),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    final textStyle = theme.typography.bodyMedium
        .toValue(theme: theme)
        .copyWith(
          color: theme.colorScheme.onSurface.toValue(),
        );
    return ResponsiveGrid(
      children: [
        for (var i = 1; i <= 5; i += 1)
          Card(
            cardStyle: const CoreCardStyle(
              padding: CoreEdgeInsets.all(CoreSpace.space16),
            ),
            child: Text('Item $i', style: textStyle),
          ),
      ],
    ).withStyle(
      const CoreResponsiveGridStyle(
        columns: 2,
        cellSpacing: CoreSpace.space24,
        responsive: false,
      ),
    );
  }
}

사용 시기 (When to Use)#

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

• 대시보드처럼 N × M 셀의 카드/모듈을 배치할 때
• 뷰포트 폭에 따라 열 수가 달라져야 할 때
• Wrap이나 flex보다 명시적으로 열 수를 정하고 싶을 때

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

• ResponsiveContainer: 단일 콘텐츠를 화면 중앙에 max-width로 제약
• Row / flex: 1행 배치
• Wrap / flex-wrap: 셀 너비가 content 기반인 경우

기본 사용법 (Basic Usage)#

ResponsiveGrid(
  columns: 3,
  cellSpacing: CoreSpace.space16,
  children: [
    for (var i = 1; i <= 6; i++)
      Card(
        cardStyle: const CoreCardStyle(
          padding: CoreEdgeInsets.all(CoreSpace.space16),
        ),
        child: Text('Item $i'),
      ),
  ],
)

col/row span#

ResponsiveGrid(
  columns: 4,
  cellSpacing: CoreSpace.space16,
  responsive: false,
  children: [
    GridItem(colSpan: 2, child: Card(child: Text('Wide'))),
    Card(child: Text('Cell')),
    Card(child: Text('Cell')),
    GridItem(rowSpan: 2, child: Card(child: Text('Tall'))),
    // ...
  ],
)

반응형 커스터마이징#

기본 breakpoint 매핑을 덮어쓰려면 breakpoints를 제공:

ResponsiveGrid(
  columns: 6,
  breakpoints: {
    CoreBreakpoint.xs: 1,
    CoreBreakpoint.sm: 2,
    CoreBreakpoint.md: 3,
    CoreBreakpoint.lg: 4,
    CoreBreakpoint.xl: 5,
    CoreBreakpoint.xxl: 6,
  },
  children: [...],
)

Props / Parameters#

ResponsiveGrid#

GridItem#

스타일 시스템 (Style System)#

CoreResponsiveGridStyle 필드#

동작 스펙 (Behavior)#

배치 알고리즘#

자식을 순서대로 좌→우, 상→하로 스캔하며 colSpan × rowSpan이 완전히 비어있는 최초의 사각형 영역을 예약합니다 (row-major packing).

렌더링#

• Flutter: MultiChildRenderObjectWidget → RenderGrid (bit-field 점유 그리드로 span 계산)
• Web: CSS Grid (display: grid, grid-template-columns: repeat(N, minmax(0, 1fr))) + @media (min-width: ...) 스코프 블록으로 responsive 처리

반응형 breakpoint 기본값#

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

✅ Do#

ResponsiveGrid(
  columns: 4,
  responsive: false,   // 4열 고정 — colSpan 이 항상 columns 이하로 유지됨
  children: [
    GridItem(colSpan: 2, child: Card(child: Text('Wide'))),
    Card(child: Text('Cell')),
    Card(child: Text('Cell')),
  ],
)

❌ Don't#

// ❌ 반응형(columns 축소)인데 colSpan이 최대 columns에 가까움
ResponsiveGrid(
  columns: 4,
  responsive: true,
  children: [
    GridItem(colSpan: 4, child: Card(child: Text('Full width'))),
    // ...
  ],
)

접근성 (Accessibility)#

• 정적 레이아웃 컴포넌트 — 인터랙션 없음
• 자식 위젯의 접근성은 각자 책임

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

레거시 vs 통일 비교 (Migration Notes)#

이전 버전의 Web CoUI 를 참조하는 코드에는 이 컴포넌트가 Grid 라는 이름이었을 수 있습니다. Flutter 쪽 이름(ResponsiveGrid)에 맞춰 Web 도 ResponsiveGrid 로 개명되었습니다.

마이그레이션: Grid(...) → ResponsiveGrid(...) — 파라미터는 그대로이므로 클래스명만 바꾸면 됩니다.

관련 컴포넌트 (Related Components)#

• ResponsiveContainer: 단일 max-width 래퍼
• Basic: slot 기반 단일 영역 레이아웃