ChatKit 위젯

ChatKit 위젯

위젯은 ChatKit과 함께 제공되는 컨테이너와 컴포넌트예요. 미리 만들어진 위젯을 쓰거나, 템플릿을 수정하거나, 직접 디자인해서 제품에서 ChatKit을 완전히 커스터마이즈할 수 있어요.

출처: 문서

본문

위젯을 빠르게 디자인하기

ChatKit Studio의 Widget Builder를 사용해 카드 레이아웃, 목록 행, 미리보기 컴포넌트를 실험해 보세요. 만족스러운 디자인이 나오면 생성된 JSON을 통합에 복사하고 백엔드에서 서빙하면 돼요.

자산 업로드하기

자산을 업로드해 ChatKit 위젯을 제품에 맞게 커스터마이즈할 수 있어요. ChatKit은 업로드(파일과 이미지)가 메시지에서 참조되기 전에 백엔드에서 호스팅될 것으로 기대해요. 참조 구현은 Python SDK의 업로드 가이드를 따르세요.

ChatKit 위젯은 컨텍스트, 바로가기, 인터랙티브 카드를 대화에 직접 표시할 수 있어요. 사용자가 위젯 버튼을 클릭하면 애플리케이션이 커스텀 액션 payload를 받아 백엔드에서 응답할 수 있어요.

서버에서 액션 처리하기

위젯 액션은 사용자가 UI에서 로직을 트리거할 수 있게 해요. 액션은 다양한 위젯 노드의 여러 이벤트(예: 버튼 클릭)에 바인딩될 수 있고, 서버나 클라이언트 통합에서 처리돼요.

WidgetsOption(또는 그에 상응하는 React 훅)의 onAction 콜백으로 위젯 이벤트를 잡아요. 액션 payload를 백엔드로 전달해 액션을 처리하세요.

chatkit.setOptions({
  widgets: {
    async onAction(action, item) {
      await fetch("/api/widget-action", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ action, itemId: item.id }),
      });
    },
  },
});

완전한 서버 예시를 찾고 있다면 ChatKit Python SDK 문서의 종단 간 워크스루를 참고하세요.

자세한 내용은 actions 문서에서 더 알아보세요.

Reference

위의 비주얼 빌더와 툴부터 시작하는 걸 권장해요. 나머지 문서는 위젯이 어떻게 동작하는지 배우고 모든 옵션을 보기 위한 것이에요.

위젯은 단일 컨테이너(WidgetRoot)로 구성되고, 그 안에 많은 컴포넌트(WidgetNode)가 들어 있어요.

컨테이너 (WidgetRoot)

컨테이너는 상태 표시 텍스트와 기본 액션 같은 특정 특성이 있어요.

• Card – 위젯을 위한 경계가 있는 컨테이너. 위젯 아래에 상태 표시기와 액션 버튼을 위한 status, confirm, cancel 필드를 지원해요.

  • children: list[WidgetNode]
  • size: "sm" | "md" | "lg" | "full" (기본값: "md")
  • padding: float | str | dict[str, float | str] | None (키: top, right, bottom, left, x, y)
  • background: str | { dark: str, light: str } | None
  • status: { text: str, favicon?: str } | { text: str, icon?: str } | None
  • collapsed: bool | None
  • asForm: bool | None
  • confirm: { label: str, action: ActionConfig } | None
  • cancel: { label: str, action: ActionConfig } | None
  • theme: "light" | "dark" | None
  • key: str | None

• ListView – 항목 각각을 ListViewItem으로 표시하는 세로 목록을 보여줘요.

  • children: list[ListViewItem]
  • limit: int | "auto" | None
  • status: { text: str, favicon?: str } | { text: str, icon?: str } | None
  • theme: "light" | "dark" | None
  • key: str | None

컴포넌트 (WidgetNode)

다음 위젯 유형이 지원돼요. Widget Builder의 components 섹션에서 컴포넌트를 둘러보고 인터랙티브 편집기를 사용할 수도 있어요.

• Badge – 상태나 메타데이터를 위한 작은 라벨.

  • label: str
  • color: "secondary" | "success" | "danger" | "warning" | "info" | "discovery" | None
  • variant: "solid" | "soft" | "outline" | None
  • pill: bool | None
  • size: "sm" | "md" | "lg" | None
  • key: str | None

