Spacedrive 文件操作 UI 实现指南:复制、移动、删除、重命名与进度反馈
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 按阶段推进并持续推送进度事件:
- Initializing:初始化,记录源文件数量;
- DatabaseQuery:通过
CopyDatabaseQuery查询库内估计值,获得即时大小/数量预估(含置信度confidence()),若数据库查询失败则回退到文件系统计算; - Preparation:实际统计文件数与总字节数,收集文件元数据并持久化任务状态(
persist_job_state_to_db),UI 可实时查询每个文件的复制状态(进行中/完成/失败/跳过); - Copying:按源路径逐个处理,通过
CopyStrategyRouter依据源/目标拓扑选择具体策略并执行; - 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 阶段执行两条校验:
- 文件名合法性:调用
validate_filename(&self.new_name)(定义在 core/src/ops/files/rename/validation.rs),失败时返回带字段名的ActionError::Validation,前端可据此定位到new_name字段并给出内联错误提示; - 路径类型限制:
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 阶段):
- 模态框打开 → 显示 Validating 状态(spinner);
- 核心返回
ValidationResult; - 若存在目标文件冲突 → 展示冲突解决选项:覆盖(Overwrite)/ 保留两者(Keep both,自动重命名)/ 跳过(Skip);
- 用户选择 → 调用
resolve_confirmation(choice_index)把选择映射为后端FileConflictResolution; - 执行 → 按已解决的冲突运行任务。
需要说明的实现现状(依据 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 仍处于持续迭代中;但核心动作的后端能力与前端骨架已在仓库中成形,上述表格可作为继续完善时的对照清单。
十、快速上手指南
如果你希望在自己的代码中接入这些文件操作能力,最小实践路径如下:
- 程序化发起复制/移动:在任意组件中调用
useFileOperationDialog(),传入operation("copy" | "move")、sources、destination,模态框会自动完成校验、冲突解决、执行与进度展示; - 接入拖拽:文件展示使用
File组件(默认可拖拽),目标文件夹包裹DropZoneFile,侧边栏位置使用DropZoneSidebarItem,在onFilesDropped回调中调用openFileOperation; - 删除:复用 useDeleteFiles.ts 的
deleteFiles(files, permanent),它会处理确认、mutation 与错误提示; - 监听进度:通过
useJobManager/useJobDispatch订阅任务事件,解析CopyProgress中的phase、transfer_rate、estimated_remaining渲染进度条与 Toast; - 理解后端契约:所有路径参数使用
SdPath(Physical/Content/Sidecar等变体),后端FileCopyJob/DeleteJob会自动解析、路由并支持断点恢复,前端无需关心设备拓扑差异。
综上,Spacedrive 文件操作 UI 是一套"统一 mutation 入口 + 策略模式任务 + 多阶段进度事件 + 显式安全确认"的完整方案:UI 层的每个交互点(右键菜单、快捷键、拖拽、内联编辑)都最终收敛到 useLibraryMutation 对核心动作的调用,而核心层以可恢复的 Job 承载复制、移动、删除,并把实时速率、ETA、冲突信息等结构化地推送给界面。理解这条链路,既能帮助你正确接入与扩展文件操作,也是深入 Spacedrive 任务系统(core/src/infra/job)与路径寻址体系(core/src/domain/addressing.rs)的最佳入口。