Molecule Framework - ExplorerService API 详细文档

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

服务概述

ExplorerService（资源管理器服务）是 Molecule 框架中用于管理 IDE 资源管理器（Explorer）面板的核心服务。

资源管理器是 IDE 中用于显示和管理文件树、文件夹结构等资源的面板区域。它支持多个面板（Panel），每个面板可以有自己的工具栏和自定义渲染内容。

它提供了完整的资源管理器操作功能，包括：

添加、删除、更新面板
管理面板的展开/折叠状态
管理工具栏操作项
监听各种事件（点击、移除、折叠等）

继承关系:

java 复制代码

ExplorerService extends Component<IExplorer> implements IExplorerService

1. 面板管理方法

addPanel(panel: IExplorerPanelItem | IExplorerPanelItem[]): void

功能: 添加新的资源管理器面板

参数:

panel: 单个面板数据或面板数据数组

说明:

添加面板的同时，也会添加对应的工具栏数据
可以一次添加单个或多个面板
面板 ID 必须在资源管理器中唯一

示例:

javascript 复制代码

// 添加单个面板
molecule.explorer.addPanel({
  id: 'file-tree',
  name: '文件树',
  sortIndex: 1,
  toolbar: [
    {
      id: 'refresh',
      title: '刷新',
      icon: 'refresh',
    },
  ],
});

// 添加多个面板
molecule.explorer.addPanel([
  {
    id: 'file-tree',
    name: '文件树',
    sortIndex: 1,
  },
  {
    id: 'outline',
    name: '大纲',
    sortIndex: 2,
  },
]);

updatePanel(data: Partial): void

功能: 更新面板数据

参数:

data: 面板的部分数据（Partial 类型，只需提供要更新的字段）

说明:

更新面板数据的同时，也会修改对应的工具栏数据
使用面板 ID 来定位要更新的面板

示例:

javascript 复制代码

// 更新面板名称和排序
molecule.explorer.updatePanel({
  id: 'file-tree',
  name: '项目文件',
  sortIndex: 0,
});

// 更新面板的隐藏状态
molecule.explorer.updatePanel({
  id: 'outline',
  hidden: true,
});

removePanel(id: UniqueId): void

功能: 通过 ID 移除面板

参数:

id: 要移除的面板 ID

说明:

移除面板的同时，也会移除对应的操作栏（Action Bar）

示例:

javascript 复制代码

molecule.explorer.removePanel('file-tree');

togglePanel(id: UniqueId): void

功能: 切换面板的显示/隐藏状态

参数:

id: 要切换的面板 ID

说明:

切换面板隐藏状态的同时，也会切换工具栏状态

示例:

javascript 复制代码

// 切换面板显示/隐藏
molecule.explorer.togglePanel('file-tree');

setExpandedPanels(activePanelKeys: UniqueId[]): void

功能: 设置资源管理器中展开的面板

参数:

activePanelKeys: 要展开的面板 ID 数组

说明:

设置哪些面板应该处于展开状态
传入空数组可以折叠所有面板

示例:

javascript 复制代码

// 展开指定的面板
molecule.explorer.setExpandedPanels(['file-tree', 'outline']);

// 折叠所有面板
molecule.explorer.setExpandedPanels([]);

2. 工具栏管理方法

addAction(action: IMenuItemProps): void

功能: 在工具栏操作中添加一个操作项

参数:

action: 菜单项属性对象

说明:

仅添加工具栏操作，不影响面板数据
可以添加单个或多个操作项

示例:

javascript 复制代码

// 添加单个操作项
molecule.explorer.addAction({
  id: 'new-file',
  name: '新建文件',
  icon: 'file-add',
  onClick: (e, item) => {
    console.log('创建新文件');
  },
});

// 添加多个操作项（实际实现支持数组）
molecule.explorer.addAction({
  id: 'refresh',
  name: '刷新',
  icon: 'refresh',
});

getAction(id: UniqueId): IMenuItemProps | undefined

功能: 获取工具栏中指定的操作项

参数:

id: 操作项 ID

返回值:

找到的操作项对象，如果不存在则返回 undefined

示例:

javascript 复制代码

const action = molecule.explorer.getAction('new-file');
if (action) {
  console.log('操作项名称:', action.name);
}

updateAction(action: Partial): void

功能: 更新工具栏中的操作项

