工具栏按钮扩展

本文说明如何向右下角工具栏追加外部业务按钮，以及如何设置 toggle 按钮激活状态。

1. 功能说明

3D SDK 默认会在右下角显示工具栏，用于承载设置、测量、剖切、漫游等快捷入口。

外部业务可以通过 BimEngine 实例追加自定义按钮：

• addRadialToolbarButton(item)：追加一个按钮。
• setRadialToolbarButtonActive(id, active)：设置 toggle 按钮激活状态。

该能力只负责追加按钮和设置状态，不提供删除按钮能力。

2. 前置条件

创建 BimEngine 时需要启用工具栏：

const bimEngine = new BimEngine('bim-container', {
  locale: 'zh-CN',
  theme: 'dark',
  enableRadialToolbar: true,
});

如果 enableRadialToolbar 为 false，addRadialToolbarButton() 和 setRadialToolbarButtonActive() 会静默忽略。

3. 类型定义

interface RadialMenuItem {
  /** 按钮唯一标识 */
  id: string;
  /** 国际化 key 或默认文本 */
  label: string;
  /** 直接显示的文本，优先级高于 label 的国际化翻译 */
  title?: string;
  /** SVG 字符串，或其他可放入 innerHTML 的图标字符串 */
  icon?: string;
  /** 普通按钮点击回调 */
  onClick?: (item: RadialMenuItem) => void;
  /** 是否为开关按钮 */
  isToggle?: boolean;
  /** 初始激活状态，仅 isToggle=true 时有效 */
  isActive?: boolean;
  /** 开关按钮状态变化回调，仅 isToggle=true 时有效 */
  onToggle?: (nextActive: boolean, item: RadialMenuItem) => void;
}

TypeScript 使用方式：

import type { RadialMenuItem } from 'iflow-engine';

4. 添加普通按钮

import type { RadialMenuItem } from 'iflow-engine';

const customButton: RadialMenuItem = {
  id: 'business-action',
  label: '业务操作',
  title: '业务操作',
  icon: '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M12 2l9 20H3L12 2z"/></svg>',
  onClick: () => {
    console.log('点击业务操作');
  },
};

bimEngine.addRadialToolbarButton(customButton);

说明：

• id 必须唯一，避免与内置按钮或其他业务按钮冲突。
• title 会作为按钮 tooltip 和无障碍标签。
• 如果不传 icon，按钮会显示 label 或 title 的首字符。

5. 添加开关按钮

bimEngine.addRadialToolbarButton({
  id: 'business-toggle',
  label: '业务开关',
  title: '业务开关',
  icon: '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="8" fill="currentColor"/></svg>',
  isToggle: true,
  isActive: false,
  onToggle: (active) => {
    console.log('业务开关状态:', active);
  },
});

说明：

• isToggle: true 表示按钮有激活态。
• 用户点击按钮时，SDK 会自动切换内部激活状态，并调用 onToggle(active, item)。
• 如果需要外部业务主动同步按钮状态，使用 setRadialToolbarButtonActive()。

6. 设置开关按钮激活状态

bimEngine.setRadialToolbarButtonActive('business-toggle', true);
bimEngine.setRadialToolbarButtonActive('business-toggle', false);

说明：

• 该方法只对 isToggle: true 的按钮生效。
• 如果传入的 id 不存在，会静默忽略。
• 如果按钮不是 toggle 按钮，会静默忽略。

7. API 参考

7.1 addRadialToolbarButton(item)

bimEngine.addRadialToolbarButton(item: RadialMenuItem): void

参数：

| 参数 | 类型 | 必填 | 说明 | |---|---|---:|---| | item | RadialMenuItem | 是 | 工具栏按钮配置。 |

行为：

• 将按钮追加到右下角工具栏末尾。
• 追加后会重新渲染工具栏布局。
• 按钮数量较多时，工具栏会自动分环展示。

7.2 setRadialToolbarButtonActive(id, active)

bimEngine.setRadialToolbarButtonActive(id: string, active: boolean): void

参数：

| 参数 | 类型 | 必填 | 说明 | |---|---|---:|---| | id | string | 是 | 按钮 ID。 | | active | boolean | 是 | 是否激活。 |

行为：

• 更新指定 toggle 按钮的激活样式。
• 同步按钮内部 isActive 状态。
• 不会主动触发该按钮的 onToggle 回调。

8. 完整示例

import { BimEngine } from 'iflow-engine';
import type { RadialMenuItem } from 'iflow-engine';

const bimEngine = new BimEngine('bim-container', {
  locale: 'zh-CN',
  theme: 'dark',
  enableRadialToolbar: true,
});

bimEngine.engine?.initialize({
  backgroundColor: 0x333333,
  showViewCube: true,
});

const isolateButton: RadialMenuItem = {
  id: 'business-isolate-mode',
  label: '隔离模式',
  title: '隔离模式',
  icon: '<svg viewBox="0 0 24 24"><rect x="5" y="5" width="14" height="14" rx="2" fill="currentColor"/></svg>',
  isToggle: true,
  isActive: false,
  onToggle: (active) => {
    if (active) {
      console.log('开启业务隔离模式');
      return;
    }

    console.log('关闭业务隔离模式');
    bimEngine.engine?.showAllModels();
  },
};

bimEngine.addRadialToolbarButton(isolateButton);

// 外部业务状态变化时，同步按钮激活态
function setBusinessIsolateMode(active: boolean) {
  bimEngine.setRadialToolbarButtonActive('business-isolate-mode', active);
}

9. 注意事项

• 当前只支持追加按钮，不支持删除按钮。
• 建议业务按钮 ID 增加业务前缀，例如 business-xxx，避免与内置按钮冲突。
• icon 建议使用简洁 SVG，并使用 currentColor 继承主题色。
• setRadialToolbarButtonActive() 只更新按钮状态，不会触发 onToggle。
• 关闭工具栏配置后，相关 API 不会报错，但不会产生实际效果。