TelegramEditor

专为移动端打磨的 Telegram 富文本编辑器，严格遵循 Telegram Bot API HTML 规范。

核心特性

✅ 严格遵循 Telegram 规范 - 完整支持 Telegram Bot API 的所有 HTML 标签，包括简写标签和特殊协议
📱 移动端体验优化 - 键盘上方工具栏、自动滚动、48px 最小点击区域
🎨 纯文本粘贴 - 自动过滤垃圾样式，只保留纯文本内容
🔧 自定义变量 - 支持外部传入自定义变量，与内置变量合并
💡 源码/预览模式 - 可视化编辑与源码编辑自由切换，支持高级 HTML 标签
⚡️ 轻量级 - 体积 ≈38KB (gzip 后 ≈14KB)

导入

tsx

import { TelegramEditor } from '@xcloud/ui-mobile'

示例

基础用法

TelegramEditor 是一个专为 Telegram Bot API 设计的富文本编辑器，输出的 HTML 严格遵循 Telegram 规范。

tsx

import { TelegramEditor } from '@xcloud/ui-mobile'
import { useState } from 'react'

function Example() {
  const [html, setHtml] = useState('')

  return (
    <TelegramEditor
      placeholder="输入消息..."
      onChange={(telegramHtml) => {
        setHtml(telegramHtml)
        // 直接发送给 Telegram Bot API
        sendToTelegramBot(telegramHtml)
      }}
      maxLength={4096}
    />
  )
}

受控模式

TelegramEditor 支持受控模式和非受控模式：

tsx

// 受控模式
function ControlledExample() {
  const [value, setValue] = useState('<b>初始内容</b>')

  return (
    <TelegramEditor
      value={value}
      onChange={(html) => setValue(html)}
    />
  )
}

// 非受控模式
function UncontrolledExample() {
  return (
    <TelegramEditor
      defaultValue="<b>默认内容</b>"
      onChange={(html) => console.log(html)}
    />
  )
}

支持的格式

TelegramEditor 完整支持 Telegram Bot API 的所有 HTML 标签：

基础格式（有 UI 工具）

格式	图标	标签	说明
粗体	`B`	`<b>`, `<strong>`	加粗文字强调
斜体	`I`	`<i>`, `<em>`	斜体表示引用
下划线	`U`	`<u>`, `<ins>`	添加下划线突出
~~删除线~~	`S̶`	`<s>`, `<strike>`, `<del>`	表示已删除内容
`行内代码`	`</>`	`<code>`	显示行内代码
代码块	`{ }`	`<pre><code>`	多行代码块，支持 `language-*` class
等宽文本	`≡`	`<pre>`	等宽格式文本块（不带语法高亮）
隐藏文字	`👁`	`<span class="tg-spoiler">` 或 `<tg-spoiler>`	点击后显示（blur 效果）
引用	`"`	`<blockquote>` 或 `<blockquote expandable>`	引用内容，支持智能切换（见下文）
链接	`🔗`	`<a href="url">`	可点击的超链接，支持 `tg://` 协议

引用按钮智能切换

引用按钮支持三状态智能切换，每次点击会循环切换状态：

未激活 → 普通引用：首次点击，创建 <blockquote> 标签
普通引用 → 可展开引用：再次点击，添加 expandable 属性，按钮显示 "(折叠)" 标识
可展开引用 → 取消引用：第三次点击，移除引用格式

tsx

// 使用示例
// 第一次点击：未激活 → <blockquote>内容</blockquote>
// 第二次点击：普通引用 → <blockquote expandable>内容</blockquote>
// 第三次点击：可展开引用 → 内容（取消引用）

视觉反馈：

普通引用：按钮高亮，显示 "引用 (展开)"（10px小字，带括号）
可展开引用：按钮高亮，显示 "引用 (折叠)"（10px小字，带括号）
未激活：按钮无高亮

高级标签（源码模式支持）

以下标签可以在源码模式直接输入，编辑器会正确处理：

