548 lines
15 KiB
Markdown
548 lines
15 KiB
Markdown
# 右键菜单功能对接
|
||
|
||
## TL;DR
|
||
|
||
> **Quick Summary**: 对接右键菜单的构件操作功能，包括隐藏、半透明、隔离、显示全部，以及新增"快速选择"子菜单。
|
||
>
|
||
> **Deliverables**:
|
||
> - 国际化文件更新（types.ts, zh-CN.ts, en-US.ts）
|
||
> - Engine 层新增 8 个方法
|
||
> - EngineManager 层新增 8 个代理方法
|
||
> - 右键菜单 handler 实现功能调用
|
||
>
|
||
> **Estimated Effort**: Short (约 30 分钟)
|
||
> **Parallel Execution**: NO - sequential
|
||
> **Critical Path**: Task 1 → Task 2 → Task 3 → Task 4
|
||
|
||
---
|
||
|
||
## Context
|
||
|
||
### Original Request
|
||
对接右键菜单的以下功能：
|
||
1. 隐藏选中构件：`engine.modelToolModule.hideModel(engine.engineStatus.highlightModels)`
|
||
2. 半透明选中构件：`engine.modelToolModule.translucentModel(engine.engineStatus.highlightModels)`
|
||
3. 隔离/隐藏其他构件：`engine.modelToolModule.isolateModel(engine.engineStatus.highlightModels)`
|
||
4. 隔离/半透明其他构件：`engine.modelToolModule.translucentOtherModel(engine.engineStatus.highlightModels)`
|
||
5. 显示所有模型：`engine.modelToolModule.showAllModels()`
|
||
|
||
新增快速选择子菜单：
|
||
6. 选择同类模型：`engine.modelToolModule.batchSelectSameTypeModel(engine.engineStatus.highlightModels)`
|
||
7. 选择同层模型：`engine.modelToolModule.batchSelectSameLevelModel(engine.engineStatus.highlightModels)`
|
||
8. 选择同层同类模型：`engine.modelToolModule.batchSelectSameLevelTypeModel(engine.engineStatus.highlightModels)`
|
||
|
||
### 底层 API 模式
|
||
```typescript
|
||
// 获取选中构件
|
||
const models = engine.engineStatus.highlightModels;
|
||
|
||
// 调用 modelToolModule 方法
|
||
engine.modelToolModule.hideModel(models);
|
||
engine.modelToolModule.translucentModel(models);
|
||
engine.modelToolModule.isolateModel(models);
|
||
engine.modelToolModule.translucentOtherModel(models);
|
||
engine.modelToolModule.showAllModels();
|
||
engine.modelToolModule.batchSelectSameTypeModel(models);
|
||
engine.modelToolModule.batchSelectSameLevelModel(models);
|
||
engine.modelToolModule.batchSelectSameLevelTypeModel(models);
|
||
```
|
||
|
||
---
|
||
|
||
## Work Objectives
|
||
|
||
### Core Objective
|
||
将底层引擎的构件操作 API 对接到右键菜单，实现完整的构件隐藏、半透明、隔离和快速选择功能。
|
||
|
||
### Concrete Deliverables
|
||
- `src/locales/types.ts` - 添加 4 个新字段
|
||
- `src/locales/zh-CN.ts` - 添加中文翻译
|
||
- `src/locales/en-US.ts` - 添加英文翻译
|
||
- `src/components/engine/index.ts` - 添加 8 个方法
|
||
- `src/managers/engine-manager.ts` - 添加 8 个代理方法 + 更新右键菜单 handler
|
||
|
||
### Definition of Done
|
||
- [x] 右键选中构件时，所有菜单功能可正常调用
|
||
- [x] 快速选择子菜单正确显示三个选项
|
||
- [x] 构建成功：`npm run build`
|
||
|
||
### Must Have
|
||
- 所有 8 个底层 API 都要对接
|
||
- 国际化支持中英文
|
||
- 保持现有代码风格
|
||
|
||
### Must NOT Have (Guardrails)
|
||
- 不要修改底层引擎 API
|
||
- 不要添加额外的 UI 组件
|
||
- 不要修改菜单的显示逻辑
|
||
|
||
---
|
||
|
||
## Verification Strategy
|
||
|
||
### Test Decision
|
||
- **Infrastructure exists**: NO
|
||
- **User wants tests**: Manual-only
|
||
- **QA approach**: Manual verification
|
||
|
||
---
|
||
|
||
## TODOs
|
||
|
||
- [x] 1. 更新国际化文件
|
||
|
||
**What to do**:
|
||
1. 在 `src/locales/types.ts` 的 `menu` 对象中添加：
|
||
```typescript
|
||
quickSelect: string;
|
||
selectSameType: string;
|
||
selectSameLevel: string;
|
||
selectSameLevelType: string;
|
||
```
|
||
2. 在 `src/locales/zh-CN.ts` 的 `menu` 对象中添加：
|
||
```typescript
|
||
quickSelect: '快速选择',
|
||
selectSameType: '选择同类模型',
|
||
selectSameLevel: '选择同层模型',
|
||
selectSameLevelType: '选择同层同类模型'
|
||
```
|
||
3. 在 `src/locales/en-US.ts` 的 `menu` 对象中添加：
|
||
```typescript
|
||
quickSelect: 'Quick Select',
|
||
selectSameType: 'Select Same Type',
|
||
selectSameLevel: 'Select Same Level',
|
||
selectSameLevelType: 'Select Same Level & Type'
|
||
```
|
||
|
||
**Must NOT do**:
|
||
- 不要修改其他现有字段
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`coding-standards`]
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: NO
|
||
- **Parallel Group**: Sequential
|
||
- **Blocks**: Task 2, 3, 4
|
||
- **Blocked By**: None
|
||
|
||
**References**:
|
||
- `src/locales/types.ts:53-64` - 现有 menu 类型定义
|
||
- `src/locales/zh-CN.ts:34-45` - 现有中文翻译
|
||
- `src/locales/en-US.ts:34-45` - 现有英文翻译
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] TypeScript 无类型错误
|
||
- [ ] 三个文件都已更新
|
||
|
||
**Commit**: NO (与 Task 2-4 一起提交)
|
||
|
||
---
|
||
|
||
- [x] 2. Engine 层添加构件操作方法
|
||
|
||
**What to do**:
|
||
在 `src/components/engine/index.ts` 中添加以下 8 个公共方法（在路径漫游区域之后、destroy 之前）：
|
||
|
||
```typescript
|
||
// ==================== 构件操作 ====================
|
||
|
||
/**
|
||
* 隐藏选中构件
|
||
*/
|
||
public hideSelectedModels(): void {
|
||
if (!this._isInitialized || !this.engine?.modelToolModule) {
|
||
console.warn('[Engine] Cannot hide models: engine not initialized.');
|
||
return;
|
||
}
|
||
const models = this.engine.engineStatus?.highlightModels;
|
||
if (models) {
|
||
this.engine.modelToolModule.hideModel(models);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 半透明选中构件
|
||
*/
|
||
public translucentSelectedModels(): void {
|
||
if (!this._isInitialized || !this.engine?.modelToolModule) {
|
||
console.warn('[Engine] Cannot translucent models: engine not initialized.');
|
||
return;
|
||
}
|
||
const models = this.engine.engineStatus?.highlightModels;
|
||
if (models) {
|
||
this.engine.modelToolModule.translucentModel(models);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 隔离选中构件（隐藏其他）
|
||
*/
|
||
public isolateSelectedModels(): void {
|
||
if (!this._isInitialized || !this.engine?.modelToolModule) {
|
||
console.warn('[Engine] Cannot isolate models: engine not initialized.');
|
||
return;
|
||
}
|
||
const models = this.engine.engineStatus?.highlightModels;
|
||
if (models) {
|
||
this.engine.modelToolModule.isolateModel(models);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 半透明其他构件
|
||
*/
|
||
public translucentOtherModels(): void {
|
||
if (!this._isInitialized || !this.engine?.modelToolModule) {
|
||
console.warn('[Engine] Cannot translucent other models: engine not initialized.');
|
||
return;
|
||
}
|
||
const models = this.engine.engineStatus?.highlightModels;
|
||
if (models) {
|
||
this.engine.modelToolModule.translucentOtherModel(models);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 显示所有模型
|
||
*/
|
||
public showAllModels(): void {
|
||
if (!this._isInitialized || !this.engine?.modelToolModule) {
|
||
console.warn('[Engine] Cannot show all models: engine not initialized.');
|
||
return;
|
||
}
|
||
this.engine.modelToolModule.showAllModels();
|
||
}
|
||
|
||
/**
|
||
* 批量选择同类模型
|
||
*/
|
||
public batchSelectSameTypeModel(): void {
|
||
if (!this._isInitialized || !this.engine?.modelToolModule) {
|
||
console.warn('[Engine] Cannot batch select: engine not initialized.');
|
||
return;
|
||
}
|
||
const models = this.engine.engineStatus?.highlightModels;
|
||
if (models) {
|
||
this.engine.modelToolModule.batchSelectSameTypeModel(models);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 批量选择同层模型
|
||
*/
|
||
public batchSelectSameLevelModel(): void {
|
||
if (!this._isInitialized || !this.engine?.modelToolModule) {
|
||
console.warn('[Engine] Cannot batch select: engine not initialized.');
|
||
return;
|
||
}
|
||
const models = this.engine.engineStatus?.highlightModels;
|
||
if (models) {
|
||
this.engine.modelToolModule.batchSelectSameLevelModel(models);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 批量选择同层同类模型
|
||
*/
|
||
public batchSelectSameLevelTypeModel(): void {
|
||
if (!this._isInitialized || !this.engine?.modelToolModule) {
|
||
console.warn('[Engine] Cannot batch select: engine not initialized.');
|
||
return;
|
||
}
|
||
const models = this.engine.engineStatus?.highlightModels;
|
||
if (models) {
|
||
this.engine.modelToolModule.batchSelectSameLevelTypeModel(models);
|
||
}
|
||
}
|
||
|
||
// ==================== 结束：构件操作 ====================
|
||
```
|
||
|
||
**Must NOT do**:
|
||
- 不要修改现有方法
|
||
- 不要修改 `fitSectionBoxToModel` 方法
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`coding-standards`]
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: NO
|
||
- **Parallel Group**: Sequential
|
||
- **Blocks**: Task 3
|
||
- **Blocked By**: Task 1
|
||
|
||
**References**:
|
||
- `src/components/engine/index.ts:496-506` - `fitSectionBoxToModel` 参考模式（使用 highlightModels）
|
||
- `src/components/engine/index.ts:431-491` - 路径漫游方法区域（在此之后添加）
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 8 个方法都已添加
|
||
- [ ] 方法有 JSDoc 注释
|
||
- [ ] 使用项目规范的区域注释标记
|
||
|
||
**Commit**: NO (与其他 Task 一起提交)
|
||
|
||
---
|
||
|
||
- [x] 3. EngineManager 添加代理方法
|
||
|
||
**What to do**:
|
||
在 `src/managers/engine-manager.ts` 中添加 8 个代理方法（在路径漫游区域之后、destroy 之前）：
|
||
|
||
```typescript
|
||
// ==================== 构件操作 ====================
|
||
|
||
/**
|
||
* 隐藏选中构件
|
||
*/
|
||
public hideSelectedModels(): void {
|
||
this.engineInstance?.hideSelectedModels();
|
||
}
|
||
|
||
/**
|
||
* 半透明选中构件
|
||
*/
|
||
public translucentSelectedModels(): void {
|
||
this.engineInstance?.translucentSelectedModels();
|
||
}
|
||
|
||
/**
|
||
* 隔离选中构件（隐藏其他）
|
||
*/
|
||
public isolateSelectedModels(): void {
|
||
this.engineInstance?.isolateSelectedModels();
|
||
}
|
||
|
||
/**
|
||
* 半透明其他构件
|
||
*/
|
||
public translucentOtherModels(): void {
|
||
this.engineInstance?.translucentOtherModels();
|
||
}
|
||
|
||
/**
|
||
* 显示所有模型
|
||
*/
|
||
public showAllModels(): void {
|
||
this.engineInstance?.showAllModels();
|
||
}
|
||
|
||
/**
|
||
* 批量选择同类模型
|
||
*/
|
||
public batchSelectSameTypeModel(): void {
|
||
this.engineInstance?.batchSelectSameTypeModel();
|
||
}
|
||
|
||
/**
|
||
* 批量选择同层模型
|
||
*/
|
||
public batchSelectSameLevelModel(): void {
|
||
this.engineInstance?.batchSelectSameLevelModel();
|
||
}
|
||
|
||
/**
|
||
* 批量选择同层同类模型
|
||
*/
|
||
public batchSelectSameLevelTypeModel(): void {
|
||
this.engineInstance?.batchSelectSameLevelTypeModel();
|
||
}
|
||
|
||
// ==================== 结束：构件操作 ====================
|
||
```
|
||
|
||
**Must NOT do**:
|
||
- 不要修改现有方法
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`coding-standards`]
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: NO
|
||
- **Parallel Group**: Sequential
|
||
- **Blocks**: Task 4
|
||
- **Blocked By**: Task 2
|
||
|
||
**References**:
|
||
- `src/managers/engine-manager.ts:431-492` - 路径漫游代理方法区域
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 8 个代理方法都已添加
|
||
- [ ] 方法有 JSDoc 注释
|
||
|
||
**Commit**: NO (与其他 Task 一起提交)
|
||
|
||
---
|
||
|
||
- [x] 4. 更新右键菜单 Handler
|
||
|
||
**What to do**:
|
||
在 `src/managers/engine-manager.ts` 的 `registerHandler` 回调中：
|
||
|
||
1. **替换隐藏选中构件的 onClick**（约第 78-81 行）：
|
||
```typescript
|
||
onClick: () => {
|
||
this.hideSelectedModels();
|
||
this.rightKey?.hide();
|
||
}
|
||
```
|
||
|
||
2. **替换半透明选中构件的 onClick**（约第 90-93 行）：
|
||
```typescript
|
||
onClick: () => {
|
||
this.translucentSelectedModels();
|
||
this.rightKey?.hide();
|
||
}
|
||
```
|
||
|
||
3. **替换隔离-隐藏其他的 onClick**（约第 107-110 行）：
|
||
```typescript
|
||
onClick: () => {
|
||
this.isolateSelectedModels();
|
||
this.rightKey?.hide();
|
||
}
|
||
```
|
||
|
||
4. **替换隔离-半透明其他的 onClick**（约第 114-117 行）：
|
||
```typescript
|
||
onClick: () => {
|
||
this.translucentOtherModels();
|
||
this.rightKey?.hide();
|
||
}
|
||
```
|
||
|
||
5. **替换显示全部的 onClick**（约第 142-144 行）：
|
||
```typescript
|
||
onClick: () => {
|
||
this.showAllModels();
|
||
this.rightKey?.hide();
|
||
}
|
||
```
|
||
|
||
6. **在隔离选中构件菜单项之后（order: 4 之后），添加快速选择子菜单**（order: 5，将剖切盒适应改为 order: 6，显示全部改为 order: 7）：
|
||
```typescript
|
||
// 5. 快速选择（带子菜单）
|
||
items.push({
|
||
id: 'quickSelect',
|
||
label: 'menu.quickSelect',
|
||
group: 'component',
|
||
order: 5,
|
||
children: [
|
||
{
|
||
id: 'selectSameType',
|
||
label: 'menu.selectSameType',
|
||
onClick: () => {
|
||
this.batchSelectSameTypeModel();
|
||
this.rightKey?.hide();
|
||
}
|
||
},
|
||
{
|
||
id: 'selectSameLevel',
|
||
label: 'menu.selectSameLevel',
|
||
onClick: () => {
|
||
this.batchSelectSameLevelModel();
|
||
this.rightKey?.hide();
|
||
}
|
||
},
|
||
{
|
||
id: 'selectSameLevelType',
|
||
label: 'menu.selectSameLevelType',
|
||
onClick: () => {
|
||
this.batchSelectSameLevelTypeModel();
|
||
this.rightKey?.hide();
|
||
}
|
||
}
|
||
]
|
||
});
|
||
```
|
||
|
||
7. **更新剖切盒适应的 order 为 6**
|
||
|
||
8. **更新显示全部的 order 为 7**
|
||
|
||
**Must NOT do**:
|
||
- 不要修改菜单项的 id 和 label（除了新增的）
|
||
- 不要修改 group 分组逻辑
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`coding-standards`]
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: NO
|
||
- **Parallel Group**: Sequential (final task)
|
||
- **Blocks**: None
|
||
- **Blocked By**: Task 3
|
||
|
||
**References**:
|
||
- `src/managers/engine-manager.ts:53-149` - 现有右键菜单 handler
|
||
- `src/managers/engine-manager.ts:96-121` - 隔离子菜单结构参考
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有 console.log 占位符已替换为实际方法调用
|
||
- [ ] 快速选择子菜单正确添加
|
||
- [ ] 菜单项 order 正确排序
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(menu): implement right-click menu functions for model operations`
|
||
- Files:
|
||
- `src/locales/types.ts`
|
||
- `src/locales/zh-CN.ts`
|
||
- `src/locales/en-US.ts`
|
||
- `src/components/engine/index.ts`
|
||
- `src/managers/engine-manager.ts`
|
||
- Pre-commit: `npm run build`
|
||
|
||
---
|
||
|
||
- [x] 5. 构建验证
|
||
|
||
**What to do**:
|
||
- 运行 `npm run build` 确保构建成功
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: []
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: NO
|
||
- **Blocks**: None
|
||
- **Blocked By**: Task 4
|
||
|
||
**Acceptance Criteria**:
|
||
```bash
|
||
npm run build
|
||
# 预期: 构建成功，无错误
|
||
```
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
## Commit Strategy
|
||
|
||
| After Task | Message | Files | Verification |
|
||
|------------|---------|-------|--------------|
|
||
| 4 | `feat(menu): implement right-click menu functions for model operations` | types.ts, zh-CN.ts, en-US.ts, engine/index.ts, engine-manager.ts | npm run build |
|
||
|
||
---
|
||
|
||
## Success Criteria
|
||
|
||
### Verification Commands
|
||
```bash
|
||
npm run build # Expected: Build successful
|
||
```
|
||
|
||
### Final Checklist
|
||
- [x] 国际化文件已更新（3 个文件）
|
||
- [x] Engine 层添加 8 个方法
|
||
- [x] EngineManager 层添加 8 个代理方法
|
||
- [x] 右键菜单 handler 已更新
|
||
- [x] 快速选择子菜单已添加
|
||
- [x] 构建成功
|