ChatMessage
GPT-5식 비대칭 대화 메시지 — 사용자는 우측 회색 버블, 어시스턴트는 버블 없는 전폭 텍스트 + 하단 액션바. 화자는 정렬·표면으로 구분(아바타 없음).
마지막 업데이트 2026-06-25
한눈에#
대화 한 턴을 그리는 비대칭 메시지입니다. role로 렌더가 갈립니다 — 사용자는 우측 회색 버블, 어시스턴트는 버블 없는 전폭 텍스트에 하단 액션바를 답니다. 메신저식 양방향 버블이 아니라 ChatGPT(GPT-5) 컨벤션을 따릅니다(스레드 내 아바타·타임스탬프 없음).
--wds-color-* 토큰이 다크 테마에서 자동으로 재바인딩되므로, 컴포넌트는 색을 하드코딩하지 않고 토큰만 소비하면 그대로 적응합니다.- 역할별 렌더 — user/assistant
- 사용자 = 우측 회색 버블
- 어시스턴트 = 전폭 텍스트 + 액션바
- 화자 구분 = 정렬·표면(아바타 없음)
children으로 텍스트·마크다운·스트리밍 부분 텍스트를 그대로 받습니다
사용 시점#
AI 대화 한 턴을 그릴 때 — 스레드(ChatThread) 안에서 메시지를 쌓는 단위입니다. 일반 메신저처럼 양쪽 다 버블이 필요한 화면이면 이 컴포넌트가 아닙니다.
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
--wds-color-* 토큰이 다크 테마에서 자동으로 재바인딩되므로, 컴포넌트는 색을 하드코딩하지 않고 토큰만 소비하면 그대로 적응합니다.쓴다 — AI 대화 — 사용자/어시스턴트 비대칭 메시지
스레드로 묶기 — 여러 메시지는 ChatThread로 — role=log·자동 스크롤
해부#
role이 레이아웃을 가르고, 내용·액션은 슬롯으로 주입합니다.
| 영역 | prop | 설명 |
|---|---|---|
| 화자 | role | user(우측 회색 버블) · assistant(전폭 텍스트) |
| 내용 | children | 텍스트·마크다운·스트리밍 부분 텍스트 노드 |
| 액션바 | actions | assistant 전용 — 하단 액션바(MessageActions). user면 무시 |
| 진행 라벨 | activityLabel | assistant 전용 — 진행 단계 라벨(“문서 검색 중”). 값이 있을 때만 렌더(없으면 침묵) |
| 라벨 톤 | activityTone | running(기본) · error(실패·타임아웃) |
스트리밍 중 부분 텍스트도 children으로 주입합니다 — 부분 텍스트 버블은 aria-hidden을 루트로 전달해 토큰마다 낭독되는 잼을 막습니다(나머지 div 속성도 루트로 전달).
진행 라벨(activity)#
파이프라인 단계가 진행 중일 때 thinking 인디케이터에 인접한 단일 라인으로 상태를 알립니다.
ai-chat 패턴의 활동 진위 규율을 구현으로 옮긴 것 — 라벨은 실제 단계
이벤트가 있을 때만 넘기고(없으면 미지정=침묵), 값이 바뀌면 그 자리에서 텍스트가 교체·fade됩니다.
실패·타임아웃은 activityTone="error"로 실제 상태를 드러냅니다(시간 기반 가짜 완료 금지).
- 별도
aria-live를 두지 않습니다 —ChatThread의role="log"(aria-live) 영역이 라벨 교체를 낭독해 이중 낭독을 피합니다. - 누적 단계를 펼쳐 보여야 하면 새 컴포넌트 대신 Accordion으로 접이식 영역을 만듭니다.
API#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
role | 'user' | 'assistant' | — | 화자 — user | assistant. |
children | ReactNode | — | 메시지 내용 — 텍스트·마크다운 노드(스트리밍 부분 텍스트도 가능). |
actions | ReactNode | — | assistant 전용 — 하단 액션바(예: MessageActions). user면 무시한다. |
activityLabel | string | — | assistant 전용 — 진행 단계 라벨(예: "문서 검색 중"). 실제 단계 이벤트가 있을 때만 넘긴다. 빈 문자열·미지정이면 렌더하지 않는다(없으면 침묵). 값이 바뀌면 그 자리에서 텍스트가 교체·fade된다. |
activityTone | 'running' | 'error' | running | 진행 라벨 톤 — 기본 running. 실패/타임아웃은 error(실제 상태 반영, 가짜 완료 금지). |
그 외 표준 div 속성(aria-hidden·id·data-* 등)을 루트로 전달합니다 — role만 화자 prop으로 가로챕니다.
접근성#
| 계약 | 구현 |
|---|---|
| 화자 구분 | 각 메시지에 보조기술 전용 화자 접두(“나:/어시스턴트:”) — 시각은 정렬·표면으로 구분(아바타 없음) |
| 스트리밍 낭독 | 부분 텍스트 버블은 aria-hidden(루트 전달) — 완성 메시지만 1회 낭독, 토큰마다 잼 방지 |
| 액션바 | MessageActions가 role="group" + 버튼별 aria-label 내장 |
| 모션 | 메시지 등장은 transform/opacity만, prefers-reduced-motion에서 정지 |