# t-agent-ui-ray

## Overview

t-agent-ui-ray is a UI component library based on the Ray framework that provides a complete set of conversation interface components for t-agent. It allows developers to quickly build conversational applications with modern design, supporting various content types such as text, images, and videos, and provides a rich interactive experience.

t-agent-ui-ray has built-in virtual scrolling, internationalization system, message action bar, and other features, greatly improving user experience and development efficiency.

For more detailed information, please visit the [official documentation](https://developer.tuya.com/material/library_oHEKLjj0/component?code=TAgent#t-agent-ui-ray).

## Core Concepts

### ChatContainer

ChatContainer is the container component for the entire conversation UI, responsible for managing conversation state and providing context. It is the parent container for other components, handling core functions such as displaying, updating, and removing messages.

Main functions:

- Initializes and manages ChatAgent instances
- Provides message context to child components
- Handles keyboard height changes
- Manages network status changes
- Coordinates message list scrolling behavior

Basic usage:

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

Main properties:

- `createAgent`: Function to create a ChatAgent instance
- `renderOptions`: Custom rendering options, supporting custom tiles, cards, long press menus, etc.
- `className`: Custom class name
- `style`: Custom style
- `agentRef`: Reference to the ChatAgent instance

### MessageList

The MessageList component is responsible for rendering the conversation message list, with built-in LazyScrollView component providing better performance optimization.

Main functions:

- Renders the conversation message list
- **Virtual Scrolling**: Only renders messages within the visible area, greatly improving performance
- **Height Adaptation**: Automatically calculates message height, supporting dynamic content
- Automatically scrolls to the latest message
- Supports different layouts for user and assistant messages
- Handles history message limits

Basic usage:

```tsx
<MessageList 
  roleSide={{
    user: 'end',
    assistant: 'start'
  }}
  historyLimit={{
    count: 50,
    tipText: 'Only showing the most recent 50 messages'
  }}
/>
```

Main properties:

- `className`: Custom class name
- `style`: Custom style
- `roleSide`: Message bubble position configuration ('start'|'end')
- `historyLimit`: History message count limit configuration
- `wrapperClassName`: Container's custom class name
- `wrapperStyle`: Container's custom style

### MessageInput

The MessageInput component provides a user input interface, supporting text input, voice input, and multimedia content upload functions.

Main functions:

- Text input
- **Voice to Text (ASR)**: Supports real-time speech recognition
- Image upload (supports camera capture and album selection)
- Video upload
- Send button state management
- Response status display (responding/interrupted)
- Multi-file upload support

Basic usage:

```tsx
<MessageInput placeholder="Please enter a message..." />
```

Main properties:

- `className`: Custom class name
- `style`: Custom style
- `placeholder`: Input box placeholder text
- `renderTop`: Custom rendering content for the top of the input box

### MessageActionBar

MessageActionBar is the message action bar component, used to display action buttons when multi-selecting messages, supporting deletion of selected messages and clearing history.

Main functions:

- **Back Button**: Exit multi-select mode
- **Clear History Button**: Clear all history messages
- **Delete Selected Button**: Delete currently selected messages
- Automatically shows and hides based on multi-select state

Basic usage:

```tsx
<MessageActionBar />
```

## Core Features

### Virtual Scrolling (LazyScrollView)

MessageList internally integrates the LazyScrollView component to optimize rendering performance for large numbers of messages:

- **Lazy Loading Rendering**: Only renders messages within the visible area
- **Height Adaptation**: Automatically calculates message height, supporting dynamic content
- **notifyHeightChanged()**: Automatically notifies height updates when message content changes
- Ensures the bottom 10 messages are always rendered to avoid blank screens

### Internationalization System

Complete internationalization system supporting multiple languages:

- **Simplified Chinese** (`zh-Hans`)
- **Traditional Chinese** (`zh-Hant`)
- **English** (`en`)
- **Japanese** (`ja`)
- **German** (`de`)
- **French** (`fr`)
- **Spanish** (`es`)
- **Italian** (`it`)

Use the `useTranslate` Hook to get the translation function:

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

const MyComponent = () => {
  const t = useTranslate();
  
  return (
    <div>
      {t('t-agent.message.action.copy')} {/* Output: Copy Message */}
      {t('t-agent.message.delete.title')} {/* Output: Delete Message */}
    </div>
  );
};
```

### Enhanced Long Press Menu

Bubble messages support richer long press operations:

- **Copy Message**: Copy text content to clipboard
- **Delete Message**: Delete a single message
- **Multi-select**: Enter multi-select mode
- **Like/Dislike**: Provide feedback on assistant messages (only available for assistant role messages)

### Custom Rendering

Support for more customization options through `renderOptions`:

- `renderLongPressAs`: Custom long press menu rendering
- `formatErrorMessageAs`: Custom error message formatting
- `customCardMap`: Custom card mapping
- `i18nTranslate`: Custom multilingual translation

## React Hooks

### useChatAgent

Get the `ChatAgent` instance within the `ChatContainer` context.

### useAgentMessage

Get the `messages: ChatMessageObject[]` list within the `ChatContainer` context.

### useTranslate

Get the internationalization translation function for translating interface text.

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

## Other Components

In addition to the core components, t-agent-ui-ray also provides many auxiliary components:

- **MessageRender**: Message rendering component
- **TileRender**: Tile rendering component
- **MarkdownRender**: Markdown rendering component
- **PrivateImage**: Image component with permissions

## Summary

t-agent-ui-ray provides complete UI components for t-agent, simplifying the development process of intelligent conversation applications. Through the core components of ChatContainer, MessageList, MessageInput, and MessageActionBar, developers can quickly build conversation interfaces with professional appearance and smooth interaction.

This component library seamlessly integrates with the t-agent core library and t-agent-plugin-aistream plugin, allowing developers to focus on business logic rather than UI implementation details. With built-in virtual scrolling, internationalization, and enhanced interaction features, it provides excellent user experience and development efficiency.

For more detailed information and API documentation, please visit the [official documentation](https://developer.tuya.com/material/library_oHEKLjj0/component?code=TAgent#t-agent-ui-ray).