380 lines
8.9 KiB
Markdown
380 lines
8.9 KiB
Markdown
# 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`
|
||
|
||
```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`
|
||
|
||
```html
|
||
<!-- 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
|
||
|
||
### 初始化
|
||
|
||
```javascript
|
||
// 注入 kernel 实例（必须首先调用）
|
||
initApp(kernel)
|
||
|
||
// 初始化 SDK 配置
|
||
await init(customConfig?)
|
||
|
||
// 加载模型列表
|
||
await getAutoLoadModelList()
|
||
```
|
||
|
||
### 产品配置
|
||
|
||
```javascript
|
||
// 获取产品配置并应用
|
||
await getProductConfig(sku)
|
||
|
||
// 获取放置区域
|
||
await getPlacementZone(sku)
|
||
```
|
||
|
||
### 热点管理
|
||
|
||
```javascript
|
||
// 加载并渲染热点
|
||
await getHotspot()
|
||
```
|
||
|
||
### 事件处理
|
||
|
||
```javascript
|
||
// 执行放置区域事件
|
||
await getEvent(dropzone_data, sku)
|
||
|
||
// 执行产品切换事件
|
||
await executeEvent2(result)
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 完整 Demo 功能
|
||
|
||
两个完整 demo（`demo-module.html` 和 `demo-global.html`）都包含：
|
||
|
||
### UI 功能
|
||
- ✅ 3D 模型渲染画布
|
||
- ✅ 配置面板（产品选择、热点控制）
|
||
- ✅ 加载进度显示
|
||
- ✅ 点击信息提示
|
||
|
||
### 交互功能
|
||
- ✅ 产品切换
|
||
- ✅ 热点加载
|
||
- ✅ 模型点击事件
|
||
- ✅ 热点点击事件
|
||
|
||
### 事件监听
|
||
```javascript
|
||
// 加载进度
|
||
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 方式
|
||
|
||
```bash
|
||
# 需要本地服务器（ES Module 不支持 file:// 协议）
|
||
cd examples
|
||
npx serve .
|
||
|
||
# 访问 http://localhost:3000/demo-module.html
|
||
```
|
||
|
||
### 全局脚本方式
|
||
|
||
```bash
|
||
# 可以直接双击打开
|
||
# 或使用本地服务器
|
||
cd examples
|
||
npx serve .
|
||
|
||
# 访问 http://localhost:3000/demo-global.html
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 集成到项目
|
||
|
||
### Vue 3 项目
|
||
|
||
```vue
|
||
<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 项目
|
||
|
||
```jsx
|
||
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
|
||
|
||
```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:** 可以！有两种方案：
|
||
1. **只用 ES Module**：使用构建工具（如 Vite）将 ES Module 转换为全局脚本
|
||
2. **只用全局脚本**：所有项目都使用 `app-global.js`
|
||
|
||
### Q: `initApp(kernel)` 必须调用吗？
|
||
|
||
**A:** 是的！这是核心设计：
|
||
```javascript
|
||
// ❌ 错误 - 直接调用会报错
|
||
await init(); // Error: 请先调用 initApp(kernel)
|
||
|
||
// ✅ 正确 - 先注入 kernel
|
||
initApp(kernel);
|
||
await init();
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关资源
|
||
|
||
- SDK 文档: https://sdk.zguiy.com/docs
|
||
- 后端 API: https://ztserver.zguiy.com
|
||
- GitHub: [项目地址]
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|