ChatKit ウィジェット

ウィジェットは、ChatKit が提供するコンテナとコンポーネントです。既製のウィジェットを使うことも、テンプレートを変更することも、独自のウィジェットを設計することもできます。製品に合わせて ChatKit を自由にカスタマイズできます。

ウィジェットの手軽な設計

ChatKit Studio の Widget Builder を使うと、カードのレイアウトやリストの各行の構成を試し、コンポーネントをプレビューできます。デザインが決まったら、生成された JSON をアプリケーションにコピーし、バックエンドから配信します。

アセットのアップロード

アセットをアップロードすると、製品に合わせて ChatKit ウィジェットをカスタマイズできます。ChatKit では、アップロードしたファイルや画像をメッセージ内で参照する前に、バックエンドでホストしておく必要があります。実装例は Python SDK のアップロードガイドを参照してください。

ChatKit ウィジェットを使うと、コンテキストやショートカット、操作可能なカードを会話内に直接表示できます。ユーザーがウィジェットのボタンをクリックすると、アプリケーションがカスタムアクションのペイロードを受け取り、バックエンドから応答できます。

サーバーでのアクション処理

ウィジェットのアクションを使うと、ユーザーは UI から処理を実行できます。各ウィジェットノードのイベント（ボタンのクリックなど）にアクションを割り当て、そのアクションをサーバー側またはクライアント側で処理できます。

onAction コールバックは WidgetsOption または同等の React フックから利用できます。このコールバックでウィジェットのイベントを受け取り、アクションのペイロードをバックエンドに転送して処理します。

1
2
3
4
5
6
7
8
9
10
11chatkit.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 のドキュメントを参照してください。実装の手順を最初から最後まで説明しています。

詳しくは、アクションのドキュメントを参照してください。

リファレンス

まずは、上で紹介したビジュアルビルダーやツールを使ってみてください。以降では、ウィジェットの仕組みと、指定できるすべてのオプションを説明します。

