# @mxmweb/rtext

> 统一富文本组件库，基于 Slate 与 React 封装，支持富文本编辑/渲染、Markdown/HTML/纯文本多源输入、模板字段、虚拟滚动与分段加载等能力。

## 快速开始

```tsx
import React from 'react';
import { UnifiedRichText, DataType } from '@mxmweb/rtext';
import '@mxmweb/rtext/style.css';

function App() {
  return (
    <UnifiedRichText
      dataSource={{
        type: DataType.MARKDOWN,
        content: '# Hello World\n\n这是一个**富文本**组件！'
      }}
      theme={{
        primaryColor: '#1890ff',
        backgroundColor: '#ffffff'
      }}
    />
  );
}

export default App;
```

## 核心组件

### UnifiedRichText

统一富文本组件，支持多种数据源和编辑模式。

**特性：**
- ✅ 多数据源支持：Slate、Markdown、HTML、纯文本
- ✅ 编辑/只读模式切换
- ✅ 模板字段支持：`<template>...</template>`
- ✅ 主题系统：支持 zui-theme 和自定义主题
- ✅ 自定义渲染：可扩展元素和叶子节点渲染
- ✅ TypeScript 支持

### Markdownit

高性能富文本渲染器，专为大量内容设计。

**特性：**
- ✅ 虚拟滚动：处理大量内容时保持性能
- ✅ 分段加载：支持流式内容加载
- ✅ 多格式混排：支持不同数据类型的段落
- ✅ 滚动事件：支持滚动到顶部/底部回调
- ✅ 分段点击：支持段落级别的交互

### ChatMessageAdapter

聊天消息适配器，专为对话场景设计。

**特性：**
- ✅ 用户/AI 消息区分
- ✅ 引用系统：知识库、网络、数据库引用
- ✅ 文件上传：支持图片和文档预览
- ✅ 交互功能：复制、点赞、转发等
- ✅ 追问建议：智能推荐后续问题

### PromptTempDesigner

模板字段设计器，可视化创建模板。

**特性：**
- ✅ 可视化编辑：所见即所得的模板编辑
- ✅ 属性配置：支持 key、placeholder 等属性
- ✅ 多格式导出：支持纯文本、Markdown、HTML
- ✅ 主题集成：与 zui-theme 完美集成

## 安装说明

### 1. 安装 rtext 库

```bash
# 使用 pnpm（推荐）
pnpm add @mxmweb/rtext

# 或使用 npm
npm install @mxmweb/rtext

# 或使用 yarn
yarn add @mxmweb/rtext
```

### 2. 必需依赖

rtext 库依赖以下包，请确保已安装：

```bash
# 核心依赖
pnpm add react react-dom
pnpm add styled-components@^6
pnpm add marked

# 图标库（可选，用于内置图标）
pnpm add lucide-react

# UI 组件库（可选，用于 Tooltip 等组件）
pnpm add antd

# 注意：slate 相关依赖已内嵌，无需单独安装
```

### 3. 样式配置

#### 3.1 基础样式导入

```tsx
// 在应用入口导入基础样式
import '@mxmweb/rtext/style.css';
```

#### 3.2 主题配置

rtext 支持两种主题配置方式：

**方式一：使用 zui-theme（推荐）**

```tsx
import { ThemeProvider, defaultTheme } from '@mxmweb/zui';
import { UnifiedRichText, DataType } from '@mxmweb/rtext';

// 配置全局主题
const App = () => {
  return (
    <ThemeProvider theme={defaultTheme}>
      <UnifiedRichText
        dataSource={{
          type: DataType.MARKDOWN,
          content: '# Hello World'
        }}
      />
    </ThemeProvider>
  );
};
```

**方式二：直接传入 theme 属性**

