---
title: AI 助手方案 - t-agent-ui-ray
summary: t-agent-ui-ray 对话 UI 组件库文档，基于 Ray 框架为 t-agent 提供完整对话界面。涵盖核心组件：ChatContainer（对话容器与状态管理）、MessageList（虚拟滚动消息列表）、MessageInput（文本/语音/图片/视频多模态输入）、MessageActionBar（多选操作栏）。核心功能包括 LazyScrollView 虚拟滚动性能优化、8 语言国际化系统、长按菜单增强（复制/删除/多选/反馈）、自定义渲染选项。提供 React Hooks（useChatAgent、useAgentMessage、useTranslate、useOnEvent、useEmitEvent、useSendAction）及内置 Tile/Card/工具组件。
---

# t-agent-ui-ray

## 概述

t-agent-ui-ray 是基于 Ray 框架的 UI 组件库，为 t-agent 提供了一套完整的对话界面组件。它允许开发者快速构建具有现代设计的对话式应用，支持文本、图片、视频等多种内容类型，并提供了丰富的交互体验。

t-agent-ui-ray 内置了虚拟滚动、国际化系统、消息操作栏等功能，大幅提升了用户体验和开发效率。

想了解更多详细信息，请访问[官方文档](https://developer.tuya.com/material/library_oHEKLjj0/component?code=TAgent#t-agent-ui-ray)。

## 核心概念

### ChatContainer

ChatContainer 是整个对话 UI 的容器组件，负责管理对话状态和提供上下文。它是其他组件的父容器，处理消息的显示、更新和移除等核心功能。

主要功能：

- 初始化并管理 ChatAgent 实例
- 提供消息上下文给子组件
- 处理键盘高度变化
- 管理网络状态变化
- 协调消息列表的滚动行为

基本用法：

```tsx
<ChatContainer createAgent={createAgent}>
  <MessageList />
  <MessageInput />
  <MessageActionBar />
</ChatContainer>
```

主要属性：

- `createAgent`：创建 ChatAgent 实例的函数
- `renderOptions`：自定义渲染选项，支持自定义 tile、卡片、长按菜单等
- `className`：自定义类名
- `style`：自定义样式
- `agentRef`：ChatAgent 实例的引用

### MessageList

MessageList 组件负责渲染对话消息列表，内置了 LazyScrollView 组件，提供了更好的性能优化。

主要功能：

- 渲染对话消息列表
- **虚拟滚动**：只渲染可见区域内的消息，大幅提升性能
- **高度自适应**：自动计算消息高度，支持动态内容
- 自动滚动到最新消息
- 支持用户和助手消息的不同布局
- 处理历史消息限制

基本用法：

```tsx
<MessageList 
  roleSide={{
    user: 'end',
    assistant: 'start'
  }}
  historyLimit={{
    count: 50,
    tipText: '只显示最近 50 条消息'
  }}
/>
```

主要属性：

- `className`：自定义类名
- `style`：自定义样式
- `roleSide`：消息气泡位置配置（'start'|'end'）
- `historyLimit`：历史消息数量限制配置
- `wrapperClassName`：容器的自定义类名
- `wrapperStyle`：容器的自定义样式

### MessageInput

MessageInput 组件提供了用户输入界面，支持文本输入、语音输入及多媒体内容上传等功能。

主要功能：

- 文本输入
- **语音输入转文字（ASR）**：支持实时语音识别
- 图片上传（支持相机拍摄和相册选择）
- 视频上传
- 发送按钮状态管理
- 响应状态显示（正在响应/中断）
- 多文件上传支持

基本用法：

```tsx
<MessageInput placeholder="请输入消息..." />
```

主要属性：

- `className`：自定义类名
- `style`：自定义样式
- `placeholder`：输入框占位文本
- `renderTop`：输入框顶部自定义渲染内容

### MessageActionBar

MessageActionBar 是消息操作栏组件，用于多选消息时显示操作按钮，支持删除选中消息和清空历史记录。

主要功能：

- **返回按钮**：退出多选模式
- **清空历史按钮**：清空所有历史消息
- **删除选中按钮**：删除当前选中的消息
- 自动根据多选状态显示和隐藏

基本用法：

```tsx
<MessageActionBar />
```

## 核心功能

### 虚拟滚动 (LazyScrollView)

MessageList 内部集成了 LazyScrollView 组件来优化大量消息的渲染性能：

- **懒加载渲染**：只渲染可见区域内的消息
- **高度自适应**：自动计算消息高度，支持动态内容
- **notifyHeightChanged()**：当消息内容发生变化时，自动通知高度更新
- 保证最下面 10 条消息始终渲染，避免白屏

### 国际化系统

完整的国际化系统，支持多语言：

- **中文简体**（`zh-Hans`）
- **中文繁体**（`zh-Hant`）
- **英文**（`en`）
- **日文**（`ja`）
- **德文**（`de`）
- **法文**（`fr`）
- **西班牙文**（`es`）
- **意大利文**（`it`）

使用 `useTranslate` Hook 获取翻译函数：

```tsx
import { useTranslate } from '@ray-js/t-agent-ui-ray';

const MyComponent = () => {
  const t = useTranslate();
  
  return (
    <div>
      {t('t-agent.message.action.copy')} {/* 输出：复制消息 */}
      {t('t-agent.message.delete.title')} {/* 输出：删除消息 */}
    </div>
  );
};
```

### 长按菜单增强

气泡消息支持更丰富的长按操作：

- **复制消息**：复制文本内容到剪贴板
- **删除消息**：删除单条消息
- **多选**：进入多选模式
- **喜欢/不喜欢**：对助手消息进行反馈（仅对 assistant 角色消息可用）

### 自定义渲染

通过 `renderOptions` 支持更多自定义选项：

- `renderLongPressAs`：自定义长按菜单渲染
- `formatErrorMessageAs`：自定义错误消息格式化
- `customCardMap`：自定义卡片映射
- `i18nTranslate`：自定义多语言翻译

## React Hooks

### useChatAgent

在 `ChatContainer` 上下文里获取 `ChatAgent` 实例。

### useAgentMessage

在 `ChatContainer` 上下文里获取 `messages: ChatMessageObject[]` 列表。

### useTranslate

获取国际化翻译函数，用于翻译界面文本。

```tsx
const t = useTranslate();
console.log(t('t-agent.message.action.copy'));
```

### useOnEvent

在 `ChatContainer` 上下文里注册 ui 事件，在组件卸载时自动取消注册。

```tsx
useOnEvent('scrollToBottom', payload => {
  console.log('scroll to bottom', payload.animation);
});
```

### useEmitEvent

在 `ChatContainer` 上下文里触发 ui 事件。

```tsx
const emitEvent = useEmitEvent();
emitEvent('scrollToBottom', { animation: false });
```

### useSendAction

发送一个 TTTAction，注意只能在 tile 组件（或 card）里使用。

```tsx
const sendAction = useSendAction();
sendAction({ type: 'sendMessage', blocks: [{ type: 'text', text: 'hello' }] });
```

## 内置组件

### Tile 组件

- **BubbleTile**：气泡消息，支持 Markdown 渲染
- **ButtonsTile**：按钮组
- **CardTile**：卡片
- **ImageTile**：图片
- **VideoTile**：视频
- **FileTile**：文件
- **RecommendationsTile**：推荐行动
- **TextTile**：文本
- **TimeTile**：时间标识
- **TipTile**：提示
- **WorkflowTile**：工作选项

### Card 组件

- **WorkflowReplyCard**：工作流回复卡片

### 工具组件

- **PrivateImage**：私有图片组件，支持权限控制
- **LazyScrollView**：懒加载滚动视图，用于性能优化
- **MarkdownRender**：Markdown 渲染器

## 总结

t-agent-ui-ray 为 t-agent 提供了完整的 UI 解决方案。通过虚拟滚动、国际化系统、消息操作栏等功能，大幅提升了用户体验和开发效率。

该组件库与 t-agent 核心库和 t-agent-plugin-aistream 插件无缝集成，让开发者能够专注于业务逻辑而非 UI 实现细节。通过丰富的自定义选项和 Hook 系统，开发者可以轻松构建符合自己需求的对话界面。

更多详细信息和 API 说明，请访问[官方文档](https://developer.tuya.com/material/library_oHEKLjj0/component?code=TAgent#t-agent-ui-ray)。