Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
207 lines (158 loc) · 21.1 KB

DEVELOPMENT.md

File metadata and controls

207 lines (158 loc) · 21.1 KB
Raw

FastFile 开发与功能参考

用 DuiLib + 原生 C++ / Win32 写的文件管理器。观感贴近 Windows 11 资源管理器，布局密度参考 360 文件；所有图标资源来自 Windows Shell 或自绘。

免责声明：本仓库为原创实现。不引用 360 二进制或其代码；2026-10-04 在用户授权下只读检查本机既有 360 文件夹组件的进程、服务、文件元数据和 PE 导入表，未安装其软件、未复制其实现，不使用其图标、商标或皮肤资源；仅在 third_party/duilib 中嵌入了开源 DuiLib 的库本体（BSD 风格许可，见该目录下 LICENSE）。

项目开发规则见 AGENTS.md；详细架构、交接和验收记录见 HANDOFF.md；按版本的已完成改动见 CHANGELOG.md。

当前源码候选版本：1.0.14（独立后台代理与界面退出）；公开下载仍为 1.0.12 预发布版。仓库根目录的 VERSION 是版本号唯一来源；CMake 和安装脚本都会读取它。

设置 → 系统集成新增“检测接管状态”和“修复并应用接管”，区分已勾选的偏好与实际生效的入口，并显示当前程序路径、Windows 资源管理器、其他文件管理程序或另一处 FastFile。可单独启用“自动转交新打开的资源管理器文件夹”：独立 FastFileAgent 进程在当前用户会话检测新窗口，界面关闭后退出，代理按需启动界面，确认实际目录与选中文件已到达 FastFile 后再关闭原窗口。已有窗口、其他管理器、多标签窗口、虚拟目录、正在操作的窗口、选中文件超过 256 项以及验证失败的窗口会保留；资源管理器可能短暂出现，此模式并非拦截进程启动。架构依据见 360 交互分析。完整验证结果和未验收部分见 HANDOFF.md。

安装（推荐）

dist\FastFile-Setup-<版本>.exe 双击即可：当前用户安装、免管理员，装到 %LOCALAPPDATA%\Programs\FastFile，创建开始菜单快捷方式，并在「设置 → 应用」里登记卸载项。 卸载不会删除 %APPDATA%\FastFile 里的个人设置。

安装程序不需要任何第三方打包工具，用仓库里的脚本即可重新生成：

powershell -ExecutionPolicy Bypass -File installer\build_installer.ps1 -BuildDirectory build-ui\Release

源码直接运行也可以：构建后启动 build\Release\FastFile.exe。

设置（源码构建版本）

点击命令栏最右侧的齿轮打开设置，修改后点击「保存」，「取消」放弃本次修改。

标签栏不播放滑入或自动横向移动动画；新增、关闭、切换和重排直接显示最终布局。标签超出可用宽度时仍可用滚轮滚动，选中标签会进入视野，+ 继续位于末标签右侧。

原生列表和详细信息视图统一采用 26 逻辑像素的非紧凑行高，进入文件夹时在视图显示前应用，避免先窄后宽。文件夹和磁盘的右键菜单提供「在新选项卡中打开」；该显式命令保留原标签并强制创建 FastFile 新标签，即使开启同目录标签复用也一样。其他原生菜单操作继续由 Windows Shell 提供。

  • 常规与标签：启动位置、外部路径新标签 / 新窗口、同目录标签复用、多标签关闭确认。
  • 外观：紧凑 / 标准 / 宽松布局、导航字号、标签栏及收藏栏高度、标签宽度比例、导航滚动条宽度。尺寸为 96 DPI 逻辑像素，运行时随窗口 DPI 缩放。
  • 浏览：默认视图、每文件夹视图记忆、默认排序和方向、分组方式。
  • 系统集成：目录及磁盘默认打开、桌面此电脑、右键入口和可选的新资源管理器窗口转交；可检测实际接管状态，并通过「修复并应用接管」重新应用当前选择。「恢复 Windows 打开方式」只暂存关闭选择，点击「保存」后执行。

偏好保存在 %APPDATA%\FastFile\settings.ini；系统集成状态和原值备份保存在当前用户注册表。卸载前会恢复本程序添加的默认入口，个人设置保留。2026-10-02 重新生成的 1.0.9 安装包已包含设置功能。

测试

系统右键启动专项执行实际注册的「使用 FastFile 打开」命令，并使用同一生产启动入口的独立测试进程，验证目录、磁盘、子目录转发至已有窗口，以及没有已有窗口时打开指定目录。历史「停用默认接管」标记不再拦截明确的 FastFile 请求。主窗口回归在隔离桌面运行，启动专项还隔离注册表和配置，不改用户真实的系统接管设置。

