bim_engine/docs/Toolbar.md

工具栏组件 (Toolbar)

BimEngine SDK 提供了功能强大的工具栏组件 ToolbarManager (底层基于 OptBtnGroups)，支持多级菜单、按钮分组、动态显隐和样式高度定制。

1. 组件作用

• 提供一个统一的底部操作栏。
• 支持按钮分组管理。
• 支持层级下拉菜单。
• 提供标准的交互反馈（Hover、Active、Disabled）。
• 支持完全的样式定制（背景色、图标色、文字色等）。

2. 初始化与使用

通常通过 BimEngine 实例访问：

const engine = new BimEngine('container-id');
// engine.toolbar 即为 ToolbarManager 实例

或者单独使用（不推荐，除非只需工具栏）：

import { ToolbarManager } from 'bim-engine-sdk';
const toolbar = new ToolbarManager(document.getElementById('toolbar-container'));

3. 配置项

ToolbarManager 没有直接的配置项，但它管理着底层的 OptBtnGroups。主要配置在于添加按钮时的 ButtonConfig 和样式设置。

ButtonConfig (按钮配置)

属性	类型	说明
id	string	按钮唯一标识
type	'button' | 'menu'	按钮类型
label	string	按钮显示文字
icon	string	SVG 图标字符串
groupId	string	所属组 ID (必需)
parentId	string	父按钮 ID (可选，用于子菜单)
keepActive	boolean	是否保持激活状态 (Toggle 模式)
disabled	boolean	是否禁用
onClick	Function	点击回调
children	ButtonConfig[]	子按钮数组

ToolbarColors (颜色配置)

用于 setColors 方法。

属性	说明	默认值
backgroundColor	工具栏背景色	rgba(17, 17, 17, 0.88)
btnBackgroundColor	按钮默认背景	transparent
btnHoverColor	按钮 Hover 背景	#444
btnActiveColor	按钮激活背景	rgba(255, 255, 255, 0.15)
iconColor	图标默认颜色	#ccc
iconActiveColor	图标激活颜色	#fff
textColor	文字默认颜色	#ccc
textActiveColor	文字激活颜色	#fff

4. 使用案例

案例 1: 添加自定义按钮组和按钮

// 1. 添加一个新组
engine.toolbar.addGroup('my-group');

// 2. 在该组添加按钮
engine.toolbar.addButton({
    id: 'my-btn',
    groupId: 'my-group',
    type: 'button',
    label: '自定义功能',
    icon: '<svg>...</svg>', // 填入 SVG 内容
    onClick: (btn) => {
        console.log('Clicked!', btn);
    }
});

案例 2: 添加带下拉菜单的按钮

engine.toolbar.addButton({
    id: 'menu-btn',
    groupId: 'my-group',
    type: 'menu',
    label: '更多选项',
    children: [
        {
            id: 'sub-1',
            type: 'button',
            label: '选项 A',
            onClick: () => console.log('A')
        },
        {
            id: 'sub-2',
            type: 'button',
            label: '选项 B',
            onClick: () => console.log('B')
        }
    ]
});

案例 3: 修改工具栏样式

engine.toolbar.setColors({
    backgroundColor: 'rgba(0, 122, 255, 0.9)', // 蓝色背景
    iconColor: '#ffffff', // 白色图标
    btnHoverColor: 'rgba(255, 255, 255, 0.2)'
});

案例 4: 控制显隐

// 隐藏整个工具栏
engine.toolbar.setVisible(false);

// 隐藏特定按钮
engine.toolbar.setButtonVisibility('my-btn', false);

// 隐藏文字标签
engine.toolbar.setShowLabel(false);