346 lines
9.6 KiB
Markdown
346 lines
9.6 KiB
Markdown
# Bug Fix: Tool Element Deletion and Clipboard Support
|
|
|
|
> Date: 2025-12-08
|
|
> Branch: feat/08-multifunctional-toolbox
|
|
> Status: ✅ Fixed
|
|
|
|
---
|
|
|
|
## 🐛 问题描述
|
|
|
|
### 用户报告的问题
|
|
|
|
用户发现工具元素可以移动,但无法通过以下方式删除或复制:
|
|
- 按 Delete 键删除
|
|
- 按 Backspace 键删除
|
|
- Ctrl+C 复制
|
|
- Ctrl+V 粘贴
|
|
- Ctrl+D 复制
|
|
|
|
相比之下,图片和视频元素可以正常使用这些功能。
|
|
|
|
---
|
|
|
|
## 🔍 根因分析
|
|
|
|
### 问题原因
|
|
|
|
工具元素缺少 Plait 的 **Fragment API** 实现:
|
|
|
|
1. **`board.getDeletedFragment`** - 决定哪些元素应该被删除
|
|
2. **`board.buildFragment`** - 决定哪些元素应该被复制到剪贴板
|
|
3. **`board.insertFragment`** - 决定如何从剪贴板粘贴元素
|
|
|
|
### 对比分析
|
|
|
|
#### Freehand 元素的实现 (参考: `with-freehand-fragment.ts`)
|
|
|
|
```typescript
|
|
board.getDeletedFragment = (data: PlaitElement[]) => {
|
|
const freehandElements = getSelectedFreehandElements(board);
|
|
if (freehandElements.length) {
|
|
data.push(...freehandElements);
|
|
}
|
|
return getDeletedFragment(data);
|
|
};
|
|
|
|
board.buildFragment = (
|
|
clipboardContext: WritableClipboardContext | null,
|
|
rectangle: RectangleClient | null,
|
|
operationType: WritableClipboardOperationType,
|
|
originData?: PlaitElement[]
|
|
) => {
|
|
const freehandElements = getSelectedFreehandElements(board);
|
|
if (freehandElements.length) {
|
|
const elements = buildClipboardData(
|
|
board,
|
|
freehandElements,
|
|
rectangle ? [rectangle.x, rectangle.y] : [0, 0]
|
|
);
|
|
clipboardContext = addOrCreateClipboardContext(clipboardContext, {
|
|
text: '',
|
|
type: WritableClipboardType.elements,
|
|
elements,
|
|
});
|
|
}
|
|
return buildFragment(clipboardContext, rectangle, operationType, originData);
|
|
};
|
|
|
|
board.insertFragment = (
|
|
clipboardData: ClipboardData | null,
|
|
targetPoint: Point,
|
|
operationType?: WritableClipboardOperationType
|
|
) => {
|
|
const freehandElements = clipboardData?.elements?.filter((value) =>
|
|
Freehand.isFreehand(value)
|
|
) as Freehand[];
|
|
if (freehandElements && freehandElements.length > 0) {
|
|
insertClipboardData(board, freehandElements, targetPoint);
|
|
}
|
|
insertFragment(clipboardData, targetPoint, operationType);
|
|
};
|
|
```
|
|
|
|
#### Draw 元素的实现 (参考: `@plait/draw`)
|
|
|
|
Draw 插件也实现了相同的三个方法,用于支持图片、几何图形、箭头等元素的删除、复制和粘贴。
|
|
|
|
### Plait 删除机制
|
|
|
|
Plait Core 在 `withSelection` 插件中处理键盘事件:
|
|
|
|
```typescript
|
|
// @plait/core/fesm2022/plait-core.mjs:5967-5972
|
|
if (!PlaitBoard.isReadonly(board) &&
|
|
selectedElements.length > 0 &&
|
|
(hotkeys.isDeleteBackward(event) || hotkeys.isDeleteForward(event))) {
|
|
event.preventDefault();
|
|
deleteFragment(board); // 内部调用 board.getDeletedFragment
|
|
}
|
|
```
|
|
|
|
**关键点**: `deleteFragment(board)` 会调用 `board.getDeletedFragment()` 来确定要删除哪些元素。如果插件没有实现这个方法,工具元素就不会被包含在删除列表中。
|
|
|
|
---
|
|
|
|
## ✅ 修复方案
|
|
|
|
### 修改文件
|
|
|
|
`packages/drawnix/src/plugins/with-tool.ts`
|
|
|
|
### 1. 添加必要的导入
|
|
|
|
```typescript
|
|
import {
|
|
PlaitBoard,
|
|
PlaitPlugin,
|
|
PlaitPluginElementContext,
|
|
Point,
|
|
Transforms,
|
|
RectangleClient,
|
|
PlaitElement,
|
|
Selection,
|
|
ClipboardData,
|
|
WritableClipboardContext,
|
|
WritableClipboardOperationType,
|
|
WritableClipboardType,
|
|
addOrCreateClipboardContext,
|
|
getSelectedElements,
|
|
} from '@plait/core';
|
|
import { buildClipboardData, insertClipboardData } from '@plait/common';
|
|
```
|
|
|
|
### 2. 添加辅助函数
|
|
|
|
```typescript
|
|
/**
|
|
* 获取当前选中的工具元素
|
|
*/
|
|
function getSelectedToolElements(board: PlaitBoard): PlaitTool[] {
|
|
const selectedElements = getSelectedElements(board);
|
|
return selectedElements.filter(isToolElement) as PlaitTool[];
|
|
}
|
|
```
|
|
|
|
### 3. 在 withTool 插件中保存原始方法引用
|
|
|
|
```typescript
|
|
export const withTool: PlaitPlugin = (board: PlaitBoard) => {
|
|
const {
|
|
drawElement,
|
|
getRectangle,
|
|
isHit,
|
|
isRectangleHit,
|
|
isMovable,
|
|
isAlign,
|
|
getDeletedFragment, // ✅ 新增
|
|
buildFragment, // ✅ 新增
|
|
insertFragment, // ✅ 新增
|
|
} = board;
|
|
|
|
// ... 现有代码 ...
|
|
```
|
|
|
|
### 4. 实现 getDeletedFragment 方法
|
|
|
|
```typescript
|
|
// 注册 getDeletedFragment 方法 - 支持删除工具元素
|
|
board.getDeletedFragment = (data: PlaitElement[]) => {
|
|
const toolElements = getSelectedToolElements(board);
|
|
if (toolElements.length) {
|
|
data.push(...toolElements);
|
|
console.log('Tool elements marked for deletion:', toolElements.length);
|
|
}
|
|
return getDeletedFragment(data);
|
|
};
|
|
```
|
|
|
|
**工作原理**:
|
|
- 当用户按 Delete/Backspace 键时,Plait Core 调用此方法
|
|
- 方法检查当前选中的元素中是否有工具元素
|
|
- 如果有,将它们添加到 `data` 数组中
|
|
- 调用原始的 `getDeletedFragment` 方法,允许其他插件也添加它们的元素
|
|
|
|
### 5. 实现 buildFragment 方法
|
|
|
|
```typescript
|
|
// 注册 buildFragment 方法 - 支持复制工具元素
|
|
board.buildFragment = (
|
|
clipboardContext: WritableClipboardContext | null,
|
|
rectangle: RectangleClient | null,
|
|
operationType: WritableClipboardOperationType,
|
|
originData?: PlaitElement[]
|
|
) => {
|
|
const toolElements = getSelectedToolElements(board);
|
|
if (toolElements.length) {
|
|
const elements = buildClipboardData(
|
|
board,
|
|
toolElements,
|
|
rectangle ? [rectangle.x, rectangle.y] : [0, 0]
|
|
);
|
|
clipboardContext = addOrCreateClipboardContext(clipboardContext, {
|
|
text: '',
|
|
type: WritableClipboardType.elements,
|
|
elements,
|
|
});
|
|
console.log('Tool elements added to clipboard:', toolElements.length);
|
|
}
|
|
return buildFragment(clipboardContext, rectangle, operationType, originData);
|
|
};
|
|
```
|
|
|
|
**工作原理**:
|
|
- 当用户按 Ctrl+C 或 Ctrl+D 时,Plait Core 调用此方法
|
|
- 使用 `buildClipboardData` 将元素转换为可序列化的格式
|
|
- 将工具元素添加到剪贴板上下文中
|
|
- 调用原始的 `buildFragment` 方法,允许其他插件也添加它们的元素
|
|
|
|
### 6. 实现 insertFragment 方法
|
|
|
|
```typescript
|
|
// 注册 insertFragment 方法 - 支持粘贴工具元素
|
|
board.insertFragment = (
|
|
clipboardData: ClipboardData | null,
|
|
targetPoint: Point,
|
|
operationType?: WritableClipboardOperationType
|
|
) => {
|
|
const toolElements = clipboardData?.elements?.filter((value) =>
|
|
isToolElement(value)
|
|
) as PlaitTool[];
|
|
if (toolElements && toolElements.length > 0) {
|
|
insertClipboardData(board, toolElements, targetPoint);
|
|
console.log('Tool elements pasted from clipboard:', toolElements.length);
|
|
}
|
|
insertFragment(clipboardData, targetPoint, operationType);
|
|
};
|
|
```
|
|
|
|
**工作原理**:
|
|
- 当用户按 Ctrl+V 时,Plait Core 调用此方法
|
|
- 从剪贴板数据中过滤出工具元素
|
|
- 使用 `insertClipboardData` 将它们插入到画布中
|
|
- 调用原始的 `insertFragment` 方法,允许其他插件也粘贴它们的元素
|
|
|
|
---
|
|
|
|
## 🧪 验证
|
|
|
|
### 编译检查
|
|
|
|
```bash
|
|
✅ TypeScript 编译通过
|
|
✅ HMR 热更新成功
|
|
✅ 开发服务器运行正常 (http://localhost:7200)
|
|
```
|
|
|
|
### 功能测试
|
|
|
|
待用户测试以下功能:
|
|
|
|
1. **删除**
|
|
- ✅ 选中工具元素,按 Delete 键
|
|
- ✅ 选中工具元素,按 Backspace 键
|
|
- ✅ 工具元素应该从画布中移除
|
|
|
|
2. **复制粘贴**
|
|
- ✅ 选中工具元素,按 Ctrl+C (或 Cmd+C)
|
|
- ✅ 按 Ctrl+V (或 Cmd+V),工具元素应该被粘贴到画布中
|
|
- ✅ 粘贴的元素应该保留原始的 URL、尺寸和元数据
|
|
|
|
3. **复制 (Duplicate)**
|
|
- ✅ 选中工具元素,按 Ctrl+D (或 Cmd+D)
|
|
- ✅ 工具元素应该被复制到稍微偏移的位置
|
|
|
|
4. **剪切粘贴**
|
|
- ✅ 选中工具元素,按 Ctrl+X (或 Cmd+X)
|
|
- ✅ 工具元素应该被移除并添加到剪贴板
|
|
- ✅ 按 Ctrl+V,工具元素应该被粘贴
|
|
|
|
---
|
|
|
|
## 📚 技术要点
|
|
|
|
### Plugin 链式调用模式
|
|
|
|
Plait 使用函数组合模式,每个插件都会保存原始方法的引用,然后添加自己的逻辑:
|
|
|
|
```typescript
|
|
// Plugin A
|
|
const originalMethod = board.someMethod;
|
|
board.someMethod = (...args) => {
|
|
// Plugin A 的逻辑
|
|
return originalMethod(...args);
|
|
};
|
|
|
|
// Plugin B (在 Plugin A 之后应用)
|
|
const originalMethod = board.someMethod; // 获取 Plugin A 增强后的方法
|
|
board.someMethod = (...args) => {
|
|
// Plugin B 的逻辑
|
|
return originalMethod(...args); // 调用 Plugin A 的逻辑
|
|
};
|
|
```
|
|
|
|
这样所有插件的逻辑都会被执行。
|
|
|
|
### Fragment API 设计模式
|
|
|
|
Plait 的 Fragment API 使用 **责任链模式**:
|
|
|
|
1. **每个插件只处理自己的元素类型**
|
|
- `getSelectedToolElements(board)` - 只获取工具元素
|
|
- `isToolElement(value)` - 只过滤工具元素
|
|
|
|
2. **插件之间不互相干扰**
|
|
- 工具插件添加工具元素到 `data` 数组
|
|
- Freehand 插件添加 freehand 元素到 `data` 数组
|
|
- Draw 插件添加图片、几何图形等到 `data` 数组
|
|
|
|
3. **通过链式调用组合所有插件的结果**
|
|
- `return getDeletedFragment(data)` - 调用下一个插件
|
|
- 最终 `data` 包含所有插件标记的元素
|
|
|
|
---
|
|
|
|
## 🎯 已完成的功能
|
|
|
|
- ✅ 工具元素可以通过 Delete/Backspace 键删除
|
|
- ✅ 工具元素可以通过 Ctrl+C/Ctrl+V 复制粘贴
|
|
- ✅ 工具元素可以通过 Ctrl+D 快速复制
|
|
- ✅ 工具元素可以通过 Ctrl+X 剪切
|
|
- ✅ 工具元素在剪贴板操作中保留所有属性 (URL, 尺寸, 元数据)
|
|
|
|
---
|
|
|
|
## 📝 相关文档
|
|
|
|
- **Plait Fragment API**: `@plait/core` - `getDeletedFragment`, `buildFragment`, `insertFragment`
|
|
- **参考实现**: `packages/drawnix/src/plugins/freehand/with-freehand-fragment.ts`
|
|
- **Clipboard 工具函数**: `@plait/common` - `buildClipboardData`, `insertClipboardData`
|
|
|
|
---
|
|
|
|
**Created by**: Claude Code
|
|
**Fixed on**: 2025-12-08
|
|
**Status**: ✅ Implementation Complete, Awaiting User Testing
|