Molecule Framework - FolderTreeService API 详细文档

大菜菜
48 阅读9分钟

Molecule Framework - FolderTreeService API 详细文档

本文档详细描述了 IFolderTreeService 接口和 FolderTreeService 类的所有方法和功能。

服务概述

FolderTreeService（文件夹树服务）是 Molecule 框架中用于管理文件资源管理器中文件夹树结构的核心服务。

它提供了完整的文件树操作功能，包括：

  • 添加、删除、更新节点
  • 管理展开状态
  • 处理上下文菜单
  • 监听各种文件树事件

继承关系: {code} FolderTreeService extends Component implements IFolderTreeService {code}

1. 基础操作方法

reset(): void

功能: 重置文件夹树服务状态

说明: 清除所有文件夹树数据，恢复到初始状态

使用场景: 需要完全重新构建文件夹树时使用

示例: {code:javascript} molecule.folderTree.reset(); {code}

add(data: IFolderTreeNodeProps, id?: UniqueId): void

功能: 向文件夹树添加数据

参数:

  • data: 要添加的文件夹树节点属性
  • id: 父节点 ID（可选） 注意: 除了添加根文件夹外，id 参数是必需的

说明:

  • 如果提供 id，则作为子节点添加到指定父节点下
  • 如果不提供 id，则作为根文件夹添加

示例: {code:javascript} // 添加根文件夹 molecule.folderTree.add({ id: 'root1', name: '项目根目录', fileType: 'RootFolder', isLeaf: false });

// 添加子节点 molecule.folderTree.add({ id: 'file1', name: 'example.js', fileType: 'File', isLeaf: true, data: { language: 'javascript', value: '' } }, 'root1'); {code}

remove(id: UniqueId): void

功能: 从文件夹树中移除指定数据

参数:

  • id: 要移除的节点 ID

说明: 移除节点及其所有子节点

示例: {code:javascript} molecule.folderTree.remove('file1'); {code}

update(data: IFolderTreeNodeProps): void

功能: 更新文件夹树中的指定数据

参数:

  • data: 要更新的节点数据 注意: 必须包含 id 属性

说明: 根据 id 查找节点并更新其属性