ウィジェットは、1 つのコンテナ（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 のコンポーネント一覧では、各コンポーネントを確認し、対話型エディターで試すこともできます。

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: list[WidgetNode] | None
- direction: “row” | “column” | None
- align: “start” | “center” | “end” | “baseline” | “stretch” | None
- justify: “start” | “center” | “end” | “stretch” | “between” | “around” | “evenly” | None
- wrap: “nowrap” | “wrap” | “wrap-reverse” | None
- flex: int | str | None
- height: float | str | None
- width: float | str | None
- minHeight: int | str | None
- minWidth: int | str | None
- maxHeight: int | str | None
- maxWidth: int | str | None
- size: float | str | None
- minSize: int | str | None
- maxSize: int | str | None
- gap: int | str | None
- padding: float | str | dict[str, float | str] | None （キー: top、right、bottom、left、x、y）
- margin: float | str | dict[str, float | str] | None （キー: top、right、bottom、left、x、y）
- border: int | dict[str, Any] | None （全辺共通: { size: int, color?: str | { dark: str, light: str }, style?: “solid” | “dashed” | “dotted” | “double” | “groove” | “ridge” | “inset” | “outset” } per-side: { top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict }）
- radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
- background: str | { dark: str, light: str } | None
- aspectRatio: float | str | None
- key: str | None
Row – 子要素を横方向に並べます。
- children: list[WidgetNode] | None
- gap: int | str | None
- padding: float | str | dict[str, float | str] | None （キー: top、right、bottom、left、x、y）
- align: “start” | “center” | “end” | “baseline” | “stretch” | None
- justify: “start” | “center” | “end” | “stretch” | “between” | “around” | “evenly” | None
- flex: int | str | None
- height: float | str | None
- width: float | str | None
- minHeight: int | str | None
- minWidth: int | str | None
- maxHeight: int | str | None
- maxWidth: int | str | None
- size: float | str | None
- minSize: int | str | None
- maxSize: int | str | None
- margin: float | str | dict[str, float | str] | None （キー: top、right、bottom、left、x、y）
- border: int | dict[str, Any] | None （全辺共通: { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } 辺ごと: { top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict }）
- radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
- background: str | { dark: str, light: str } | None
- aspectRatio: float | str | None
- key: str | None
Col – 子要素を縦方向に並べます。
- children: list[WidgetNode] | None
- gap: int | str | None
- padding: float | str | dict[str, float | str] | None （キー: top、right、bottom、left、x、y）
- align: “start” | “center” | “end” | “baseline” | “stretch” | None
- justify: “start” | “center” | “end” | “stretch” | “between” | “around” | “evenly” | None
- wrap: “nowrap” | “wrap” | “wrap-reverse” | None
- flex: int | str | None
- height: float | str | None
- width: float | str | None
- minHeight: int | str | None
- minWidth: int | str | None
- maxHeight: int | str | None
- maxWidth: int | str | None
- size: float | str | None
- minSize: int | str | None
- maxSize: int | str | None
- margin: float | str | dict[str, float | str] | None （キー: top、right、bottom、left、x、y）
- border: int | dict[str, Any] | None （全辺共通: { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } 辺ごと: { top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict }）
- radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
- background: str | { dark: str, light: str } | None
- aspectRatio: float | str | None
- key: str | None
Button – 用途に合わせて設定できるアクションボタン
- submit: bool | None
- style: “primary” | “secondary” | None
- label: str
- onClickAction: ActionConfig
- iconStart: str | None
- 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: bool | None
- block: bool | None
- uniform: bool | None
- iconSize: “sm” | “md” | “lg” | “xl” | “2xl” | None
- key: str | None
Caption – 補足情報を示す小さめのテキスト
- value: str
- size: “sm” | “md” | “lg” | None
- weight: “normal” | “medium” | “semibold” | “bold” | None
- textAlign: “start” | “center” | “end” | None
- color: str | { dark: str, light: str } | None
- truncate: bool | None
- maxLines: int | None
- key: str | None
DatePicker – ドロップダウンカレンダー付きの日付入力欄
- onChangeAction: ActionConfig | None
- name: str
- min: datetime | None
- max: datetime | None
- side: “top” | “bottom” | “left” | “right” | None
- align: “start” | “center” | “end” | None
- placeholder: str | None
- defaultValue: datetime | None
- variant: “solid” | “soft” | “outline” | “ghost” | None
- size: “3xs” | “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | None
- pill: bool | None
- block: bool | None
- clearable: bool | None
- disabled: bool | None
- key: str | None
Divider – 横方向または縦方向の区切り線
- spacing: int | str | None
- color: str | { dark: str, light: str } | None
- size: int | str | None
- flush: bool | None
- key: str | None
Icon – 名前で指定したアイコンを表示します。
- name: str
- color: str | { dark: str, light: str } | None
- size: “xs” | “sm” | “md” | “lg” | “xl” | None
- key: str | None
Image – 画像を表示します。必要に応じてスタイル、表示領域への収め方、位置を指定できます。
- size: int | str | None
- height: int | str | None
- width: int | str | None
- minHeight: int | str | None
- minWidth: int | str | None
- maxHeight: int | str | None
- maxWidth: int | str | None
- minSize: int | str | None
- maxSize: int | str | None
- radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
- background: str | { dark: str, light: str } | None
- margin: int | str | dict[str, int | str] | None （キー: top、right、bottom、left、x、y）
- aspectRatio: float | str | None
- flex: int | str | None
- src: str
- alt: str | None
- fit: “none” | “cover” | “contain” | “fill” | “scale-down” | None
- position: “center” | “top” | “bottom” | “left” | “right” | “top left” | “top right” | “bottom left” | “bottom right” | None
- frame: bool | None
- flush: bool | None
- key: str | None
ListView – 項目を縦に並べたリストを表示します。
- children: list[ListViewItem] | None
- limit: int | “auto” | None
- status: dict[str, Any] | None （形式: { text: str, favicon?: str }）
- theme: “light” | “dark” | None
- key: str | None
ListViewItem – ListView 内の項目です。必要に応じてアクションを設定できます。
- children: list[WidgetNode] | None
- onClickAction: ActionConfig | None
- gap: int | str | None
- align: “start” | “center” | “end” | “baseline” | “stretch” | None
- key: str | None
Markdown – Markdown 形式のテキストをレンダリングします。ストリーミングによる更新に対応しています。
- value: str
- streaming: bool | None
- key: str | None
Select – 項目を 1 つ選択できるドロップダウン入力欄
- options: list[dict[str, str]] （各選択肢の形式: { label: str, value: str }）
- onChangeAction: ActionConfig | None
- name: str
- placeholder: str | None
- defaultValue: str | None
- variant: “solid” | “soft” | “outline” | “ghost” | None
- size: “3xs” | “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | None
- pill: bool | None
- block: bool | None
- clearable: bool | None
- disabled: bool | None
- key: str | None
Spacer – レイアウト内に配置する伸縮可能な空白
- minSize: int | str | None
- key: str | None
Text – プレーンテキストを表示します（Markdown のレンダリングには Markdown を使います）。ストリーミングによる更新に対応しています。
- value: str
- color: str | { dark: str, light: str } | None
- width: float | str | None
- size: “xs” | “sm” | “md” | “lg” | “xl” | None
- weight: “normal” | “medium” | “semibold” | “bold” | None
- textAlign: “start” | “center” | “end” | None
- italic: bool | None
- lineThrough: bool | None
- truncate: bool | None
- minLines: int | None
- maxLines: int | None
- streaming: bool | None
- editable: bool | dict[str, Any] | None （辞書の場合: { name: str, autoComplete?: str, autoFocus?: bool, autoSelect?: bool, allowAutofillExtensions?: bool, required?: bool, placeholder?: str, pattern?: str }）
- key: str | None
Title – 目立つように表示する見出しテキスト
- value: str
- size: “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “5xl” | None
- weight: “normal” | “medium” | “semibold” | “bold” | None
- textAlign: “start” | “center” | “end” | None
- color: str | { dark: str, light: str } | None
- truncate: bool | None
- maxLines: int | None
- key: str | None
Form – アクションを送信できるレイアウト用コンテナ
- onSubmitAction: ActionConfig
- children: list[WidgetNode] | None
- align: “start” | “center” | “end” | “baseline” | “stretch” | None
- justify: “start” | “center” | “end” | “stretch” | “between” | “around” | “evenly” | None
- flex: int | str | None
- gap: int | str | None
- height: float | str | None
- width: float | str | None
- minHeight: int | str | None
- minWidth: int | str | None
- maxHeight: int | str | None
- maxWidth: int | str | None
- size: float | str | None
- minSize: int | str | None
- maxSize: int | str | None
- padding: float | str | dict[str, float | str] | None （キー: top、right、bottom、left、x、y）
- margin: float | str | dict[str, float | str] | None （キー: top、right、bottom、left、x、y）
- border: int | dict[str, Any] | None （全辺共通: { size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" } 辺ごと: { top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict }）
- radius: “2xs” | “xs” | “sm” | “md” | “lg” | “xl” | “2xl” | “3xl” | “4xl” | “full” | “100%” | “none” | None
- background: str | { dark: str, light: str } | None
- key: str | None
Transition – アニメーションを適用する可能性のあるコンテンツを囲みます。
- children: WidgetNode | None
- key: str | None

おすすめ

はじめに

基本概念

SDK と CLI

クラウドプロバイダー

リソース

レガシー API

モデルの選び方

テキストとコード

プロンプトの書き方

推論

画像

リアルタイム処理とオーディオ

特化型モデル

Agents API

Agents SDK

ChatKit

検索と情報取得

ツールとデータの接続

ツールを使ったワークフローの構築

コンピューターとコード

メディア

GPT-Live

Realtime API

音声を使った開発

接続

音声処理

本番稼働の開始

パフォーマンスと品質

評価

コストとスループット

安全性とガバナンス

インフラとアクセス

業務運営

基本概念

計画

開発

テストと公開

コンバージョン仕様

ガイド

リソース

アイデンティティ

ChatGPT プランの利用状況

ガイド

ファイルのアップロード

API

効果測定

広告主向け API

API リファレンス

はじめに

はじめに

基礎

探す

対応プラットフォーム

リリース

ワークフロー

できること

Sites

dot

ChatGPT Space

リファレンス

カスタマイズ

設定ファイル

エージェントの設定

ChatGPT と Codex の機能拡張

Linux

Windows

開発ワークフロー

機能拡張と自動化

環境

Codex Cloud

Codex を使った開発

サードパーティ連携

リファレンス

権限

Codex Security

サイバー安全対策

はじめに

機能設定

ID とアクセス管理

コンテナ（`WidgetRoot`）

コンポーネント（`WidgetNode`）