配置时默认会启用 CTest。构建后运行：

ctest --test-dir build-ui -C Release --output-on-failure

目前共有 13 项自动测试，覆盖路径 / 文件名工具、文件大小格式、版本号来源一致性、收藏 JSON 和星按钮多 DPI 绘制，以及 Shell 浏览器导航、视图表头、排序、刷新和选择通知。系统集成专项覆盖实际关联检测和窗口转交；真实 Explorer 转交专项验证新窗口目录打开与文件定位。Shell 窗口专项通过真实跨进程 SHOpenFolderAndSelectItems 验证窗口发现及文件选中；构建一致性专项检查 CMake 与 Visual Studio 工程的生产源码和资源登记。主窗口回归还覆盖目录详情计数、选中对象绑定、嵌套树可见性、快捷单处高亮、命令状态、标签宽度及本地化标题。UI 精致度专项覆盖 96 / 144 / 192 DPI 固定缩略图槽、整格选中、圆角预览、尾部路径、命令图标透明度和首次启动快捷行；Shell 测试在真实窗口 DPI 下验证格距，防止兼容列表二次缩放。文件操作专项检查复制 / 移动 / 回收 / 永久删除及拖放均经 IFileOperation，生产标志保留原生进度、冲突与错误界面（不含 FOF_SILENT / FOF_NOERRORUI / FOFX_NOMINIMIZEBOX），并在临时目录用仅供测试的无界面模式验证引擎结果、取消和 SHFileOperation 回退；还检查 FastFile 与资源管理器撤销记录的顺序一致。菜单专项检查分隔线规范化，以及背景菜单取自真实 Shell 视图并含原生粘贴 / 分组依据 / 属性。主窗口回归依赖可访问的 Windows 剪贴板和 explorer.exe 会话撤销服务；系统服务不可用时应定位环境原因，不能跳过断言后宣称交付通过。点击、快捷键和上下文菜单仍需结合真实界面进行运行回归。每次更新的交付要求见 AGENTS.md。

功能现状

浏览与导航

  • 多标签页（新建/关闭/路径记忆）、前进后退、上级、刷新；新建标签会优先打开选中的 文件夹，或选中文件所在的目录；默认所有打开入口（含「+」、Ctrl+T、收藏及外部双击）均复用同目录已有标签，设置中可关闭复用。 新打开当前目录的下级目录时沿用当前标签，连续进入多层目录不会增加标签，后退可返回上一级
  • 地址栏与面包屑合一：默认面包屑，点击进入编辑，Enter 导航，Esc/失焦回到面包屑
  • 默认启动进入「此电脑」，设置中可选择恢复上次标签或指定文件夹；预览开关 / 收藏栏 / 列宽等设置照旧恢复
  • 每文件夹独立视图记忆（同一目录下次打开仍是上次的视图）
  • 左侧：快速访问 + 目录树；快速访问与树之间的高度、左栏宽度、预览窗格宽度都可拖拽 （鼠标靠近分隔线变成左右/上下箭头），位置持久化

列表与视图

  • 六种视图：超大图标 / 大图标 / 中等图标 / 列表 / 详细信息 / 平铺
  • 普通目录由 Windows ExplorerBrowser / Shell 视图承载，复用系统文件区的项目选择、单击后再次单击重命名、F2、原生项目右键菜单和系统文件类型行为；FastFile 保留自己的窗口、标签、地址栏、目录树和预览区域
  • 视图模式与排序交给 Shell 视图；普通搜索和递归搜索使用 FastFile 的结果列表，清空搜索后恢复 Shell 目录视图
  • 搜索结果沿用 FastFile 的图标、平铺、列表和详细信息布局；普通目录项目排列、列和缩略图由 Windows Shell 提供
  • 搜索：即时过滤 + 「含子目录」递归搜索
  • 键盘导航：普通目录使用 Shell 视图的系统键盘交互；递归搜索结果保留 FastFile 的方向键、Home / End、PageUp / PageDown、Enter / 空格及多选导航