示例: {code:javascript} molecule.folderTree.update({ id: 'file1', name: 'example-updated.js', // 其他属性... }); {code}

get(id: UniqueId): IFolderTreeNodeProps | null

功能: 获取文件夹树中的指定数据

参数:

  • id: 节点 ID

返回值: 节点属性对象，如果不存在则返回 null

示例: {code:javascript} const node = molecule.folderTree.get('file1');

if (node) { console.log('节点名称:', node.name); } {code}

getParentNode(id: UniqueId): IFolderTreeNodeProps | null

功能: 获取当前树节点的父节点

参数:

  • id: 子节点 ID

返回值: 父节点属性对象，如果不存在或为根节点则返回 null

示例: {code:javascript} const parent = molecule.folderTree.getParentNode('file1');

if (parent) { console.log('父节点:', parent.name); } {code}

2. 展开状态管理方法

getExpandKeys(): UniqueId[]

功能: 获取文件夹树中展开的键（节点 ID 数组）

返回值: 当前展开的所有节点 ID 数组

说明: 用于保存和恢复文件夹树的展开状态

示例: {code:javascript} const expandedKeys = molecule.folderTree.getExpandKeys(); console.log('展开的节点:', expandedKeys); {code}

setExpandKeys(expandKeys: UniqueId[]): void

功能: 设置文件夹树的展开键

参数:

  • expandKeys: 要展开的节点 ID 数组

说明: 用于恢复文件夹树的展开状态

示例: {code:javascript} // 展开特定节点 molecule.folderTree.setExpandKeys(['root1', 'folder1']);

// 折叠所有节点 molecule.folderTree.setExpandKeys([]); {code}

getLoadedKeys(): string[]

功能: 获取文件夹树中已加载的键

返回值: 已加载的节点 ID 字符串数组

说明: 用于跟踪哪些节点已经加载过数据（懒加载场景）

示例: {code:javascript} const loadedKeys = molecule.folderTree.getLoadedKeys(); {code}

setLoadedKeys(loadedKeys: string[]): void

功能: 设置文件夹树的已加载键

参数:

  • loadedKeys: 已加载的节点 ID 字符串数组

说明: 用于标记哪些节点已经加载过数据

示例: {code:javascript} molecule.folderTree.setLoadedKeys(['root1', 'folder1']); {code}

3. 节点激活和入口页面方法

setActive(id?: UniqueId): void

功能: 激活指定的节点，或取消激活文件夹树中的任何节点

参数:

  • id: 要激活的节点 ID（可选） 如果不提供，则取消所有节点的激活状态

说明: 用于高亮显示当前选中的节点

示例: {code:javascript} // 激活节点 molecule.folderTree.setActive('file1');

// 取消激活 molecule.folderTree.setActive(); {code}

setEntry(entry: React.ReactNode): void

功能: 为文件夹树设置入口页面

参数:

  • entry: React 节点，作为文件夹树的入口页面

说明: 当文件夹树为空或需要显示欢迎页面时使用

示例: {code:javascript} molecule.folderTree.setEntry(

欢迎使用文件资源管理器
); {code}

4. 上下文菜单管理方法

getFileContextMenu(): IMenuItemProps[]

功能: 获取文件的上下文菜单

返回值: 文件右键菜单项数组

说明: 返回当前配置的文件右键菜单

示例: {code:javascript} const fileMenus = molecule.folderTree.getFileContextMenu(); console.log('文件菜单项数量:', fileMenus.length); {code}

setFileContextMenu(menus: IMenuItemProps[]): void

功能: 设置文件的上下文菜单

参数:

  • menus: 菜单项数组

说明: 自定义文件右键菜单

示例: {code:javascript} molecule.folderTree.setFileContextMenu([ { id: 'open', name: '打开', icon: 'file' }, { id: 'delete', name: '删除', icon: 'trash' } ]); {code}

getFolderContextMenu(): IMenuItemProps[]

功能: 获取文件夹的上下文菜单

返回值: 文件夹右键菜单项数组

说明: 返回当前配置的文件夹右键菜单

示例: {code:javascript} const folderMenus = molecule.folderTree.getFolderContextMenu(); {code}

setFolderContextMenu(menus: IMenuItemProps[]): void

功能: 设置文件夹的上下文菜单

参数:

  • menus: 菜单项数组

说明: 自定义文件夹右键菜单

示例: {code:javascript} molecule.folderTree.setFolderContextMenu([ { id: 'new-file', name: '新建文件', icon: 'file-add' }, { id: 'new-folder', name: '新建文件夹', icon: 'folder-add' } ]); {code}

5. 事件监听方法

onRename(callback: (id: UniqueId) => void): void

功能: 监听点击重命名按钮的事件

参数:

  • callback: 回调函数，参数为要重命名的节点 ID

说明: 当用户点击重命名按钮时触发

示例: {code:javascript} molecule.folderTree.onRename((id) => { console.log('开始重命名节点:', id); // 显示重命名输入框等操作 }); {code}

onRemove(callback: (id: UniqueId) => void): void

功能: 监听移除节点的事件

参数:

  • callback: 回调函数，参数为要移除的节点 ID

说明: 当用户删除文件或文件夹时触发

示例: {code:javascript} molecule.folderTree.onRemove((id) => { console.log('删除节点:', id);

// 调用 API 删除文件 API.removeFile({ id }).then(() => { molecule.folderTree.remove(id); }); }); {code}

onUpdateFileName(callback: (file: IFolderTreeNodeProps) => void): void

功能: 监听更新文件或文件夹名称的事件

参数:

  • callback: 回调函数，参数为更新后的文件节点属性

说明: 当用户完成重命名操作时触发

示例: {code:javascript} molecule.folderTree.onUpdateFileName((file) => { console.log('文件已重命名:', file.name);

// 调用 API 更新文件名 API.renameFile({ id: file.id, name: file.name }); }); {code}

onSelectFile(callback: (file: IFolderTreeNodeProps) => void): void

功能: 监听选择文件的事件

参数:

  • callback: 回调函数，参数为选中的文件节点属性

说明: 当用户点击文件时触发，通常用于打开文件

示例: {code:javascript} molecule.folderTree.onSelectFile((file) => { console.log('选择了文件:', file.name);

// 在编辑器中打开文件 molecule.editor.open(transformToEditorTab(file)); }); {code}

onDropTree(callback: (source: IFolderTreeNodeProps, target: IFolderTreeNodeProps) => void): void

功能: 监听拖放事件

参数:

  • callback: 回调函数 ** source: 被拖拽的源节点 ** target: 拖放目标节点

说明: 当用户拖放文件或文件夹时触发

示例: {code:javascript} molecule.folderTree.onDropTree((source, target) => { console.log('拖放:', source.name, '到', target.name);

// 调用 API 移动文件 API.moveFile({ sourceId: source.id, targetId: target.id }); }); {code}

onRightClick(callback: (treeData: IFolderTreeNodeProps, menus: IMenuItemProps[]) => void): void

功能: 监听右键点击事件

参数:

  • callback: 回调函数 ** treeData: 被右键点击的节点 ** menus: 当前显示的菜单项数组

说明: 当用户右键点击节点时触发，可以自定义菜单行为

示例: {code:javascript} molecule.folderTree.onRightClick((treeData, menus) => { console.log('右键点击:', treeData.name); console.log('可用菜单:', menus.map(m => m.name)); }); {code}

onCreate(callback: (type: FileType, nodeId?: UniqueId) => void): void

功能: 监听在文件夹树中创建节点的事件

参数:

  • callback: 回调函数 ** type: 节点类型（'File' | 'Folder' | 'RootFolder'） ** nodeId: 父节点 ID（可选）

说明: 当用户创建新文件或文件夹时触发

示例: {code:javascript} molecule.folderTree.onCreate((type, nodeId) => { console.log('创建类型:', type, '父节点:', nodeId);

// 创建新文件或文件夹 const newNode = { id: Date.now().toString(), name: type === 'File' ? '新建文件' : '新建文件夹', fileType: type, isLeaf: type === 'File' };

molecule.folderTree.add(newNode, nodeId); }); {code}

onContextMenu(callback: (contextMenu: IMenuItemProps, treeNode?: IFolderTreeNodeProps) => void): void

功能: 监听上下文菜单点击事件（不包括内置菜单）

参数:

  • callback: 回调函数 ** contextMenu: 被点击的菜单项 ** treeNode: 关联的树节点（可选）

说明: 当用户点击自定义菜单项时触发

示例: {code:javascript} molecule.folderTree.onContextMenu((menu, node) => { console.log('点击了菜单:', menu.name);

if (menu.id === 'custom-action') { // 执行自定义操作 } }); {code}

onLoadData(callback: (treeNode: IFolderTreeNodeProps, callback: (treeNode: IFolderTreeNodeProps) => void) => void): void

功能: 回调函数，用于懒加载文件夹树数据

参数:

  • callback: 回调函数 ** treeNode: 需要加载数据的节点 ** callback: 加载完成后的回调函数，用于更新节点数据

说明: 用于实现懒加载，当节点展开时动态加载子节点数据

示例: {code:javascript} molecule.folderTree.onLoadData((treeNode, updateCallback) => { console.log('加载节点数据:', treeNode.name);

// 异步加载子节点数据 API.getChildren(treeNode.id).then((children) => { // 更新节点数据 updateCallback({ ...treeNode, children: children }); }); }); {code}

onExpandKeys(callback: (expandKeys: UniqueId[]) => void): void

功能: 回调函数，用于监听展开树节点的事件

参数:

  • callback: 回调函数，参数为当前展开的节点 ID 数组

说明: 当文件夹树的展开状态改变时触发

示例: {code:javascript} molecule.folderTree.onExpandKeys((expandKeys) => { console.log('展开的节点:', expandKeys);

// 保存展开状态到本地存储 localStorage.setItem('expandKeys', JSON.stringify(expandKeys)); }); {code}

6. 其他方法

toggleAutoSort(): void

功能: 切换是否启用排序功能（默认禁用）

说明: 启用后，文件夹树会自动按名称排序

示例: {code:javascript} // 启用自动排序 molecule.folderTree.toggleAutoSort();

// 再次调用则禁用 molecule.folderTree.toggleAutoSort(); {code}

完整使用示例

{code:javascript} // 1. 初始化文件夹树 molecule.folderTree.reset();

// 2. 添加根文件夹 molecule.folderTree.add({ id: 'root', name: '项目根目录', fileType: 'RootFolder', isLeaf: false, children: [] });

// 3. 添加子文件和文件夹 molecule.folderTree.add({ id: 'folder1', name: 'src', fileType: 'Folder', isLeaf: false }, 'root');

molecule.folderTree.add({ id: 'file1', name: 'index.js', fileType: 'File', isLeaf: true, data: { language: 'javascript', value: 'console.log("Hello");' } }, 'folder1');

// 4. 设置上下文菜单 molecule.folderTree.setFileContextMenu([ { id: 'open', name: '打开', icon: 'file' }, { id: 'delete', name: '删除', icon: 'trash' } ]);

// 5. 监听文件选择事件 molecule.folderTree.onSelectFile((file) => { console.log('选择了文件:', file.name); molecule.editor.open(transformToEditorTab(file)); });

// 6. 监听创建事件 molecule.folderTree.onCreate((type, parentId) => { const newNode = { id: Date.now().toString(), name: type === 'File' ? '新建文件' : '新建文件夹', fileType: type, isLeaf: type === 'File' };

molecule.folderTree.add(newNode, parentId); });

// 7. 监听删除事件 molecule.folderTree.onRemove((id) => { API.removeFile({ id }).then(() => { molecule.folderTree.remove(id); }); });

// 8. 保存和恢复展开状态 const savedExpandKeys = molecule.folderTree.getExpandKeys(); localStorage.setItem('expandKeys', JSON.stringify(savedExpandKeys));

// 恢复展开状态 const savedKeys = JSON.parse(localStorage.getItem('expandKeys') || '[]'); molecule.folderTree.setExpandKeys(savedKeys); {code}

注意事项

{panel:title=重要提示|borderColor=#ffab00|titleBGColor=#fff3cd|bgColor=#fffbf0}

  1. 节点 ID 唯一性 每个节点的 id 必须是唯一的，不能重复

  2. 文件类型

    • 'File': 文件
    • 'Folder': 文件夹
    • 'RootFolder': 根文件夹

  3. isLeaf 属性

    • true: 叶子节点（文件）
    • false: 非叶子节点（文件夹）

  4. 懒加载 使用 onLoadData 可以实现懒加载，提高性能

  5. 展开状态 使用 getExpandKeys 和 setExpandKeys 可以保存和恢复展开状态

  6. 事件监听 所有 on* 方法都是事件监听器，可以多次调用注册多个回调

  7. 上下文菜单 文件菜单和文件夹菜单是分开管理的

  8. 数据更新 使用 update 方法更新节点时，必须包含 id 属性 {panel}

相关类型定义

IFolderTreeNodeProps

文件夹树节点属性接口

||属性||类型||说明|| |id|UniqueId|节点 ID| |name|string|节点名称| |fileType|FileType|文件类型| |isLeaf|boolean|是否为叶子节点| |location|string (可选)|文件路径| |data|any (可选)|节点数据（如文件内容、语言等）| |children|IFolderTreeNodeProps[] (可选)|子节点数组| |parentId|UniqueId (可选)|父节点 ID|

FileType

{code} 'File' | 'Folder' | 'RootFolder' {code}

UniqueId

{code} string | number {code}

文档信息

文档生成时间: 2024 版本: @dtinsight/molecule@1.3.6

avatar
文章
阅读
粉丝