• Box – 방향, 간격, 스타일링을 지원하는 유연한 레이아웃 컨테이너.

  • children, direction, align, justify, wrap, flex, height, width, minHeight, minWidth, maxHeight, maxWidth, size, minSize, maxSize, gap, padding, margin, border, radius, background, aspectRatio, key를 지원해요.

• Row – 자식을 가로로 배열해요.

  • children, gap, padding, align, justify, flex, height, width, minHeight, minWidth, maxHeight, maxWidth, size, minSize, maxSize, margin, border, radius, background, aspectRatio, key를 지원해요.

• Col – 자식을 세로로 배열해요.

  • children, gap, padding, align, justify, wrap, flex, height, width, minHeight, minWidth, maxHeight, maxWidth, size, minSize, maxSize, margin, border, radius, background, aspectRatio, key를 지원해요.

• Button – 유연한 액션 버튼.

  • submit: bool | None
  • style: "primary" | "secondary" | None
  • label: str
  • onClickAction: ActionConfig
  • iconStart, iconEnd: str | None
  • color: "primary" | "secondary" | "info" | "discovery" | "success" | "caution" | "warning" | "danger" | None
  • variant: "solid" | "soft" | "outline" | "ghost" | None
  • size: "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | None
  • pill, block, uniform, iconSize, key 지원.

• Caption – 더 작은 보조 텍스트.

  • value: str
  • size("sm" | "md" | "lg"), weight, textAlign, color, truncate, maxLines, key 지원.

• DatePicker – 드롭다운 달력이 있는 날짜 입력.

  • onChangeAction, name, min, max, side, align, placeholder, defaultValue, variant, size, pill, block, clearable, disabled, key 지원.

• Divider – 가로 또는 세로 구분선.

  • spacing, color, size, flush, key 지원.

• Icon – 이름으로 아이콘을 표시해요.

  • name: str
  • color, size("xs" | "sm" | "md" | "lg" | "xl"), key 지원.

• Image – 선택적 스타일링, fit, position으로 이미지를 표시해요.

  • size, height, width, minHeight, minWidth, maxHeight, maxWidth, minSize, maxSize, radius, background, margin, aspectRatio, flex, src, alt, fit("none" | "cover" | "contain" | "fill" | "scale-down"), position, frame, flush, key 지원.

• ListView – 항목의 세로 목록을 표시해요.

  • children, limit, status(모양: { text: str, favicon?: str }), theme, key 지원.

• ListViewItem – 선택적 액션이 있는 ListView의 항목.

  • children, onClickAction, gap, align, key 지원.

• Markdown – markdown 형식 텍스트를 렌더링하며, 스트리밍 업데이트를 지원해요.

  • value: str
  • streaming: bool | None
  • key: str | None

• Select – 드롭다운 단일 선택 입력.

  • options: list[dict[str, str]] (각 옵션: { label: str, value: str })
  • onChangeAction, name, placeholder, defaultValue, variant, size, pill, block, clearable, disabled, key 지원.

• Spacer – 레이아웃에 쓰는 유연한 빈 공간.

  • minSize, key 지원.

• Text – 일반 텍스트를 표시해요(markdown 렌더링은 Markdown 사용). 스트리밍 업데이트를 지원해요.

  • value: str
  • color, width, size("xs" | "sm" | "md" | "lg" | "xl"), weight, textAlign, italic, lineThrough, truncate, minLines, maxLines, streaming, editable (dict일 때: { name: str, autoComplete?: str, autoFocus?: bool, autoSelect?: bool, allowAutofillExtensions?: bool, required?: bool, placeholder?: str, pattern?: str })
  • key 지원.

• Title – 눈에 띄는 제목 텍스트.

  • value: str
  • size("xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl"), weight, textAlign, color, truncate, maxLines, key 지원.

• Form – 액션을 제출할 수 있는 레이아웃 컨테이너.

  • onSubmitAction: ActionConfig
  • children, align, justify, flex, gap, height, width, minHeight, minWidth, maxHeight, maxWidth, size, minSize, maxSize, padding, margin, border, radius, background, key 지원.

• Transition – 애니메이션될 수 있는 콘텐츠를 감싸요.

  • children: WidgetNode | None
  • key: str | None

더 알아보기 (Learn more)

• ChatKit 시작하기
• ChatKit 액션
• Widget Builder