use-x-chat

Focus on explaining how to use the useXChat Hook, including custom Provider integration, message management, error handling, multi-conversation management, and more

Ir a la instalación

Repositorio: ant-design/x
Última actividad en el origen: 23 de julio de 2026 a las 06:55
Idioma detectado de SKILL.md: inglés
Estrellas: 4743
Forks: 1151

Opciones de instalación

De forma predeterminada está seleccionado el prompt que primero revisa el origen. Puedes cambiar a un comando directo o descargar una copia local.

Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.

Un comando directo omite el prompt de revisión. Revisa el origen antes de ejecutarlo.

npx skills add https://github.com/ant-design/x --skill use-x-chat

El comando permanece en una sola línea. Desplázate horizontalmente para revisarlo antes de copiarlo.

¿Prefieres una copia local? Descarga los archivos que SkillsMP tiene disponibles ahora.

Revisa los archivos de origen

Lee SKILL.md y los archivos complementarios que muestra SkillsMP antes de decidir si quieres instalarlo.

Explorador de archivos

4 archivos

SKILL.md

Instrucciones de origen · Vista previa de solo lectura

Volver a la búsqueda Volver a la instalación

import { MyChatProvider } from './MyChatProvider';
import { XRequest } from '@ant-design/x-sdk';

// ⚠️ manual: true is required
const provider = new MyChatProvider({
  request: XRequest('https://your-api.com/chat', { manual: true }),
});

import { useXChat } from '@ant-design/x-sdk';

const ChatComponent = () => {
  const { messages, onRequest, isRequesting } = useXChat({
    provider,
    requestPlaceholder: (_, { messages }) => ({
      content: 'Thinking...',
      role: 'assistant',
    }),
    requestFallback: (_, { error, messageInfo }) => {
      if (error.name === 'AbortError') {
        return { content: messageInfo?.message?.content || 'Reply cancelled', role: 'assistant' };
      }
      return { content: 'Network error, please try again later', role: 'assistant' };
    },
  });

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          {msg.message.role}: {msg.message.content}
        </div>
      ))}
      <button onClick={() => onRequest({ query: 'Hello' })}>Send</button>
    </div>
  );
};

import { Bubble, Sender } from '@ant-design/x';

const ChatUI = () => {
  const { messages, onRequest, isRequesting, abort } = useXChat({ provider });

  return (
    <div style={{ height: 600 }}>
      <Bubble.List
        // ✅ Correct: use role (not roles)
        role={{
          user: { placement: 'end' },
          assistant: { placement: 'start' },
        }}
        items={messages.map(({ id, message, status }) => ({
          key: id,
          role: message.role, // matches role config key
          content: message.content, // message content
          loading: status === 'loading', // loading animation
        }))}
      />
      <Sender
        loading={isRequesting}
        onSubmit={(content) => onRequest({ query: content })}
        onCancel={abort}
      />
    </div>
  );
};

<Bubble.List
  role={{
    assistant: {
      placement: 'start',
      // contentRender receives content param, which is the message field itself
      contentRender(content: MyMessage) {
        return (
          <div>
            <div>{content.content}</div>
            {content.attachments?.map((a) => (
              <FileCard key={a.url} name={a.name} />
            ))}
          </div>
        );
      },
    },
    user: {
      placement: 'end',
      contentRender(content: MyMessage) {
        return content.content;
      },
    },
  }}
  items={messages.map(({ id, message, status }) => ({
    key: id,
    role: message.role,
    content: message, // ⚠️ Pass the entire message object; contentRender handles rendering
    loading: status === 'loading',
  }))}
/>

interface MessageInfo<ChatMessage> {
  id: number | string; // Message unique identifier
  message: ChatMessage; // Actual message content (your ChatMessage type)
  status: MessageStatus; // Message status
  extraInfo?: AnyObject; // Extended info (note: extraInfo, not extra)
}

type MessageStatus = 'local' | 'loading' | 'updating' | 'success' | 'error' | 'abort';
// local: locally sent user message
// loading: AI reply placeholder (corresponds to requestPlaceholder)
// updating: AI streaming output in progress
// success: AI reply complete
// error: request failed
// abort: user actively cancelled