标签	说明	示例
`<tg-spoiler>`	Spoiler 简写标签	`<tg-spoiler>隐藏内容</tg-spoiler>`
`<tg-emoji>`	自定义 emoji（需 Fragment 购买）	`<tg-emoji emoji-id="5368324170671202286">🔥</tg-emoji>`
`<a href="tg://user?id=123">`	用户提及链接	`<a href="tg://user?id=123456789">@admin</a>`
`<pre><code class="language-python">`	带语言的代码块	`<pre><code class="language-python">print("Hello")</code></pre>`
`<blockquote expandable>`	可展开的引用	`<blockquote expandable>长文本引用...</blockquote>`

所有按钮使用 Lucide React 图标库，提供清晰直观的视觉体验。

源码/预览模式

TelegramEditor 支持在可视化编辑和源码编辑之间切换，方便高级用户直接编辑 HTML 代码。

功能特性

一键切换 - 点击工具栏的源码/预览按钮即可切换模式
智能转换 - 自动处理换行符和 HTML 标签转换
双向同步 - 源码和预览模式的内容实时同步
源码高亮 - 源码模式使用等宽字体，便于阅读和编辑

转换规则

预览 → 源码：

段落标签  转换为换行符 \n
HTML 标签转换为 Telegram 格式（ → ,  → ）
移除不必要的 CSS class 属性（保留 language-* 和 tg-spoiler）
如果启用 useShorthandTags，将  转换为 <tg-spoiler>

源码 → 预览：

换行符 \n 转换为段落标签 
自动识别块级标签（<blockquote>, <pre>），不额外包裹
<tg-spoiler> 自动转换为 （编辑器内部格式）
保留所有 Telegram 支持的 HTML 标签（<tg-emoji>, tg:// 链接等）

使用示例

tsx

// 在源码模式使用 Telegram 特殊标签
<TelegramEditor
  defaultValue={`
    <b>欢迎</b> <tg-spoiler>惊喜内容</tg-spoiler>

    提及用户: <a href="tg://user?id=123456789">@admin</a>

    自定义 emoji: <tg-emoji emoji-id="5368324170671202286">🔥</tg-emoji>

    代码示例:
    <pre><code class="language-python">
def hello():
    print("Hello, Telegram!")
    </code></pre>
  `}
  useShorthandTags={true}  // 输出简写标签格式
/>

切换效果：

从源码切换到预览：

<tg-spoiler> → 显示为可点击的模糊文字
<tg-emoji> → 保持原样（编辑器不修改）
tg://user?id=123 → 显示为可点击链接
language-python → 保留语言标识

从预览切换到源码：

模糊文字 → <tg-spoiler> 或 （取决于 useShorthandTags）
保留所有 Telegram 特殊标签和协议

变量插入功能

TelegramEditor 支持插入变量用于动态内容替换，包括内置的 Telegram 变量和自定义变量。

内置变量列表

变量	说明
{{t.id}}	Telegram 目标用户数字ID
{{t.name}}	Telegram 目标@用户名
{{t.first_name}}	Telegram 目标用户名字
{{t.last_name}}	Telegram 目标用户姓氏
{{t.nickname}}	Telegram 目标Name 姓/名
{{warn_num}}	警告次数上限 (0:不警告, >0:警告上限数次)
{{warned_num}}	已警告次数
{{warn_remain_num}}	剩余警告次数
{{mute_time}}	禁言时长
{{kick_out}}	踢出群 (0:不踢出群, 1:踢出群, 允许再次加入, 2:踢出群，直至管理员解禁)
{{time}}	当前时间

自定义变量

除了内置变量，你还可以传入自定义变量，它们会与内置变量合并显示在变量选择器中：

tsx

import { TelegramEditor } from '@xcloud/ui-mobile'

