feat: Refactor engine structure and add UI customization support
- Refactor to delegate logic to and - Add for manager classes - Implement dynamic styling for Toolbar (color config, CSS vars) - Implement dynamic styling for Dialog (options, CSS vars) - Add example - Add documentation for Toolbar and Dialog - Update demo to showcase new styling features
This commit is contained in:
yuding
95
docs/Dialog.md
Normal file
95
docs/Dialog.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# 弹窗组件 (Dialog)
|
||||
|
||||
BimEngine SDK 提供了可拖拽、可缩放的通用弹窗组件 `DialogManager` (底层基于 `BimDialog`)，支持自定义内容和高度定制的样式。
|
||||
|
||||
## 1. 组件作用
|
||||
|
||||
* 提供浮动的交互窗口。
|
||||
* 支持任意 HTML 内容挂载。
|
||||
* 内置拖拽移动和拖拽缩放功能。
|
||||
* 支持丰富的样式定制接口。
|
||||
|
||||
## 2. 初始化与使用
|
||||
|
||||
通过 `BimEngine` 实例访问：
|
||||
|
||||
```typescript
|
||||
const engine = new BimEngine('container-id');
|
||||
// engine.dialog 即为 DialogManager 实例
|
||||
```
|
||||
|
||||
## 3. 配置项 (DialogOptions)
|
||||
|
||||
`engine.dialog.create(options)` 方法接受以下配置：
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `title` | `string` | `'Dialog'` | 弹窗标题 |
|
||||
| `content` | `string \| HTMLElement` | - | 弹窗内容 |
|
||||
| `width` | `number \| string` | `300` | 宽度 |
|
||||
| `height` | `number \| string` | `'auto'` | 高度 |
|
||||
| `position` | `DialogPosition` | `'center'` | 初始位置 (支持 'center', 'top-left' 等或坐标对象) |
|
||||
| `draggable` | `boolean` | `true` | 是否可拖拽 |
|
||||
| `resizable` | `boolean` | `false` | 是否可调整大小 |
|
||||
| `minWidth` | `number` | `200` | 最小宽度 |
|
||||
| `minHeight` | `number` | `100` | 最小高度 |
|
||||
| `onClose` | `Function` | - | 关闭时的回调 |
|
||||
| `backgroundColor` | `string` | `rgba(17, 17, 17, 0.95)` | 窗体背景色 |
|
||||
| `headerBackgroundColor` | `string` | `#2a2a2a` | 标题栏背景色 |
|
||||
| `titleColor` | `string` | `#fff` | 标题文字颜色 |
|
||||
| `textColor` | `string` | `#ccc` | 内容默认文字颜色 |
|
||||
| `borderColor` | `string` | `#444` | 边框颜色 |
|
||||
|
||||
## 4. 使用案例
|
||||
|
||||
### 案例 1: 创建基本弹窗
|
||||
|
||||
```typescript
|
||||
engine.dialog.create({
|
||||
title: '欢迎',
|
||||
content: 'Hello World!',
|
||||
width: 400
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 2: 创建包含复杂 DOM 的弹窗
|
||||
|
||||
```typescript
|
||||
const div = document.createElement('div');
|
||||
div.innerHTML = '<button>Click Me</button>';
|
||||
div.querySelector('button').onclick = () => alert('Clicked');
|
||||
|
||||
engine.dialog.create({
|
||||
title: '交互组件',
|
||||
content: div,
|
||||
resizable: true
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 3: 定制样式 (红色主题)
|
||||
|
||||
```typescript
|
||||
engine.dialog.create({
|
||||
title: '警告',
|
||||
content: '这是一个红色主题的警告弹窗。',
|
||||
backgroundColor: 'rgba(100, 0, 0, 0.9)', // 深红背景
|
||||
headerBackgroundColor: '#ff0000', // 鲜红标题栏
|
||||
titleColor: '#ffffff',
|
||||
borderColor: '#ff4444'
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 4: 监听关闭事件
|
||||
|
||||
```typescript
|
||||
const dlg = engine.dialog.create({
|
||||
title: '任务',
|
||||
content: '处理中...',
|
||||
onClose: () => {
|
||||
console.log('弹窗已关闭');
|
||||
}
|
||||
});
|
||||
|
||||
// 手动关闭
|
||||
// dlg.close();
|
||||
```
|
||||
130
docs/Toolbar.md
Normal file
130
docs/Toolbar.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# 工具栏组件 (Toolbar)
|
||||
|
||||
BimEngine SDK 提供了功能强大的工具栏组件 `ToolbarManager` (底层基于 `OptBtnGroups`)，支持多级菜单、按钮分组、动态显隐和样式高度定制。
|
||||
|
||||
## 1. 组件作用
|
||||
|
||||
* 提供一个统一的底部操作栏。
|
||||
* 支持按钮分组管理。
|
||||
* 支持层级下拉菜单。
|
||||
* 提供标准的交互反馈（Hover、Active、Disabled）。
|
||||
* 支持完全的样式定制（背景色、图标色、文字色等）。
|
||||
|
||||
## 2. 初始化与使用
|
||||
|
||||
通常通过 `BimEngine` 实例访问：
|
||||
|
||||
```typescript
|
||||
const engine = new BimEngine('container-id');
|
||||
// engine.toolbar 即为 ToolbarManager 实例
|
||||
```
|
||||
|
||||
或者单独使用（不推荐，除非只需工具栏）：
|
||||
|
||||
```typescript
|
||||
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: 添加自定义按钮组和按钮
|
||||
|
||||
```typescript
|
||||
// 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: 添加带下拉菜单的按钮
|
||||
|
||||
```typescript
|
||||
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: 修改工具栏样式
|
||||
|
||||
```typescript
|
||||
engine.toolbar.setColors({
|
||||
backgroundColor: 'rgba(0, 122, 255, 0.9)', // 蓝色背景
|
||||
iconColor: '#ffffff', // 白色图标
|
||||
btnHoverColor: 'rgba(255, 255, 255, 0.2)'
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 4: 控制显隐
|
||||
|
||||
```typescript
|
||||
// 隐藏整个工具栏
|
||||
engine.toolbar.setVisible(false);
|
||||
|
||||
// 隐藏特定按钮
|
||||
engine.toolbar.setButtonVisibility('my-btn', false);
|
||||
|
||||
// 隐藏文字标签
|
||||
engine.toolbar.setShowLabel(false);
|
||||
```
|
||||
Reference in New Issue
Block a user