Spacedrive 文件操作 UI 实现指南:复制、移动、删除、重命名与进度反馈

原创2026-09-18 16:04:351,983 阅读
文章标签:桌面应用移动开发分布式文件系统数据同步网络跨平台插件系统任务调度图像处理语音密码学对象存储

Spacedrive 文件操作 UI 实现指南:复制、移动、删除、重命名与进度反馈

本文围绕 Spacedrive 探索任务 EXPL-003(File Operations UI)展开,系统讲解如何在 Spacedrive 的 React 界面层(packages/interface)实现核心文件操作(复制、移动、删除、重命名、新建文件夹、复制副本等),并与 Rust 核心(core/src/ops/files)的任务系统(Job System)无缝集成,包括 useLibraryMutation 的调用方式、任务进度事件订阅、错误处理与确认对话框等关键实践。读完本文,你将掌握 Spacedrive 文件操作从前端交互到后端任务执行、再到实时进度反馈的完整技术链路。

一、任务背景与文件操作 UI 的定位

EXPL-003 是 Spacedrive 界面层(interface)的探索任务,其核心描述是:

为核心文件操作(copy、move、delete、rename)实现 UI,并与后端任务(backend jobs)集成、展示进度。

这份规格定义了文件操作 UI 的五大实施要点(Implementation Notes):

  • 所有操作统一使用 useLibraryMutation 发起;
  • 长耗时操作通过进度 Toast 展示;
  • 订阅任务进度事件(job progress events);
  • 优雅地处理错误并向用户反馈;
  • 破坏性操作(如删除)必须弹出确认对话框。

以及九项验收标准(Acceptance Criteria):复制(右键菜单 / Cmd+C)、拖拽移动、删除确认、内联重命名、复制副本(Duplicate)、新建文件夹、长任务进度指示、友好错误提示、安全操作的 Undo。

从仓库现状看,这一设计意图已经沉淀为可运行的实现:前端有 FileOperationModal.tsx 及其使用文档 FileOperationModal.README.md,共享删除 Hook useDeleteFiles.ts;后端则在 core/src/ops/files 下形成了 copy、delete、rename、create_folder、duplicate_detection、validation、query 等模块化目录。下文将把任务规格与源码实现相互印证,给出完整的落地指南。

二、统一入口:useLibraryMutation 驱动所有文件操作

任务规格要求所有操作走 useLibraryMutation,这一约定在界面层被严格执行。useLibraryMutation 由 SpacedriveContext.tsx 提供,它把 TypeScript 客户端(@sd/ts-client)自动生成的库级 mutation 封装为 React Hook,使组件能够以声明式方式调用核心动作(如 files.copy、files.delete、files.rename、files.createFolder)。

以删除操作为例,useDeleteFiles.ts 是共享删除逻辑的典范实现:

import { useCallback } from "react";
import type { File } from "@sd/ts-client";
import { useLibraryMutation } from "../../../contexts/SpacedriveContext";

export function useDeleteFiles() {
	const mutation = useLibraryMutation("files.delete");

	const deleteFiles = useCallback(
		async (files: File[], permanent: boolean) => {
			if (files.length === 0) return false;
			if (files.some((f) => !f.sd_path)) return false;
			if (mutation.isPending) return false;

			const label = permanent ? "Permanently delete" : "Delete";
			const suffix = permanent ? " This cannot be undone." : "";
			const message =
				files.length > 1
					? `${label} ${files.length} items?${suffix}`
					: `${label} "${files[0].name}"?${suffix}`;

			if (!confirm(message)) return false;

			try {
				await mutation.mutateAsync({
					targets: { paths: files.map((f) => f.sd_path) },
					permanent,
					recursive: true,
				});
				return true;
			} catch (err) {
				console.error("Failed to delete:", err);
				alert(`Failed to delete: ${err}`);
				return false;
			}
		},
		[mutation],
	);

	return { deleteFiles, isPending: mutation.isPending };
}

这个 Hook 同时被 useExplorerKeyboard(键盘 DEL 键)和 useFileContextMenu(右键菜单)复用,覆盖了"删除"的两大入口。它同时示范了任务规格中"错误处理"与"确认对话框"两条要求的落地方式:通过 confirm() 弹出确认框,通过 try/catch 捕获 mutation 异常并向用户 alert 展示。useFileContextMenu 位于 useFileContextMenu.ts,对应验收标准中的"右键菜单"入口。