```tsx
import { UnifiedRichText, DataType } from '@mxmweb/rtext';

const App = () => {
  return (
    <UnifiedRichText
      dataSource={{
        type: DataType.MARKDOWN,
        content: '# Hello World'
      }}
      theme={{
        primaryColor: '#007bff',
        backgroundColor: '#ffffff',
        textColor: '#333333',
        borderRadius: '8px',
        padding: '16px'
      }}
    />
  );
};
```

#### 3.3 自定义样式

```tsx
<UnifiedRichText
  dataSource={{ type: DataType.SLATE, content: [] }}
  styles={{
    // 文本样式
    letterSpacing: '0.5px',
    lineHeight: '1.8',
    text: {
      fontSize: '16px',
      color: '#333'
    },
    // 模板字段样式
    templateField: {
      backgroundColor: '#e3f2fd',
      borderColor: '#2196f3',
      borderRadius: '4px',
      padding: '4px 8px',
      textColor: '#1976d2'
    }
  }}
/>
```

### 4. TypeScript 支持

rtext 内置 TypeScript 类型定义，无需额外安装：

```tsx
import { 
  UnifiedRichText, 
  DataType, 
  type UnifiedRichTextProps,
  type DataSource 
} from '@mxmweb/rtext';
```

### 5. 环境要求

- **React**: >= 18.0.0
- **Node.js**: >= 16.0.0
- **TypeScript**: >= 4.5.0（可选）

### 6. 最佳实践

#### 6.1 性能优化

```tsx
// 对于大量内容，使用 Markdownit 组件
import { Markdownit, DataType } from '@mxmweb/rtext';

<Markdownit
  dataSource={largeContentArray}
  enableVirtualScroll
  itemHeight={200}
  preloadCount={5}
/>
```

#### 6.2 主题定制

```tsx
// 创建自定义主题
const customTheme = {
  primaryColor: '#1890ff',
  backgroundColor: '#f5f5f5',
  textColor: '#262626',
  borderRadius: '6px',
  padding: '12px',
  // 支持更多主题属性...
};

// 全局应用
<ThemeProvider theme={customTheme}>
  <App />
</ThemeProvider>
```

#### 6.3 错误处理

```tsx
<UnifiedRichText
  dataSource={{
    type: DataType.MARKDOWN,
    content: markdownContent
  }}
  onError={(error) => {
    console.error('Rich text error:', error);
    // 处理错误
  }}
/>
```

### 7. 常见问题

#### Q: 样式不生效怎么办？

A: 确保已正确导入样式文件：
```tsx
import '@mxmweb/rtext/style.css';
```

#### Q: 如何自定义模板字段样式？

A: 使用 `styles.templateField` 属性：
```tsx
<UnifiedRichText
  styles={{
    templateField: {
      backgroundColor: '#e6f7ff',
      borderColor: '#91d5ff',
      textColor: '#1890ff'
    }
  }}
/>
```

#### Q: 如何禁用某些功能？

A: 使用 `disabledTags` 属性：
```tsx
<UnifiedRichText
  disabledTags={['template', 'think']}
  // 禁用模板字段和思考标签
/>
```


## 🔗 链接

- **NPM**: <https://www.npmjs.com/package/@mxmweb/rtext>
- **GitHub**: <https://github.com/your-org/rtext>

## 📚 API 文档

> 📖 完整 API 文档请查看：[doc_assets/接口/](./doc_assets/接口/)

- **接口文档**: [UnifiedRichText API](./doc_assets/接口/UnifiedRichText.md)、[Markdownit API](./doc_assets/接口/Markdownit.md)、[ChatMessageAdapter API](./doc_assets/接口/ChatMessageAdapter.md)、[PromptTempDesigner API](./doc_assets/接口/PromptTempDesigner.md)
- **更新说明**: [CHANGELOG](./doc_assets/更新说明/CHANGELOG.md)
- **演示说明**: [演示文档](./doc_assets/演示/index.md)

## 📝 演示

请查看 [详细说明文档](./doc_assets/演示/index.md) 了解更多信息。

### 组件介绍

