▲ AI Elements

AI Elements 是一个基于 shadcn/ui 构建的组件库，旨在帮助您更快地构建原生 AI 应用程序。

概述

AI Elements 提供了专为 AI 应用设计的预构建、可定制的 React 组件，包括对话、消息、代码块、推理展示等。通过 CLI，您可以轻松地将这些组件添加到您的 Next.js 项目中。

安装

您可以直接使用 npx 运行 AI Elements CLI，也可以将其全局安装：

# 直接使用（推荐）
npx ai-elements@latest

# 或者使用 shadcn CLI
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

先决条件

在使用 AI Elements 之前，请确保您的项目满足以下要求：

• Node.js 18 或更高版本
• 已安装 AI SDK 的 Next.js 项目
• 项目中已初始化 shadcn/ui（运行 npx shadcn@latest init）
• 配置了 Tailwind CSS（AI Elements 仅支持 CSS 变量模式）

使用方法

安装所有组件

一次安装所有可用的 AI Elements 组件：

npx ai-elements@latest

此命令将执行以下操作：

• 如果尚未配置 shadcn/ui，则进行设置
• 将所有 AI Elements 组件安装到您配置的组件目录中
• 向您的项目添加必要的依赖项

安装特定组件

使用 add 命令安装单个组件：

npx ai-elements@latest add <组件名>

示例：

# 安装消息组件
npx ai-elements@latest add message

# 安装对话组件
npx ai-elements@latest add conversation

# 安装代码块组件
npx ai-elements@latest add code-block

替代方案：与 shadcn CLI 结合使用

您也可以使用标准的 shadcn/ui CLI 来安装组件：

# 安装所有组件
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

# 安装特定组件
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/message.json

快速入门示例

安装完组件后，您可以在 React 应用中使用它们：

"use client";

import { useChat } from "@ai-sdk/react";
import {
  Conversation,
  ConversationContent,
} from "@/components/ai-elements/conversation";
import {
  Message,
  MessageContent,
  MessageResponse,
} from "@/components/ai-elements/message;

export default function Chat() {
  const { messages } = useChat();

  return (
    <Conversation>
      <ConversationContent>
        {messages.map((message, index) => (
          <Message key={index} from={message.role}>
            <MessageContent>
              <MessageResponse>{message.content}</MessageResponse>
            </MessageContent>
          </Message>
        ))}
      </ConversationContent>
    </Conversation>
  );
}

工作原理

AI Elements CLI 的工作流程如下：

1. 自动检测您的包管理器（npm、pnpm、yarn 或 bun）
2. 从 https://elements.ai-sdk.dev/api/registry/registry.json 获取组件注册表
3. 在后台使用 shadcn/ui CLI 安装组件
4. 添加依赖项，并与您现有的 shadcn/ui 设置集成

组件将被安装到您配置的 shadcn/ui 组件目录中（通常为 @/components/ai-elements/），并成为代码库的一部分，从而允许完全自定义。

配置

AI Elements 使用您现有的 shadcn/ui 配置。组件将被安装到 components.json 文件中指定的目录。

推荐设置

为了获得最佳体验，我们建议：

1. AI 网关：设置 Vercel AI 网关，并将 AI_GATEWAY_API_KEY 添加到 .env.local
2. CSS 变量：使用 shadcn/ui 的 CSS 变量模式进行主题设置
3. TypeScript：启用 TypeScript 以获得更好的开发体验

贡献

如果您希望为 AI Elements 做出贡献，请按照以下步骤操作：

1. 分支仓库
2. 创建新分支
3. 在 packages/elements 中对组件进行修改
4. 向 main 分支提交 PR

---

由 Vercel 用心打造

AI Elements 快速上手指南

AI Elements 是一个基于 shadcn/ui 构建的组件库，专为加速开发 AI 原生应用（如对话界面、代码块展示、推理过程显示等）而设计。它通过 CLI 工具将组件直接安装到你的项目中，支持完全自定义。

环境准备

在开始之前，请确保你的项目满足以下要求：

• Node.js: 版本 18 或更高。
• 框架: 基于 Next.js 的项目。
• 核心依赖:
  • 已安装 AI SDK (@ai-sdk/react)。
  • 已初始化 shadcn/ui (运行过 npx shadcn@latest init)。
  • 已配置 Tailwind CSS (注意：AI Elements 仅支持 CSS Variables 模式)。

安装步骤

你可以直接使用 npx 运行 CLI（推荐），无需全局安装。

方式一：一键安装所有组件

该命令会自动检测包管理器，配置 shadcn/ui（如未配置），并安装所有可用的 AI 组件及依赖。

npx ai-elements@latest

方式二：安装指定组件

如果你只需要特定功能，可以使用 add 命令单独安装。

# 安装消息组件
npx ai-elements@latest add message

# 安装对话组件
npx ai-elements@latest add conversation

# 安装代码块组件
npx ai-elements@latest add code-block

方式三：使用 shadcn CLI 安装

你也可以通过标准的 shadcn 命令从注册表添加组件：

# 安装所有组件
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

# 安装单个组件
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/message.json

提示：组件将被安装到你 components.json 中配置的目录（通常为 @/components/ai-elements/），成为你代码库的一部分，可随意修改。

基本使用

安装完成后，即可在 React 组件中引入并使用。以下是一个最简单的聊天界面示例：

"use client";

import { useChat } from "@ai-sdk/react";
import {
  Conversation,
  ConversationContent,
} from "@/components/ai-elements/conversation";
import {
  Message,
  MessageContent,
  MessageResponse,
} from "@/components/ai-elements/message";

export default function Chat() {
  const { messages } = useChat();

  return (
    <Conversation>
      <ConversationContent>
        {messages.map((message, index) => (
          <Message key={index} from={message.role}>
            <MessageContent>
              <MessageResponse>{message.content}</MessageResponse>
            </MessageContent>
          </Message>
        ))}
      </ConversationContent>
    </Conversation>
  );
}

推荐配置

为了获得最佳体验，建议：

1. AI Gateway: 配置 Vercel AI Gateway 并在 .env.local 中添加 AI_GATEWAY_API_KEY。
2. 主题模式: 确保 shadcn/ui 使用 CSS Variables 模式以支持主题定制。
3. TypeScript: 启用 TypeScript 以获得更好的类型提示。