# @alwith/module-file-tree 中文文档

规范地址：https://npmcn.com/package/%40alwith/module-file-tree/

版本：0\.6\.0
npm 元数据更新时间：2026-11-03T14:15:28.506Z
中文译文更新时间：2026-11-08T05:33:04.560Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40alwith/module-file-tree
原文对照：https://npmcn.com/package/%40alwith/module-file-tree/?lang=original
项目主页：https://github.com/ALwith-ai/alwith-modules#readme
源码仓库：https://github.com/ALwith-ai/alwith-modules

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.5 MB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：react ^19\.3\.1，react-dom ^19\.3\.1
- 首次发布：2026-10-22T10:35:31.188Z
- 最新版本发布：2026-11-03T14:15:27.891Z
- 近 30 天下载量：1891（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

一个独立的文件树 。 这取决于 `@alwith/module-fs` ,不导入编辑器软件包.

## 安装

```sh
npm install @alwith/module-file-tree
```

也可以使用：`pnpm add @alwith/module-file-tree`、`yarn add @alwith/module-file-tree`、`bun add @alwith/module-file-tree`

## README

# @alwith/module-file-tree (英语)

一个独立的文件树 。 这取决于 `@alwith/module-fs` ,不导入编辑器软件包.

```tsx
import { createFileTreeController, FileTree } from "@alwith/module-file-tree"
import "@alwith/module-file-tree/styles.css"
const tree = createFileTreeController({ fs, root: "/project", reportError })
await tree.refresh()
<FileTree controller={tree} onOpenFile={openFile} requestName={requestName}
  confirmDelete={confirmDelete} onError={reportError} />
// On workspace disposal:
tree.dispose()
```

`/core` 导出无反应控制器、快照、行和 `PartialOperationError`。根条目导出 React UI 和所有核心类型。 在主机中导入 CSS 一次 .

## 包含行为

目录-第一排序,懒散扩展,虚拟行,过滤已装入的条目(包括倒塌的后人),隐藏文件切换,多程选择,键盘导航,创建/重命名/删除,复制/剪切/粘贴和内部拖放到目录. 原生适配器采用吉地格诺过滤. 过滤器被明确限制在已加载的条目;它不是一个递归式搜索索引.

`requestName` 财务报告和审定财务报表 `confirmDelete` 是同步主机对话框 。 返回无效/ 假以取消 . `onOpenFile` 可以打开预览,编辑器,外部应用程序或任何主机动作. `renderDecoration` 添加每行元数据 。 所有字符串均可使用 `FileTreeLabels`; CSS 消耗语义主机主题符号.

`expanded` 财务报告和审定财务报表 `onExpandedChange` 让一个主机持续视图状态。 主机拥有工作空间/会话选择. 控制器从不加载全局设置或订阅全局应用程序商店.

变异使用共享的FS实例,因此使用它的守卫. 将一个FS实例传递给树和编辑器是标准成分;树上仍然不知道编辑器的内部. 在第一次失败时有一批停止,报告已完成路径加上失败路径. 复制使用桌面式增量复制名. 移动飞行前所有目的地冲突,然后触摸来源. 剪贴机替换需要主机 `confirmReplace` 在确认后调用并重新检查目标版本;去除目标使用FS突变后卫. 一个批次不是OS交易:后来I/O故障报告完成的项目;替换在移动源头前删除一个被批准的目标. 文件系统通知在刷新已装入的树之前被连接 .

见 `examples/files/tree-only.tsx` 用于不导入编辑包的消费者.

## 探索器 UI 和主机适配器

工具栏会显示搜索,创建,刷新,崩溃和查看偏好. 行使用22px高,文件类型图标,内线重命名,范围选择,键盘 导航和上下文菜单。 Cmd/Ctrl+F过滤名称和相对路径碎片; 输入/Shift+ 输入匹配和逃逸搜索之间的移动 。 计算机/计算机+A, C/X/V在焦作树上运行. 重命名并删除使用行上下文菜单, 和桌面一样.

`activePath` 通过懒惰的祖先扩展显示编辑器的选择. `onReveal`, (中文(简体) ), `onCopyPath`, (中文(简体) ), `onImport`,以及 `requestMoveDestination` 是宿主的能力. `onPinFile`, (中文(简体) ), `renderIcon`, (中文(简体) ), `renderDecoration`,以及 `renderActions` 整合更丰富的 编辑器,图标, Git 和应用程序行为而不导入主机. `explorerLabels` 在不突破现有消费者的情况下补充原标签. OS拖放注册,本土同意,文件取取者和持久性留在主机. 云授权、同步、共享和侧边栏平接是应用 特性,而不被捆绑到本地文件树上.

## 桌面执行出处

视觉解析器、图标关联、指针-拖曳钩和浮动拖曳预览 从桌面提取 `file-visual.ts`, (中文(简体) ), `use-tree-drag.ts` 财务报告和审定财务报表 `drag-preview.tsx`图标在本地捆绑;默认 vscode-icons 收藏 被绑入桌面的1.2.86版本. `isDark` 选择浅/暗绘图和 `iconTheme` 选择 vscode-icons, cappucin-latte, cappucin-mocha 或 材料主题。 主机提供主题设置; 没有全局设置商店 输入。 图标提供工具栏并扩展/缩放符号.

TanStack Virtual 制作出22px行并有桌面的8px嵌入增量. 这个 项目根是可扩展行。 折叠 都保持工程根的扩展. 指向拖放使用桌面的 5px 阈值和浮动预览, 避免 HTML5 拖曳在 WKWebView 中不可靠的事件 。 滴水仅限于树上 查看并拒绝进入源或源的后人.

该建筑验证了发射的图标映射,以检测意外重写 由无害环境管理模块路径变压器制造的普通字符串.

`explorerControl` 用主机内容替换工具栏标题. `collapsed` 保留 用于隐藏树及其剩余工具栏动作时显示的控件. 主机控制了崩溃的容器宽度和切换状态.

## 源码对齐

`desktop-provenance.json` 在提取时记录桌面源散列. `filter-tree.ts`, (中文(简体) ), `copy-name.ts` 财务报告和审定财务报表 `move-plan.ts` 保存他们的原始 算法; 它们的桌面测试套件被复制,只有跑取/导入更改. `use-tree-keyboard.ts` 保存桌面导航并注入存储访问. UI 点击处理器如下 `Explorer.handleItemClick`; 本地上下文菜单 如下 `TreeItem` 根排除,一行删除和多行复制.

主机适配器取代了全球商店,本地呼叫和通知. 键盘 钩子额外处理一个空列表而不索引缺失的节点. 现有 FS警卫仍然保护着肮脏的文件和工作空间界限. 请求 右侧布局, 探索者图标切换和微妙滚动条是有意的 UI 差别。 云动作需要云宿;它们不会被本地模拟.

## 常见问题

### @alwith/module-file-tree 是什么？

一个独立的文件树 。 这取决于 @alwith/module-fs ,不导入编辑器软件包\.

### 如何安装 @alwith/module-file-tree？

在项目目录运行 npm install @alwith/module-file-tree，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.3\.1）、react-dom（^19\.3\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alwith/module-file-tree 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @alwith/module-file-tree 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @alwith/module-file-tree 可以商用吗？

@alwith/module-file-tree 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @alwith/module-file-tree 的下载量有多少？

根据 npm 官方下载统计，@alwith/module-file-tree 在 2026/10/06 – 2026/11/04 这 30 天内被下载 1,891 次，日均约 63 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alwith/module-file-tree 还在维护吗？

最新版本 0\.6\.0 发布于 2026/11/03（4 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。