function CustomVariablesExample() {
  return (
    <TelegramEditor
      variables={[
        { key: 'order.id', label: '订单编号', value: '{{order.id}}' },
        { key: 'order.amount', label: '订单金额', value: '{{order.amount}}' },
        { key: 'product.name', label: '商品名称', value: '{{product.name}}' },
        { key: 'user.points', label: '用户积分', value: '{{user.points}}' },
      ]}
      onChange={(html) => console.log(html)}
    />
  )
}

变量列表顺序：

内置 Telegram 变量（11个）
自定义变量（按传入顺序）

所有变量在工具栏的「变量」面板中显示，点击即可插入到编辑器光标位置。

使用示例

typescript

// 插入变量后的内容示例
"欢迎 {{t.first_name}} 加入群组！你还有 {{warn_remain_num}} 次警告机会。"

// 发送到 Telegram 后会自动替换为：
"欢迎 张三 加入群组！你还有 3 次警告机会。"

变量选择器特性

弹窗式界面 - 从底部滑出，不遮挡编辑内容
搜索友好 - 每个变量都有清晰的中文说明
一键插入 - 点击变量即可插入到光标位置
自动关闭 - 插入后自动关闭选择器
暗黑模式支持 - 自动适配系统主题

Spoiler（隐藏文字）交互效果

在非 Telegram 环境中，Spoiler 使用 CSS blur 效果模拟隐藏状态，提供与 Telegram 相似的交互体验：

css

/* 默认模糊状态 */
.tg-spoiler:not(.revealed) {
  color: transparent;
  filter: blur(5px);
}

/* 悬停时减少模糊 */
.tg-spoiler:not(.revealed):hover {
  filter: blur(3px);
}

/* 点击后显示 */
.tg-spoiler.revealed {
  filter: none;
  color: inherit;
}

交互流程：

默认: 文字完全模糊，无法阅读
悬停: 模糊度降低，提示可以点击
点击: 移除模糊效果，显示原文
显示后: 可正常选择和复制文字

移动端优化

键盘上方固定工具栏

工具栏固定在键盘上方，确保输入时不被遮挡：

css

.xc-telegram-editor-toolbar {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  height: 48px;
}

工具栏横向滚动

当工具栏按钮数量较多时，支持横向滚动查看所有按钮：

css

.xc-telegram-editor-toolbar {
  overflow-x: auto;
  overflow-y: hidden;
  -webkit-overflow-scrolling: touch; /* iOS 平滑滚动 */
  touch-action: pan-x; /* 允许横向滚动 */
  scrollbar-width: none; /* 隐藏滚动条 */
}

特性：

自动横向滚动，不会压缩按钮
iOS 平滑滚动体验
隐藏滚动条，保持界面简洁
所有按钮保持 48px 最小宽度

自动滚动

键盘弹出时，编辑器自动滚动到底部，光标始终可见：

tsx

React.useEffect(() => {
  const handleResize = () => {
    setTimeout(() => {
      window.scrollTo(0, document.body.scrollHeight)
      editor?.commands.focus('end')
    }, 300)
  }

  window.addEventListener('resize', handleResize)
  return () => window.removeEventListener('resize', handleResize)
}, [editor])

最小点击区域

所有工具栏按钮都设置了 48px × 48px 的最小点击区域，符合移动端最佳实践。

组件 API

TelegramEditor Props

属性	类型	默认值	描述
`defaultValue`	`string`	`''`	非受控模式下的初始内容
`value`	`string`	-	受控模式下的值
`onChange`	`(html: string, editor: Editor) => void`	-	内容变化回调
`placeholder`	`string`	`'写点什么…'`	Placeholder 文字
`maxLength`	`number`	`4096`	最大字符数限制（Telegram API 限制）
`showCounter`	`boolean`	`true`	是否显示字符计数器
`showToolbar`	`boolean`	`true`	是否显示工具栏
`className`	`string`	-	附加的 CSS 类名
`style`	`React.CSSProperties`	-	自定义样式（支持 CSS 变量覆盖）
`autoFocus`	`boolean`	`false`	是否自动聚焦
`disabled`	`boolean`	`false`	是否禁用
`variables`	`TelegramVariable[]`	`[]`	自定义变量列表（与内置变量合并）
`useShorthandTags`	`boolean`	`false`	是否使用 Telegram 简写标签格式
`i18n`	`TelegramEditorI18n`	`defaultI18n`	国际化文本配置
`onPreview`	`() => void`	-	预览/源码切换回调
`toolbar`	`Partial<TelegramEditorToolbarProps>`	-	自定义工具栏属性