- **UnifiedRichText**: 全能型富文本组件，统一处理多种数据源，并在编辑/只读间自由切换。
  - 数据源类型: `DataType.SLATE | DataType.MARKDOWN | DataType.HTML | DataType.TEXT`
  - 主题样式: 使用 `styled-components v6`，通过 `theme`、`styles` 进行主题与细粒度样式定制
  - 模板字段: 支持在文本中识别 `<template>...</template>` 并渲染为可编辑占位元素
  - 自定义渲染: 通过 `renderElement` 与 `renderLeaf` 注入自定义渲染逻辑

### 调用案例说明

```tsx
import { UnifiedRichText, DataType } from '@mxmweb/rtext';

// 编辑模式（Slate 数据）
<UnifiedRichText
  dataSource={{
    type: DataType.SLATE,
    content: [{ type: 'paragraph', children: [{ text: 'Hello World' }] }]
  }}
  isEditing
  theme={{ primaryColor: '#007bff', backgroundColor: '#fff' }}
  styles={{ letterSpacing: '0.5px', lineHeight: '1.8' }}
  onChange={(content) => console.log('change', content)}
/>;

// 渲染 Markdown
<UnifiedRichText
  dataSource={{ type: DataType.MARKDOWN, content: '# Title\n\n`inline`' }}
/>;

// 渲染 HTML
<UnifiedRichText dataSource={{ type: DataType.HTML, content: '<b>Bold</b>' }} />;

// 渲染 纯文本
<UnifiedRichText dataSource={{ type: DataType.TEXT, content: 'Plain Text' }} />;
```

### 接口类型说明

```ts
// 数据类型
enum DataType { SLATE = 'slate', MARKDOWN = 'markdown', HTML = 'html', TEXT = 'text' }

// 数据源
interface DataSource { type: DataType; content: any }

// 核心 Props（节选）
interface UnifiedRichTextProps {
  dataSource: { type: DataType; content?: any };
  isEditing?: boolean;
  placeholder?: string;
  size?: 'sm' | 'md';
  theme?: { primaryColor?: string; backgroundColor?: string; /* ... */ };
  styles?: { letterSpacing?: string; lineHeight?: string; templateField?: { textColor?: string } };
  onChange?: (content: any, type: DataType) => void;
  renderElement?: (props: any) => JSX.Element;
  renderLeaf?: (props: any) => JSX.Element;
}
```

## 业务组件

> 通过 `adopters/` 提供典型业务场景封装，遵循"核心组件 + 业务适配层"架构。

### 组件介绍

- **Markdownit**: 面向长文档/富文本的高性能渲染器，支持虚拟滚动、分段加载与多格式混排。
  - 大量内容渲染时，启用虚拟滚动（`enableVirtualScroll`、`itemHeight`）
  - 流式加载内容时，启用分段加载（`enableSegmentedLoading`、`onLoadMore`）
  - 支持多格式混排：Markdown、HTML、纯文本等

- **ChatMessageAdapter**: 面向对话消息流的渲染/编排适配器（按需组装 `UnifiedRichText`）
  - 支持用户/AI 消息的不同样式
  - 集成引用系统：知识库、网络搜索、数据库查询
  - 支持文件上传和预览功能
  - 提供丰富的交互功能：复制、点赞、转发、编辑等

- **PromptTempDesigner**: 模板字段设计器，用于可视化创建 `<template>...</template>` 字段
  - 支持新协议：`<template key="name" placeholder="提示">内容</template>`
  - 兼容旧协议：`<template>占位文本</template>`
  - 支持多格式导出：纯文本、Markdown、HTML
  - 与 zui-theme 完美集成

### 调用案例说明

```tsx
import { Markdownit, DataType } from '@mxmweb/rtext';

const segments = [
  { id: '1', type: DataType.MARKDOWN, content: '# 第一段' },
  { id: '2', type: DataType.TEXT, content: '纯文本段落' },
];

<Markdownit
  dataSource={segments}
  enableVirtualScroll
  itemHeight={240}
  enableSegmentedLoading
  onLoadMore={async (lastId) => [{ id: String(+lastId + 1), type: DataType.TEXT, content: '更多内容' }]}
  onSegmentClick={(id) => console.log('click', id)}
  height="600px"
/>;
```

