Operit 粘贴超长文本自动转文件:设置、粘贴增量识别与附件转换实现解析
Operit 粘贴超长文本自动转文件:设置、粘贴增量识别与附件转换实现解析
本指南基于 Operit 仓库中 paste-long-text-as-file 系列设计文档,完整讲解"粘贴超长文本转文件"这一聊天输入优化能力的实现:包括设置项与字符阈值的设计与持久化、粘贴增量文本的识别算法、超过阈值后写入临时目录并作为 text/plain 附件进入待发送列表的完整链路,以及中英文本地化与单元测试核查方案。读完本文,你将掌握该功能的配置入口、默认行为、底层调用链与验证方法,可直接对照仓库源码进行二次开发或测试扩展。
功能背景与设计目标
在 Operit 的聊天输入场景中,用户经常从网页、文档中复制大段文本直接粘贴到输入框。改动前,聊天输入的文本变更与附件添加分属不同代码路径:粘贴操作没有被专门识别,输入框会直接保留粘贴的全部文本,也没有针对超长文本的阈值设置(详见 01-settings-and-paste-conversion.md)。
大量文本直接进入编辑器会带来两个实际问题:编辑器难以操作(滚动、定位光标、二次编辑都变得困难),大段文本也可能影响界面响应性能。
为此,该功能定义了明确的设计边界(见 index.md):
- 只处理聊天输入框的粘贴增量:当纯文本粘贴长度超过用户设定的阈值时,创建 UTF-8 文本附件,并清空该次粘贴产生的输入内容;
- 不改变既有路径:手动文件选择、普通文本编辑、未达到阈值的粘贴,以及消息协议与已有附件处理流程均保持原有行为。
改动的作用域集中在:聊天输入控件、持久化设置、临时附件创建和中英文资源四个层面。
设置项与阈值持久化:默认 3000 字符
持久化键与默认值
设置项存储在 UserPreferencesManager 中,使用 DataStore 的 intPreferencesKey / booleanPreferencesKey 定义键名:
- 功能总开关:
convert_long_pasted_text_to_file(布尔值),默认 开启; - 字符阈值:
long_pasted_text_file_threshold(整数值),默认 3000。
对应实现位于 UserPreferencesManager.kt,默认值常量定义为:
const val DEFAULT_LONG_PASTED_TEXT_FILE_THRESHOLD = 3000
读取与写入通过 Flow 与挂起函数暴露(UserPreferencesManager.kt):
val convertLongPastedTextToFile: Flow<Boolean> =
context.userPreferencesDataStore.data.map { preferences ->
preferences[CONVERT_LONG_PASTED_TEXT_TO_FILE] ?: true
}
val longPastedTextFileThreshold: Flow<Int> =
context.userPreferencesDataStore.data.map { preferences ->
preferences[LONG_PASTED_TEXT_FILE_THRESHOLD]
?: DEFAULT_LONG_PASTED_TEXT_FILE_THRESHOLD
}
写入方法(UserPreferencesManager.kt):
suspend fun saveConvertLongPastedTextToFile(enabled: Boolean) {
context.userPreferencesDataStore.edit { preferences ->
preferences[CONVERT_LONG_PASTED_TEXT_TO_FILE] = enabled
}
}
suspend fun saveLongPastedTextFileThreshold(threshold: Int) {
context.userPreferencesDataStore.edit { preferences ->
preferences[LONG_PASTED_TEXT_FILE_THRESHOLD] = threshold
}
}
未显式配置时,两个 Flow 分别回落到 true 与 DEFAULT_LONG_PASTED_TEXT_FILE_THRESHOLD,即用户升级后功能默认可用、默认阈值为 3000 字符。
设置界面的开关与阈值输入
设置项位于"全局显示设置"界面(GlobalDisplaySettingsScreen),由两个 UI 组件组合而成(GlobalDisplaySettingsScreen.kt):
- 功能开关:
DisplayToggleItem,标题为"超长粘贴文本转文件",副标题说明"粘贴超过设定字符数的文本时,自动作为文本附件添加",勾选状态直接绑定convertLongPastedTextToFileFlow; - 条件显示的阈值输入:仅在开关打开时显示
EditableNumberSetting,标题"转换阈值",说明"粘贴文本超过此字符数时转为文件",单位为"字符",取值范围为1_000f..100_000f(即 1000~100000 字符),输入即通过saveLongPastedTextFileThreshold(threshold.toInt())落盘。
if (convertLongPastedTextToFile) {
EditableNumberSetting(
title = stringResource(R.string.long_pasted_text_threshold),
subtitle = stringResource(R.string.long_pasted_text_threshold_desc),
value = longPastedTextFileThreshold.toFloat(),
onValueChange = { threshold ->
scope.launch {
userPreferences.saveLongPastedTextFileThreshold(threshold.toInt())
}
},
valueRange = 1_000f..100_000f,
unitText = stringResource(R.string.long_pasted_text_threshold_unit),
backgroundColor = componentBackgroundColor
)
}
聊天主界面(AIChatScreen)同样通过 collectAsState 读取这两项设置,作为粘贴处理的运行参数(AIChatScreen.kt)。
粘贴增量识别:比较粘贴前后的新增区间
粘贴识别的核心算法位于 extractClipboardPastedText(PastedTextAttachment.kt)。它的输入是粘贴前的输入框状态 previous、粘贴后的 proposed,以及剪贴板文本 clipboardText,输出是"本次粘贴实际新增的区间文本"。
算法分四步:
- 空剪贴板直接返回 null;
- 计算插入区间:取
previous.selection的起止位置(归一化到文本长度内),insertionStart为选区起点、insertionEnd为选区终点,从而得到粘贴前文本的prefix(光标前)与suffix(光标后)——这同时兼容"光标处插入"与"选中文本后被替换"两种粘贴形态; - 校验前后缀:若
proposed.text不是以prefix开头或以suffix结尾,说明本次文本变更并非单纯粘贴(可能夹杂输入法/自动纠错等),返回 null; - 截取增量并与剪贴板比对:从
proposed中截取prefix.length到proposed.text.length - suffix.length之间的子串,即粘贴新增区间;再通过归一化换行后与剪贴板内容逐字符比对,只有完全一致才认定为一次真实粘贴。
internal fun extractClipboardPastedText(
previous: TextFieldValue,
proposed: TextFieldValue,
clipboardText: String,
): String? {
if (clipboardText.isEmpty()) return null
val previousText = previous.text
val selectionStart = previous.selection.start.coerceIn(0, previousText.length)
val selectionEnd = previous.selection.end.coerceIn(0, previousText.length)
val insertionStart = minOf(selectionStart, selectionEnd)
val insertionEnd = maxOf(selectionStart, selectionEnd)
val prefix = previousText.substring(0, insertionStart)
val suffix = previousText.substring(insertionEnd)
if (!proposed.text.startsWith(prefix) || !proposed.text.endsWith(suffix)) return null
val pastedEnd = proposed.text.length - suffix.length
if (pastedEnd < prefix.length) return null
val pastedText = proposed.text.substring(prefix.length, pastedEnd)
return pastedText.takeIf {
normalizeLineEndings(it) == normalizeLineEndings(clipboardText)
}
}
其中 normalizeLineEndings 将 \r\n 与 \r 统一为 \n,以兼容不同平台复制文本的换行差异:
private fun normalizeLineEndings(text: String): String {
return text.replace("\r\n", "\n").replace('\r', '\n')
}
单元测试验证
仓库在 PastedTextAttachmentTest.kt 中为该算法提供了四个方向的测试用例:
- 光标处插入:
extractClipboardPastedText(previous, proposed, "inserted ")应返回"inserted "; - 替换选区:粘贴文本覆盖已有选区时返回替换后的内容
"replacement"; - 换行归一化:剪贴板为
"first\r\nsecond"时,识别结果应归一化为"first\nsecond"; - 负例:当文本变更内容与剪贴板不一致时返回
null,避免把非粘贴输入误判为粘贴。
这四个用例恰好覆盖了算法的成功路径、选区替换路径、跨平台换行兼容路径与误判防护路径,可作为后续改动时的回归基线。
触发判定与文本落地:从剪贴板到待发送附件
输入变更钩子中的判定逻辑
AIChatScreen 的 handleUserMessageChange 是粘贴处理的入口(AIChatScreen.kt):
fun handleUserMessageChange(value: TextFieldValue) {
val clipboardText = clipboardManager.primaryClip?.getItemAt(0)?.text?.toString()
val pastedText =
if (convertLongPastedTextToFile && clipboardText != null) {
extractClipboardPastedText(userMessage, value, clipboardText)
} else {
null
}
if (
pastedText != null &&
pastedText.length > longPastedTextFileThreshold &&
!currentChatId.isNullOrBlank()
) {
coroutineScope.launch {
// Keep the draft unchanged until the attachment has been created, so I/O errors do not lose text.
if (!actualViewModel.attachPastedText(pastedText)) {
commitUserMessageChange(value)
}
}
return
}
commitUserMessageChange(value)
}
判定条件由三个因素共同决定,缺一不可:
- 功能开关
convertLongPastedTextToFile已开启且剪贴板有文本; extractClipboardPastedText识别出真实的粘贴增量,且其长度 严格大于 阈值longPastedTextFileThreshold;- 当前存在有效的聊天会话(
currentChatId非空)。
值得注意的实现细节是草稿保留策略:当识别为超长粘贴时,并不立即提交文本变更,而是先异步创建附件。只有当 attachPastedText 返回 false(I/O 失败)时才回退为 commitUserMessageChange(value),将文本留在输入框——这样即使写入失败也不会丢失用户粘贴的内容。附件创建成功后该次粘贴产生的输入内容即被清空,输入框不会承载超长文本,符合设计文档"输入框不会承载该文本"的预期。
附件创建:清理目录中的 UTF-8 临时文件
ChatViewModel.attachPastedText 负责包装状态与委托调用(ChatViewModel.kt):先为当前聊天设置 InputProcessingState.Processing 状态(文案为"正在处理附件"),调用 attachmentDelegate.attachPastedText(text),无论成败都在 finally 中恢复 Idle。
真正的落盘逻辑在 AttachmentDelegate.attachPastedText(AttachmentDelegate.kt):
- 获取
OperitPaths.cleanOnExitDir()作为存放目录,目录不存在时创建; - 确保目录中存在
.nomedia文件,避免生成的文本文件出现在系统媒体库中; - 使用
File.createTempFile("pasted_text_", ".txt", externalDir)创建唯一命名的.txt临时文件; - 以 UTF-8 编码写入完整粘贴文本:
textFile.writeText(text, Charsets.UTF_8); - 构造
AttachmentInfo(filePath, fileName, mimeType = "text/plain", fileSize)并appendAttachment加入当前聊天的附件列表,使其出现在附件预览中、可随消息一起发送; - 弹出提示 toast
chat_pasted_text_attached("已将粘贴文本作为附件添加:%1$s")。
suspend fun attachPastedText(text: String): Boolean =
withContext(Dispatchers.IO) {
try {
val externalDir = OperitPaths.cleanOnExitDir()
if (!externalDir.exists()) {
externalDir.mkdirs()
}
val noMediaFile = File(externalDir, ".nomedia")
if (!noMediaFile.exists()) {
noMediaFile.createNewFile()
}
val textFile = File.createTempFile("pasted_text_", ".txt", externalDir)
textFile.writeText(text, Charsets.UTF_8)
val addedAttachment =
appendAttachment(
AttachmentInfo(
filePath = textFile.absolutePath,
fileName = textFile.name,
mimeType = "text/plain",
fileSize = textFile.length(),
)
)
_toastEvent.emit(
context.getString(R.string.chat_pasted_text_attached, addedAttachment.fileName)
)
true
} catch (e: Exception) {
AppLogger.e(TAG, "Error creating pasted text attachment", e)
_toastEvent.emit(context.getString(R.string.attachment_add_failed, e.message ?: ""))
false
}
}
写入在 Dispatchers.IO 线程池执行,避免大文本的文件 I/O 阻塞主线程;失败路径记录日志并返回 false,由上层决定是否回退保留草稿。
清理目录的定位
cleanOnExitDir 位于 Operit 的应用根目录之下(OperitPaths.kt):
fun cleanOnExitDir(): File {
return ensureDir(File(operitRootDir(), CLEAN_ON_EXIT_DIR_NAME))
}
该目录是 Operit 的"退出即清理"临时目录,同样被截图、临时文件等场景复用(如 AccessibilityUITools、StandardUITools 的截图存放),因此粘贴生成的 .txt 文件不会长期占用存储空间,也无需用户手动清理。
本地化与静态核查
按 02-localization-and-verification.md 的规划,该功能新增的文案全部走 Android 资源文件,并完成中英文(及多语言)覆盖。
新增资源键如下(以中英文为例,另覆盖西班牙语、马来语、罗马尼亚语等,见 values/strings.xml 与 values-en/strings.xml):
| 资源键 | 中文 | 英文 |
|---|---|---|
chat_pasted_text_attached |
已将粘贴文本作为附件添加:%1$s | Pasted text added as an attachment: %1$s |
long_pasted_text_to_file |
超长粘贴文本转文件 | Convert long pasted text to a file |
long_pasted_text_to_file_desc |
粘贴超过设定字符数的文本时,自动作为文本附件添加 | Pasted text longer than the configured limit is added as a text attachment |
long_pasted_text_threshold |
转换阈值 | Conversion limit |
long_pasted_text_threshold_desc |
粘贴文本超过此字符数时转为文件 | Pasted text longer than this number of characters is converted to a file |
long_pasted_text_threshold_unit |
字符 | characters |
设置名称、说明与转换提示(toast)均由 stringResource / context.getString 引用这些资源键,因此切换应用语言后会自动展示对应语言的文案。本地化核查还包括对受影响调用点与资源引用的静态检查,确保新增字符串在所有语言资源中成对出现、无缺失引用。
行为边界与预期效果
综合设计文档与源码实现,该功能的最终行为可归纳如下:
- 未达阈值 / 功能关闭:粘贴文本照常进入输入框,走原有文本编辑与发送路径,与改动前行为一致;
- 超过阈值:输入框不承载该次粘贴的文本,系统在清理目录生成
pasted_text_*.txt临时文件(UTF-8、text/plain),附件预览中出现可发送的.txt文件,并弹出"已将粘贴文本作为附件添加"提示; - 写入失败:附件创建失败时回退提交文本变更,粘贴内容保留在输入框中,不因 I/O 错误丢失;
- 误判防护:仅当新增区间与剪贴板内容(换行归一化后)完全一致时才触发转换,普通输入与输入法行为不会被误触发;
- 不涉及的范围:消息协议、已有附件处理流程、手动文件选择均不受影响(见 index.md)。
整个功能从设置持久化(UserPreferencesManager)、设置界面(GlobalDisplaySettingsScreen)、粘贴识别(extractClipboardPastedText + PastedTextAttachmentTest.kt)到附件落地(AttachmentDelegate + OperitPaths)形成了完整闭环,为长文本粘贴场景提供了"自动转文件"的轻量解决方案。