三、复制与移动:从 Cmd+C / 拖拽到 FileCopyJob

3.1 任务规格中的复制/移动验收点

  • 通过右键菜单或 Cmd+C 复制文件;
  • 通过拖拽移动文件(默认复制,按住 Alt/Option 变为移动);
  • 复制副本(Duplicate);
  • 长任务显示进度指示。

3.2 前端交互:FileOperationModal 与拖拽体系

复制与移动的前端核心是文件操作模态框(File Operation Modal),其使用方式记录在 FileOperationModal.README.md 中。模态框以 useFileOperationDialog() 为编程式入口,支持 copy / move 两种操作:

import { useFileOperationDialog } from '@sd/interface';

function MyComponent() {
  const openFileOperation = useFileOperationDialog();

  const handleCopyFiles = () => {
    openFileOperation({
      operation: "copy",
      sources: [
        { Physical: { device_slug: "", path: "/source/file1.txt" } },
        { Physical: { device_slug: "", path: "/source/file2.txt" } },
      ],
      destination: { Physical: { device_slug: "", path: "/destination/" } },
      onComplete: () => {
        console.log("Operation completed!");
      },
    });
  };

  return <button onClick={handleCopyFiles}>Copy Files</button>;
}

注意 sources / destination 使用 SdPath 结构(如 Physical { device_slug, path }),与后端 core/src/ops/files/copy 中的 SdPathBatch / SdPath 一一对应,这保证了跨设备(Remote)、内容寻址(Content)、云存储(Cloud)等各类路径都能被后端统一处理。

拖拽体系由三个组件协作:

  • File 基础组件默认可拖拽(draggable 默认开启,可显式关闭);
  • DropZoneFile 用于文件夹作为放置目标,仅接受文件夹类型,拖入时显示高亮边框;
  • DropZoneSidebarItem 用于侧边栏位置(Location)作为放置目标,接受任意文件拖入。

拖拽行为约定如下:默认操作为复制;按住 Alt/Option 拖拽切换为移动;拖拽单个文件时只拖动该文件;若拖动的文件处于多选状态,则一次拖动全部选中文件。

3.3 后端实现:策略模式(Strategy Pattern)的任务

后端复制/移动任务统一由 FileCopyJob 实现(定义在 core/src/ops/files/copy/job.rs),任务名为 file_copy,声明为可恢复(RESUMABLE = true)。模块边界见 core/src/ops/files/copy/mod.rs:action、database、input、job、metadata、output、routing、strategy 各司其职。

MoveMode(移动语义):任务规格要求复制与移动共用一套 UI,后端通过 MoveMode 枚举区分语义上下文:

pub enum MoveMode {
	Move,   // 标准移动
	Rename, // 重命名单个文件/目录
	Cut,    // 剪切粘贴(与 Move 等价,但 UX 语境不同)
}

CopyOptions(操作选项):决定一次复制行为的全部可调参数,默认值如下:

字段 类型 默认值 说明
overwrite bool false 是否覆盖已存在的目标文件
verify_checksum bool false 复制后是否校验校验和
preserve_timestamps bool true 是否保留时间戳
delete_after_copy bool false 复制后删除源(即"移动")
move_mode Option<MoveMode> None 移动语义标注(供 UI 展示)
copy_method CopyMethod Auto 复制方法(自动选择)
conflict_resolution Option<FileConflictResolution> None 冲突解决策略

其中 conflict_resolution 支持四种策略:Skip(跳过已存在文件)、AutoModifyName(自动生成唯一名称,如追加计数器)、Overwrite(覆盖)、Abort(中止整个操作)。这些策略与前端模态框"Requires Confirmation"阶段的冲突解决选项一一对应。

