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: 如何选择使用哪种方式？
A:
- 现代项目 + 构建工具 → 使用 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