文件操作

  • 复制 / 剪切 / 粘贴与 Windows 文件剪贴板互通（可跨资源管理器）
  • 复制、移动（剪切 + 粘贴）、拖放复制 / 移动、删除到回收站和永久删除统一通过 Windows IFileOperation 执行，进度显示为 Windows 资源管理器原生进度窗口（暂停 / 取消 / 剩余时间、替换或跳过冲突对话框、管理员权限提示均由系统提供）；短操作系统可能不弹进度窗口。操作在独立后台线程运行，FastFile 窗口保持可用，多项操作可同时进行。状态栏不再显示进度文字，只在完成后显示结果摘要。操作进行中关闭窗口会先询问是否取消剩余操作
  • 普通删除直接进入回收站；永久删除（Shift+Delete）带确认。删除通过 Windows Shell IFileOperation 执行，管理员权限、占用及失败提示由 Windows 提供，无法回收时显示系统警告。支持重命名、新建文件夹。
  • 拖放：拖到文件夹移动、拖到收藏栏固定、支持从资源管理器拖入；拖入 Shell 文件区本身由 Windows 处理，同样显示原生进度
  • 撤销 / 重做（Ctrl+Z / Ctrl+Y）：当前会话中的复制、移动（整批还原）、新建文件夹、重命名及删除到回收站；「更多」菜单提供两项命令。永久删除不可撤销。
  • 复制 / 移动只记入 FastFile 的撤销历史（不写入资源管理器撤销记录，因为资源管理器的「撤销复制」会直接永久删除副本）；删除到回收站同时写入资源管理器撤销记录，Ctrl+Z 通过它还原。两者顺序保持一致。替换或合并到已有同名项目的结果不记入撤销，避免误删原有内容
  • 撤销复制会在目标目录旁暂存副本供重做，重做后移回；退出程序或新操作清除重做历史时清理暂存。重做不覆盖新出现的同名项目，撤销新建目录不会删除后来加入的内容。

系统集成

  • FastFile 内部双击磁盘 / 文件夹或按 Enter 会在程序内导航，不依赖系统集成开关；该开关控制其他入口调用系统默认目录打开命令时的行为。
  • 设置中的系统集成默认关闭，可分别启用右键「使用 FastFile 打开」、文件夹和磁盘默认打开、桌面「此电脑」打开。只修改当前用户的文件夹入口，保存原值以便关闭时恢复；后来由其他程序设置的默认项不会被覆盖。图片、视频及其他文件的默认程序继续由 Windows 管理。
  • 调用系统文件夹默认操作，以及明确指定 open、explore、opennewwindow 的普通目录和磁盘请求可使用上述入口。标准动作的原有用户配置会完整备份，关闭接管时恢复；不修改通用 Folder 虚拟对象的动作。直接启动 explorer.exe 的应用、系统文件选择对话框和其他 Shell 虚拟对象不保证被接管。
  • “自动转交”默认关闭，需保持 FastFile 运行；开启后只处理新出现的 Windows 资源管理器物理文件夹窗口，不结束 explorer.exe 进程。慢磁盘或导航失败时保留原窗口，其他管理器的默认关联可检测和重新应用，但不关闭其独立窗口。
  • 普通目录的文件区由 Windows ExplorerBrowser / Shell 视图承载，因此文件项目与背景使用系统原生右键菜单；目录树、快速访问和磁盘入口仍通过 IShellFolder / IContextMenu(2/3) 显示系统菜单
  • 普通目录中的右键菜单由 Shell 视图提供；命令栏和 F2 调用 Shell 原生重命名。递归搜索结果仍使用 FastFile 的重命名输入框和应用内撤销记录
  • 文件区空白处右键直接使用当前 Shell 视图的原生背景菜单（IShellView::GetItemObject(SVGIO_BACKGROUND)），与资源管理器一致地包含 粘贴、粘贴快捷方式、撤销 / 重做、分组依据、自定义文件夹等系统项（以 Windows 实际提供为准；按住 Shift 右键显示扩展项）。其中 查看 / 排序方式 换成 FastFile 的同名子菜单以驱动 FastFile 视图状态；粘贴、刷新、撤销 / 重做由 FastFile 执行以保持历史一致，其他项交给 Windows。未显示 Shell 视图的位置（此电脑快速行、搜索结果）使用文件夹自身菜单并补上 查看 / 排序方式 / 刷新
  • 所有 FastFile 显示的 Shell 菜单（背景、项目、目录树）在显示前规范分隔线：去掉开头、结尾和连续重复的分隔线（Shell 用 0、-1、0x7FFD 等不同 id 标记分隔线，不能按 id 判断）
  • 会隐藏 Windows 自己也不会显示的项：旧版「在此处打开 PowerShell 窗口」、第三方 「用 <应用> 打开」、以及子菜单为空的项（如 Win11 文件夹背景上的「授予访问权限」）
  • 「属性」直接作用于选中路径（磁盘就是磁盘属性页）；多选时用系统多项属性页
  • 默认重复启动激活已有窗口；设置可让外部路径在新窗口打开。关闭最后一个标签或窗口即退出进程
  • 崩溃自诊断：异常码 + 模块内偏移 + 调用栈写入 %LOCALAPPDATA%\FastFile\last_crash.txt， 配合 build\Release\FastFile.map 可直接反查函数