多阶段执行流程:FileCopyJob::run 按阶段推进并持续推送进度事件:

  1. Initializing:初始化,记录源文件数量;
  2. DatabaseQuery:通过 CopyDatabaseQuery 查询库内估计值,获得即时大小/数量预估(含置信度 confidence()),若数据库查询失败则回退到文件系统计算;
  3. Preparation:实际统计文件数与总字节数,收集文件元数据并持久化任务状态(persist_job_state_to_db),UI 可实时查询每个文件的复制状态(进行中/完成/失败/跳过);
  4. Copying:按源路径逐个处理,通过 CopyStrategyRouter 依据源/目标拓扑选择具体策略并执行;
  5. Complete:汇总结果并输出 FileCopyOutput(含 copied_count、failed_count、total_bytes、failed_copies 明细)。

路径解析的容错细节:当目标路径已存在且是文件时(用户误把文件拖到文件上),任务会回退使用其父目录;多源复制时一律将源文件名 join 到目标目录;远端目标(非本地)因无法探测目录属性,也统一 join 文件名。这些细节保障了"拖到文件上"这类常见误操作的健壮性。

移动的原子性处理:is_move 由 options.delete_after_copy 决定。同卷移动由 LocalMoveStrategy 原子完成(复制+删除一体);跨卷移动由 LocalStreamCopyStrategy 完成复制后,任务手动删除源文件,若删除失败则记录为 CopyError 并通过 add_non_critical_error 上报,避免整个任务失败。

四、删除:确认对话框 + 后端安全校验

4.1 任务规格的删除要求

删除属于破坏性操作,规格明确要求"带确认对话框",同时在验收标准中强调"安全操作的 Undo"。前端实现即上文展示的 useDeleteFiles:单文件/多文件分别生成不同的确认文案,永久删除会追加 "This cannot be undone." 警示。

4.2 后端 DeleteJob 的三级删除模式

后端删除任务 DeleteJob(见 core/src/ops/files/delete/job.rs)通过 DeleteMode 区分三种删除强度:

pub enum DeleteMode {
	Trash,     // 移入回收站(可恢复,是 Undo 的基础)
	Permanent, // 永久删除(不可撤销)
	Secure,    // 安全删除(覆写数据)
}

DeleteOptions 提供 permanent 与 recursive 两个布尔选项。任务执行的关键安全约束:

// Safety check for permanent deletion
if matches!(self.mode, DeleteMode::Permanent | DeleteMode::Secure)
	&& !self.confirm_permanent
{
	return Err(JobError::execution(
		"Permanent deletion requires explicit confirmation",
	));
}

也就是说,永久删除和安全删除必须携带显式确认标记 confirm_permanent,否则任务直接拒绝执行——这是后端层面的强制确认,与前端 confirm() 对话框形成双重保障,防止绕过 UI 直接调用接口造成误删。任务在真正删除前还会:校验目标存在(validate_targets)、将 Content 路径解析为 Physical 路径、再由 DeleteStrategyRouter 按路径拓扑选择 LocalDeleteStrategy 或 RemoteDeleteStrategy(模块导出见 core/src/ops/files/delete/mod.rs)。

关于 Undo:当前实现下,Trash(移入回收站)模式天然具备可恢复性,是实现"安全操作 Undo"的物理基础;规格中的 Undo 验收项需要在此基础上由 UI 层补充"撤销删除"入口。

五、重命名:内联编辑 + 文件名校验

5.1 验收要求与前端形态

验收标准要求重命名采用"内联编辑"(inline editing)方式——即在文件名/缩略图上直接进入编辑态,而非弹出独立对话框。右键菜单中的 Rename 入口同样来自 useFileContextMenu。

5.2 后端 FileRenameAction 的校验规则

重命名后端由 FileRenameAction 实现(见 core/src/ops/files/rename/action.rs),输入为 { target: SdPath, new_name: String }。其 validate 阶段执行两条校验:

  1. 文件名合法性:调用 validate_filename(&self.new_name)(定义在 core/src/ops/files/rename/validation.rs),失败时返回带字段名的 ActionError::Validation,前端可据此定位到 new_name 字段并给出内联错误提示;
  2. 路径类型限制:Content(内容寻址)与 Sidecar(侧车元数据)路径禁止直接重命名,因为这类路径由内容哈希或元数据体系管理,直接改名会破坏寻址结构。

值得注意的是,重命名最终通过 FileCopyJob(MoveMode::Rename)执行——即"同卷内以新文件名再复制一次并删除源"的移动语义,这与第 3 节的复制/移动任务共用同一套进度与恢复基础设施。