Option	Type	Description
`provider`	`AbstractChatProvider<ChatMessage, Input, Output>`	Required, Provider instance
`conversationKey`	`string`	Conversation unique identifier, required for multi-conversation
`defaultMessages`	`DefaultMessageInfo[] \| () => ... \| async () => ...`	Default display messages, supports async loading
`requestPlaceholder`	`ChatMessage \| (requestParams, { messages }) => ChatMessage`	Placeholder message during request
`requestFallback`	`ChatMessage \| (requestParams, { error, errorInfo, messages, messageInfo }) => ChatMessage \| Promise<ChatMessage>`	Fallback message on request failure/abort
`parser`	`(message: ChatMessage) => BubbleMessage \| BubbleMessage[]`	Convert ChatMessage to component-consumable format, supports one-to-many

Return Value	Type	Description
`messages`	`MessageInfo<ChatMessage>[]`	Message list; must be mapped before passing to `Bubble.List`
`parsedMessages`	`MessageInfo<ParsedMessage>[]`	Message list after `parser` transform (use this when parser is set)
`onRequest`	`(params: Partial<Input>, opts?: { extraInfo: AnyObject }) => void`	Add message and trigger request
`isRequesting`	`boolean`	Whether request is in progress
`abort`	`() => void`	Abort current request
`setMessages`	`(messages: Partial<MessageInfo<ChatMessage>>[]) => void`	Directly modify message list, no request triggered
`setMessage`	`(id: string \| number, info: Partial<MessageInfo<ChatMessage>>) => void`	Modify single message, no request triggered
`removeMessage`	`(id: string \| number) => boolean`	Delete a message, returns whether deletion was successful
`onReload`	`(id: string \| number, params: Partial<Input>, opts?: { extraInfo: AnyObject }) => void`	Regenerate an AI reply
`queueRequest`	`(conversationKey: string \| symbol, params: Partial<Input>, opts?: { extraInfo: AnyObject }) => void`	Queue request, sent after conversation initializes
`isDefaultMessagesRequesting`	`boolean`	Whether default messages are async loading

import { useXConversations } from '@ant-design/x-sdk';
import type { ConversationData } from '@ant-design/x-sdk';

const {
  conversations, // ConversationData[]: conversation list
  activeConversationKey, // string: currently active conversation key
  setActiveConversationKey, // (key: string) => void: switch conversation
  addConversation, // (ConversationData, placement?) => boolean
  removeConversation, // (key: string) => boolean
  setConversation, // (key: string,  ConversationData) => boolean
  getConversation, // (key: string) => ConversationData | undefined
  setConversations, // (list: ConversationData[]) => void
  getMessages, // (key: string) => MessageInfo[] | undefined (read messages across components)
} = useXConversations({
  defaultConversations: [
    { key: 'conv-1', label: 'Conversation 1' },
    { key: 'conv-2', label: 'Conversation 2' },
  ],
  defaultActiveConversationKey: 'conv-1',
});

import { useXChat, useXConversations } from '@ant-design/x-sdk';
import { OpenAIChatProvider, XRequest } from '@ant-design/x-sdk';
import { Bubble, Conversations, Sender } from '@ant-design/x';
import React, { useEffect, useRef } from 'react';

// ⚠️ Each conversation must have its own Provider instance, otherwise state mixes
const providerCache = new Map<string, OpenAIChatProvider>();

function getProvider(key: string): OpenAIChatProvider {
  if (!providerCache.has(key)) {
    providerCache.set(
      key,
      new OpenAIChatProvider({
        request: XRequest(BASE_URL, { manual: true, params: { model: 'gpt-4o', stream: true } }),
      }),
    );
  }
  return providerCache.get(key)!;
}

