zhengte.babylonjs-sdk/docs/adapter-dropzone-api.md

# 新的 Adapter API 使用指南

## 放置区域 API 更新

### 旧的调用方式（已废弃）

```javascript
// 旧方式：基于模型包围盒
kernel.dropZone.generate({
  modelName: "框架",
  divisions: 4,
  color: "#21c7ff",
  alpha: 0.3
});

kernel.dropZone.show("框架");
kernel.dropZone.hide("框架");
kernel.dropZone.clear("框架");
```

### 新的调用方式

```javascript
// 新方式：直接定义墙面坐标
kernel.dropZone.generate({
  walls: [
    {
      name: 'front',
      startPoint: [-50, 0, -50],  // [x, y, z]
      endPoint: [50, 0, -50],
      height: 30,
      divisions: 5
    },
    {
      name: 'back',
      startPoint: [50, 0, 50],
      endPoint: [-50, 0, 50],
      height: 30,
      divisions: 5
    },
    {
      name: 'left',
      startPoint: [-50, 0, 50],
      endPoint: [-50, 0, -50],
      height: 30,
      divisions: 4
    },
    {
      name: 'right',
      startPoint: [50, 0, -50],
      endPoint: [50, 0, 50],
      height: 30,
      divisions: 4
    }
  ],
  color: "#21c7ff",
  alpha: 0.3,
  thickness: 2,
  showBorder: true,
  borderColor: "#ffffff"
});

// 显示/隐藏特定墙面
kernel.dropZone.show('front');
kernel.dropZone.hide('front');

// 显示/隐藏所有
kernel.dropZone.showAll();
kernel.dropZone.hideAll();

// 清除所有
kernel.dropZone.clearAll();
```

## 完整示例

### 1. 创建矩形放置区域

```javascript
// 定义一个 100x100 的矩形区域
const zones = kernel.dropZone.generate({
  walls: [
    {
      name: 'front',
      startPoint: [-50, 0, -50],
      endPoint: [50, 0, -50],
      height: 30,
      divisions: 10
    },
    {
      name: 'back',
      startPoint: [50, 0, 50],
      endPoint: [-50, 0, 50],
      height: 30,
      divisions: 10
    },
    {
      name: 'left',
      startPoint: [-50, 0, 50],
      endPoint: [-50, 0, -50],
      height: 30,
      divisions: 10
    },
    {
      name: 'right',
      startPoint: [50, 0, -50],
      endPoint: [50, 0, 50],
      height: 30,
      divisions: 10
    }
  ],
  color: "#21c7ff",
  alpha: 0.3
});

console.log(`创建了 ${zones.length} 个放置区域`);
```

### 2. 创建L形放置区域

```javascript
const zones = kernel.dropZone.generate({
  walls: [
    {
      name: 'wall1',
      startPoint: [0, 0, 0],
      endPoint: [100, 0, 0],
      height: 25,
      divisions: 10
    },
    {
      name: 'wall2',
      startPoint: [100, 0, 0],
      endPoint: [100, 0, 60],
      height: 25,
      divisions: 6
    },
    {
      name: 'wall3',
      startPoint: [100, 0, 60],
      endPoint: [40, 0, 60],
      height: 25,
      divisions: 6
    }
  ],
  color: "#ff6b6b",
  alpha: 0.4
});
```

### 3. 创建单个展示墙

```javascript
const zones = kernel.dropZone.generate({
  walls: [
    {
      name: 'display',
      startPoint: [-30, 0, 0],
      endPoint: [30, 0, 0],
      height: 20,
      divisions: 6
    }
  ],
  color: "#4ecdc4",
  alpha: 0.35
});
```

### 4. 获取放置区域信息

```javascript
// 获取所有放置区域
const allZones = kernel.dropZone.getAll();
console.log('总共有', allZones.length, '个放置区域');

// 获取特定墙面的所有区域
const frontZones = kernel.dropZone.getByWall('front');
console.log('前墙有', frontZones.length, '个区域');

// 获取特定的某一块
const zone = kernel.dropZone.getZone('front', 2);
if (zone) {
  console.log('前墙第3块:', {
    center: zone.center,
    width: zone.width,
    height: zone.height,
    normal: zone.normal
  });
}
```

### 5. 检查位置是否在放置区域内

