[RFC] 新组件：TextSelection 文本划词操作

[ZQDesigned]

Summary

计划在后续版本中新增一个 TextSelection 组件。

TextSelection 用于在一段普通内容区域内选择可见文本，并在选区附近弹出上下文操作浮层。它主要服务于企业后台里常见的文本二次操作场景，例如关键词标记、脱敏、搜索、复制、批注入口等。

本 RFC 提议的第一版只聚焦以下能力：

• 在普通 DOM 内容中的文本选择
• 选区产生后的浮层承载
• open 受控与非受控模式
• 一套克制的默认浮层约定
• 浮层内容自定义渲染

Motivation

在很多中后台场景中，用户并不是只“阅读”文本，而是需要直接对选中的文本执行操作。尤其是在长文档、HTML 内容、审查页面、日志页面、知识库页面中，这类需求会反复出现。

典型场景包括：

• 选中一个关键词并标记为敏感词
• 选中一段文本并发起搜索
• 选中一个短句并创建批注
• 选中文本并执行业务自定义动作

今天用户当然可以通过浏览器 Selection API 配合 Popover 自己拼装这套行为，但它并不简单：

• 选区生命周期比较脆弱
• 点击浮层时很容易把选区提前清空
• 基于 Range 的定位细节容易踩坑
• 跨富文本节点的选区逻辑需要反复重复实现
• 受控开关与关闭时机缺少统一约定

相关 issue：#58165

我认为这类能力已经具备足够通用性，适合抽象为一个原子组件，同时保持足够轻量，不把业务数据模型和持久化状态内建进去。

Non-Goals

第一版不打算包含以下能力：

• 持久化文本高亮
• 批注存储、审核流、评论流
• 直接修改或替换选中文本
• 支持 input、textarea、contenteditable 内的文本选择
• 完整承诺复杂移动端选区交互
• 导出复杂 HTML 片段数据

如果第一版验证下来价值明确，这些能力可以在后续继续讨论。

API

TextSelection

属性	说明	类型	默认值
popupRender	自定义浮层渲染	(originNode, info) => ReactNode	-
minLength	选中文本经 trim() 后的最小长度	number	1
disabled	是否禁用文本划词浮层	boolean	false
open	是否打开浮层	boolean	-
defaultOpen	是否默认打开浮层	boolean	false
popoverProps	内部浮层配置	Pick<PopoverProps, 'placement' | 'arrow' | 'getPopupContainer' | 'autoAdjustOverflow' | 'destroyOnHidden' | 'zIndex'>	-
classNames	语义化 className 配置	semantic object | function	-
styles	语义化 style 配置	semantic object | function	-
onSelectionChange	有效选区变化时触发	(info: SelectionInfo | null) => void	-
onOpenChange	浮层开关变化时触发	(open, info) => void	-

SelectionInfo

type SelectionInfo = {
  text: string;
  range: Range;
  rect: DOMRect;
};

OpenChangeInfo

type OpenChangeInfo = {
  source: 'selection' | 'popup' | 'outside' | 'escape' | 'programmatic';
};

Basic Example

import { TextSelection } from 'antd';

export default () => (
  <TextSelection>
    <div style={{ padding: 16, lineHeight: 1.8 }}>
      这是一段可选中文本，选中任意内容后会弹出默认浮层。
    </div>
  </TextSelection>
);

Custom Popup Example

import { Button, Space, TextSelection } from 'antd';

export default () => (
  <TextSelection
    popupRender={(_, { text, close }) => (
      <Space size="small">
        <Button
          type="primary"
          size="small"
          onClick={() => {
            console.log('脱敏', text);
            close();
          }}
        >
          脱敏
        </Button>
        <Button
          size="small"
          onClick={() => {
            console.log('标记', text);
            close();
          }}
        >
          标记
        </Button>
      </Space>
    )}
  >
    <div style={{ padding: 16 }}>
      这是一段用于业务自定义操作的可划词内容。
    </div>
  </TextSelection>
);