外观

  • 应用图标：res\FastFile.ico（多尺寸 16–256）→ exe 图标 + 标题栏 / 任务栏 / Alt+Tab + 安装程序
  • Per-Monitor DPI v2；设计令牌集中在 src/UiTokens.h（间距 4/8/12/16、字号、颜色、圆角）
  • Win11 浅色 chrome，命令栏 / 地址栏按资源管理器 150% 实测尺寸：命令栏 48（按钮 32、图标间距 48、1×32 浅色分隔线），Segoe Fluent 双色图标（灰 #555555 + 强调蓝 #0078D4，不可用 36%）；地址栏 48，地址 / 搜索框 32 高、圆角 4、无边框，搜索框宽度为行宽 30%（240–435）；容器 8 / 控件 4 圆角
  • 收藏栏：左侧星按钮可收藏 / 取消当前目录，已收藏时显示实心星；芯片按文件名实测宽度排布，可在「查看」菜单折叠
  • 滚动条：静止时为 4 逻辑像素细轨，靠近文件区、目录树或预览导轨时悬停加宽至 8 逻辑像素，并显示圆角轨道；悬浮绘制不挤占内容布局

快捷键

键 作用
Ctrl+C / X / V 复制 / 剪切 / 粘贴
Ctrl+Z / Ctrl+Y（或 Ctrl+Shift+Z） 撤销 / 重做当前会话文件操作
Ctrl+Insert / Shift+Insert 复制 / 粘贴文件（文本框内保留文字操作）
Ctrl+Shift+C 复制所选项目的完整路径
Ctrl+A 全选当前文件区
Ctrl+Shift+N 新建文件夹
Ctrl+T / Ctrl+W 新建标签 / 关闭当前标签
Ctrl+N 在当前目录打开新窗口
Ctrl+1…8 / Ctrl+9 第 N 个标签 / 最后一个标签（沿用目录去重规则）
Ctrl+F4 / Ctrl+Tab / Ctrl+Shift+Tab 关闭当前标签 / 下一个标签 / 上一个标签
Ctrl+F / Ctrl+E / F3 聚焦搜索框
Alt+D / Ctrl+L / F4 聚焦地址栏 / 显示地址历史下拉列表
F6 / Shift+F6 循环 / 反向循环地址、搜索、文件区和导航树焦点
Ctrl+Shift+E 展开当前路径并聚焦导航树
Alt+← / → / ↑、Backspace 后退 / 前进 / 上级 / 后退
F2 / F5 或 Ctrl+R 重命名 / 刷新
Delete 或 Ctrl+D / Shift+Delete 删除到回收站 / 永久删除
Ctrl+Shift+1…8 超大、大、中、小图标、列表、详细信息、平铺、内容
Alt+P / Alt+Shift+P 显示 / 隐藏右侧预览与详情窗格
F11 最大化 / 还原窗口
Alt+Enter 显示属性
Shift+F10 / 菜单键 显示当前对象的上下文菜单
导航树 ← / →、小键盘 − / + 折叠 / 展开，已折叠或展开时进入父节点 / 首个子节点
Esc 退出地址编辑 / 取消选择
↑ / ↓ / ← / → 文件区导航（按视图布局移动）
Home / End、PageUp / PageDown 跳到首尾 / 翻页
Shift / Ctrl + 方向键 连选 / 在现有选择上增减选择
Enter / Space 打开光标所在项目

构建

工具链：CMake ≥ 3.16 + Visual Studio 2022（x64），Release 配置。

cmake -S . -B build-ui -G "Visual Studio 17 2022" -A x64 -DBUILD_TESTING=ON
if ($LASTEXITCODE -ne 0) { throw "配置失败" }
cmake --build build-ui --config Release
if ($LASTEXITCODE -ne 0) { throw "构建失败" }
ctest --test-dir build-ui -C Release --output-on-failure
if ($LASTEXITCODE -ne 0) { throw "回归失败" }