```javascript
const result = kernel.dropZone.checkPosition([10, 15, -50]);

if (result.inZone) {
  console.log('在放置区域内:', {
    墙面: result.wallName,
    索引: result.index,
    中心: result.center
  });
} else {
  console.log('不在任何放置区域内');
}
```

### 6. 显示/隐藏操作

```javascript
// 显示所有放置区域
kernel.dropZone.showAll();

// 隐藏所有放置区域
kernel.dropZone.hideAll();

// 显示特定墙面
kernel.dropZone.show('front');

// 隐藏特定墙面
kernel.dropZone.hide('back');

// 清除所有放置区域
kernel.dropZone.clearAll();
```

## HTML 按钮示例

```html
<!-- 生成放置区域 -->
<button onclick="
  kernel.dropZone.generate({
    walls: [
      {
        name: 'front',
        startPoint: [-50, 0, -50],
        endPoint: [50, 0, -50],
        height: 30,
        divisions: 5
      },
      {
        name: 'back',
        startPoint: [50, 0, 50],
        endPoint: [-50, 0, 50],
        height: 30,
        divisions: 5
      }
    ],
    color: '#21c7ff',
    alpha: 0.3
  });
">生成放置区域</button>

<!-- 显示所有 -->
<button onclick="kernel.dropZone.showAll()">显示所有</button>

<!-- 隐藏所有 -->
<button onclick="kernel.dropZone.hideAll()">隐藏所有</button>

<!-- 清除所有 -->
<button onclick="kernel.dropZone.clearAll()">清除所有</button>

<!-- 显示前墙 -->
<button onclick="kernel.dropZone.show('front')">显示前墙</button>

<!-- 隐藏前墙 -->
<button onclick="kernel.dropZone.hide('front')">隐藏前墙</button>
```

## API 参考

### `kernel.dropZone.generate(options)`

生成放置区域

**参数：**
- `walls` - 墙面配置数组
  - `name` - 墙面名称
  - `startPoint` - 起始点坐标 `[x, y, z]`
  - `endPoint` - 结束点坐标 `[x, y, z]`
  - `height` - 墙面高度
  - `divisions` - 分割数
- `color` - 颜色（可选，默认 `#21c7ff`）
- `alpha` - 透明度（可选，默认 `0.3`）
- `thickness` - 厚度（可选，默认 `2`）
- `showBorder` - 是否显示边框（可选，默认 `false`）
- `borderColor` - 边框颜色（可选，默认 `#ffffff`）

**返回：** 放置区域信息数组

### `kernel.dropZone.showAll()`

显示所有放置区域

### `kernel.dropZone.hideAll()`

隐藏所有放置区域

### `kernel.dropZone.show(wallName)`

显示指定墙面的放置区域

**参数：**
- `wallName` - 墙面名称

### `kernel.dropZone.hide(wallName)`

隐藏指定墙面的放置区域

**参数：**
- `wallName` - 墙面名称

### `kernel.dropZone.clearAll()`

清除所有放置区域

### `kernel.dropZone.getAll()`

获取所有放置区域信息

**返回：** 放置区域信息数组

### `kernel.dropZone.getByWall(wallName)`

获取指定墙面的所有放置区域

**参数：**
- `wallName` - 墙面名称

**返回：** 放置区域信息数组

### `kernel.dropZone.getZone(wallName, index)`

获取特定的放置区域

**参数：**
- `wallName` - 墙面名称
- `index` - 区域索引

**返回：** 放置区域信息对象

### `kernel.dropZone.checkPosition(position)`

检查位置是否在放置区域内

**参数：**
- `position` - 位置坐标 `[x, y, z]`

**返回：** 检查结果对象
```javascript
{
  inZone: boolean,      // 是否在区域内
  zone: object,         // 区域信息（如果在区域内）
  wallName: string,     // 墙面名称
  index: number,        // 区域索引
  center: Vector3       // 中心点坐标
}
```

## 迁移注意事项

1. **不再依赖模型名称** - 新API使用墙面名称而不是模型名称
2. **坐标需要手动指定** - 不再自动计算包围盒，需要明确指定每个墙面的坐标
3. **更灵活的分割** - 每个墙面可以有不同的分割数
4. **支持任意形状** - 可以创建L形、U形等不规则形状

## 优势

- ✅ 精确控制每个墙面的位置
- ✅ 每个墙面可以独立配置
- ✅ 支持任意数量的墙面
- ✅ 可以创建不规则形状
- ✅ 不依赖模型，更灵活