参数:

action: 操作项的部分数据（Partial 类型）

说明:

使用操作项 ID 来定位要更新的操作项

示例:

javascript 复制代码

// 更新操作项的禁用状态
molecule.explorer.updateAction({
  id: 'new-file',
  disabled: true,
});

// 更新操作项的名称和图标
molecule.explorer.updateAction({
  id: 'refresh',
  name: '重新加载',
  icon: 'reload',
});

removeAction(id: UniqueId): void

功能: 移除指定的工具栏操作项

参数:

id: 要移除的操作项 ID

示例:

javascript 复制代码

molecule.explorer.removeAction('new-file');

toggleHeaderBar(id: UniqueId): void

功能: 仅切换工具栏状态

参数:

id: 工具栏 ID

说明:

只切换工具栏的显示状态，不影响面板数据

示例:

javascript 复制代码

molecule.explorer.toggleHeaderBar('file-tree-toolbar');

3. 状态重置方法

reset(): void

功能: 重置 ExplorerService 状态

说明:

主要用于自定义资源管理器时重置状态
清除所有面板和工具栏数据，恢复到初始状态

示例:

javascript 复制代码

// 重置资源管理器，然后重新添加自定义面板
molecule.explorer.reset();
molecule.explorer.addPanel({
  id: 'custom-panel',
  name: '自定义面板',
});

4. 事件监听方法

onClick(callback: (e: MouseEvent, item: IActionBarItemProps) => void): any

功能: 监听资源管理器头部工具栏点击事件

参数:

callback: 回调函数
- e: 鼠标事件对象
- item: 被点击的操作栏项属性

返回值:

返回取消监听的函数（如果支持）

说明:

当用户点击资源管理器头部工具栏的操作项时触发

示例:

javascript 复制代码

molecule.explorer.onClick((e, item) => {
  console.log('点击了工具栏项:', item.id);
  console.log('操作项标题:', item.title);
});

onRemovePanel(callback: (panel: IExplorerPanelItem) => void): void

功能: 监听资源管理器面板移除事件

参数:

callback: 回调函数
- panel: 被移除的面板数据

说明:

当面板被移除时触发此事件

示例:

javascript 复制代码

molecule.explorer.onRemovePanel((panel) => {
  console.log('面板已移除:', panel.id);
  console.log('面板名称:', panel.name);
});

onCollapseAllFolders(callback: () => void): void

功能: 监听文件夹树面板折叠所有文件夹事件

参数:

callback: 回调函数（无参数）

说明:

当文件夹树面板触发"折叠所有文件夹"操作时触发

示例:

javascript 复制代码

molecule.explorer.onCollapseAllFolders(() => {
  console.log('所有文件夹已折叠');
});

onPanelToolbarClick(callback: (panel: IExplorerPanelItem, toolbarId: string) => void): void

功能: 监听资源管理器面板工具栏点击事件

参数:

callback: 回调函数
- panel: 面板数据对象
- toolbarId: 被点击的工具栏项 ID

说明:

当用户点击面板工具栏中的操作项时触发

示例:

javascript 复制代码

molecule.explorer.onPanelToolbarClick((panel, toolbarId) => {
  console.log('面板:', panel.name);
  console.log('工具栏项 ID:', toolbarId);

  if (toolbarId === 'refresh') {
    // 刷新面板内容
    refreshPanelContent(panel.id);
  }
});

5. 类型定义

IExplorerPanelItem

资源管理器面板项接口

属性:

id: UniqueId - 面板唯一标识符（必需，必须在资源管理器中唯一）
name: string - 面板标题（必需）
sortIndex: number - 排序索引（可选，数字越大越靠前）
className: string - 自定义 CSS 类名（可选）
toolbar: IActionBarItemProps[] - 工具栏操作项数组（可选）
renderPanel: RenderFunctionProps - 自定义渲染函数（可选）
hidden: boolean - 是否在资源管理器中隐藏（可选）
[key: string]: any - 允许添加其他自定义属性

示例:

javascript 复制代码

const panel: IExplorerPanelItem = {
  id: 'file-tree',
  name: '文件树',
  sortIndex: 1,
  className: 'custom-panel',
  toolbar: [
    {
      id: 'refresh',
      title: '刷新',
      icon: 'refresh',
      onClick: (e, item) => {
        console.log('刷新文件树');
      },
    },
  ],
  renderPanel: (props) => {
    return <FileTreeComponent {...props} />;
  },
  hidden: false,
};

