1
This commit is contained in:
286
examples/README.md
Normal file
286
examples/README.md
Normal file
@ -0,0 +1,286 @@
|
||||
# SDK 调用示例
|
||||
|
||||
本目录包含两种 SDK 调用方式的完整示例。
|
||||
|
||||
## 📁 文件说明
|
||||
|
||||
- `example-module.html` - ES Module 方式调用示例
|
||||
- `example-global.html` - 全局脚本方式调用示例
|
||||
|
||||
## 🚀 两种调用方式对比
|
||||
|
||||
### 1. ES Module 方式 (推荐)
|
||||
|
||||
**文件:** `example-module.html`
|
||||
|
||||
**特点:**
|
||||
- ✅ 现代化的模块化开发方式
|
||||
- ✅ 支持按需导入，代码更清晰
|
||||
- ✅ 更好的 IDE 智能提示
|
||||
- ✅ 适合现代前端框架（Vue、React、Angular）
|
||||
|
||||
**引入方式:**
|
||||
```html
|
||||
<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 页面
|
||||
- ⚠️ 会污染全局命名空间
|
||||
|
||||
**引入方式:**
|
||||
```html
|
||||
<script src="https://sdk.zguiy.com/zt/assets/index.global.js"></script>
|
||||
<script>
|
||||
const sdkKernel = window.faceSDK.kernel;
|
||||
|
||||
sdkKernel.init(config);
|
||||
</script>
|
||||
```
|
||||
|
||||
**适用场景:**
|
||||
- 需要兼容旧版浏览器
|
||||
- 传统 HTML 页面（无构建工具）
|
||||
- 快速原型开发
|
||||
- 第三方页面集成
|
||||
|
||||
---
|
||||
|
||||
## 📖 使用方法
|
||||
|
||||
### 基础配置
|
||||
|
||||
两种方式的配置参数完全相同：
|
||||
|
||||
```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 // 距离
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 事件监听
|
||||
|
||||
```javascript
|
||||
// 模型加载进度
|
||||
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 方式:**
|
||||
```bash
|
||||
# 需要本地服务器（因为 ES Module 不支持 file:// 协议）
|
||||
npx serve .
|
||||
# 访问 http://localhost:3000/example-module.html
|
||||
```
|
||||
|
||||
2. **全局脚本方式:**
|
||||
```bash
|
||||
# 可以直接双击打开，或使用本地服务器
|
||||
# 双击 example-global.html 即可
|
||||
```
|
||||
|
||||
### 部署到服务器
|
||||
|
||||
将示例文件上传到任意 Web 服务器即可访问。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 集成到项目
|
||||
|
||||
### 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';
|
||||
|
||||
const canvasRef = ref(null);
|
||||
|
||||
onMounted(() => {
|
||||
kernel.init({
|
||||
container: canvasRef.value,
|
||||
autoLoadModels: true,
|
||||
autoLoadModelsUrl: 'https://ztserver.zguiy.com/api/models/auto-load/list'
|
||||
});
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
### React 项目
|
||||
|
||||
```jsx
|
||||
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
|
||||
|
||||
```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 文档
|
||||
|
||||
### 初始化
|
||||
|
||||
```javascript
|
||||
kernel.init(config)
|
||||
```
|
||||
|
||||
### 事件系统
|
||||
|
||||
```javascript
|
||||
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` 事件：
|
||||
```html
|
||||
<script src="https://sdk.zguiy.com/zt/assets/index.global.js" onload="initSDK()"></script>
|
||||
```
|
||||
|
||||
### Q: 如何选择使用哪种方式？
|
||||
**A:**
|
||||
- 现代项目 + 构建工具 → 使用 **ES Module**
|
||||
- 传统 HTML 页面 + 无构建工具 → 使用 **全局脚本**
|
||||
- 需要兼容旧浏览器 → 使用 **全局脚本**
|
||||
|
||||
---
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
- SDK 文档: https://sdk.zguiy.com/docs
|
||||
- 后端 API: https://ztserver.zguiy.com
|
||||
- 问题反馈: [GitHub Issues](https://github.com/your-repo/issues)
|
||||
|
||||
---
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT License
|
||||
Reference in New Issue
Block a user