@mxmweb/rtext

v1.6.16

Published

3 days ago

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

0High
0Medium
0Low

mxmweb

@mxmweb/rtext

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

快速开始

import React from 'react';
import { UnifiedRichText, DataType } from '@mxmweb/rtext';
import '@mxmweb/rtext/dist/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 库

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

# 或使用 npm
npm install @mxmweb/rtext

# 或使用 yarn
yarn add @mxmweb/rtext

2. 必需依赖

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

# 核心依赖
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 基础样式导入

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

3.2 主题配置

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

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

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 属性

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 自定义样式

<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 类型定义，无需额外安装：

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 性能优化

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

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

6.2 主题定制

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

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

6.3 错误处理

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

7. 常见问题

Q: 样式不生效怎么办？

A: 确保已正确导入样式文件：

import '@mxmweb/rtext/dist/style.css';

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

A: 使用 styles.templateField 属性：

<UnifiedRichText
  styles={{
    templateField: {
      backgroundColor: '#e6f7ff',
      borderColor: '#91d5ff',
      textColor: '#1890ff'
    }
  }}
/>

Q: 如何禁用某些功能？

A: 使用 disabledTags 属性：

<UnifiedRichText
  disabledTags={['template', 'think']}
  // 禁用模板字段和思考标签
/>

🔗 链接

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

📚 API 文档

📖 完整 API 文档请查看：doc_assets/接口/

接口文档: UnifiedRichText API、Markdownit API、ChatMessageAdapter API、PromptTempDesigner API
更新说明: CHANGELOG
演示说明: 演示文档

📝 演示

请查看详细说明文档了解更多信息。

组件介绍

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

调用案例说明

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' }} />;

接口类型说明

// 数据类型
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 完美集成

调用案例说明

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"
/>;

接口类型说明

// 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() 获取的主题配置：

// 主题属性映射
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,
};

自定义主题属性

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

样式配置

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;
  };
}

事件回调

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 中扩展。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@mxmweb/rtext

快速开始

核心组件

UnifiedRichText

Markdownit

ChatMessageAdapter

PromptTempDesigner

安装说明

1. 安装 rtext 库

2. 必需依赖

3. 样式配置

3.1 基础样式导入

3.2 主题配置

3.3 自定义样式

4. TypeScript 支持

5. 环境要求

6. 最佳实践

6.1 性能优化

6.2 主题定制

6.3 错误处理

7. 常见问题

Q: 样式不生效怎么办？

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

Q: 如何禁用某些功能？

🔗 链接

📚 API 文档

📝 演示

组件介绍

调用案例说明

接口类型说明

业务组件

组件介绍

调用案例说明

接口类型说明

API 参考

主题配置

zui-theme 集成

自定义主题属性

样式配置

事件回调