TelegramVariable 接口

typescript

interface TelegramVariable {
  /** 变量唯一标识 */
  key: string
  /** 变量显示标签 */
  label: string
  /** 变量插入值（例如 {{var_name}}） */
  value: string
}

useShorthandTags 说明

控制输出 HTML 中 Spoiler 标签的格式：

tsx

// useShorthandTags={false} (默认)
<span class="tg-spoiler">隐藏内容</span>

// useShorthandTags={true}
<tg-spoiler>隐藏内容</tg-spoiler>

两种格式都是 Telegram 官方支持的，选择哪种取决于你的使用场景。

HTML 转换规则

TelegramEditor 会自动将标准 HTML 标签转换为 Telegram 支持的格式：

基础标签转换

typescript

'<strong>' → '<b>'
'<em>' → '<i>'
'<strike>' → '<s>'
'<del>' → '<s>'
'<ins>' → '<s>'
// Telegram 不支持 <p> 标签，自动移除
'<p>段落1</p><p>段落2</p>' → '段落1\n段落2'

**重要说明：**Telegram Bot API 不支持  标签。编辑器会自动将段落标签转换为换行符（\n）。

特殊标签处理

段落和换行处理：

html

<!-- 编辑器内部格式 -->
<p>第一段</p><p>第二段</p>

<!-- 输出为 Telegram 格式 -->
第一段
第二段

<!-- blockquote 内的段落也会被处理 -->
<blockquote expandable="true"><p>引用内容</p></blockquote>
<!-- 输出 -->
<blockquote expandable="true">引用内容</blockquote>

代码块语言保留：

html

<!-- 输入 -->
<pre><code class="language-python">code</code></pre>

<!-- 输出（保留 language-* class） -->
<pre><code class="language-python">code</code></pre>

Spoiler 标签转换：

html

<!-- 源码模式输入 -->
<tg-spoiler>隐藏内容</tg-spoiler>

<!-- 转换为编辑器内部格式 -->
<span class="tg-spoiler">隐藏内容</span>

<!-- 如果 useShorthandTags={true}，输出时转回 -->
<tg-spoiler>隐藏内容</tg-spoiler>

引用标签保留：

html

<!-- 普通引用 -->
<blockquote>引用内容</blockquote>

<!-- 可展开引用 -->
<blockquote expandable>长引用内容</blockquote>

保留的特殊标签

以下标签会被完整保留，不做修改：

html

<!-- 自定义 emoji -->
<tg-emoji emoji-id="5368324170671202286">🔥</tg-emoji>

<!-- 用户提及链接 -->
<a href="tg://user?id=123456789">@username</a>

<!-- 带语言的代码块 -->
<pre><code class="language-python">print("Hello")</code></pre>

Class 属性清理

所有不必要的 CSS class 会被移除：

html

<!-- 输入 -->
<a class="xc-telegram-editor-link" href="https://example.com">链接</a>
<code class="some-class">代码</code>
<blockquote class="custom-class">引用</blockquote>

<!-- 输出 -->
<a href="https://example.com">链接</a>
<code>代码</code>
<blockquote>引用</blockquote>

**例外情况：**保留 language-* 和 tg-spoiler class。

样式定制

可以通过覆盖 CSS 变量来定制组件样式：

css

.xc-telegram-editor {
  --xc-editor-bg: #ffffff;
  --xc-editor-border: #e5e7eb;
  --xc-editor-text: #000000;
  --xc-editor-toolbar-active: #3b82f6;

  /* 布局变量 */
  --xc-editor-position: absolute;  /* 默认 absolute，可改为 fixed/relative */
  --xc-editor-variables-max-height: 50vh; /* 变量选择器最大高度 */
}

