zhengte/zhengte.babylonjs-sdk

Fork 0

Files

zguiy fdc031673f 1

2026-05-18 12:13:34 +08:00

8.9 KiB

Raw Blame History

SDK 调用示例

本目录包含完整的 SDK 调用示例，展示了两种不同的集成方式。

📁 文件说明

完整 Demo（推荐）

demo-module.html - ES Module 方式完整示例（推荐）
demo-global.html - 全局脚本方式完整示例
app-global.js - 全局脚本方式的业务逻辑文件

简单示例

example-module.html - ES Module 方式简单示例
example-global.html - 全局脚本方式简单示例

🎯 核心设计理念

业务逻辑与 SDK 解耦

根目录的 index.js 是一个通用的业务逻辑层，通过 initApp(kernel) 接收外部传入的 kernel 实例，实现了：

✅ SDK 调用方式无关 - 同一套业务逻辑，适配两种 SDK 引入方式
✅ 代码复用 - 避免重复编写业务逻辑
✅ 易于维护 - 业务逻辑集中管理，修改一处即可

架构图：

┌─────────────────────────────────────────┐
│         应用层 (HTML)                    │
│  ┌─────────────┐    ┌─────────────┐    │
│  │ ES Module   │    │ 全局脚本     │    │
│  │ 方式引入     │    │ 方式引入     │    │
│  └──────┬──────┘    └──────┬──────┘    │
│         │                  │            │
│         ▼                  ▼            │
│  ┌─────────────────────────────────┐   │
│  │   通用业务逻辑 (index.js)        │   │
│  │   - initApp(kernel)              │   │
│  │   - init()                       │   │
│  │   - getAutoLoadModelList()       │   │
│  │   - getHotspot()                 │   │
│  │   - getProductConfig()           │   │
│  └──────────────┬──────────────────┘   │
│                 │                       │
│                 ▼                       │
│  ┌─────────────────────────────────┐   │
│  │      SDK Kernel                  │   │
│  │   (从外部注入)                    │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

🚀 快速开始

方式 1: ES Module（推荐）

文件： demo-module.html

<script type="module">
  // 1. 从 CDN 导入 SDK
  import { kernel } from 'https://sdk.zguiy.com/zt/assets/index.js';
  
  // 2. 导入业务逻辑
  import { initApp, init, getAutoLoadModelList } from '../index.js';
  
  // 3. 注入 kernel 实例
  initApp(kernel);
  
  // 4. 初始化应用
  await init();
  await getAutoLoadModelList();
</script>

特点：

✅ 现代化模块化开发
✅ 直接引用根目录的 index.js
✅ 支持 async/await
✅ 更好的 IDE 智能提示

方式 2: 全局脚本

文件： demo-global.html + app-global.js

<!-- 1. 引入 SDK -->
<script src="https://sdk.zguiy.com/zt/assets/index.global.js"></script>

<!-- 2. 引入业务逻辑 -->
<script src="./app-global.js"></script>

<script>
  // 3. 获取 SDK kernel
  var kernel = window.faceSDK.kernel;
  
  // 4. 注入 kernel 实例
  window.AppLogic.initApp(kernel);
  
  // 5. 初始化应用
  (async function() {
    await window.AppLogic.init();
    await window.AppLogic.getAutoLoadModelList();
  })();
</script>

特点：

✅ 兼容所有浏览器
✅ 无需构建工具
✅ 使用 app-global.js（根目录 index.js 的全局脚本版本）
⚠️ 需要维护两份业务逻辑文件

📖 业务逻辑 API

初始化

// 注入 kernel 实例（必须首先调用）
initApp(kernel)

// 初始化 SDK 配置
await init(customConfig?)

// 加载模型列表
await getAutoLoadModelList()

产品配置

// 获取产品配置并应用
await getProductConfig(sku)

// 获取放置区域
await getPlacementZone(sku)

热点管理

// 加载并渲染热点
await getHotspot()

事件处理

// 执行放置区域事件
await getEvent(dropzone_data, sku)

// 执行产品切换事件
await executeEvent2(result)

🎨 完整 Demo 功能

两个完整 demo（demo-module.html 和 demo-global.html）都包含：

UI 功能

✅ 3D 模型渲染画布
✅ 配置面板（产品选择、热点控制）
✅ 加载进度显示
✅ 点击信息提示

交互功能

✅ 产品切换
✅ 热点加载
✅ 模型点击事件
✅ 热点点击事件

事件监听

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

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

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

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

🔧 本地运行

ES Module 方式

# 需要本地服务器（ES Module 不支持 file:// 协议）
cd examples
npx serve .

# 访问 http://localhost:3000/demo-module.html

全局脚本方式

# 可以直接双击打开
# 或使用本地服务器
cd examples
npx serve .

# 访问 http://localhost:3000/demo-global.html

📦 集成到项目

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';
import { initApp, init, getAutoLoadModelList } from '@/utils/app-logic.js';

const canvasRef = ref(null);

onMounted(async () => {
  // 注入 kernel
  initApp(kernel);
  
  // 初始化
  await init({ container: canvasRef.value });
  await getAutoLoadModelList();
});
</script>

React 项目

import { useEffect, useRef } from 'react';

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

  useEffect(() => {
    (async () => {
      // 动态导入 SDK
      const { kernel } = await import('https://sdk.zguiy.com/zt/assets/index.js');
      const { initApp, init, getAutoLoadModelList } = await import('./app-logic.js');
      
      // 注入 kernel
      initApp(kernel);
      
      // 初始化
      await init({ container: canvasRef.current });
      await getAutoLoadModelList();
    })();
  }, []);

  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 src="./app-global.js"></script>
  <script>
    var kernel = window.faceSDK.kernel;
    window.AppLogic.initApp(kernel);
    
    (async function() {
      await window.AppLogic.init();
      await window.AppLogic.getAutoLoadModelList();
    })();
  </script>
</body>
</html>

🔄 业务逻辑文件说明

根目录 `index.js` (ES Module 版本)

使用 ES6+ 语法
支持 import/export
适用于现代构建工具
推荐用于新项目

`app-global.js` (全局脚本版本)

使用 ES5 语法
通过 IIFE 包装
暴露到 window.AppLogic
适用于传统 HTML 页面

两个文件功能完全相同，只是语法不同。

❓ 常见问题

Q: 为什么需要两个业务逻辑文件？

A: 因为 ES Module 和全局脚本的语法不兼容：

ES Module 使用 import/export，不能在全局脚本中使用
全局脚本需要通过 window 对象暴露 API

如果你的项目只使用一种方式，只需要维护对应的文件即可。

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

现代项目 + 构建工具 → 使用 ES Module (demo-module.html)
传统 HTML + 无构建工具 → 使用全局脚本 (demo-global.html)
需要兼容旧浏览器 → 使用全局脚本

Q: 可以只维护一份业务逻辑吗？

A: 可以！有两种方案：

只用 ES Module：使用构建工具（如 Vite）将 ES Module 转换为全局脚本
只用全局脚本：所有项目都使用 app-global.js

Q: `initApp(kernel)` 必须调用吗？

A: 是的！这是核心设计：

// ❌ 错误 - 直接调用会报错
await init();  // Error: 请先调用 initApp(kernel)

// ✅ 正确 - 先注入 kernel
initApp(kernel);
await init();

📚 相关资源

SDK 文档: https://sdk.zguiy.com/docs
后端 API: https://ztserver.zguiy.com
GitHub: [项目地址]

📄 许可证

MIT License

8.9 KiB Raw Blame History Unescape Escape