SelectionActions 划词工具条
把选中文字交给智能体改写的浮动工具条
用法
划词改写
状态依次为 idle → thinking → streaming → result,由宿主推进;thinking 的文案带微光。
Loading demo...
追踪选区
组件只负责呈现;useSelectionAnchor() 追踪普通正文的选区,其他场景自行构造 SelectionPayload。
import { resolveSelectionPayload, useSelectionAnchor } from '@talex-touch/tuffex/selection-actions'
const { selection, clear } = useSelectionAnchor({
root: articleRef, // 只追踪这棵子树里的选区
debounce: 120, // selectionchange 每帧都触发,必须收敛
minLength: 1, // 太短的选区不值得弹条
ignore: () => [barEl], // 焦点落在工具条上不算「取消选中」
})
最佳实践
- 流式改写时,在更新文本后的同一帧调用
updatePosition(),不要放进setTimeout。 ignore传入实例的el:() => [barRef.value?.el ?? null];document.querySelector在页面有两个工具条时会取错。keep/discard后调用clear(),否则快照不释放,工具条不会收起。root限定到正文容器,否则页面上任何一次选中都会弹出工具条。- 消息尾部的复制、重生成、朗读用
TxMessageActions;本组件只用于改写选区。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
selection | SelectionPayload | null | null | { text, rects, range? } 快照;为空时收起工具条。 |
state | 'idle' | 'thinking' | 'streaming' | 'result' | 'idle' | 状态机由宿主持有,组件不发请求。 |
actions | SelectionActionItem[] | Explain / Improve + 折叠的 Shorten / Tone / Grammar | 动作列表 { id, label, more?, busyLabel? };自定义动作应设 busyLabel。 |
activeActionId | string | — | 正在运行的动作 id,决定忙碌文案。 |
expanded | boolean | — | v-model:expanded,折叠的动作组。 |
prompt | string | — | v-model:prompt,自由指令输入。 |
hidePrompt | boolean | false | 隐藏输入框与发送键,用于只读场景。 |
placeholder | string | 'Describe edits' | 输入框占位,同时作为它的无障碍名。 |
ariaLabel | string | 'Selection actions' | 工具条的无障碍名。 |
keepLabel / discardLabel | string | 'Keep' / 'Discard' | 结果态的两个按钮。 |
retryLabel | string | 'Try again' | 重试按钮的无障碍名。 |
sendLabel | string | 'Send edit instruction' | 发送键的无障碍名。 |
expandLabel / collapseLabel | string | 'Show more actions' / 'Show fewer actions' | 展开按钮的无障碍名。 |
busyLabel | string | 'Editing' | 动作未设 busyLabel 时的兜底忙碌文案。 |
offset | number | 8 | 与选区最后一行的距离(px)。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
action | ({ id, action, selection }) | 按下预设动作,携带选区快照。 |
submit | ({ prompt, selection }) | 输入框回车或按发送键;prompt 已 trim,空白时不触发。 |
keep / discard | () | 结果态的保留 / 放弃。 |
retry | () | 结果态的重试。 |
update:expanded | (expanded: boolean) | 折叠组开合。 |
update:prompt | (prompt: string) | 输入内容变化。 |
插槽
| 插槽名 | 作用域参数 | 说明 |
|---|---|---|
action-icon | { action } | 覆盖动作图标;自定义 id 必须使用。 |
busy | { label } | 覆盖忙碌区。 |
result | — | 覆盖保留 / 放弃 / 重试按钮组。 |
暴露方法
| 名称 | 说明 |
|---|---|
updatePosition() | 按当前 selection.rects 重新定位;流式宿主必须调用。 |
focusInput() | 聚焦自由指令输入框。 |
el | 工具条根元素,传给 useSelectionAnchor 的 ignore。 |
useSelectionAnchor 选项
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
root | MaybeRefOrGetter<Element | null | undefined> | — | 限定追踪范围;不传则监听整篇文档。 |
debounce | number | 120 | selectionchange 的收敛时间(ms)。 |
minLength | number | 1 | 去空白后的最小长度。 |
disabled | MaybeRefOrGetter<boolean> | false | 暂停上报而不卸载。 |
ignore | MaybeRefOrGetter<Array<Element | null | undefined>> | [] | 焦点落进这些元素时不视为取消选中。 |
返回 { selection, clear }:selection 是 Ref<SelectionPayload | null>,clear() 在改写落地或放弃后调用。resolveSelectionPayload() 是其内部的纯函数规则,单独导出供测试或自定义追踪;两者都是运行时函数,需从 @talex-touch/tuffex/selection-actions 显式导入。
概述
- 锚点是选区最后一行的底边,水平居中于整段选区;工具条不翻面(
disableFlip),只横向推回视口。 - 锚点是虚拟参考点,
floating-ui不会跟随文本重排;流式写入时由宿主调用updatePosition(),窗口缩放与滚动由组件处理。 selection是快照:聚焦输入框会清掉浏览器选区,动作仍作用于传入的那一份。- 根节点吞掉
pointerdown,按按钮不会转移焦点或毁掉选区;input、textarea、contenteditable内除外。Safari 与 Firefox 此后的光标行为不同,接入时需真机验证。 - 根节点为
role="group",方向键留给输入框光标;折叠的动作与prompt为空时的发送键不在 Tab 序列中。 - 入场是越过终值的弹簧动画;减少动态效果时去掉入场动画、跳过宽度补间,元素停在可见终态。
技术实现
- 宽度形变走 WAAPI,因此在脚本中读取
prefers-reduced-motion;追踪层基于@vueuse/core的useTextSelection,并 clone 选区的 range。 - 移植自 Beautiful UI(https://www.beautifului.dev),© 2026 Shane Levine,MIT;追踪层是移植时新写的,上游没有真实选区。
- 源码:
packages/tuffex/packages/components/src/selection-actions/。
查看源码
packages/tuffex/packages/components/src/selection-actions/index.ts