使用固定定位

在移动端应用中使用固定定位（键盘上方固定）：

tsx

<TelegramEditor
  style={{ '--xc-editor-position': 'fixed' } as React.CSSProperties}
  // ...
/>

在 Demo 中使用相对定位

在文档或 Demo 页面中，使用默认的绝对定位：

tsx

<TelegramEditor
  className="demo-editor"
  // 默认是 absolute，无需额外设置
  // ...
/>

暗黑模式

组件自动支持暗黑模式：

css

@media (prefers-color-scheme: dark) {
  .xc-telegram-editor {
    --xc-editor-bg: #1a1a1a;
    --xc-editor-border: #2d2d2d;
    --xc-editor-text: #ffffff;
    --xc-editor-toolbar-bg: #1f1f1f;
    --xc-editor-toolbar-active: #60a5fa;
  }
}

注意事项

字符限制 - Telegram Bot API 限制单条消息最多 4096 个字符（包含 HTML 标签）
纯文本粘贴 - 粘贴时自动过滤所有样式，只保留纯文本，避免引入不支持的标签
定位模式 - 默认使用 absolute 定位，移动端应用可通过 CSS 变量改为 fixed
iOS Safari - 已针对 iOS Safari 的选区和输入法问题进行优化
特殊标签 - <tg-emoji> 和 tg:// 协议链接在编辑器中会被保留，但可能无法实时预览效果
代码语言 - 代码块的 language-* class 会被保留，但编辑器 UI 不提供语言选择器，需在源码模式手动添加

依赖

TelegramEditor 基于 Tiptap 构建，需要以下依赖：

@tiptap/react - React 集成
@tiptap/starter-kit - 基础编辑器功能
@tiptap/extension-link - 链接支持
@tiptap/extension-placeholder - Placeholder 支持
@tiptap/core - 核心库

所有依赖已包含在 @xcloud/ui-mobile 中，无需额外安装。

TelegramEditor ​

核心特性 ​

导入 ​

示例 ​

基础用法 ​

受控模式 ​

支持的格式 ​

基础格式（有 UI 工具） ​

引用按钮智能切换 ​

高级标签（源码模式支持） ​

源码/预览模式 ​

功能特性 ​

转换规则 ​

使用示例 ​

变量插入功能 ​

内置变量列表 ​

自定义变量 ​

使用示例 ​

变量选择器特性 ​

Spoiler（隐藏文字）交互效果 ​

移动端优化 ​

键盘上方固定工具栏 ​

工具栏横向滚动 ​

自动滚动 ​

最小点击区域 ​

组件 API ​

TelegramEditor Props ​

TelegramVariable 接口 ​

useShorthandTags 说明 ​

HTML 转换规则 ​

基础标签转换 ​

特殊标签处理 ​

保留的特殊标签 ​

Class 属性清理 ​

样式定制 ​

使用固定定位 ​

在 Demo 中使用相对定位 ​

暗黑模式 ​

注意事项 ​

依赖 ​

相关资源 ​

TelegramEditor

核心特性

导入

示例

基础用法

受控模式

支持的格式

基础格式（有 UI 工具）

引用按钮智能切换

高级标签（源码模式支持）

源码/预览模式

功能特性

转换规则

使用示例

变量插入功能

内置变量列表

自定义变量

使用示例

变量选择器特性

Spoiler（隐藏文字）交互效果

移动端优化

键盘上方固定工具栏

工具栏横向滚动

自动滚动

最小点击区域

组件 API

TelegramEditor Props

TelegramVariable 接口

useShorthandTags 说明

HTML 转换规则

基础标签转换

特殊标签处理

保留的特殊标签

Class 属性清理

样式定制

使用固定定位

在 Demo 中使用相对定位

暗黑模式

注意事项

依赖

相关资源