const App = () => {
  const senderRef = useRef<any>(null);

  const { conversations, activeConversationKey, setActiveConversationKey, addConversation } =
    useXConversations({
      defaultConversations: [{ key: 'conv-1', label: 'New Conversation' }],
      defaultActiveConversationKey: 'conv-1',
    });

  const { messages, onRequest, isRequesting, abort, queueRequest } = useXChat({
    provider: getProvider(activeConversationKey),
    conversationKey: activeConversationKey,
    // Async load default messages
    defaultMessages: async ({ conversationKey }) => {
      // Load history from server based on conversationKey
      return [];
    },
    requestFallback: (_, { error, messageInfo }) => {
      if (error.name === 'AbortError') {
        return { content: messageInfo?.message?.content || 'Cancelled', role: 'assistant' };
      }
      return { content: 'Request failed', role: 'assistant' };
    },
  });

  // Clear input on conversation switch
  useEffect(() => {
    senderRef.current?.clear?.();
  }, [activeConversationKey]);

  const handleNewConversation = () => {
    const newKey = `conv-${Date.now()}`;
    addConversation({ key: newKey, label: `New Conversation ${conversations.length + 1}` });
    setActiveConversationKey(newKey);
  };

  return (
    <div style={{ display: 'flex', height: '100vh' }}>
      <Conversations
        items={conversations}
        activeKey={activeConversationKey}
        onActiveChange={setActiveConversationKey}
        creation={{ onClick: handleNewConversation }}
      />
      <div style={{ flex: 1, display: 'flex', flexDirection: 'column' }}>
        <Bubble.List
          role={{ assistant: { placement: 'start' }, user: { placement: 'end' } }}
          items={messages.map(({ id, message, status }) => ({
            key: id,
            role: message.role,
            content: message.content,
            loading: status === 'loading',
          }))}
        />
        <Sender
          ref={senderRef}
          loading={isRequesting}
          onCancel={abort}
          onSubmit={(val) => {
            onRequest({ messages: [{ role: 'user', content: val }] });
          }}
        />
      
    
  );
};

// Scenario: user switches to a new conversation and triggers an initial message simultaneously
// queueRequest waits for defaultMessages async loading to complete, then sends the request

const handleNewConversationWithFirstMessage = () => {
  const newKey = `conv-${Date.now()}`;
  addConversation({ key: newKey, label: 'New Conversation' });
  setActiveConversationKey(newKey);

  // Queue the message; sent automatically after newKey conversation's defaultMessages finish loading
  queueRequest(newKey, {
    messages: [{ role: 'user', content: 'Hello! Please introduce yourself.' }],
  });
};

Usage Scenario	Required Skill/Provider	Order
Private API Adaptation	x-chat-provider → use-x-chat	Create Provider first
Standard API	Built-in Provider + use-x-chat	Direct use
Multi-conversation	Provider factory + useXConversations + useXChat	Use together

use-x-chat

Opciones de instalación

Revisa los archivos de origen

🎯 Skill Positioning

Table of Contents

🚀 Quick Start

1. Dependency Management

2. Three-step Integration

Step 1: Prepare Provider

🎯 Skill Positioning

Table of Contents

🚀 Quick Start

1. Dependency Management

2. Three-step Integration

Step 1: Prepare Provider

Step 2: Basic Usage

Step 3: UI Integration

When ChatMessage is an object type (not string)

🧩 Core Concepts

Data Model

useXChat Configuration Options

useXChat Return Values

🔧 Core Function Details

🗂️ Multi-conversation Management

useXConversations Hook

Multi-conversation Full Pattern

queueRequest: Delayed Send After Conversation Switch

📋 Prerequisites and Dependencies

🚨 Development Rules

Test Case Rules

Code Quality Rules

🔗 Reference Resources

📚 Core Reference Documentation

🌐 SDK Official Documentation

💻 Example Code

name	use-x-chat
version	2.9.0
description	Focus on explaining how to use the useXChat Hook, including custom Provider integration, message management, error handling, multi-conversation management, and more

use-x-chat

Datos de origen

Opciones de instalación

Revisa los archivos de origen

Más de este repositorio

Más de este repositorio

🎯 Skill Positioning

Table of Contents

🚀 Quick Start

1. Dependency Management

2. Three-step Integration

Step 1: Prepare Provider

🎯 Skill Positioning

Table of Contents

🚀 Quick Start

1. Dependency Management

2. Three-step Integration

Step 1: Prepare Provider

Step 2: Basic Usage

Step 3: UI Integration

When ChatMessage is an object type (not string)

🧩 Core Concepts

Data Model

useXChat Configuration Options

useXChat Return Values

🔧 Core Function Details

🗂️ Multi-conversation Management

useXConversations Hook

Multi-conversation Full Pattern

queueRequest: Delayed Send After Conversation Switch

📋 Prerequisites and Dependencies

🚨 Development Rules

Test Case Rules

Code Quality Rules

🔗 Reference Resources

📚 Core Reference Documentation

🌐 SDK Official Documentation

💻 Example Code