Detailed Design

组件定位

TextSelection 应该是一个独立组件，而不是 Typography 的新 prop。

原因：

• 划词操作是跨内容的交互能力，而不是文本装饰能力
• 它需要包裹任意内容，不只限于 Typography
• 可以让 Typography 继续聚焦于 copyable、editable、ellipsis 等文本展示能力
• 后续独立演进更自然

选区范围

组件只响应自身子树内的有效选区。

一个“有效选区”需要满足：

• 选区不是折叠状态
• 选中文本经 trim() 后不为空
• Range 的起点和终点都在组件根节点内部
• 选中文本长度大于等于 minLength
• 选区不位于 input、textarea 或 contenteditable 内

浮层行为

当产生有效选区时，浮层自动打开。

默认情况下，组件会渲染一个非常轻量的默认浮层，用来承载当前选中的文本内容。它的目标是提供稳定的选区锚定和最小展示约定，而不是内建完整业务动作。

浮层在以下情况下关闭：

• 点击外部区域
• 按下 Escape
• 选区失效或折叠
• 选区移出组件子树
• 通过浮层内部逻辑主动关闭
• 受控 open 变为 false

渲染策略

默认浮层会展示一份最小内容约定，第一版不提供可配置的 actions 数据结构。

当提供 popupRender 时，会收到：

• originNode：默认浮层节点
• info：当前选区信息与辅助方法

辅助方法包括：

• close()：关闭当前浮层
• update()：基于最新选区重新计算浮层位置

这套设计与 antd 现有的 popupRender、panelRender、actionsRender 等自定义模式保持一致。

浮层定位

浮层应基于选区 Range 的矩形信息进行定位，而不是依赖一个普通触发元素。

内部实现建议维护一个基于当前选区几何信息的虚拟锚点，并尽量复用现有 popup 的定位能力。

无障碍

第一版至少需要保证：

• 浮层操作按钮可以通过键盘聚焦
• Escape 可以关闭浮层
• 组件支持语义化 classNames 与 styles
• 点击浮层操作时不会因为选区过早丢失而导致无法使用

Semantic DOM

建议暴露以下语义槽位：

• root
• toolbar
• action
• popup.root
• popup.container

Demos

建议至少提供以下 demo：

• 基础用法
• 自定义浮层
• 受控模式
• 富文本内容选择
• 语义化样式定制

可选后续 demo：

• 异步操作
• 不同浮层位置
• 禁用状态

How we teach this

• 为 TextSelection 新增组件文档页
• 说明它适合“选中文本后展示上下文浮层”的场景
• 明确第一版不包含持久化高亮和批注存储
• 同时提供默认浮层与 popupRender 扩展用法示例
• 在 FAQ 中说明不支持 input / textarea 选区

Adoption Strategy

第一版可以先完全实现在 antd 内部，不急着拆出新的 rc-* 包。

如果后续需求演进到以下方向：

• 跨框架复用
• 更复杂的 Range 抽象
• 持久化高亮
• 更重的浮层定位能力

再考虑下沉为更底层的包会更合适。

Alternatives Considered

方案一：给 Typography 增加 selectable

当前不优先选择。

虽然 Typography 已经有 copyable 和 editable，但“划词后动作”比文本装饰和文本编辑更宽，会让 Typography 语义继续变重。

方案二：只提供 Hook

当前不优先选择。

Hook 当然更灵活，但它无法提供标准化的 antd 浮层行为、语义 DOM 和一致的 API 体验。对于一个准备面向社区推广的新能力来说，组件化更符合预期。

方案三：给 Popover / Dropdown 增加一种基于文本选区的交互形式

当前不优先选择。

这个方向看起来可以减少新组件数量，但这里的复杂度并不只在“弹层如何展示”，还包括：

