178 lines
5.8 KiB
Markdown
178 lines
5.8 KiB
Markdown
# Canvas 场景下使用 Driver.js 的指南
|
||
|
||
## 概述
|
||
|
||
Driver.js 可以用于 Canvas 场景，但有一些限制和特殊处理方式。
|
||
|
||
## Driver.js 在 Canvas 中的限制
|
||
|
||
1. **无法直接高亮 Canvas 内部元素**：Driver.js 只能高亮 DOM 元素，而 Canvas 内部绘制的内容（如设备图标、点标记等）不是 DOM 元素，无法直接高亮。
|
||
|
||
2. **可以高亮 Canvas 元素本身**：可以高亮整个 `<canvas>` 标签，但无法精确定位到 Canvas 内部的某个绘制内容。
|
||
|
||
## 解决方案
|
||
|
||
### 方案 1：高亮整个 Canvas（最简单）
|
||
|
||
直接高亮 Canvas 元素本身，适用于引导用户了解 Canvas 区域的功能。
|
||
|
||
```javascript
|
||
{
|
||
element: '.main-canvas', // 或 '.canvas-wrapper'
|
||
popover: {
|
||
title: '平面图区域',
|
||
description: '这是平面图显示区域，您可以在这里查看设备位置和状态。',
|
||
side: 'top',
|
||
align: 'center'
|
||
}
|
||
}
|
||
```
|
||
|
||
### 方案 2：使用占位元素（推荐用于精确引导）
|
||
|
||
如果需要在 Canvas 内部某个特定位置进行引导，可以创建一个临时的占位 DOM 元素：
|
||
|
||
```javascript
|
||
// 创建占位元素
|
||
const createPlaceholder = (x, y, width, height) => {
|
||
const placeholder = document.createElement('div');
|
||
placeholder.className = 'canvas-placeholder';
|
||
placeholder.style.position = 'absolute';
|
||
placeholder.style.left = `${x}px`;
|
||
placeholder.style.top = `${y}px`;
|
||
placeholder.style.width = `${width}px`;
|
||
placeholder.style.height = `${height}px`;
|
||
placeholder.style.pointerEvents = 'none'; // 不阻挡 Canvas 交互
|
||
placeholder.style.zIndex = '1000';
|
||
document.body.appendChild(placeholder);
|
||
return placeholder;
|
||
};
|
||
|
||
// 在引导步骤中使用
|
||
{
|
||
element: '.canvas-placeholder',
|
||
popover: {
|
||
title: '设备图标',
|
||
description: '这是设备图标的位置，在编辑模式下可以拖拽移动。',
|
||
side: 'top',
|
||
align: 'center'
|
||
}
|
||
}
|
||
```
|
||
|
||
### 方案 3：使用自定义高亮（高级）
|
||
|
||
结合 Canvas 坐标计算和自定义高亮层：
|
||
|
||
```javascript
|
||
// 计算 Canvas 内部元素的屏幕坐标
|
||
const getCanvasElementScreenPos = (canvasElement, canvasX, canvasY, scale, offsetX, offsetY) => {
|
||
const rect = canvasElement.getBoundingClientRect();
|
||
const screenX = rect.left + (canvasX * scale + offsetX);
|
||
const screenY = rect.top + (canvasY * scale + offsetY);
|
||
return { screenX, screenY };
|
||
};
|
||
|
||
// 创建自定义高亮层
|
||
const createCustomHighlight = (x, y, width, height) => {
|
||
const highlight = document.createElement('div');
|
||
highlight.className = 'custom-canvas-highlight';
|
||
highlight.style.position = 'fixed';
|
||
highlight.style.left = `${x}px`;
|
||
highlight.style.top = `${y}px`;
|
||
highlight.style.width = `${width}px`;
|
||
highlight.style.height = `${height}px`;
|
||
highlight.style.border = '3px solid #4dabf7';
|
||
highlight.style.borderRadius = '8px';
|
||
highlight.style.boxShadow = '0 0 20px rgba(77, 171, 247, 0.5)';
|
||
highlight.style.pointerEvents = 'none';
|
||
highlight.style.zIndex = '9999';
|
||
document.body.appendChild(highlight);
|
||
return highlight;
|
||
};
|
||
```
|
||
|
||
## 实际应用示例
|
||
|
||
### 示例 1：引导 Canvas 区域
|
||
|
||
```javascript
|
||
{
|
||
element: '.canvas-wrapper',
|
||
popover: {
|
||
title: '平面图区域',
|
||
description: '这是主要的平面图显示区域，所有设备都会在这里显示。',
|
||
side: 'top',
|
||
align: 'center'
|
||
}
|
||
}
|
||
```
|
||
|
||
### 示例 2：引导 Canvas 中的特定设备（需要坐标计算）
|
||
|
||
```javascript
|
||
// 假设要引导一个设备，其 Canvas 坐标为 (pointX, pointY)
|
||
const guideDevice = (pointX, pointY) => {
|
||
nextTick(() => {
|
||
if (!canvasRef.value) return;
|
||
|
||
// 计算设备在屏幕上的位置
|
||
const rect = canvasRef.value.getBoundingClientRect();
|
||
const screenX = rect.left + (pointX * BL.value * scale.value + offsetX.value);
|
||
const screenY = rect.top + (pointY * BL.value * scale.value + offsetY.value);
|
||
|
||
// 创建占位元素
|
||
const placeholder = document.createElement('div');
|
||
placeholder.className = 'device-placeholder';
|
||
placeholder.style.position = 'fixed';
|
||
placeholder.style.left = `${screenX - 20}px`;
|
||
placeholder.style.top = `${screenY - 20}px`;
|
||
placeholder.style.width = '40px';
|
||
placeholder.style.height = '40px';
|
||
placeholder.style.pointerEvents = 'none';
|
||
placeholder.style.zIndex = '9999';
|
||
document.body.appendChild(placeholder);
|
||
|
||
// 使用 driver.js 高亮占位元素
|
||
driverObj.highlight({
|
||
element: '.device-placeholder',
|
||
popover: {
|
||
title: '设备图标',
|
||
description: '这是设备图标，在编辑模式下可以拖拽移动。',
|
||
side: 'bottom',
|
||
align: 'center'
|
||
}
|
||
});
|
||
|
||
// 引导结束后移除占位元素
|
||
setTimeout(() => {
|
||
placeholder.remove();
|
||
}, 5000);
|
||
});
|
||
};
|
||
```
|
||
|
||
## 当前项目中的最佳实践
|
||
|
||
在当前项目中，由于主要功能按钮（筛选、分区、编辑）都是 DOM 元素，Driver.js 可以正常工作。对于 Canvas 内部的引导，建议：
|
||
|
||
1. **引导 Canvas 容器**：高亮整个 Canvas 区域，说明整体功能
|
||
2. **引导相关操作按钮**：通过引导操作按钮（如编辑按钮）来间接引导 Canvas 功能
|
||
3. **结合文字说明**：在引导提示中详细说明 Canvas 的操作方式
|
||
|
||
## 注意事项
|
||
|
||
1. **坐标转换**：Canvas 内部坐标需要转换为屏幕坐标才能创建占位元素
|
||
2. **缩放和偏移**：需要考虑 Canvas 的缩放（scale）和偏移（offsetX, offsetY）
|
||
3. **动态更新**：如果 Canvas 内容会移动或变化，占位元素的位置也需要动态更新
|
||
4. **性能考虑**：占位元素应该及时清理，避免内存泄漏
|
||
|
||
## 总结
|
||
|
||
Driver.js **可以**用于 Canvas 场景，但需要根据具体需求选择合适的方案：
|
||
- 简单场景：直接高亮 Canvas 元素
|
||
- 精确引导：使用占位元素或自定义高亮
|
||
- 当前项目：已有 DOM 按钮的引导已经足够，无需额外处理 Canvas 内部元素
|
||
|
||
|