161 lines
3.1 KiB
Markdown
161 lines
3.1 KiB
Markdown
|
# OptBtnGroups 组件使用文档
|
|||
|
|
|
|||
|
|
## 📋 组件简介
|
|||
|
|
|
|||
|
|
`OptBtnGroups` 是一个纯 TypeScript 实现的操作按钮组组件，使用原生 DOM API 开发，无任何框架依赖。
|
|||
|
|
|
|||
|
|
## 🎯 核心特性
|
|||
|
|
|
|||
|
|
- ✅ 纯 TypeScript + 原生 DOM API
|
|||
|
|
- ✅ 多组分隔，独立背景块
|
|||
|
|
- ✅ 二级下拉菜单
|
|||
|
|
- ✅ 多选激活状态
|
|||
|
|
- ✅ 可控的标签显示
|
|||
|
|
- ✅ 按钮显隐控制
|
|||
|
|
- ✅ SVG 图标支持
|
|||
|
|
- ✅ 响应式横向滚动
|
|||
|
|
|
|||
|
|
## 🚀 快速开始
|
|||
|
|
|
|||
|
|
### 1. 安装/引入
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<!-- UMD 方式 -->
|
|||
|
|
<script src="./dist/bim-engine-sdk.umd.js"></script>
|
|||
|
|
|
|||
|
|
<script>
|
|||
|
|
const { OptBtnGroups } = window.BimEngineSDK;
|
|||
|
|
</script>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// ES Module 方式
|
|||
|
|
import { OptBtnGroups } from 'bim-engine-sdk';
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 基础使用
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
const optBtnGroups = new OptBtnGroups({
|
|||
|
|
container: 'btn-container', // 容器 ID 或 HTMLElement
|
|||
|
|
showLabel: true, // 显示文字标签
|
|||
|
|
onClick: (payload) => {
|
|||
|
|
console.log('点击了按钮:', payload.button.label);
|
|||
|
|
console.log('操作类型:', payload.action);
|
|||
|
|
if (payload.isActive !== undefined) {
|
|||
|
|
console.log('激活状态:', payload.isActive);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 控制显隐
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
new OptBtnGroups({
|
|||
|
|
container: 'btn-container',
|
|||
|
|
visibility: {
|
|||
|
|
'1-1': true, // 显示
|
|||
|
|
'3-2-1': false // 隐藏
|
|||
|
|
},
|
|||
|
|
onClick: (payload) => console.log(payload)
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 📝 API 文档
|
|||
|
|
|
|||
|
|
### 构造函数参数
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
interface OptBtnGroupsOptions {
|
|||
|
|
container: HTMLElement | string; // 必需：容器
|
|||
|
|
showLabel?: boolean; // 可选：显示标签（默认 true）
|
|||
|
|
visibility?: Record<string, boolean>; // 可选：显隐控制
|
|||
|
|
onClick?: (payload: ClickPayload) => void; // 可选：点击回调
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 点击事件载荷
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
interface ClickPayload {
|
|||
|
|
button: OptButton; // 被点击的按钮
|
|||
|
|
action: 'trigger' | 'activate' | 'deactivate'; // 操作类型
|
|||
|
|
isActive?: boolean; // 激活状态（仅 keepActive 按钮有值）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- `trigger`: 触发型操作（无状态保持）
|
|||
|
|
- `activate`: 激活按钮
|
|||
|
|
- `deactivate`: 取消激活
|
|||
|
|
|
|||
|
|
### 方法
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// 销毁组件
|
|||
|
|
optBtnGroups.destroy();
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🛠️ 二次开发
|
|||
|
|
|
|||
|
|
### 修改内置按钮
|
|||
|
|
|
|||
|
|
编辑 `src/OptBtnGroups.ts` 中的 `defaultGroups`:
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
private readonly defaultGroups: ButtonGroup[] = [
|
|||
|
|
{
|
|||
|
|
id: 'my-group',
|
|||
|
|
buttons: [
|
|||
|
|
{
|
|||
|
|
id: 'home',
|
|||
|
|
label: '首页',
|
|||
|
|
icon: '<svg viewBox="0 0 24 24">...</svg>',
|
|||
|
|
keepActive: true
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
];
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 修改样式
|
|||
|
|
|
|||
|
|
编辑 `src/OptBtnGroups.css`:
|
|||
|
|
|
|||
|
|
```css
|
|||
|
|
.opt-btn {
|
|||
|
|
width: 50px; /* 按钮宽度 */
|
|||
|
|
min-height: 50px; /* 最小高度 */
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.opt-btn.active {
|
|||
|
|
background-color: rgba(255, 255, 255, 0.15); /* 激活背景 */
|
|||
|
|
border-bottom: 2px solid #fff; /* 底部指示条 */
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 📦 构建
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 安装依赖
|
|||
|
|
npm install
|
|||
|
|
|
|||
|
|
# 开发模式
|
|||
|
|
npm run dev
|
|||
|
|
|
|||
|
|
# 构建生产版本
|
|||
|
|
npm run build
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🎨 示例
|
|||
|
|
|
|||
|
|
查看 `demo-optbtn.html` 获取完整示例。
|
|||
|
|
|
|||
|
|
## 🤝 贡献
|
|||
|
|
|
|||
|
|
修改组件时请遵循：
|
|||
|
|
1. 保持中文注释
|
|||
|
|
2. 使用原生 DOM API（无框架依赖）
|
|||
|
|
3. TypeScript 严格模式
|
|||
|
|
4. 测试多种使用场景
|