TextBlock

시맨틱 역할(element)을 가진 prose 텍스트 블록입니다. Web 은 각 element 를 시맨틱 HTML 태그(<p>·<h1>~<h6>·<blockquote> 등)에 바인딩하고, Flutter 는 동일 element 로 타이포그래피 토큰과 제목 레벨을 함께 고릅니다 — 그래서 제목이 크게 보일 뿐 아니라 스크린 리더에도 제목으로 읽힙니다. 단일 Text chain 이 한 줄 텍스트라면, TextBlock 은 제목/문단/인용 같은 문서 구조 단위입니다.

Live Preview#

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

  @override
  Component build(BuildContext context) {
    return div(
      styles: Styles(raw: {'width': '360px'}),
      [
        div(
          classes: 'flex flex-col gap-${CoreSpace.scale.space8}',
          [
            TextBlock(text: '문서 제목', element: CoreTextBlockElement.h3),
            TextBlock(
              text: '본문은 paragraph 역할로 렌더됩니다. element 가 시맨틱 타이포 역할을 고릅니다.',
            ),
          ],
        ),
      ],
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 360,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        spacing: Theme.of(context).geometry.space(CoreSpace.space8),
        children: [
          TextBlock(text: '문서 제목', element: CoreTextBlockElement.h3),
          TextBlock(
            text: '본문은 paragraph 역할로 렌더됩니다. element 가 시맨틱 타이포 역할을 고릅니다.',
          ),
        ],
      ),
    );
  }
}

사용법#

// Flutter / Web 동일 — element 가 시맨틱 역할(타이포)을 고른다
TextBlock(text: '문서 제목', element: CoreTextBlockElement.h3)
TextBlock(text: '본문 단락입니다.') // element 기본값 = p

Props / Parameters#

W는 Flutter의 Widget, Web의 Component를 뜻하는 자식 콘텐츠 타입입니다.

element 는 구조 역할을, presets 는 그 위에 얹는 시각 프리셋을 정합니다. Flutter 의 preset 헬퍼는 BuildContext 를 받아 테마 타이포를 해석합니다(TextBlock.heading2(context)).

CoreTextBlockStyle 필드#

// Flutter / Web 동일 — withStyle 체인이 xxxStyle 슬롯으로 merge 한다
TextBlock(
  text: '인용문',
  element: CoreTextBlockElement.blockquote,
).withStyle(
  const CoreTextBlockStyle(blockQuoteBorderWidth: CoreStrokeWidth.stroke4),
)

동작 스펙 (Behavior)#

children이 null이 아니면 빈 목록이어도 text를 사용하지 않습니다. 자식이 없을 때 문자열을 렌더하고 element가 구조 역할과 기본 타이포를, presets가 추가 시각 스타일을 정합니다. blockquote/pre는 해당 박스 chrome을 합성하고, 박스 안 글자도 스스로 정합니다 — blockquote 는 bodyMedium 역할을 onSurfaceVariant 색으로, pre(인라인 코드)는 고정폭 codeMd 역할을 onSurface 색으로 그립니다(blockQuoteTextStyle · inlineCodeTextStyle 로 바꿉니다). presets 를 주면 Web 은 프리셋이 타이포 전체를 대신하므로 이 글자 슬롯은 적용되지 않습니다. 편집·선택·클릭 콜백은 없으며 정적 문서 내용을 표시합니다.

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

제목·문단·인용처럼 문서 구조를 표현할 때는 TextBlock을 사용합니다. 일반 라벨과 짧은 텍스트의 시각 스타일은 Text chain, 사용자 복사가 필요한 텍스트는 SelectableText를 선택합니다.

✅ Do#

// ✅ 문서 구조는 문단(p) 유지, 시각적 크기만 크게
TextBlock(text: '강조 문구', presets: [TextBlock.lead(context)])

❌ Don't#

// ❌ Flutter 에서는 strong 이 타이포그래피일 뿐, 실제 강조 시맨틱이 없음
TextBlock(text: '반드시 확인하세요', element: CoreTextBlockElement.strong)

접근성 (Accessibility)#

역할#

element 가 시맨틱을 정하지만 두 플랫폼이 담아내는 범위가 다릅니다.

• Flutter — 제목만 시맨틱을 갖습니다. .h1~.h6 일 때만 Semantics(headingLevel:) 로 감싸고(header: true 는 이 킷에서 페이지 배너 랜드마크용이라 함께 쓰지 않습니다), p / span / label / strong / em / small 은 시맨틱 노드 없이 텍스트만 렌더합니다. blockquote / pre 는 DecoratedBox + Padding chrome 뿐이라 역시 역할이 없습니다.
• Web — ARIA 를 전혀 쓰지 않는 대신 element 가 고른 네이티브 태그(<p> · <span> · <h1>~<h6> · <blockquote> · <pre> · <label> · <strong> · <em> · <small>)가 시맨틱을 담당합니다.

키보드#

처리하는 키가 없습니다.

포커스 관리#

포커스를 받지 않고 포커스를 관리하지도 않습니다. Flutter 는 평범한 Text 를 렌더하므로 텍스트 선택도 되지 않습니다.

스크린 리더#

Flutter 는 h1~h6 만 해당 레벨의 제목으로 읽히고 나머지 element 는 역할 없는 일반 텍스트로 읽힙니다. Web 은 네이티브 태그가 그대로 전달되어 제목이 문서 아웃라인에 들어가고 blockquote / strong / em / small / label 도 각자의 HTML 시맨틱을 유지합니다. 두 플랫폼이 일치하는 지점은 제목뿐입니다.

알려진 제약#

• blockquote / pre / strong / em / small 은 Flutter 에서 타이포그래피일 뿐이고, 실제 요소 시맨틱은 Web 만 얻습니다. 강조나 인용의 의미가 읽혀야 한다면 Flutter 쪽에는 소비자가 직접 Semantics 를 얹어야 합니다.
• Web <label> 은 for 없이 렌더되므로 어떤 컨트롤과도 프로그래밍적으로 연결되지 않습니다 — 필요하면 attributes 로 직접 넘겨야 합니다. Flutter 에는 label 시맨틱 자체가 없습니다.
• 제목 레벨은 element 가 그대로 정합니다 — 시각적 크기를 위해 h1 을 고르면 문서 아웃라인도 그렇게 바뀝니다. 크기만 바꾸려면 element 대신 presets 를 쓰세요.

고대비 · 강제 색상처럼 전 컴포넌트에 공통으로 걸리는 축은 전역 접근성 축에서 다룹니다.

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