六、新建文件夹:CreateFolderAction

新建文件夹对应 CreateFolderAction(见 core/src/ops/files/create_folder/action.rs),其数据结构:

pub struct CreateFolderAction {
	pub parent: SdPath,      // 父目录
	pub name: String,        // 新文件夹名称
	pub items: Vec<SdPath>,  // 创建后可选移动进新文件夹的条目
}

with_items 构造器允许"新建文件夹并同时把选中文件移入其中"的组合操作——这正是 UI 层"新建文件夹"菜单在存在选中项时的常见行为。文件夹名称同样复用 validate_filename 做合法性校验,保证命名规则与重命名一致。CreateFolderAction 的输出为 CreateFolderOutput,属于轻量操作,不依赖长任务。

七、进度反馈:订阅任务进度事件

任务规格的第三、七条要求"订阅任务进度事件"与"长任务进度指示"。Spacedrive 的进度链路设计如下:

7.1 后端:CopyProgress 实时指标

FileCopyJob 在执行期间通过 ctx.progress(Progress::generic(...)) 持续推送 CopyProgress(定义于 core/src/ops/files/copy/job.rs),其字段覆盖:

  • phase:当前阶段(CopyPhase:Initializing / DatabaseQuery / Preparation / Copying / Complete);
  • current_file / current_source_path:正在处理的文件;
  • files_copied / total_files、bytes_copied / total_bytes:文件与字节双维度进度;
  • transfer_rate:实时传输速率(字节/秒);
  • estimated_remaining:预估剩余时间(ETA);
  • elapsed:已耗时;
  • error_count:累计失败数;
  • strategy_metadata:当前所选复制策略元数据,供 UI 展示"本地流式复制 / 跨设备传输"等操作说明。

7.2 底层:SpeedTracker 与 ProgressAggregator

速率与 ETA 的稳定计算由 SpeedTracker 完成:它采用指数移动平均(EMA,平滑因子 alpha = 0.3)对瞬时速率进行平滑,更新节流到至少 50ms 一次,calculate_eta 在平均速率低于 1 B/s 时返回 None 以避免除零。ProgressAggregator 则负责聚合多文件进度:回调以 (bytes_value, signal_value) 传递信号,signal_value == u64::MAX 表示某个文件已完成(bytes_value 为该文件大小),其余情况表示字节级进度,从而让进度条既能在文件粒度跳进、又能在大文件内部平滑推进。任务还支持断点恢复:completed_indices 记录已完成索引,恢复时通过 skip_completed_file 将已完成部分计入进度;此外每处理 20 个文件执行一次 ctx.checkpoint() 持久化任务状态。

7.3 前端:进度 Toast 与模态框 Executing 阶段

前端侧,FileOperationModal 的 DialogPhase 状态机包含 validating → confirmation → ready → executing → completed → error 六个阶段,其中 Executing 阶段即渲染进度条与当前操作描述;任务规格提到的"进度 Toast"可由 useJobManager(useJobManager.ts)结合 useJobDispatch(useJobDispatch.ts)监听任务事件后弹出。CopyProgress.to_generic_progress 会把上述字段映射为统一的 GenericProgress(含百分比、字节、性能指标、错误数、当前路径、策略元数据),保证所有任务类型共享同一套进度渲染组件。

八、错误处理与多阶段冲突解决

任务规格要求"优雅处理错误并提供用户反馈"。File Operation Modal 的六阶段状态机中专门设计了 Error 阶段:显示错误消息并提供关闭选项。错误来源包括:

  • mutation 层:如 useDeleteFiles 中 mutateAsync 抛出的异常,以 alert 提示;
  • 校验层:如重命名时 validate_filename 失败返回的 ActionError::Validation,可在表单字段旁内联展示;
  • 任务层:FileCopyJob 对单个文件失败通过 CopyError { source, destination, error } 收集到 failed_copies 列表,同时以 add_non_critical_error 上报"非致命错误",不影响其余文件继续复制。

