React AI Renderer - AI 应用的专属渲染器

English | 中文

一个专为 AI 应用程序设计的 UI 渲染器，可以极大增强 AI 与前端的交互方式。支持流式 JSX/XML 渲染、自定义组件、生命周期钩子，让 AI 输出直接变为交互式 UI。

🚀 项目愿景

在 AI 应用井喷式爆发的今天，以 Chat Bot 为核心的交互已成为主流。然而，传统的文本化输出方式远远无法满足现代 AI 应用对视觉渲染效果的需求。React AI Renderer 提供了完美的解决方案：

传统方式的痛点

1. 等待问题：LLM 是流式输出的，但 JSON 必须等流结束才能完整交付给前端渲染
2. 构建成本高：构建 JSON 和约定渲染本身成本较高，也容易出错
3. 缺乏生命周期管理：无法在渲染之后触发动作，传统 Markdown 渲染器无法满足复杂交互需求

React AI Renderer 的解决方案

React AI Renderer 彻底解决了上述问题，让 AI 可以直接输出标准的 JSX/XML 语法糖，由前端实时渲染为交互式 UI，同时支持完整的生命周期管理。

🌟 核心特性

✅ 无缝兼容 React Markdown

只需将引入名称从 react-markdown 改为 react-ai-renderer，即可无感知继承现有能力，零成本迁移。

✅ 自定义组件渲染

支持基于项目已有的前端 UI 进行渲染，无限拉高产品体验上限，复用现有视觉主题。

✅ 真正的流式渲染

动态 token 对应动态解析，无需像 JSON 格式那样等待模型输出完毕才能看到视觉效果。

✅ 组件生命周期钩子

单一组件渲染完毕后可触发下一个事件，轻松实现文件列表+文件内容左右分栏等复杂交互效果。

✅ 丰富的内置组件

• AI 推理展示：内置 Think 组件展示 AI 思考过程
• 代码高亮：支持多种编程语言的代码高亮显示
• 数学公式：使用 KaTeX 渲染数学公式
• Mermaid 图表：支持流程图、时序图等（可选功能）

📦 安装使用

npm install react-ai-renderer

或使用 yarn：

yarn add react-ai-renderer

可选依赖

本库支持渲染 Mermaid 图表，但需要安装额外的依赖：

npm install mermaid

如果不安装 mermaid，图表将不会渲染，但不会影响其他功能。

🎯 快速开始

💡 开发调试？ 查看 开发模式使用指南 了解如何在本地开发和调试本库。
🔥 使用监听模式开发？ 运行 npm run watch 启动自动监听和重新构建，修改代码后自动更新！

基础使用

import ReactAIRenderer from 'react-ai-renderer';

const content = `
# 欢迎使用 React AI Renderer

这是一个 **粗体** 文本和 *斜体* 文本。

\`\`\`javascript
console.log('Hello World');
\`\`\`
`;

function App() {
  return <ReactAIRenderer>{content}</ReactAIRenderer>;
}

AI 流式输出渲染

import ReactAIRenderer from 'react-ai-renderer';

// 模拟 AI 流式输出内容
const aiContent = `
正在分析用户需求...

<Table>
  <TableHeader>
    <TableCell header>产品名称</TableCell>
    <TableCell header>价格</TableCell>
    <TableCell header>库存</TableCell>
  </TableHeader>
  <TableRow>
    <TableCell>iPhone 15</TableCell>
    <TableCell>¥5999</TableCell>
    <TableCell>50</TableCell>
  </TableRow>
</Table>
`;

function App() {
  return <ReactAIRenderer>{aiContent}</ReactAIRenderer>;
}

自定义组件与生命周期

import ReactAIRenderer from 'react-ai-renderer';

// 自定义按钮组件
const Button = ({ onClick, children, style }) => (
  <button 
    onClick={onClick} 
    style={{ 
      backgroundColor: 'blue', 
      color: 'white',
      padding: '8px 16px',
      border: 'none',
      borderRadius: '4px',
      cursor: 'pointer',
      ...style
    }}
  >
    {children}
  </button>
);

// 组件生命周期钩子
const componentHandlers = [
  {
    name: 'Button',
    component: Button,
    selfClosing: false,
    onRender: (item, scope) => {
      console.log('Button 组件已渲染完成');
      // 可以在这里触发下一个动作
      // 例如：更新状态、发送请求等
    }
  }
];

const content = `
<Button onClick={() => alert('点击了按钮')}>点击我</Button>
`;

function App() {
  return (
    <ReactAIRenderer 
      components={{ Button }} 
      componentHandlers={componentHandlers}
    >
      {content}
    </ReactAIRenderer>
  );
}

🛠️ API 参考

ReactAIRenderer 组件

主渲染组件，完全兼容 ReactMarkdown API。

Props:

• content: Markdown/MDX 内容字符串
• scope: 传递给 MDX 的作用域对象
• components: 自定义组件映射
• componentHandlers: 组件处理器数组（支持生命周期钩子）
• children: 作为内容的子元素（替代 content）

