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

新的 Adapter API 使用指南

放置区域 API 更新

旧的调用方式（已废弃）

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

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

新的调用方式

// 新方式：直接定义墙面坐标
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. 创建矩形放置区域

// 定义一个 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形放置区域

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. 创建单个展示墙

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. 获取放置区域信息

// 获取所有放置区域
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. 检查位置是否在放置区域内

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

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

6. 显示/隐藏操作

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

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

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

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

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

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]

返回： 检查结果对象

{
  inZone: boolean,      // 是否在区域内
  zone: object,         // 区域信息（如果在区域内）
  wallName: string,     // 墙面名称
  index: number,        // 区域索引
  center: Vector3       // 中心点坐标
}

迁移注意事项

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

优势

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