Files
Netcatty/components/terminal/hooks/useTerminalFilePaste.ts
T
Yohannandyangheng 83e0e98795 feat(terminal): auto-upload clipboard images on paste (remote sessions, opt-in setting) (#2676)
* feat(terminal): 粘贴时自动上传剪贴板图片(远程会话,设置项控制)

- 新增设置项 autoUploadClipboardImageOnPaste(默认关闭):剪贴板含图片时,远程 SSH 会话中粘贴自动通过 SFTP 上传图片到远端 .netcatty-paste-images/ 并输入远端路径,无图则回退普通文本粘贴
- terminalClipboardPaste.ts:图片检查优先于本地文件/文本粘贴;上传失败上报错误提示,不上传时静默回退
- 统一四路粘贴入口:右键/中键(onPaste)、DOM paste 事件(useTerminalFilePaste)、绑定快捷键(createXTermRuntime case "paste")
- TerminalBehaviorSettings.tsx 新增设置开关,i18n 补齐 en/ru/zh-CN/zh-TW
- syncPayload.ts 设置同步白名单加入新字段
- 测试:terminalClipboardPaste.test.ts 新增 4 个用例(上传/回退/失败上报/本地不受影响)

Author: yangheng
Model: 42865985-ead4-417f-88a9-12012a3495fe/deepseek-v4-flash

* fix(terminal): 剪贴板图片上传异常时上报错误而非静默回退

- clipboardImagePaste.ts:readClipboardImage 抛错视为 no-image(读图失败与空剪贴板无法区分,可安全回退普通粘贴)
- terminalClipboardPaste.ts:确认剪贴板有图后上传流程抛异常(如 SFTP 无法打开)→ 上报 upload-failed 错误并停止,与右键菜单路径一致,不再静默粘贴无关剪贴板内容
- 测试:新增「上传抛异常 → 上报 upload-failed 且不粘贴」「读图失败 → no-image」2 个用例,18/18 通过

Author: yangheng
Model: 42865985-ead4-417f-88a9-12012a3495fe/deepseek-v4-flash

---------

Co-authored-by: yangheng <492238647@qq.com>
2026-08-05 10:29:37 +08:00

110 lines
3.6 KiB
TypeScript

import type { Terminal as XTerm } from "@xterm/xterm";
import type React from "react";
import { useEffect } from "react";
import { netcattyBridge } from "../../../infrastructure/services/netcattyBridge";
import { logger } from "../../../lib/logger";
import type { TerminalSession } from "../../../types";
import type { RemoteClipboardImageUploadResult } from "../clipboardImagePaste";
import { handleTerminalClipboardPaste } from "../terminalClipboardPaste";
interface UseTerminalFilePasteOptions {
isLocalConnection: boolean;
status: TerminalSession["status"];
termRef: React.MutableRefObject<XTerm | null>;
sessionRef: React.MutableRefObject<string | null>;
terminalBackend: {
writeToSession: (sessionId: string, data: string, options?: { automated?: boolean; sensitive?: boolean }) => void;
};
isSensitiveInput?: () => boolean;
scrollOnPasteRef?: React.RefObject<boolean>;
onPasteData?: (data: string) => boolean | void;
scrollToBottomAfterProgrammaticInput: (data: string) => void;
containerRef: React.RefObject<HTMLDivElement | null>;
/** Remote sessions only: auto-upload a clipboard image on paste. */
autoUploadClipboardImage?: boolean;
getRemoteCwd?: () => Promise<string | null | undefined>;
onClipboardImageUploadResult?: (result: RemoteClipboardImageUploadResult) => void;
}
export function useTerminalFilePaste({
isLocalConnection,
status,
termRef,
sessionRef,
terminalBackend,
isSensitiveInput,
scrollOnPasteRef,
onPasteData,
scrollToBottomAfterProgrammaticInput,
containerRef,
autoUploadClipboardImage = false,
getRemoteCwd,
onClipboardImageUploadResult,
}: UseTerminalFilePasteOptions) {
useEffect(() => {
const container = containerRef.current;
if (!container) return;
const handlePaste = (event: ClipboardEvent) => {
if (status !== "connected") return;
const bridge = netcattyBridge.get();
const wantsImageUpload =
autoUploadClipboardImage && !isLocalConnection && !!bridge?.readClipboardImage;
if (!wantsImageUpload && (!isLocalConnection || !bridge?.readClipboardFiles)) return;
// ⚡ Must call preventDefault SYNCHRONOUSLY — the event lifecycle
// is synchronous; calling it after an await is too late and the
// browser will have already performed the default paste action.
event.preventDefault();
event.stopPropagation();
void (async () => {
try {
const term = termRef.current;
if (!term) return;
await handleTerminalClipboardPaste({
bridge,
autoUploadClipboardImage: wantsImageUpload,
clipboardImageBridge: bridge ?? undefined,
getRemoteCwd,
isLocalConnection,
isSensitiveInput,
onClipboardImageUploadResult,
readClipboardText: () => navigator.clipboard.readText(),
scrollOnPaste: scrollOnPasteRef?.current ?? false,
onPasteData,
sessionId: sessionRef.current,
terminalBackend,
term,
scrollToBottomAfterProgrammaticInput,
});
} catch (error) {
logger.error("Failed to handle file paste", error);
}
})();
};
container.addEventListener("paste", handlePaste, true);
return () => {
container.removeEventListener("paste", handlePaste, true);
};
}, [
autoUploadClipboardImage,
containerRef,
getRemoteCwd,
isLocalConnection,
isSensitiveInput,
onClipboardImageUploadResult,
onPasteData,
scrollOnPasteRef,
scrollToBottomAfterProgrammaticInput,
sessionRef,
status,
terminalBackend,
termRef,
]);
}