diff --git a/.env b/.env new file mode 100644 index 0000000..60c60d3 --- /dev/null +++ b/.env @@ -0,0 +1,6 @@ +# API 配置 +# 开发环境 +VITE_API_BASE_URL=https://ztserver.zguiy.com + +# 生产环境示例(部署时修改) +# VITE_API_BASE_URL=https://api.yourdomain.com diff --git a/ScreenShot_2026-05-17_165150_324.png b/ScreenShot_2026-05-17_165150_324.png new file mode 100644 index 0000000..8247623 Binary files /dev/null and b/ScreenShot_2026-05-17_165150_324.png differ diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..23cd7a3 --- /dev/null +++ b/examples/README.md @@ -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 + +``` + +**适用场景:** +- 现代浏览器环境(Chrome 61+, Firefox 60+, Safari 11+, Edge 16+) +- 使用构建工具的项目(Vite、Webpack、Rollup) +- Vue/React/Angular 等框架项目 + +--- + +### 2. 全局脚本方式 (兼容性好) + +**文件:** `example-global.html` + +**特点:** +- ✅ 兼容性最好,支持所有浏览器 +- ✅ 无需构建工具,直接引入即可使用 +- ✅ 适合传统 HTML 页面 +- ⚠️ 会污染全局命名空间 + +**引入方式:** +```html + + +``` + +**适用场景:** +- 需要兼容旧版浏览器 +- 传统 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 + + + +``` + +### 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 ; +} +``` + +### 原生 HTML + +```html + + + + 3D 模型展示 + + + + + + + + +``` + +--- + +## 📚 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` 已完全加载。可以在 ` +``` + +### 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 diff --git a/examples/example-global.html b/examples/example-global.html new file mode 100644 index 0000000..10ab085 --- /dev/null +++ b/examples/example-global.html @@ -0,0 +1,207 @@ + + + + + + + SDK 调用示例 - 全局脚本方式 + + + + +
+ +
+
加载中...
+
+
+
+
+ +
+ + + + + + + diff --git a/examples/example-module.html b/examples/example-module.html new file mode 100644 index 0000000..c99072d --- /dev/null +++ b/examples/example-module.html @@ -0,0 +1,197 @@ + + + + + + + SDK 调用示例 - ES Module 方式 + + + + +
+ +
+
加载中...
+
+
+
+
+ +
+ + + + + + diff --git a/index.html b/index.html index 0a1f66e..d77feb2 100644 --- a/index.html +++ b/index.html @@ -454,7 +454,7 @@