• 选区是否有效
• 选区是否位于当前组件子树内
• 选区失效后的关闭逻辑
• 点击浮层时避免选区过早丢失
• 对外暴露选区上下文与定位更新能力

这些行为已经超过了给通用弹层新增一种 trigger 的范围。相比把这套状态机塞进 Popover / Dropdown，独立组件的边界会更清晰，也更利于后续演进。

[QDyanbing]

一期api太多了吧；缩减点保证最小可用；陆续添加；

[ZQDesigned]

这里面有一些API是要从其他既有组件里透传出来的，实际上真正要自己完全处理的API数量没有列举的这么多。

[QDyanbing]

使用使用下拉组件吗？那是不是 dropdown: DropdownProps这种好一点

[ZQDesigned]

我在考虑使用 Popover，可能 Popover 的视觉效果是更符合预期的

[QDyanbing]

一样的道理；不过这个还是听听其他人的意见；我是比较倾向透传的都包一下这样干净点。

[ZQDesigned]

了解 我当前这样设计主要是考虑：虽然我要复用 Popover 这个组件，但实际上只是复用其弹层能力和视觉语义，且 Popover 里有大量属性不适用或会产生冲突，故没有直接包一个属性，也是希望假设后续可能会让用户自行选择使用哪种组件作为弹出层的壳的时候，不会被 Prop 绑死在 Popover 里，这样的设计也是有参考现有组件 ColorPicker 的。

[afc163]

给 Popover/Dropdown 新增一种交互形式如何？

[ZQDesigned]

我理解“增加新的交互形式”可能是给 trigger 增加一个触发方式，但是这似乎有些偏离 Popover/Dropdown 组件的设计初衷以及用途

并且新增这个组件更多是要提供一些额外的约束和状态管理，比如：

• 只响应组件子树内的有效选区
• 需要处理选区失效、折叠、越界后的关闭
• 点击浮层时要避免选区提前丢失
• 还会涉及选中文本信息、Range、定位更新等上下文数据透出

这些可能不是只加一种 trigger 能够覆盖的，如果直接塞进通用弹层里，可能会让它们的语义和状态模型变重。

[QDyanbing]

1. minLength 建议也先不提供，尽量缩小 api 范围；
2. 什么时候触发弹层（按照正常的交互是，选中结束后一般不会触发弹出的动作，一般我常见的交互就是选中然后右键）
3. defaultOpen 是否需要，我理解有选中才会有 open？
4. onOpenChange，open 是不是也收到 popoverProps 内；
5. 组件不应该处理trim()

[ZQDesigned]

defaultOpen 原本设计出来是为这个组件提供受控和非受控模式的，不过目前已经在新一轮优化中移除这一 API。这是新的 API 设计：link

[murisans]

如果是右键触发，浏览器正常的右键菜单弹出会被影响到吗

[ZQDesigned]

如果是右键触发，浏览器正常的右键菜单弹出会被影响到吗

会的，涉及到处理 contextmenu 事件的问题，原则上不使用这种行为，当前最新的API设计草案是只提供这样的一套封装，是否使用弹层功能自行给open参数传入值来进行控制

目前还在考虑要不要保留非受控模式的 defaultOpen 这个API，仅在不设置此值或设置此值为false时处理受控参数 open 的逻辑

[zombieJ]

如果参与浮层控制的确会后 Popover 感觉有点重复，语义上似乎又不应该和 Popover 合并。感觉可以参考一下 Tour 的形式，它也是非 vdm 绑定的。

[ZQDesigned]

感谢建议。我重新对照了现有源码看了一遍，当前比较认同这个方向：

我理解这里更合适的形态，不是把它并进 Popover/Dropdown，而是做成一个类似 Tour 的“非 VDOM 绑定”的独立组件：它自己管理选区状态和浮层锚点，但内部复用现有 popup 能力与视觉语义。

