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