@itookit/vfs-ui

原生 DOM 资源浏览组件：树、抽屉、单/双列、搜索、排序、选择和动作执行。 仅依赖 @itookit/vfs-core，不依赖 common、ui-common、LLM 包或 immer。内置 SVG、基础样式和主要控件的中英文文案，不需要 MindOS 的初始化或全局配置。

0.5.4 提供实例展示配置、抽屉节点声明、展开通知和冒泡资源激活事件；宿主通过公开 CSS 变量和 toolbarOptions.variant 调整样式，不需要访问组件内部 DOM。

Drawer 还可独立承载宿主列表，不需要文件系统：可配置折叠、独立搜索及 mountActions，搜索显示通过 search.visible / setSearchVisible() 控制。组件只发布查询变化，宿主负责过滤或异步搜索；同一抽屉可在侧栏和弹层之间移动并保留输入与内容。见 抽屉接口。

安装与文件浏览

npm install @itookit/vfs-ui @itookit/vfs-core

import { createVFSBrowser, fromVFS } from '@itookit/vfs-ui';
import { createVFS, MemoryBackend } from '@itookit/vfs-core';
import '@itookit/vfs-ui/style.css';

const container = document.querySelector<HTMLElement>('#files')!;
const { manager } = await createVFS({ rootBackend: new MemoryBackend() });
const fs = await manager.openFileSystem('/');
await fs.driver.createFile({ name: 'hello.md', content: '# Hello' });
const browser = createVFSBrowser({
  container,
  source: fromVFS(fs),
  presentation: { locale: 'en' },
  onActivate: node => console.log(node.resource),
});
await browser.start();
// At unmount:
browser.destroy();
await manager.dispose();

容器需要明确高度，例如 <div id="files" style="height: 400px"></div>。Web、Tauri、Electron 等宿主使用相同 DOM API；浏览器之外需要 DOM 环境。

此入口默认只浏览，不隐式创建文件或保存选择状态。传入 actions 可增加业务操作；同一动作可出现在工具栏、单项和多选菜单。普通文件 CRUD、标签、大纲和双列装配使用 createVFSUI(options, fs)；它与简明入口共享状态、列表和交互实现。

自定义数据源与接入接口

可以直接实现公开的 BrowserSource，不创建 VFS：

import { createVFSBrowser, type BrowserNode, type BrowserSource } from '@itookit/vfs-ui';

const nodes: BrowserNode[] = [
  { id: 'note:1', parentId: null, kind: 'file', label: 'My note' },
];
const source: BrowserSource = {
  get: async id => nodes.find(node => node.id === id),
  children: async parentId => nodes.filter(node => node.parentId === parentId),
  subscribe: () => () => {}, // Notify the listener when a mutable source changes.
};
const browser = createVFSBrowser({ container, source });
await browser.start();

ID 是展示身份；关联真实文件时用 resource: { viewId, path }。children 应返回直接子项，异步数据源应响应可选的 AbortSignal，subscribe 返回取消订阅函数。搜索覆盖当前已加载条目。

| 公共接口 | 用户提供的能力 | | --- | --- | | BrowserSource / BrowserAction | 数据读取、变化订阅、业务操作与确认 | | VFSPresentationOptions | locale、translate(key, params)、SVG 图标、fileIcon、启动 trace | | TagEditorFactory / IAutocompleteSource | 标签编辑组件与建议列表 | | ContextMenuConfig | 单项/批量菜单及动作回调 | | UIPersistencePort | 版本化 UI 快照的读取与保存 | | IFileSystem（从 vfs-core 导入） | 高级文件入口的读写、权限和事件 |

实现接口的公共结构即可，无需继承类或使用 itookit 的其他包。presentation 按实例配置，不会影响另一个浏览器。默认文案以中文为主，locale: 'en' 切换主要控件；旧高级弹窗仍有固定中文文案。自定义图标是可信 HTML/SVG，不应直接使用未经处理的用户输入。

const browser = createVFSBrowser({
  container, source,
  presentation: {
    translate: (key, params) => yourI18n(key, params),
    fileIcon: (filename, directory) => yourFileIcon(filename, directory),
  },
});

高级文件操作与宿主迁移

createVFSUI 通过端口接收宿主策略而不是复制业务：favoriteAction.state/toggle 提供收藏状态与切换，onQuickDelete 执行声明了 presentation.quickDelete 的虚拟条目删除；行级只读、固定条目与行内删除的判定集中在 src/utils/row-policy.ts。

persistence 默认关闭；true 选用包内 localStorage 存储，或传入 UIPersistencePort 使用自己的存储。编辑器通过 sessionSelected 和 navigateToHeading 等事件由宿主连接，不需要捆绑 mdxeditor。

listItems 投影隐藏容器成员时，可通过顶层 navigationChildren(node) 返回要加载的直接子容器 ID。单栏和双栏均在展开、恢复展开状态及刷新时准备这些成员，保留容器折叠状态，不读取未展开的分支；旧 columns.navigationChildren 继续兼容，顶层配置优先。

原先从 common/ui-common 导入的 Heading、TaskCounts、菜单和标签工厂类型，现可直接从 vfs-ui 导入。原有结构兼容实现继续可用。需要跟随宿主的语言、图标或启动统计时，通过 presentation 注入；MindOS 的示例在 ui/app-shell/src/browser/vfs-presentation.ts。

• 接口与组件
• 边界与迁移记录
• 开发说明

pnpm --filter @itookit/vfs-ui build
pnpm --filter @itookit/vfs-ui test

独立仓库开发

git clone --recurse-submodules [email protected]:mushuanli/vfs-ui.git
cd vfs-ui
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
pnpm pack

vendor/vfs-core 是开发用 Git 子模块，固定包含本仓库所需 API 的 core 提交；它不被打入 UI 发布产物。运行时内部依赖仍只有 @itookit/vfs-core。当前源码使用该提交新增的文件传输 API；发布 npm 前，必须先发布包含这些 API 的 core 版本，并更新 UI 的版本约束，不能仅依赖同版本号代表内容一致。

在 itookit 中，本仓库作为 packages/vfs-ui 子模块使用，pnpm 仍链接顶层工作区的 vfs-core。首次克隆 itookit 后执行 git submodule update --init packages/vfs-core packages/vfs-ui；只在独立开发 UI 时需要初始化 vendor/vfs-core。