### 接口类型说明

```ts
// Markdownit 关键 Props（节选）
interface SegmentData {
  id: string;
  content: string | CustomElement[];
  type: DataType;
  timestamp?: number;
  metadata?: Record<string, any>;
}

interface MarkdownitProps {
  dataSource: DataSource | SegmentData[];
  enableVirtualScroll?: boolean;
  itemHeight?: number;
  preloadCount?: number;
  enableSegmentedLoading?: boolean;
  onLoadMore?: (lastSegmentId: string) => Promise<SegmentData[]>;
  isLoadingMore?: boolean;
  size?: 'sm' | 'md';
  theme?: { primaryColor?: string; backgroundColor?: string; /* ... */ };
  onChange?: (content: any, type: DataType) => void;
  onScroll?: (scrollTop: number, scrollHeight: number) => void;
  onScrollToTop?: () => void;
  onScrollToBottom?: () => void;
  onSegmentClick?: (segmentId: string, segment: SegmentData) => void;
  height?: string;
}
```

## API 参考

### 主题配置

#### zui-theme 集成

rtext 完全支持 zui-theme 系统，会自动使用 `useTheme()` 获取的主题配置：

```tsx
// 主题属性映射
const themeMapping = {
  // 颜色系统
  primaryColor: zuiTheme?.colors?.primary,
  secondaryColor: zuiTheme?.colors?.secondary,
  backgroundColor: zuiTheme?.colors?.background,
  textColor: zuiTheme?.colors?.text,
  borderColor: zuiTheme?.colors?.border,
  
  // 间距系统
  padding: zuiTheme?.space?.padding,
  margin: zuiTheme?.space?.margin,
  borderRadius: zuiTheme?.space?.radius,
  
  // 字体系统
  baseFontSize: zuiTheme?.fonts?.body?.size,
  fontFamily: zuiTheme?.fonts?.body?.family,
  fontWeight: zuiTheme?.fonts?.body?.weight,
};
```

#### 自定义主题属性

```tsx
interface ThemeConfig {
  // 基础颜色
  primaryColor?: string;
  secondaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  borderColor?: string;
  disabledBackground?: string;
  
  // 布局
  borderRadius?: string;
  padding?: string;
  margin?: string;
  minHeight?: string;
  
  // 字体
  baseFontSize?: number;
}
```

### 样式配置

```tsx
interface StylesConfig {
  // 文本样式
  letterSpacing?: string;
  lineHeight?: string;
  text?: {
    fontSize?: string;
    color?: string;
  };
  
  // 模板字段样式
  templateField?: {
    backgroundColor?: string;
    borderColor?: string;
    borderRadius?: string;
    padding?: string;
    textColor?: string;
    minWidth?: string;
    maxWidth?: string;
  };
}
```

### 事件回调

```tsx
interface EventCallbacks {
  // 内容变化
  onChange?: (content: any, type: DataType) => void;
  
  // 交互事件
  onFocus?: () => void;
  onBlur?: () => void;
  
  // 自定义渲染
  renderElement?: (props: RenderElementProps) => JSX.Element;
  renderLeaf?: (props: RenderLeafProps) => JSX.Element;
  
  // 模板字段事件
  onRetriveTagClick?: (leaf: any, attributes: any) => void;
  eventsEmit?: (event: string, data: any) => void;
}
```

---

以上文档基于 `src/lib_enter.ts` 的实际导出整理：
- 核心导出: `UnifiedRichText`, `DataType`, `serializeToMarkdown`, `serializeToHtml` 及类型定义
- 业务导出: `Markdownit`, `ChatMessageAdapter`, `PromptTempDesigner` 及其类型

如需补充更多示例或 API 细节，请在对应组件的 `README` 中扩展。