也就是说，这个组件的核心价值不在“又一个浮层”，而在于：

• 只响应当前内容区域内的有效选区
• 处理选区失效 / 越界 / 折叠后的关闭时机
• 点击浮层操作时，尽量避免选区上下文过早丢失
• 对外透出稳定的 selection context，而不是让用户自己拼 Selection API + Popover

基于这个理解，我把设计文档改了一版，想继续请大家帮忙看下边界是否更清晰。

修改后的精简版设计文档

Summary

计划在后续版本中新增一个 TextSelection 组件。

TextSelection 用于在一段普通内容区域内监听文本选择，并在有效选区附近展示上下文浮层。它适用于关键词标记、搜索、复制、批注入口、脱敏等中后台常见场景。

第一版聚焦于：

• 普通 DOM 内容中的文本选择
• 选区完成后的浮层锚定与展示
• 受控 open
• 自定义浮层渲染
• 选区信息透出

Non-Goals

第一版不包含：

• 持久化高亮
• 批注存储、评论流、审核流
• 直接修改选中文本
• input / textarea / contenteditable 内的文本选择
• 移动端复杂选区交互

API

TextSelection

属性	说明	类型	默认值
popupRender	自定义浮层渲染	(originNode, info) => ReactNode	-
disabled	是否禁用	boolean	false
open	是否打开浮层	boolean	-
placement	浮层位置	TooltipPlacement	top
getPopupContainer	浮层挂载容器	(node: HTMLElement) => HTMLElement	body
classNames	语义化 className 配置	semantic object | function	-
styles	语义化 style 配置	semantic object | function	-
onSelectionChange	当前有效选区变化时触发	(info: SelectionInfo | null) => void	-
onOpenChange	浮层开关变化时触发	(open, info) => void	-

SelectionInfo

type SelectionInfo = {
  text: string;
  range: Range;
  rect: DOMRect;
};

OpenChangeInfo

type OpenChangeInfo = {
  source: 'selection' | 'popup' | 'outside' | 'escape' | 'programmatic';
};

Behavior

组件只响应自身子树内的有效选区。

一个有效选区需要满足：

• 选区不是折叠状态
• Range 起点和终点都位于组件根节点内部
• 不位于 input、textarea 或 contenteditable 内

当有效选区完成后，浮层自动打开。

浮层在以下情况下关闭：

• 点击外部区域
• 按下 Escape
• 选区失效或折叠
• 选区移出当前组件子树
• 浮层内部主动关闭
• 受控 open 变为 false

Rendering

组件会提供一个最小默认浮层，仅负责稳定锚定与最小展示约定，不内建完整 actions 数据结构。

当传入 popupRender 时，会收到：

• originNode：默认浮层节点
• info：当前选区信息与辅助方法

type PopupRenderInfo = SelectionInfo & {
  close: () => void;
  update: () => void;
};

Implementation Direction

内部方向倾向于：

• 将该组件实现为独立状态控制器
• 内部复用现有 popup 能力与视觉语义
• 但不直接暴露整套 PopoverProps
• 浮层锚点基于当前选区几何信息计算，而不是依赖普通 trigger 元素

Semantic DOM

第一版建议先暴露较小语义面：

• root
• popup.root
• popup.container

更细的 toolbar / action 语义，可根据后续实际需求补充。

Demos

至少提供：

• 基础用法
• 自定义浮层
• 受控模式
• 富文本内容选择
• 语义化样式定制

Adoption Strategy

第一版先完全实现在 antd 内部，不急着拆成新的 rc-* 包。

原因是当前更需要先验证：

• 选区状态模型是否稳定
• 关闭时机与受控语义是否合理
• 社区实际需求是否会继续演进到持久化高亮 / 富文本编辑 / 跨框架复用

如果后续这些边界稳定，再考虑是否需要继续下沉。

如果这个方向可以接受，我会继续补充完整的设计文档。欢迎继续拍砖。