#文件资源管理器

文件资源管理器把工作区身份、文件搜索、层级导航、文件状态和上下文操作组合成一个有边界的工具。文件系统读取、写入、权限和源码管理仍由可信宿主负责。

npm install @a3s-lab/ui

<section class="file-explorer" aria-labelledby="files-title">
  <header>
    <div data-file-explorer-identity><h2 id="files-title">项目文件</h2></div>
  </header>
  <div data-file-explorer-toolbar>
    <input
      class="input"
      type="search"
      data-file-explorer-search
      aria-label="筛选文件"
    />
  </div>
  <div data-file-explorer-viewport>
    <div class="tree" role="tree" aria-label="项目文件树">...</div>
  </div>
  <footer><span data-file-explorer-summary>5 个文件</span></footer>
</section>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

#用法

文件资源管理器复用 Tree 的焦点、选择、展开和字符定位行为；上下文命令由 Context Menu 提供。

<section class="file-explorer" aria-labelledby="files-title">
  <header>
    <div data-file-explorer-identity><h2 id="files-title">项目文件</h2></div>
  </header>
  <div data-file-explorer-toolbar>
    <input
      class="input"
      type="search"
      data-file-explorer-search
      aria-label="筛选文件"
    />
  </div>
  <div data-file-explorer-viewport>
    <div class="tree" role="tree" aria-label="项目文件树">...</div>
  </div>
  <footer><span data-file-explorer-summary>5 个文件</span></footer>
</section>

#参数

#JavaScript API

在 Tree、Context Menu 与 File Explorer 控制器之前加载运行时，或使用完整包。

const explorer = document.querySelector(".file-explorer");
explorer.select("src/components/App.tsx");
explorer.setFilter("status");
explorer.setReadonly(false);
explorer.beginRename();

explorer.addEventListener("a3s:file-rename", async ({ detail }) => {
  try {
    await renameFile(detail.value, detail.name);
  } catch (error) {
    explorer.setRenameError(error.message);
  }
});

getSelection() 与 select() 控制唯一文件，同时保留未保存变更拦截。getFilter()、setFilter() 和 clearFilter() 保存展开状态、显示匹配项祖先、播报数量，并在清除后恢复原文件树。getState()、setState() 与 setReadonly() 控制加载、错误、权限和写命令可见性。beginRename()、commitRename()、cancelRename() 与 setRenameError() 提供可回退的乐观重命名，runAction() 与 refresh() 完成宿主集成。

可取消钩子包括 a3s:file-before-selection-change、a3s:file-before-filter-change、a3s:file-before-action 与 a3s:file-before-rename。选择、筛选、操作、重命名、取消重命名和状态完成事件都包含来源、原始事件、稳定文件值与相关快照。宿主可以因未保存内容阻止导航、同步拒绝写入，也可以在异步失败后重新打开编辑器并显示错误。

#状态与变体

只读模式保留选择、筛选、复制路径和打开能力，同时移除写操作，不会只把所有命令禁用。筛选计数只包含叶子文件，不把目录节点计入结果。重命名使用当前行的 data-file-editor：F2 对聚焦或已选中项开始重命名，Enter 提交并把焦点交还当前项、Escape 取消；指针用户仍可通过上下文菜单重命名。除非设置 data-rename-blur="cancel"，失焦会提交。控制器拒绝空名称和路径分隔符，重名、平台规则、权限与持久化由宿主验证。

源码状态可以显示为文件尾部的简短标记；提交、暂存、分支创建和远程同步属于独立工作流，应由现有 Toolbar、Tree、Alert 和 Dialog 组合，不能塞进文件资源管理器的公共基础契约。

#无障碍

遵循 Tree 的 roving tabindex 和方向键约定。可取消选择钩子会在焦点或选择移动前保护未保存内容。筛选会播报数量；当当前焦点项消失时，焦点保留在搜索框。重命名错误与行内输入保持关联。异步展开目录时在对应分支内显示加载或错误状态。所有文件写操作都需由可信宿主完成。