Molecule Framework - AuxiliaryBarService API 详细文档Molecule Fr

Molecule Framework - AuxiliaryBarService API 详细文档

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

服务概述

AuxiliaryBarService（辅助栏服务）是 Molecule 框架中用于管理 IDE 右侧辅助面板的核心服务。

辅助栏是 IDE 右侧的辅助面板，可以显示额外的信息或工具，如大纲视图、时间线、测试等。

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

添加和管理辅助栏标签页
设置活动标签页
控制辅助栏模式（显示/隐藏）
设置自定义内容
监听标签页点击事件

继承关系:

AuxiliaryBarService extends Component<IAuxiliaryBar> implements IAuxiliaryBarService

1. 标签页管理方法

getCurrentTab(): IAuxiliaryData | undefined

功能: 获取当前活动的辅助栏标签页

返回值: 当前活动的辅助栏数据对象，如果没有活动标签页则返回 undefined

说明: 用于获取当前显示的辅助栏标签页信息

示例:

const currentTab = molecule.auxiliaryBar.getCurrentTab();

if (currentTab) {
  console.log('当前标签页:', currentTab.title);
  console.log('标签页Key:', currentTab.key);
}

addAuxiliaryBar(tabs: IAuxiliaryData[] | IAuxiliaryData): void

功能: 添加辅助栏标签页

参数:

tabs: 辅助栏数据或辅助栏数据数组

说明:

可以添加单个或多个辅助栏标签页
如果添加多个标签页，它们会以标签页形式显示在辅助栏顶部

示例:

// 添加单个标签页
molecule.auxiliaryBar.addAuxiliaryBar({
  key: 'outline',
  title: '大纲',
});

// 添加多个标签页
molecule.auxiliaryBar.addAuxiliaryBar([
  {
    key: 'outline',
    title: '大纲',
  },
  {
    key: 'timeline',
    title: '时间线',
  },
  {
    key: 'test',
    title: '测试',
  },
]);

setActive(current: UniqueId | undefined): void

功能: 设置活动的辅助栏标签页

参数:

current: 要激活的标签页 ID（可选）如果不提供，则取消所有标签页的激活状态

说明: 用于切换辅助栏显示的标签页

示例:

// 激活指定的标签页
molecule.auxiliaryBar.setActive('outline');

// 取消激活（隐藏辅助栏）
molecule.auxiliaryBar.setActive();

2. 模式和内容控制方法

setMode(mode: IAuxiliaryBarMode | ((preState: IAuxiliaryBarMode) => IAuxiliaryBarMode)): IAuxiliaryBarMode

功能: 设置辅助栏的模式

参数:

mode: 模式值或函数
- 如果提供值，直接设置模式
- 如果提供函数，函数接收当前状态并返回新状态

返回值: 设置后的模式值

说明: 用于控制辅助栏的显示模式（如 'hide' | 'show' 等）

示例:

// 直接设置模式
molecule.auxiliaryBar.setMode('tabs');

// 使用函数设置模式
molecule.auxiliaryBar.setMode((prevMode) => {
  // 切换模式
  return prevMode === 'default' ? 'tabs' : 'default';
});

setChildren(children: React.ReactNode): void

功能: 设置辅助栏的子内容

参数:

children: React 节点，作为辅助栏的内容

说明: 用于设置辅助栏显示的自定义内容

示例:

// 设置组件内容
import OutlineView from './OutlineView';

// 设置自定义内容
molecule.auxiliaryBar.setChildren(
  <div>
    <h3>自定义辅助栏内容</h3>
    <p>这里可以显示任何 React 组件</p>
  </div>
);

molecule.auxiliaryBar.setChildren(<OutlineView />);

3. 事件监听方法

onTabClick(callback: (key: UniqueId) => void): void

功能: 监听辅助栏标签页标题点击事件

参数:

callback: 回调函数，参数为被点击的标签页 ID

说明: 当用户点击辅助栏标签页标题时触发

示例:

molecule.auxiliaryBar.onTabClick((key) => {
  console.log('点击了标签页:', key);

  // 根据不同的标签页加载不同的内容
  switch (key) {
    case 'outline':
      // 加载大纲视图
      loadOutlineView();
      break;
    case 'timeline':
      // 加载时间线视图
      loadTimelineView();
      break;
  }
});

4. 重置方法

reset(): void

功能: 重置所有状态

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

使用场景: 需要完全重新构建辅助栏时使用

示例:

molecule.auxiliaryBar.reset();

完整使用示例

// 1. 重置辅助栏
molecule.auxiliaryBar.reset();

// 2. 添加辅助栏标签页
molecule.auxiliaryBar.addAuxiliaryBar([
  {
    key: 'outline',
    title: '大纲',
  },
  {
    key: 'timeline',
    title: '时间线',
  },
  {
    key: 'test',
    title: '测试',
  },
]);

// 3. 设置默认激活的标签页
molecule.auxiliaryBar.setActive('outline');

// 4. 设置辅助栏模式
molecule.auxiliaryBar.setMode('tabs'); // 或 'default'

// 5. 设置辅助栏内容
molecule.auxiliaryBar.setChildren(
  <div>
    <h3>代码大纲</h3>
    <OutlineTree />
  </div>
);

// 6. 监听标签页点击事件
molecule.auxiliaryBar.onTabClick((key) => {
  console.log('切换到标签页:', key);

  // 根据标签页切换内容
  switch (key) {
    case 'outline':
      molecule.auxiliaryBar.setChildren(<OutlineView />);
      break;
    case 'timeline':
      molecule.auxiliaryBar.setChildren(<TimelineView />);
      break;
    case 'test':
      molecule.auxiliaryBar.setChildren(<TestView />);
      break;
  }
});

// 7. 获取当前标签页
const currentTab = molecule.auxiliaryBar.getCurrentTab();
if (currentTab) {
  console.log('当前标签页:', currentTab.title);
  console.log('标签页Key:', currentTab.key);
}

// 8. 切换辅助栏模式
function toggleAuxiliaryBarMode() {
  molecule.auxiliaryBar.setMode((prevMode) => {
    return prevMode === 'default' ? 'tabs' : 'default';
  });
}

// 9. 动态切换标签页
function switchToTimeline() {
  molecule.auxiliaryBar.setActive('timeline');
  molecule.auxiliaryBar.setChildren(<TimelineView />);
}

注意事项

标签页 ID 唯一性 每个标签页的 id 必须是唯一的，不能重复
模式控制
- 使用 setMode 可以控制辅助栏的显示模式
- 模式可以是 'default' 或 'tabs'
- 可以通过函数动态计算模式值
内容设置
- 使用 setChildren 可以设置辅助栏显示的内容
- 内容可以是任何 React 组件或元素
标签页切换
- 点击标签页标题会触发 onTabClick 事件
- 需要在事件处理中更新 setChildren 来切换内容
活动状态
- 使用 setActive 可以切换活动的标签页
- 设置为 undefined 可以取消当前活动状态
- 使用 setMode 可以控制辅助栏的显示模式
事件监听
- onTabClick 是事件监听器，可以多次调用注册多个回调
与侧边栏的区别
- 辅助栏位于 IDE 右侧
- 活动栏位于 IDE 左侧
- 辅助栏主要用于显示辅助信息，而不是主要功能
内容更新
- 每次切换标签页时，需要调用 setChildren 更新内容
- 可以在 onTabClick 事件中处理内容切换逻辑

文档信息

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

Molecule Framework - AuxiliaryBarService API 详细文档