useXChat

管理一轮会话里的消息。必须传入 provider。没有 provider 时，onRequest 和 abort 抛出 provider is required。

const {
  onRequest,
  onReload,
  abort,
  messages,
  parsedMessages,
  setMessages,
  setMessage,
  isRequesting,
} = useXChat({
  provider,
  conversationKey: activeConversationKey,
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'failed' },
});

模型接入

模型接入

createOpenAIChatProvider + 本地 SSE mock：输入、流式气泡、取消。

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatModelV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  createOpenAIChatProvider,
  useXChat,
  type XModelMessage,
} from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = createOpenAIChatProvider<XModelMessage>({
  baseURL: 'https://mock.local/v1/chat/completions',
  model: 'mock-gpt',
  key: 'docs-preview',
  fetch: createMockOpenAIFetch(),
});

const { onRequest, messages, isRequesting, abort } = useXChat<XModelMessage>({
  provider,
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const items = computed(() =>
  messages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 420 }}>
    <Bubble.List
      style={{ height: 300 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => <XMarkdown content={content} />,
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Ask the local OpenAI mock"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

隐藏源代码

思考模型接入

思考模型接入

DeepSeekChatProvider 解析 reasoning_content，配合 Think + XMarkdown；仍走本地 mock。

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatDeepSeekV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  Think,
  DeepSeekChatProvider,
  useXChat,
  XRequest,
  type XModelMessage,
  type XModelParams,
} from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockDeepSeekFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = new DeepSeekChatProvider<XModelMessage, XModelParams>({
  request: XRequest('https://mock.local/v1/chat/completions', {
    manual: true,
    fetch: createMockDeepSeekFetch() as never,
    params: { stream: true, model: 'mock-deepseek' },
  }),
});

const { onRequest, messages, isRequesting, abort } = useXChat<XModelMessage>({
  provider,
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const items = computed(() =>
  messages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 420 }}>
    <Bubble.List
      style={{ height: 300 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => (
            <XMarkdown content={content} components={{ think: Think }} />
          ),
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Ask the local DeepSeek mock"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

隐藏源代码

历史消息设置

What is Ant Design X?

Ant Design X is a React/Vue AI interaction component library.

历史消息设置

defaultMessages 预填用户与助手历史，再继续对话。

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatDefaultMessagesV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  createOpenAIChatProvider,
  useXChat,
  type XModelMessage,
} from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = createOpenAIChatProvider<XModelMessage>({
  baseURL: 'https://mock.local/v1/chat/completions',
  model: 'mock-gpt',
  key: 'docs-preview',
  fetch: createMockOpenAIFetch(),
});

const { onRequest, messages, isRequesting, abort } = useXChat<XModelMessage>({
  provider,
  defaultMessages: [
    { message: { role: 'user', content: 'What is Ant Design X?' }, status: 'success' },
    {
      message: {
        role: 'assistant',
        content: 'Ant Design X is a React/Vue AI interaction component library.',
      },
      status: 'success',
    },
  ],
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const items = computed(() =>
  messages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 420 }}>
    <Bubble.List
      style={{ height: 300 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => <XMarkdown content={content} />,
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Continue from history"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

隐藏源代码

系统提示词设置

System prompt: You are a helpful chatbot

系统提示词设置

role: 'developer' 作为系统提示，可在页面上修改。

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatDeveloperV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  createOpenAIChatProvider,
  useXChat,
  type XModelMessage,
} from 'ant-design-x-vue';
import { Button, Flex, Typography } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = createOpenAIChatProvider<XModelMessage>({
  baseURL: 'https://mock.local/v1/chat/completions',
  model: 'mock-gpt',
  key: 'docs-preview',
  fetch: createMockOpenAIFetch((text) => `System-aware mock reply: ${text || 'hi'}`),
});

const { onRequest, messages, isRequesting, abort, setMessage } = useXChat<XModelMessage>({
  provider,
  defaultMessages: [
    {
      id: 'developer',
      message: { role: 'developer', content: 'You are a helpful chatbot' },
      status: 'local',
    },
  ],
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const chatMessages = computed(() =>
  messages.value.filter((m) => (m.message as any)?.role !== 'developer'),
);

const developerPrompt = computed(
  () => messages.value.find((m) => (m.message as any)?.role === 'developer')?.message?.content || 'None',
);

const items = computed(() =>
  chatMessages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 460 }}>
    <Flex gap={8} align="center" wrap="wrap">
      <Typography.Text>
        System prompt: <code>{String(developerPrompt.value)}</code>
      </Typography.Text>
      <Button
        size="small"
        onClick={() =>
          setMessage('developer', {
            message: { role: 'developer', content: 'Modified system prompt' },
            status: 'local',
          } as any)
        }
      >
        Update system prompt
      </Button>
    </Flex>
    <Bubble.List
      style={{ height: 280 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => <XMarkdown content={content} />,
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Chat with a system prompt"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

隐藏源代码

自定义 request

自定义 request

DefaultChatProvider + 自定义 fetch，返回 JSON mock。

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatCustomRequestV2' });

import { computed, ref } from 'vue';
import { Bubble, Sender, DefaultChatProvider, useXChat, XRequest } from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';

interface ChatInput {
  query: string;
}

const sleep = () => new Promise((resolve) => setTimeout(resolve, 1000));

const content = ref('');
const provider = new DefaultChatProvider<string, ChatInput, string>({
  request: XRequest('https://mock.local/chat', {
    manual: true,
    fetch: async (_url, options: any) => {
      await sleep();
      const params = options?.params as ChatInput | undefined;
      return new Response(JSON.stringify([`Mock success return. You said: ${params?.query}`]), {
        headers: { 'Content-Type': 'application/json' },
      });
    },
  }),
});

const { onRequest, messages, isRequesting } = useXChat({
  provider,
  requestPlaceholder: 'Waiting...',
  requestFallback: 'Mock failed return. Please try again later.',
});

const items = computed(() =>
  messages.value.map(({ id, message, status }) => ({
    key: id,
    loading: status === 'loading',
    role: status === 'local' ? 'local' : 'ai',
    content: message,
  })),
);

defineRender(() => (
  <Flex vertical gap="middle">
    <Bubble.List
      style={{ height: 320 }}
      items={items.value}
      roles={{
        ai: { placement: 'start' },
        local: {
          placement: 'end',
          contentRender: (msg: ChatInput | string) =>
            typeof msg === 'string' ? msg : (msg as ChatInput)?.query,
        },
      }}
    />
    <Sender
      loading={isRequesting.value}
      value={content.value}
      onUpdate:value={(v: string) => { content.value = v; }}
      onSubmit={(nextContent: string) => {
        onRequest({ query: nextContent });
        content.value = '';
      }}
    />
  </Flex>
));
</script>

隐藏源代码

API

useXChat

type useXChat<
  ChatMessage extends SimpleType = string,
  ParsedMessage extends SimpleType = ChatMessage,
  Input = RequestParams<ChatMessage>,
  Output = SSEOutput,
> = (config: XChatConfig<ChatMessage, ParsedMessage, Input, Output>) => {
  onRequest: (requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void;
  onReload: (
    id: string | number,
    requestParams: Partial<Input>,
    opts?: { extraInfo: AnyObject },
  ) => void;
  abort: () => void;
  messages: Ref<MessageInfo<ChatMessage>[]>;
  parsedMessages: ComputedRef<MessageInfo<ParsedMessage>[]>;
  setMessages: (...args: Parameters<UseChatStoreReturn['setMessages']>) => void;
  setMessage: (...args: Parameters<UseChatStoreReturn['setMessage']>) => void;
  isRequesting: ComputedRef<boolean>;
};

XChatConfig

属性	说明	类型	默认值	版本
provider	数据提供者，将不同结构的数据与请求转换为 useXChat 可消费的格式。内置 DefaultChatProvider、OpenAIChatProvider，也可继承 AbstractChatProvider 自行实现。见 Chat Provider	AbstractChatProvider<ChatMessage, Input, Output>	-	-
conversationKey	会话 key；可与 useXConversations 的 activeConversationKey 对齐，使每个会话独立消息	ConversationData['key'] | ShallowRef<ConversationData['key'] | undefined>	-	-
defaultMessages	默认展示消息	{ message: ChatMessage; status?: MessageStatus; id?: string | number; extraInfo?: AnyObject }[]	-	-
parser	将 ChatMessage 转为 ParsedMessage；未设置时直接消费 ChatMessage。支持一对多	(message: ChatMessage) => ParsedMessage | ParsedMessage[]	-	-
requestFallback	请求失败时的兜底消息；未提供则不展示兜底	ChatMessage | ((requestParams: Partial<Input>, info: { error: Error; messages: ChatMessage[]; messageInfo: MessageInfo<ChatMessage> }) => ChatMessage | Promise<ChatMessage>)	-	-
requestPlaceholder	请求中的占位消息；未提供则不展示占位	ChatMessage | ((requestParams: Partial<Input>, info: { messages: ChatMessage[] }) => ChatMessage)	-	-

Return

属性	说明	类型	默认值	版本
abort	取消请求	() => void	-	-
isRequesting	是否正在请求（computed）	ComputedRef<boolean>	-	-
messages	当前管理的消息列表	Ref<MessageInfo<ChatMessage>[]>	-	-
parsedMessages	经过 parser 转换后的列表	ComputedRef<MessageInfo<ParsedMessage>[]>	-	-
onReload	按消息 id 重放，向后端发请求并用返回数据更新该消息	(id: string | number, requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void	-	-
onRequest	追加消息并触发请求	(requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void	-	-
setMessages	直接修改消息列表，不触发请求	(messages | updater) => void	-	-
setMessage	直接修改单条消息，不触发请求	(id, info | updater) => void	-	-

MessageInfo

interface MessageInfo<ChatMessage> {
  id: number | string;
  message: ChatMessage;
  status: MessageStatus;
  extraInfo?: AnyObject;
}

MessageStatus

type MessageStatus = 'local' | 'loading' | 'updating' | 'success' | 'error' | 'abort';

1.x 的 useXChat({ agent }) 现在叫 useLegacyXChat，文档在 useXChat 数据管理。

React 文档还有 openai-node 自定义 request 示例（依赖 openai 包）。Vue 文档暂不引入该依赖，见 PR 说明中的缺口列表。