通用智能体开发解决方案——AI助手开发教程（三）

t-agent-ui-ray

概述

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

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

想了解更多详细信息，请访问官方文档。

核心概念

ChatContainer

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

主要功能：

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

基本用法：

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

主要属性：

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

MessageList

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

主要功能：

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

基本用法：

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

主要属性：

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

MessageInput

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

主要功能：

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

基本用法：

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

主要属性：

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

MessageActionBar

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

主要功能：

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

基本用法：

<MessageActionBar />

核心功能

虚拟滚动 (LazyScrollView)

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

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

国际化系统

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

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

使用 useTranslate Hook 获取翻译函数：

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

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

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

useOnEvent

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

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

useEmitEvent

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

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

useSendAction

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

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 说明，请访问官方文档。

欢迎语

如果您想在用户进入对话页面时，发送一条欢迎消息，或者在用户隔一段时间后重新进入小程序时，发送一条问候消息，可以在 createAgent 函数中添加以下逻辑。

const createAgent = () => {
  
  const { onChatStart, createMessage, onChatResume } = agent;
 
  // 创建一条初始的欢迎信息
  onChatStart(async (result) => {
    const hello = createMessage({
      role: 'assistant',
    });
 
    hello.bubble.setText('你好'); // 此处定义您想写的问候的多语言
    
    result.messages.push(hello);
    
    await hello.persist('createText'); // 将这个消息气泡持久化下来
  });
 
  return agent;
};

定制外观

使用 AI 智能体 SDK 开发对话应用，你可以定制这个对话应用的任何外观，只需在项目中创建 CSS 文件，并覆盖对应组件的样式即可。

/* 修改消息气泡的背景颜色 */
.t-agent-message-list-row-start .t-agent-bubble-tile-bubble {
  background-color: blue;
}

import './custom-style.css';
 
const createAgent = () => {
  // ...
  return agent;
};
 
export default function ChatPage() {
  // ...
}

设备控制

基于 AI 智能体 SDK 开发的智能体对话应用，如果您创建的产品支持 AI 控制时，可以在其中实现对设备的控制。

想了解更多详细信息，请访问控制设备。

效果展示

交互流程 

​