zhengte/zhengte.babylonjs-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8d784c293991fdc4919d9ef310bc1989627ae930
zhengte.babylonjs-sdk/examples/README.md
zguiy 8d784c2939 1
2026-05-17 21:23:25 +08:00

6.2 KiB
Raw Blame History

SDK 调用示例

本目录包含两种 SDK 调用方式的完整示例。

📁 文件说明

  • example-module.html - ES Module 方式调用示例
  • example-global.html - 全局脚本方式调用示例

🚀 两种调用方式对比

1. ES Module 方式 (推荐)

文件: example-module.html

特点:

  • ✅ 现代化的模块化开发方式
  • ✅ 支持按需导入，代码更清晰
  • ✅ 更好的 IDE 智能提示
  • ✅ 适合现代前端框架（Vue、React、Angular）

引入方式:

<script type="module">
  import { kernel } from 'https://sdk.zguiy.com/zt/assets/index.js';
  
  kernel.init(config);
</script>

适用场景:

  • 现代浏览器环境（Chrome 61+, Firefox 60+, Safari 11+, Edge 16+）
  • 使用构建工具的项目（Vite、Webpack、Rollup）
  • Vue/React/Angular 等框架项目

2. 全局脚本方式 (兼容性好)

文件: example-global.html

特点:

  • ✅ 兼容性最好，支持所有浏览器
  • ✅ 无需构建工具，直接引入即可使用
  • ✅ 适合传统 HTML 页面
  • ⚠️ 会污染全局命名空间

引入方式:

<script src="https://sdk.zguiy.com/zt/assets/index.global.js"></script>
<script>
  const sdkKernel = window.faceSDK.kernel;
  
  sdkKernel.init(config);
</script>

适用场景:

  • 需要兼容旧版浏览器
  • 传统 HTML 页面（无构建工具）
  • 快速原型开发
  • 第三方页面集成

📖 使用方法

基础配置

两种方式的配置参数完全相同：

const config = {
  // 必填：渲染容器 ID
  container: 'renderDom',
  
  // 方式1：自动加载模型（从后端 API 获取）
  autoLoadModels: true,
  autoLoadModelsUrl: 'https://ztserver.zguiy.com/api/models/auto-load/list',
  
  // 方式2：手动指定模型列表
  // modelUrlList: [
  //   'https://sdk.zguiy.com/resurces/model/model1.glb',
  //   'https://sdk.zguiy.com/resurces/model/model2.glb'
  // ],
  
  // 环境配置
  env: {
    envPath: 'https://sdk.zguiy.com/resurces/hdr/hdr.env',
    intensity: 1.2,      // 环境光强度
    rotationY: 0.3       // 环境贴图旋转角度
  },
  
  // 相机配置
  camera: {
    alpha: Math.PI / 2,   // 水平角度
    beta: Math.PI / 3,    // 垂直角度
    radius: 50            // 距离
  }
};

事件监听

// 模型加载进度
kernel.on('model:load:progress', (data) => {
  console.log('加载进度:', data.progress); // 0-1
});

// 模型加载完成
kernel.on('model:loaded', (data) => {
  console.log('加载完成:', data.models);
});

// 模型点击事件
kernel.on('model:click', (data) => {
  console.log('点击:', data.meshName, data.position);
});

// 热点点击事件
kernel.on('hotspot:click', (event) => {
  console.log('热点:', event.name, event.payload);
});

// 错误事件
kernel.on('error', (error) => {
  console.error('错误:', error.message);
});

🌐 在线演示

本地运行

  1. ES Module 方式:

    # 需要本地服务器（因为 ES Module 不支持 file:// 协议）
npx serve .
# 访问 http://localhost:3000/example-module.html

  2. 全局脚本方式:

    # 可以直接双击打开，或使用本地服务器
# 双击 example-global.html 即可

部署到服务器

将示例文件上传到任意 Web 服务器即可访问。

🔧 集成到项目

Vue 3 项目

<template>
  <canvas ref="canvasRef"></canvas>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { kernel } from 'https://sdk.zguiy.com/zt/assets/index.js';

const canvasRef = ref(null);

onMounted(() => {
  kernel.init({
    container: canvasRef.value,
    autoLoadModels: true,
    autoLoadModelsUrl: 'https://ztserver.zguiy.com/api/models/auto-load/list'
  });
});
</script>

React 项目

import { useEffect, useRef } from 'react';

function ModelViewer() {
  const canvasRef = useRef(null);

  useEffect(() => {
    import('https://sdk.zguiy.com/zt/assets/index.js').then(({ kernel }) => {
      kernel.init({
        container: canvasRef.current,
        autoLoadModels: true,
        autoLoadModelsUrl: 'https://ztserver.zguiy.com/api/models/auto-load/list'
      });
    });
  }, []);

  return <canvas ref={canvasRef} />;
}

原生 HTML

<!DOCTYPE html>
<html>
<head>
  <title>3D 模型展示</title>
</head>
<body>
  <canvas id="renderDom"></canvas>
  
  <script src="https://sdk.zguiy.com/zt/assets/index.global.js"></script>
  <script>
    window.faceSDK.kernel.init({
      container: 'renderDom',
      autoLoadModels: true,
      autoLoadModelsUrl: 'https://ztserver.zguiy.com/api/models/auto-load/list'
    });
  </script>
</body>
</html>

📚 API 文档

初始化

kernel.init(config)

事件系统

kernel.on(eventName, callback)    // 监听事件
kernel.off(eventName, callback)   // 取消监听
kernel.emit(eventName, data)      // 触发事件

可用事件

事件名 说明 回调参数
model:load:progress 模型加载进度 { progress: number }
model:loaded 模型加载完成 { models: Array }
model:click 模型点击 { meshName, position, materialName }
hotspot:click 热点点击 { id, name, payload }
error 错误 { message, code }

❓ 常见问题

Q: ES Module 方式报错 "CORS policy"？

A: ES Module 必须通过 HTTP(S) 协议访问，不能使用 file:// 协议。请使用本地服务器（如 npx serve）。

Q: 全局脚本方式找不到 window.faceSDK？

A: 确保 index.global.js 已完全加载。可以在 <script> 标签中添加 onload 事件：

<script src="https://sdk.zguiy.com/zt/assets/index.global.js" onload="initSDK()"></script>

Q: 如何选择使用哪种方式？

A:

  • 现代项目 + 构建工具 → 使用 ES Module
  • 传统 HTML 页面 + 无构建工具 → 使用 全局脚本
  • 需要兼容旧浏览器 → 使用 全局脚本

📞 技术支持

📄 许可证

MIT License