候选产物在 build-ui\Release\FastFile.exe；构建后会自动把 skin\ 拷到 exe 旁（运行时按 <exe>\skin\main.xml 找皮肤）。通过完整回归和适用运行验证后，才将 exe / map / skin 更新到常用 build\Release，并核对 exe 哈希；运行中的旧窗口需退出后重新启动。也可以直接打开根目录的 FastFile.sln（VS 回退工程）。build/、build-ui/ 和 dist/ 是本地产物目录，克隆仓库后需自行构建并打包。

改完皮肤或代码后的验收流程、以及必须清图标缓存的场景，见 HANDOFF.md。

目录结构

FastFile/
  CMakeLists.txt          # 主构建（静态链接 DuiLib）
  FastFile.sln            # VS 回退解决方案
  skin/main.xml           # 主窗口皮肤（设计尺寸为 96 DPI 基准，运行时按 DPI 缩放）
  src/
    main.cpp              # WinMain、DPI 感知、单实例
    MainWnd.h             # CMainWnd 声明 + UiTokens 引用
    MainWndInternal.h     # 各编译单元共用的 include 前导与共享辅助函数
    MainWnd*.cpp          # 按职责拆分的主窗口编译单元（含系统集成）
    ShellBrowserHost.*    # 承载 Windows ExplorerBrowser 原生文件视图
    TabStripUI.*          # 自绘标签栏
    FluentScrollBarUI.*   # Fluent 悬停滚动条
    UiTokens.h            # 设计令牌（间距、字号、颜色、圆角）
  res/                    # 应用图标（FastFile.ico + 资源脚本 FastFile.rc）
  installer/              # 自包含安装程序（setup.cs + build_installer.ps1）
  third_party/duilib/     # 嵌入的 DuiLib 源码（仅库本体与许可）
  vs/                     # 手写 vcxproj（无 CMake 时可用）
  scripts/                # 工具脚本
  cmake/                  # manifest 等构建辅助文件

配置与数据

运行时数据在 %APPDATA%\FastFile\：session.ini（标签/视图/排序等会话状态）、folder_views.ini（每文件夹视图）、favorites.json（按顺序保存路径，首次兼容导入旧 favorites.txt）、left_nav.ini（左栏分割位置）。图标缓存位于 %TEMP%\FastFileIconCache\v9，跨启动保留（文件名含源文件大小与修改时间；启动后在后台清理旧版本目录、上次会话的临时预览、30 天以上及超过 256 MB 的旧条目），异常时可删除后重启。环境变量 FASTFILE_ICON_CACHE_DIR 可改放缓存根目录（回归测试用它隔离缓存）。

1.0.13 导航诊断日志为 %APPDATA%\FastFile\navigation.log，可用 FASTFILE_NAV_LOG 指定其他文件。记录请求、排队、Shell 忙重试、完成、失败、超时、刷新和列表状态变化；target 是最新目标，pending 是在途目标，actual 来自实际 Shell 视图，count / listCount 分别是 Shell / Win32 列表项目数。日志超过 2 MB 后在下一次写入时重置；分享前可遮去私人目录路径。SyncLayoutDependents 的 200 ms 定时调用负责派发队列，不能删除 PollNavigation；不要在 Shell 完成回调里重入 BrowseToObject。导航等待上限为 15 秒，超时会提示失败并允许刷新，慢网络目录可能需要重试。

已知限制

  • 普通目录使用 Windows Shell 视图，性能和项目上限取决于 Shell 与对应文件系统；FastFile 自绘的递归搜索结果仍有 4000 项上限，图标缩略图上限 400 张。普通目录大 / 超大图标的缩略图在后台线程加载（未就绪时先显示类型图标），内存缓存约 96 MB / 2000 张，按最近最少使用淘汰，切换视图、刷新和返回文件夹时复用。
  • 视频 / 图片大缩略图的清晰度上限由 Windows Shell 缩略图缓存决定（我们只保证取到之后不再缩糊）。
  • 文件夹背景上的「授予访问权限」在 Windows 11 里本身就没有子项，因此按 Explorer 的做法直接隐藏； 选中文件夹时该子菜单有内容，会照常显示。
  • 暂不支持：压缩包内浏览、网络位置、批量重命名、内容搜索。

许可证

  • 本项目代码尚未声明开源许可证；公开源码不等于授权任意使用、修改或分发。第三方许可不代表整个项目的许可。
  • DuiLib：见 third_party/duilib/LICENSE 与 duilib license.txt（BSD 风格开源许可）。

明确不做

  • 不安装 360 软件，不反编译任何闭源文件管理器二进制。
  • 不把 upstream 的 360SafeDemo 或任何 360 资源打进本仓库。