IExplorer

资源管理器数据接口

属性:

data: IExplorerPanelItem[] - 面板数据数组
headerToolBar: IActionBarItemProps - 头部工具栏操作项（可选）
activePanelKeys: UniqueId[] - 当前展开的面板 ID 数组（可选）

示例:

javascript 复制代码

const explorerState: IExplorer = {
  data: [
    {
      id: 'file-tree',
      name: '文件树',
    },
    {
      id: 'outline',
      name: '大纲',
    },
  ],
  headerToolBar: {
    id: 'explorer-actions',
    title: '操作',
    icon: 'more',
  },
  activePanelKeys: ['file-tree'],
};

IMenuItemProps

菜单项属性接口（用于工具栏操作项）

属性:

id: UniqueId - 操作项唯一标识符（必需）
icon: string | JSX.Element - 图标名称或元素（可选）
type: 'divider' - 分隔线类型（可选）
name: string - 操作项名称（可选）
disabled: boolean - 是否禁用（可选）
keybinding: string - 快捷键描述（可选，例如：⇧⌘P）
render: (data: IMenuItemProps) => React.ReactNode - 自定义渲染函数（可选）
onClick: (e: React.MouseEvent, item: IMenuItemProps) => void - 点击事件处理函数（可选）
sortIndex: number - 排序索引（可选）
[key: string]: any - 允许添加其他自定义属性

示例:

javascript 复制代码

const menuItem: IMenuItemProps = {
  id: 'new-file',
  name: '新建文件',
  icon: 'file-add',
  keybinding: '⌘N',
  disabled: false,
  onClick: (e, item) => {
    console.log('创建新文件');
  },
};

IActionBarItemProps

操作栏项属性接口（用于面板工具栏）

属性:

id: UniqueId - 操作项唯一标识符（必需）
title: string | JSX.Element - 操作项标题（可选）
name: React.ReactNode - 操作项名称（可选）
icon: string | JSX.Element - 图标名称或元素（可选）
disabled: boolean - 是否禁用（可选）
checked: boolean - 是否选中（可选）
data: T - 自定义数据（可选，泛型类型）
contextMenu: IMenuItemProps[] - 上下文菜单项数组（可选）
onContextMenuClick: (e: React.MouseEvent, item: IMenuItemProps | undefined) => void - 上下文菜单点击事件（可选）
onClick: (event: React.MouseEvent, item: IActionBarItemProps) => void - 点击事件处理函数（可选）
[key: string]: any - 允许添加其他自定义属性

示例:

javascript 复制代码

const actionBarItem: IActionBarItemProps = {
  id: 'refresh',
  title: '刷新',
  name: '刷新文件树',
  icon: 'refresh',
  disabled: false,
  checked: false,
  onClick: (e, item) => {
    console.log('刷新操作');
  },
  contextMenu: [
    {
      id: 'refresh-all',
      name: '刷新全部',
    },
  ],
};

RenderFunctionProps

面板渲染函数类型

类型定义:

typescript 复制代码

type RenderFunctionProps = (props: any) => React.ReactNode;

说明:

用于自定义面板内容的渲染函数
接收任意属性对象，返回 React 节点

示例:

javascript 复制代码

const renderPanel: RenderFunctionProps = (props) => {
  return <CustomPanelComponent data={props.data} />;
};

const panel: IExplorerPanelItem = {
  id: 'custom-panel',
  name: '自定义面板',
  renderPanel: renderPanel,
};

ExplorerEvent

资源管理器事件枚举

枚举值:

onClick - 头部工具栏点击事件
onPanelToolbarClick - 面板工具栏点击事件
onCollapseChange - 折叠状态变化事件
onRemovePanel - 面板移除事件
onCollapseAllFolders - 折叠所有文件夹事件

6. 使用示例

完整示例：创建自定义资源管理器面板

javascript 复制代码

import molecule from '@dtinsight/molecule';
import React from 'react';

// 1. 重置资源管理器
molecule.explorer.reset();

// 2. 定义自定义面板组件
const CustomFileTree = (props) => {
  return <div>自定义文件树组件</div>;
};

