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 + + +
+