For AI agents: the complete documentation index is available at https://a3s-lab.github.io/UI/v0.4.1/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/UI/v0.4.1/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/UI/v0.4.1/components/file-manager.md.

文件管理器

文件管理器把工作空间位置、文件夹导航、多选、搜索、网格/列表视图、快速查看与可恢复操作组织在同一个有边界的界面中。可信宿主仍然负责文件系统读写、权限、持久化、下载与废纸篓恢复。

工作空间文件管理器
选择按 Ctrl/Cmd 或 Shift 选择多个项目
3 项已选择 DESIGN.md

产品决策

文件管理器不是源码树。仓库层级、未保存状态和编辑器重命名应使用文件资源管理器。当用户需要熟悉的工作空间导航、多选、排序、导入、预览与跨文件类型生命周期操作时,使用文件管理器。

  • 选择属于本地界面状态;每项写操作都通过可取消的 before-* 事件交给宿主授权。
  • “删除”默认表示可恢复的宿主废纸篓流程,永久删除必须单独说明并再次确认。
  • 加载和失败状态保留当前位置与搜索条件;刷新失败不会清空仍然可用的列表。
  • 网格视图把文件身份与类型分成两行,所有者和更新时间留在便于比较的列表视图或快速查看中,避免窄卡片挤压元数据。
  • 快速查看只渲染可信或已净化内容;大型、二进制或远程文件交给宿主预览器或下载动作。

控制器契约

区域契约
根元素.file-manager,推荐使用 <section>
项目data-file-item、稳定的 data-file-value、role="option" 与 aria-selected
方法select、clearSelection、getSelection、setFilter、clearFilter、setView、getView、openPreview、closePreview、runAction、setReadonly、setState、refresh、getState
授权事件a3s:file-manager-before-action、a3s:file-manager-before-filter-change、a3s:file-manager-before-selection-change
观察事件a3s:file-manager-action、a3s:file-manager-filter-change、a3s:file-manager-selection-change、a3s:file-manager-view-change、a3s:file-manager-preview-change、a3s:file-manager-state-change
状态ready、loading、empty、partial、error、offline、permission-denied、readonly

无障碍与所有权

文件视口是多选列表框。方向键移动选择,Ctrl/Cmd + A 选择可见项目,Enter 请求打开,空格请求快速查看,Delete 请求可恢复删除,Escape 先关闭预览再清空选择。工具栏操作、视图切换与搜索框保留原生 Enter/空格激活,不会被列表框快捷键截获。宿主负责路径解析、符号链接策略、冲突处理、上传限制、权限、文件内容、持久化与恢复。