冲突解决流程(模态框的 Validating → Requires Confirmation 阶段):

  1. 模态框打开 → 显示 Validating 状态(spinner);
  2. 核心返回 ValidationResult;
  3. 若存在目标文件冲突 → 展示冲突解决选项:覆盖(Overwrite)/ 保留两者(Keep both,自动重命名)/ 跳过(Skip);
  4. 用户选择 → 调用 resolve_confirmation(choice_index) 把选择映射为后端 FileConflictResolution;
  5. 执行 → 按已解决的冲突运行任务。

需要说明的实现现状(依据 FileOperationModal.README.md 的 Notes):当前模态框的验证以超时模拟、冲突检测以 50% 概率随机模拟,待守护进程(daemon)的 validate 端点协议就绪后,将替换为真实校验;进度跟踪也将进一步与任务系统事件打通。该文档还规划了 Simulation(Phase 2)能力:执行前展示文件/文件夹数量、总大小与传输字节、去重节省、空间可用性、跨设备网络传输预估、时间估算,模态框架构已为平滑接入模拟数据预留了阶段位。

九、实现状态与验收标准对照

对照 EXPL-003 的九项验收标准,结合仓库现状梳理如下:

验收项 规格要求 仓库现状(依据)
复制 右键菜单或 Cmd+C 右键菜单入口 useFileContextMenu.ts;后端 core/src/ops/files/copy
移动 拖拽 File 组件默认可拖拽,Alt/Option 切换移动;DropZoneFile / DropZoneSidebarItem 接收
删除确认 确认对话框 useDeleteFiles 的 confirm() + 后端 confirm_permanent 强制校验
内联重命名 inline editing 输入为 { target, new_name } 的 FileRenameAction,校验器 rename/validation.rs
复制副本(Duplicate) 复制副本 规格验收项(UI 层实现依赖上下文菜单与复制任务的组合)
新建文件夹 新建文件夹 CreateFolderAction,支持 items 组合移入
长任务进度 进度指示 CopyProgress + SpeedTracker + ProgressAggregator,多阶段事件推送
错误提示 友好消息 模态框 Error 阶段 + CopyError 明细 + 非致命错误上报
安全操作 Undo Undo DeleteMode::Trash 提供可恢复删除基础;UI 撤销入口为后续工作

任务元数据状态标记为 To Do(归属 EXPL-000,优先级 High),说明文件操作 UI 仍处于持续迭代中;但核心动作的后端能力与前端骨架已在仓库中成形,上述表格可作为继续完善时的对照清单。

十、快速上手指南

如果你希望在自己的代码中接入这些文件操作能力,最小实践路径如下:

  1. 程序化发起复制/移动:在任意组件中调用 useFileOperationDialog(),传入 operation("copy" | "move")、sources、destination,模态框会自动完成校验、冲突解决、执行与进度展示;
  2. 接入拖拽:文件展示使用 File 组件(默认可拖拽),目标文件夹包裹 DropZoneFile,侧边栏位置使用 DropZoneSidebarItem,在 onFilesDropped 回调中调用 openFileOperation;
  3. 删除:复用 useDeleteFiles.ts 的 deleteFiles(files, permanent),它会处理确认、mutation 与错误提示;
  4. 监听进度:通过 useJobManager / useJobDispatch 订阅任务事件,解析 CopyProgress 中的 phase、transfer_rate、estimated_remaining 渲染进度条与 Toast;
  5. 理解后端契约:所有路径参数使用 SdPath(Physical / Content / Sidecar 等变体),后端 FileCopyJob / DeleteJob 会自动解析、路由并支持断点恢复,前端无需关心设备拓扑差异。

综上,Spacedrive 文件操作 UI 是一套"统一 mutation 入口 + 策略模式任务 + 多阶段进度事件 + 显式安全确认"的完整方案:UI 层的每个交互点(右键菜单、快捷键、拖拽、内联编辑)都最终收敛到 useLibraryMutation 对核心动作的调用,而核心层以可恢复的 Job 承载复制、移动、删除,并把实时速率、ETA、冲突信息等结构化地推送给界面。理解这条链路,既能帮助你正确接入与扩展文件操作,也是深入 Spacedrive 任务系统(core/src/infra/job)与路径寻址体系(core/src/domain/addressing.rs)的最佳入口。

登录后查看全文
spacedrive