Molecule Framework - ActivityBarService API 详细文档Molecule Fra

Molecule Framework - ActivityBarService API 详细文档

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

服务概述

ActivityBarService（活动栏服务）是 Molecule 框架中用于管理 IDE 左侧垂直工具栏（活动栏）的核心服务。

活动栏是 IDE 左侧的垂直工具栏，用于切换不同的侧边栏视图，如资源管理器、搜索、源代码管理等。

它提供了完整的活动栏操作功能，包括：

添加、删除活动栏项
设置活动状态
管理上下文菜单
监听点击和变化事件

继承关系:

ActivityBarService extends Component<IActivityBar> implements IActivityBarService

1. 基础操作方法

reset(): void

功能: 重置活动栏状态数据

说明: 清除所有活动栏数据，恢复到初始状态

使用场景: 如果要完全自定义活动栏，可以先重置，然后使用 add() 方法填充需要的数据

示例:

molecule.activityBar.reset();

add(data: IActivityBarItem | IActivityBarItem[], isActive?: boolean): void

功能: 添加活动栏项数据

参数:

data: 要添加的活动栏项或活动栏项数组
isActive: 是否自动设置为活动状态（可选） 注意: 如果提供 isActive 参数，Activity Bar 会自动设置该项为活动状态。此参数仅对单个数据有效

说明:

可以添加单个或多个活动栏项
如果提供 isActive 且为 true，会自动激活该项

示例:

// 添加单个活动栏项并设置为活动状态
molecule.activityBar.add(
  {
    id: 'explorer',
    name: '资源管理器',
    icon: 'folder',
    title: '资源管理器',
  },
  true
);

// 添加多个活动栏项
molecule.activityBar.add([
  {
    id: 'explorer',
    name: '资源管理器',
    icon: 'folder',
    title: '资源管理器',
  },
  {
    id: 'search',
    name: '搜索',
    icon: 'search',
    title: '搜索',
  },
]);

setActive(id?: UniqueId): void

功能: 设置活动的活动栏项

参数:

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

说明: 用于切换活动栏的选中状态

示例:

// 激活指定的活动栏项
molecule.activityBar.setActive('explorer');

// 取消激活（取消所有项的选中状态）
molecule.activityBar.setActive();

remove(id: UniqueId | UniqueId[]): void

功能: 根据 ID 移除指定的活动栏项

参数:

id: 要移除的活动栏项 ID 或 ID 数组

说明: 可以移除单个或多个活动栏项

示例:

// 移除单个活动栏项
molecule.activityBar.remove('explorer');

// 移除多个活动栏项
molecule.activityBar.remove(['explorer', 'search']);

2. 显示/隐藏控制方法

toggleBar(id: UniqueId): void

功能: 切换指定活动栏项的显示/隐藏状态

参数:

id: 活动栏项 ID

说明: 用于控制活动栏项的可见性

示例:

// 切换资源管理器的显示/隐藏
molecule.activityBar.toggleBar('explorer');

3. 上下文菜单管理方法

toggleContextMenuChecked(id: UniqueId): void

功能: 切换上下文菜单项的选中/未选中状态

参数:

id: 上下文菜单项 ID

说明: 用于切换上下文菜单项的复选框状态

示例:

molecule.activityBar.toggleContextMenuChecked('menu-item-1');

addContextMenu(data: IActivityMenuItemProps | IActivityMenuItemProps[]): void

功能: 为活动栏添加新的上下文菜单

参数:

data: 菜单项或菜单项数组

说明: 自定义活动栏的上下文菜单

示例:

molecule.activityBar.addContextMenu([
  {
    id: 'menu-1',
    name: '菜单项1',
    icon: 'file',
  },
  {
    id: 'menu-2',
    name: '菜单项2',
    icon: 'folder',
  },
]);

removeContextMenu(id: UniqueId | UniqueId[]): void

功能: 根据 ID 移除指定的上下文菜单项

参数:

id: 要移除的上下文菜单项 ID 或 ID 数组

说明: 可以移除单个或多个上下文菜单项

示例:

// 移除单个菜单项
molecule.activityBar.removeContextMenu('menu-1');

// 移除多个菜单项
molecule.activityBar.removeContextMenu(['menu-1', 'menu-2']);

4. 事件监听方法

onClick(callback: (selectedKey: UniqueId, item: IActivityBarItem) => void): void

功能: 监听活动栏项点击事件

参数:

callback: 回调函数
- selectedKey: 被点击的活动栏项 ID
- item: 被点击的活动栏项对象