组件生命周期钩子

通过 componentHandlers 属性可以为组件添加生命周期钩子：

const componentHandlers = [
  {
    name: 'MyComponent',
    component: MyComponent,
    selfClosing: false,
    onRender: (item, scope) => {
      // 组件渲染完成后的回调
      console.log('组件已渲染:', item);
    }
  }
];

⚡ 性能优势

实时渲染

• 流式解析，无需等待完整内容
• 动态组件渲染，提升用户体验
• 内存优化，避免重复渲染

兼容性保障

• 完全兼容 React 18+
• 支持 TypeScript 类型安全
• 无依赖冲突，轻松集成

💡 应用场景

1. AI 助手应用

让 AI 助手直接输出交互式 UI，提升用户体验

2. 代码生成工具

AI 生成的代码可以直接渲染为可交互的组件

3. 数据分析报告

AI 分析结果可直接渲染为图表和表格

4. 教育培训系统

AI 生成的教学内容可直接渲染为交互式课件

5. 智能文档系统

AI 生成的文档可直接渲染为富交互页面

6. 低代码平台

AI 辅助生成界面，直接渲染为可用组件

7. 自动化运维

AI 分析结果可直接渲染为操作界面

📖 示例运行

运行示例：

npm run example

然后在浏览器中访问 http://localhost:3000

🧪 测试

npm test

🚀 高级特性

流式渲染优化

React AI Renderer 采用先进的流式解析技术，能够在 AI 模型输出的同时实时渲染内容，无需等待完整输出。

组件注册机制

支持动态组件注册，可以灵活扩展自定义组件：

const customComponents = {
  MyButton: ({ onClick, children }) => (
    <button onClick={onClick} className="custom-button">
      {children}
    </button>
  )
};

<ReactAIRenderer components={customComponents}>
  {content}
</ReactAIRenderer>

作用域传递

支持向组件传递作用域变量，实现更复杂的数据交互：

const scope = {
  userData: { name: "张三", age: 25 },
  onAction: (data) => console.log("Action triggered:", data)
};

<ReactAIRenderer scope={scope}>
  {content}
</ReactAIRenderer>

📊 架构设计

系统架构图

graph TD
    A[AI Model] -->|Streaming Output| B[React AI Renderer]
    B -->|Parse JSX/XML| C[MDX Streaming Parser]
    C -->|Component Data| D[Component Renderer]
    D -->|Render Components| E[Custom UI Components]
    D -->|Lifecycle Hooks| F[Event Triggers]
    E --> G[Interactive UI]
    F --> H[Next Actions]

工作流程

1. AI 模型流式输出 JSX/XML 格式的内容
2. React AI Renderer 实时接收并解析内容
3. MDX Streaming Parser 动态解析组件数据
4. Component Renderer 渲染自定义 UI 组件
5. 触发生命周期钩子，执行后续动作

🔧 Next.js 集成

本库已完全兼容 Next.js 的服务器端渲染（SSR）。

在 Next.js 中使用

// app/your-page/page.tsx 或 pages/your-page.tsx
import ReactAIRenderer from 'react-ai-renderer';

export default function YourPage() {
  const content = `
# 你好，Next.js!

这是一个在 Next.js 中使用 React AI Renderer 的示例。
  `;
  
  return (
    <div>
      <ReactAIRenderer>{content}</ReactAIRenderer>
    </div>
  );
}

需要客户端组件的场景

如果需要在 Next.js 13+ 的 App Router 中使用交互式组件（如按钮点击等），需要使用 'use client' 指令：

// app/your-page/client-renderer.tsx
'use client';

import ReactAIRenderer from 'react-ai-renderer';

export default function ClientAIRenderer({ content }: { content: string }) {
  return <ReactAIRenderer>{content}</ReactAIRenderer>;
}

注意事项

• ✅ 本库已添加 SSR 安全检查，不会在服务器端访问 document 或 window 对象
• ✅ 可以在服务器端安全使用，无需额外配置
• ✅ 动态功能（如 Mermaid 图表）会自动在客户端渲染

❓ 常见问题

Q: React AI Renderer 与 react-markdown 有什么区别？

A: React AI Renderer 完全兼容 react-markdown，但增加了对 JSX/XML 组件的支持、流式渲染和生命周期钩子等高级功能。

Q: 如何处理未注册的组件？

A: 未注册的组件会自动转换为对应的文本表示形式，不会导致页面崩溃。

Q: 是否支持不同组件库如antd,shadcn等

A: 是的，React AI Renderer 无组件依赖，你可以使用任意组件库以及自定义组件

Q: 在 Next.js 中出现 "document is not defined" 错误怎么办？

A: 请确保使用最新版本（v0.1.12+），该版本已完全修复 SSR 兼容性问题。如果仍有问题，请检查是否正确安装了依赖并清理 Next.js 缓存。

Q: 性能如何优化？

A: 建议合理使用组件生命周期钩子，避免在渲染过程中执行耗时操作。

📄 许可证

MIT