// 3. 添加自定义面板
molecule.explorer.addPanel({
  id: 'custom-file-tree',
  name: '文件树',
  sortIndex: 1,
  toolbar: [
    {
      id: 'refresh',
      title: '刷新',
      icon: 'refresh',
      onClick: (e, item) => {
        console.log('刷新文件树');
      },
    },
    {
      id: 'new-file',
      title: '新建文件',
      icon: 'file-add',
      onClick: (e, item) => {
        console.log('创建新文件');
      },
    },
  ],
  renderPanel: (props) => {
    return <CustomFileTree {...props} />;
  },
});

// 4. 设置展开的面板
molecule.explorer.setExpandedPanels(['custom-file-tree']);

// 5. 监听面板工具栏点击事件
molecule.explorer.onPanelToolbarClick((panel, toolbarId) => {
  console.log('面板:', panel.name);
  console.log('工具栏项:', toolbarId);
});

// 6. 监听面板移除事件
molecule.explorer.onRemovePanel((panel) => {
  console.log('面板已移除:', panel.id);
});

示例：动态更新面板

javascript 复制代码

// 更新面板名称和工具栏
molecule.explorer.updatePanel({
  id: 'file-tree',
  name: '项目文件树',
  toolbar: [
    {
      id: 'refresh',
      title: '重新加载',
      icon: 'reload',
    },
    {
      id: 'collapse-all',
      title: '折叠全部',
      icon: 'collapse',
    },
  ],
});

// 切换面板显示/隐藏
molecule.explorer.togglePanel('outline');

// 更新工具栏操作项
molecule.explorer.updateAction({
  id: 'refresh',
  disabled: true,
  name: '刷新中...',
});

示例：管理多个面板

javascript 复制代码

// 添加多个面板
molecule.explorer.addPanel([
  {
    id: 'file-tree',
    name: '文件树',
    sortIndex: 3,
  },
  {
    id: 'outline',
    name: '大纲',
    sortIndex: 2,
  },
  {
    id: 'timeline',
    name: '时间线',
    sortIndex: 1,
  },
]);

// 展开多个面板
molecule.explorer.setExpandedPanels(['file-tree', 'outline']);

// 移除指定面板
molecule.explorer.removePanel('timeline');

7. 最佳实践

面板 ID 唯一性
- 确保每个面板的 ID 在资源管理器中唯一
- 建议使用有意义的命名，如 'file-tree'、'outline' 等
排序控制
- 使用 sortIndex 控制面板显示顺序
- 数字越大越靠前显示
工具栏管理
- 面板工具栏和头部工具栏是分开管理的
- 使用 addAction 添加头部工具栏操作
- 在面板的 toolbar 属性中定义面板工具栏
事件监听
- 在组件初始化时注册事件监听器
- 注意避免重复注册导致的内存泄漏
状态同步
- 使用 setExpandedPanels 控制面板展开状态
- 在面板数据变化时及时更新展开状态
自定义渲染
- 使用 renderPanel 属性自定义面板内容
- 可以传递自定义属性给渲染函数
与 FolderTree 的关系
- ExplorerService 管理多个面板
- FolderTree 通常是其中一个面板的内容
- 两者可以配合使用，但职责不同

8. 注意事项

面板与工具栏的关联
- 添加面板时会自动添加对应的工具栏数据
- 移除面板时会自动移除对应的操作栏
展开状态管理
- activePanelKeys 控制哪些面板处于展开状态
- 使用 setExpandedPanels 更新展开状态
隐藏 vs 移除
- hidden: true 只是隐藏面板，数据仍然存在
- removePanel 会完全移除面板数据
工具栏操作项类型
- 头部工具栏使用 IMenuItemProps
- 面板工具栏使用 IActionBarItemProps
- 两者属性略有不同，注意区分
事件回调参数
- 不同事件的回调函数参数不同
- 注意查看类型定义以正确使用参数

9. 相关服务

FolderTreeService: 管理文件夹树的具体实现
ActivityBarService: 管理左侧活动栏，用于切换不同的侧边栏视图
SidebarService: 管理侧边栏的整体状态

10. 总结

ExplorerService 提供了完整的资源管理器面板管理功能，支持：

面板的增删改查
工具栏操作项的管理
面板展开/折叠状态控制
丰富的事件监听机制
自定义渲染支持

通过合理使用这些 API，可以构建出功能强大且灵活的资源管理器界面。