chat-container
채팅 인터페이스를 제공하는 Web Component입니다. 텍스트 입력과 음성 입력 모드를 지원합니다.
사용법
html
<chat-container delay="50"></chat-container>속성
| 속성 | 타입 | 기본값 | 설명 |
|---|---|---|---|
type | string | "text" | 입력 모드. "text" | "voice" |
delay | number | 30 | 응답 텍스트 타이핑 효과 딜레이 (글자당 ms). 0으로 설정해도 렌더링 프레임당 1글자씩 표시됩니다(즉시 표시 아님). |
isShowCount | boolean | true | 텍스트 모드에서 글자 수 카운터 표시 여부 |
scrollbar | boolean | false | 메시지 영역 스크롤바 표시 여부. 스크롤바를 숨기려면 속성을 쓰지 않습니다. |
boolean 속성 지정 방법
isShowCount와 scrollbar는 HTML 속성으로 쓸 때의 해석 규칙이 서로 다릅니다.
| 속성 | 속성 생략 | ="false" | 그 외 값 (="", ="true" 등) |
|---|---|---|---|
isShowCount | true (기본값) | false | true |
scrollbar | false (기본값) | true | true |
isShowCount는isShowCount="false"로 끌 수 있습니다. 속성을 생략하면 기본값true이며,"false"외의 문자열은 모두true로 해석됩니다.scrollbar는 속성이 존재하기만 하면 값과 상관없이true입니다. 끄려면 속성 자체를 쓰지 않아야 합니다.- HTML 속성명은 대소문자를 구분하지 않으므로
isShowCount와isshowcount모두 동일하게 동작합니다. 브라우저 개발자 도구에는 소문자(isshowcount)로 표시됩니다.
scrollbar="false"는 스크롤바를 숨기지 않습니다
scrollbar는 속성이 붙어 있다는 사실만으로 true가 되므로, scrollbar="false"라고 써도 스크롤바가 표시됩니다. 숨기려면 속성을 생략하거나 JavaScript 프로퍼티로 false를 지정하세요.
html
<!-- isShowCount: true (카운터 표시), scrollbar: false (스크롤바 숨김) -->
<chat-container></chat-container>html
<!-- 글자 수 카운터 숨기기 -->
<chat-container isShowCount="false"></chat-container>
<!-- 스크롤바 표시하기 (속성이 있으면 true) -->
<chat-container scrollbar></chat-container>js
const el = document.querySelector('chat-container');
// 프로퍼티에는 false를 그대로 지정할 수 있습니다.
el.isShowCount = false; // 카운터 숨김
el.scrollbar = false; // 스크롤바 숨김
el.scrollbar = true; // 스크롤바 표시입력 모드
텍스트 모드 (type="text")
텍스트 입력창과 전송 버튼을 표시합니다.
- 전송: Enter 키 또는 전송 아이콘 클릭
- 줄바꿈: Shift + Enter
- IME 처리: 한국어/일본어 등 조합 중에는 Enter로 전송되지 않습니다.
- 글자 제한: 최대 350자
- 모바일: 모바일 환경에서는 Enter 키가 줄바꿈으로 동작합니다 (전송 버튼 사용).
- 자동 포커스: 아바타 응답 완료 후 텍스트 입력창에 자동 포커스됩니다.
우측의 마이크 아이콘을 클릭하면 음성 모드로 전환됩니다.
음성 모드 (type="voice")
마이크 버튼을 표시합니다.
- 녹음 시작: 마이크 버튼 클릭
- 녹음 종료: 정지 버튼 클릭 또는 10초 경과 시 자동 종료
- 시각 피드백: 녹음 중 파형 애니메이션과 카운트다운 타이머 표시
- 내부적으로
SDK.startListening(),SDK.endListening()을 호출합니다.
좌측의 키보드 아이콘을 클릭하면 텍스트 모드로 전환됩니다.
메시지 표시
- SDK의 메시지 목록(
sendMessage,speak, STT 결과, 아바타 응답)을 자동으로 표시합니다. - 가상 스크롤링을 사용하여 대량의 메시지도 성능 저하 없이 렌더링합니다.
- 새 메시지 수신 시 자동으로 하단으로 스크롤됩니다.
타이핑 효과
- 아바타 응답(response) 메시지는
delay속성에 지정된 간격으로 한 글자씩 표시됩니다. - 사용자 메시지(request)는 타이핑 효과 없이 즉시 표시됩니다.
- 새 메시지가 도착하면 진행 중인 타이핑이 즉시 완료되고 새 메시지의 타이핑이 시작됩니다.
로딩 표시
아바타가 응답을 준비 중일 때(RESPONSE_PREPARING 시그널) 마지막 사용자 메시지 아래에 로딩 애니메이션이 표시됩니다.
비활성 상태
SDK 상태가 CONNECTED_FINISH가 아니거나, 아바타가 응답 중일 때 입력이 비활성화됩니다. 다음 시그널이 수신되면 입력이 다시 활성화됩니다:
RESPONSE_ENDED— 아바타 응답 완료ERROR— 에러 수신REJECTED— 요청 거절
스타일링
Shadow DOM
Shadow DOM으로 캡슐화되어 있어, style 속성은 컴포넌트의 크기, 위치, 테두리 등 외부 레이아웃에만 적용됩니다. 내부 요소(배경색, 메시지 버블 등)의 스타일은 변경할 수 없습니다.
html
<chat-container
style="
height: 300px;
border: 1px solid #e0e0e0;
border-radius: 12px;
"
></chat-container>