说明: 当用户点击活动栏项时触发

示例:

molecule.activityBar.onClick((selectedKey, item) => {
  console.log('点击了活动栏项:', item.name);
  console.log('活动栏项ID:', selectedKey);

  // 根据不同的活动栏项执行不同的操作
  switch (selectedKey) {
    case 'explorer':
      // 显示资源管理器
      break;
    case 'search':
      // 显示搜索面板
      break;
  }
});

onChange(callback: (prevSelectedKey?: UniqueId, nextSelectedKey?: UniqueId) => void): void

功能: 监听活动栏项变化事件

参数:

callback: 回调函数
- prevSelectedKey: 之前选中的活动栏项 ID（可选）
- nextSelectedKey: 当前选中的活动栏项 ID（可选）

说明: 当非全局的活动栏项改变时调用

示例:

molecule.activityBar.onChange((prevKey, nextKey) => {
  console.log('活动栏项变化:', {
    之前: prevKey,
    当前: nextKey,
  });

  // 可以在这里保存用户的选择偏好
  if (nextKey) {
    localStorage.setItem('lastActiveBar', nextKey);
  }
});

完整使用示例

// 1. 重置活动栏
molecule.activityBar.reset();

// 2. 添加活动栏项
molecule.activityBar.add(
  [
    {
      id: 'explorer',
      name: '资源管理器',
      icon: 'folder',
      type: 'normal',
      sortIndex: 1,
    },
    {
      id: 'search',
      name: '搜索',
      icon: 'search',
      type: 'normal',
      sortIndex: 2,
    },
    {
      id: 'source-control',
      name: '源代码管理',
      icon: 'source-control',
      type: 'normal',
      sortIndex: 3,
    },
  ],
  false
); // 不自动激活

// 3. 设置默认激活项
molecule.activityBar.setActive('explorer');

// 4. 添加上下文菜单
molecule.activityBar.addContextMenu([
  {
    id: 'view-menu',
    name: '视图',
    icon: 'eye',
  },
  {
    id: 'settings-menu',
    name: '设置',
    icon: 'settings',
  },
]);

// 5. 监听点击事件
molecule.activityBar.onClick((selectedKey, item) => {
  console.log('用户点击了:', item.name);

  // 根据点击的活动栏项切换侧边栏内容
  switch (selectedKey) {
    case 'explorer':
      molecule.sidebar.setActive('explorer-panel');
      break;
    case 'search':
      molecule.sidebar.setActive('search-panel');
      break;
  }
});

// 6. 监听变化事件
molecule.activityBar.onChange((prevKey, nextKey) => {
  console.log('活动栏切换:', prevKey, '->', nextKey);
});

// 7. 动态切换活动栏项
function switchToSearch() {
  molecule.activityBar.setActive('search');
}

// 8. 隐藏/显示活动栏项
function toggleExplorer() {
  molecule.activityBar.toggleBar('explorer');
}

注意事项

活动栏项 ID 唯一性 每个活动栏项的 id 必须是唯一的，不能重复
isActive 参数限制 isActive 参数仅在添加单个活动栏项时有效，添加多个项时会被忽略
全局活动栏项
- 设置 type: 'global' 的活动栏项不会触发 onChange 事件
- 普通活动栏项（type: 'normal'）会触发 onChange 事件
图标设置
- 活动栏项通常需要设置 icon 属性
- icon 可以是字符串图标名称或 React 组件（JSX.Element）
- 也可以使用 render 函数自定义渲染
排序
- 使用 sortIndex 属性可以控制活动栏项的显示顺序
- sortIndex 越小，显示位置越靠上
与侧边栏的关联
- 活动栏项通常与侧边栏面板关联
- 点击活动栏项会切换对应的侧边栏内容
- 可以通过 onClick 事件处理侧边栏切换逻辑
事件监听
- 所有 on* 方法都是事件监听器，可以多次调用注册多个回调
- onClick 监听点击事件，onChange 监听切换事件
上下文菜单
- 上下文菜单是活动栏的右键菜单，用于显示额外的操作选项
- 可以通过 addContextMenu 添加菜单项
- 使用 toggleContextMenuChecked 可以切换菜单项的选中状态
显示/隐藏
- 使用 toggleBar 可以控制活动栏项的可见性，但不会移除数据
- 使用 hidden 属性也可以控制显示/隐藏
自定义渲染
- 可以使用 render 函数自定义活动栏项的渲染方式
- render 函数返回 React.ReactNode 或 JSX.Element

文档信息

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

Molecule Framework - ActivityBarService API 详细文档