zhengte/zhengte.babylonjs-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

1

Browse Source
This commit is contained in:
zguiy
2026-05-18 12:13:34 +08:00
parent 8d784c2939
commit fdc031673f
12 changed files with 361672 additions and 297926 deletions
Download Patch File Download Diff File Expand all files Collapse all files

403
examples/README.md
View File

@ -1,160 +1,233 @@
# SDK 调用示例
本目录包含两种 SDK 调用方式的完整示例。
本目录包含完整的 SDK 调用示例，展示了两种不同的集成方式。
## 📁 文件说明
- `example-module.html` - ES Module 方式调用示例
- `example-global.html` - 全局脚本方式调用示例
### 完整 Demo（推荐）
- `demo-module.html` - **ES Module 方式完整示例**（推荐）
- `demo-global.html` - **全局脚本方式完整示例**
- `app-global.js` - 全局脚本方式的业务逻辑文件
## 🚀 两种调用方式对比
### 简单示例
- `example-module.html` - ES Module 方式简单示例
- `example-global.html` - 全局脚本方式简单示例
### 1. ES Module 方式 (推荐)
## 🎯 核心设计理念
**文件:** `example-module.html`
### 业务逻辑与 SDK 解耦
**特点:**
- ✅ 现代化的模块化开发方式
- ✅ 支持按需导入，代码更清晰
- ✅ 更好的 IDE 智能提示
- ✅ 适合现代前端框架（Vue、React、Angular）
根目录的 `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';
kernel.init(config);
</script>
```
**适用场景:**
- 现代浏览器环境（Chrome 61+, Firefox 60+, Safari 11+, Edge 16+）
- 使用构建工具的项目（Vite、Webpack、Rollup）
- Vue/React/Angular 等框架项目
---
### 2. 全局脚本方式 (兼容性好)
**文件:** `example-global.html`
**特点:**
- ✅ 兼容性最好，支持所有浏览器
- ✅ 无需构建工具，直接引入即可使用
- ✅ 适合传统 HTML 页面
- ⚠️ 会污染全局命名空间
**引入方式:**
```html
<script src="https://sdk.zguiy.com/zt/assets/index.global.js"></script>
<script>
const sdkKernel = window.faceSDK.kernel;
// 2. 导入业务逻辑
import { initApp, init, getAutoLoadModelList } from '../index.js';
sdkKernel.init(config);
// 3. 注入 kernel 实例
initApp(kernel);
// 4. 初始化应用
await init();
await getAutoLoadModelList();
</script>
```
**适用场景:**
- 需要兼容旧版浏览器
- 传统 HTML 页面（无构建工具）
- 快速原型开发
- 第三方页面集成
**特点：**
- ✅ 现代化模块化开发
- ✅ 直接引用根目录的 `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
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 实例（必须首先调用）
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); // 0-1
console.log('进度:', data.progress);
});
// 模型加载完成
// 加载完成
kernel.on('model:loaded', (data) => {
console.log('加载完成:', data.models);
console.log('模型列表:', data.models);
});
// 模型点击事件
// 模型点击
kernel.on('model:click', (data) => {
console.log('点击:', data.meshName, data.position);
console.log('点击:', data.meshName);
});
// 热点点击事件
// 热点点击
kernel.on('hotspot:click', (event) => {
console.log('热点:', event.name, event.payload);
});
// 错误事件
kernel.on('error', (error) => {
console.error('错误:', error.message);
console.log('热点:', event.name);
});
```
---
## 🌐 在线演示
## 🔧 本地运行
### 本地运行
### ES Module 方式
1. **ES Module 方式:**
```bash
# 需要本地服务器（因为 ES Module 不支持 file:// 协议）
npx serve .
# 访问 http://localhost:3000/example-module.html
```
```bash
# 需要本地服务器（ES Module 不支持 file:// 协议）
cd examples
npx serve .
2. **全局脚本方式:**
```bash
# 可以直接双击打开，或使用本地服务器
# 双击 example-global.html 即可
```
# 访问 http://localhost:3000/demo-module.html
```
### 部署到服务器
### 全局脚本方式
将示例文件上传到任意 Web 服务器即可访问。
```bash
# 可以直接双击打开
# 或使用本地服务器
cd examples
npx serve .
# 访问 http://localhost:3000/demo-global.html
```
---
## 🔧 集成到项目
## 📦 集成到项目
### Vue 3 项目
@ -166,15 +239,17 @@ kernel.on('error', (error) => {
<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(() => {
kernel.init({
container: canvasRef.value,
autoLoadModels: true,
autoLoadModelsUrl: 'https://ztserver.zguiy.com/api/models/auto-load/list'
});
onMounted(async () => {
// 注入 kernel
initApp(kernel);
// 初始化
await init({ container: canvasRef.value });
await getAutoLoadModelList();
});
</script>
```
@ -188,13 +263,18 @@ 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'
});
});
(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} />;
@ -213,12 +293,15 @@ function ModelViewer() {
<canvas id="renderDom"></canvas>
<script src="https://sdk.zguiy.com/zt/assets/index.global.js"></script>
<script src="./app-global.js"></script>
<script>
window.faceSDK.kernel.init({
container: 'renderDom',
autoLoadModels: true,
autoLoadModelsUrl: 'https://ztserver.zguiy.com/api/models/auto-load/list'
});
var kernel = window.faceSDK.kernel;
window.AppLogic.initApp(kernel);
(async function() {
await window.AppLogic.init();
await window.AppLogic.getAutoLoadModelList();
})();
</script>
</body>
</html>
@ -226,58 +309,68 @@ function ModelViewer() {
---
## 📚 API 文档
## 🔄 业务逻辑文件说明
### 初始化
### 根目录 `index.js` (ES Module 版本)
```javascript
kernel.init(config)
```
- 使用 ES6+ 语法
- 支持 `import/export`
- 适用于现代构建工具
- **推荐用于新项目**
### 事件系统
### `app-global.js` (全局脚本版本)
```javascript
kernel.on(eventName, callback) // 监听事件
kernel.off(eventName, callback) // 取消监听
kernel.emit(eventName, data) // 触发事件
```
- 使用 ES5 语法
- 通过 IIFE 包装
- 暴露到 `window.AppLogic`
- 适用于传统 HTML 页面
### 可用事件
| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| `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: 为什么需要两个业务逻辑文件？
### Q: 全局脚本方式找不到 `window.faceSDK`？
**A:** 确保 `index.global.js` 已完全加载。可以在 `<script>` 标签中添加 `onload` 事件：
```html
<script src="https://sdk.zguiy.com/zt/assets/index.global.js" onload="initSDK()"></script>
```
**A:** 因为 ES Module 和全局脚本的语法不兼容：
- ES Module 使用 `import/export`，不能在全局脚本中使用
- 全局脚本需要通过 `window` 对象暴露 API
如果你的项目只使用一种方式，只需要维护对应的文件即可。
### Q: 如何选择使用哪种方式？
**A:**
- 现代项目 + 构建工具 → 使用 **ES Module**
- 传统 HTML 页面 + 无构建工具 → 使用 **全局脚本**
- 需要兼容旧浏览器 → 使用 **全局脚本**
- **现代项目 + 构建工具** → 使用 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 Issues](https://github.com/your-repo/issues)
- GitHub: [项目地址]
---