docs: 文档中文化重命名并添加规范文档
- 将所有英文文档重命名为中文格式 - 新增 AI代码规范模板.md（通用开发规范） - 新增 国际化实现指南.md（i18n 规范） - 重复文档移至 .recycle 目录
This commit is contained in:
yuding
95
.recycle/2026-01-21/docs/Dialog.md
Normal file
95
.recycle/2026-01-21/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();
|
||||
```
|
||||
160
.recycle/2026-01-21/docs/OptBtnGroups.md
Normal file
160
.recycle/2026-01-21/docs/OptBtnGroups.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 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. 测试多种使用场景
|
||||
130
.recycle/2026-01-21/docs/Toolbar.md
Normal file
130
.recycle/2026-01-21/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