148 lines
4.3 KiB
Markdown
148 lines
4.3 KiB
Markdown
# SGS Map SDK 快速接入指南
|
||
|
||
> 版本: V2.0.0 | 支持终端: H5 浏览器、大屏终端、微信小程序
|
||
|
||
## 1. 引入方式
|
||
|
||
SDK 提供多种模块规范的产出文件，适配不同的应用场景：
|
||
|
||
### 1.1 Script 标签引入 (浏览器直连)
|
||
将 `dist/index.global.js`（IIFE 格式）通过 `<script>` 标签引入，SDK 会挂载全局变量 `window.SGSMapSDK`。
|
||
```html
|
||
<script src="./dist/index.global.js"></script>
|
||
<script>
|
||
const sdk = new SGSMapSDK({ ... });
|
||
</script>
|
||
```
|
||
|
||
### 1.2 ESM Import (Webpack / Vite / Next.js)
|
||
在现代前端工程中，直接使用 ESM 格式：
|
||
```javascript
|
||
import SGSMapSDK from 'path/to/sdk/index.mjs';
|
||
|
||
const sdk = new SGSMapSDK({ ... });
|
||
```
|
||
|
||
### 1.3 微信小程序 WebView 接入
|
||
在微信小程序中，无需引入外壳 SDK，直接通过 `web-view` 组件加载地图基座，并通过 URL 传递参数。
|
||
```html
|
||
<!-- 小程序 WXML -->
|
||
<web-view src="https://map.museum.com/h5-sdk?floorId=1&mode=miniapp"></web-view>
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 初始化与生命周期
|
||
|
||
### 2.1 创建实例
|
||
```javascript
|
||
const map = new SGSMapSDK({
|
||
container: 'map-container', // 挂载的 DOM 容器 ID
|
||
sdkUrl: 'https://map.museum.com/h5-sdk', // 渲染基座的 URL
|
||
targetOrigin: 'https://map.museum.com', // [重要] 安全防范，配置只允许该域名通信
|
||
floorId: 1, // 初始楼层 ID
|
||
timeout: 5000 // API 调用的默认超时时间（毫秒）
|
||
});
|
||
```
|
||
|
||
### 2.2 等待就绪事件
|
||
**重要：** SDK 的所有控制指令（如聚焦、寻路等）必须在 `ready` 事件触发后调用。
|
||
```javascript
|
||
map.on('ready', (info) => {
|
||
console.log('地图引擎加载完成', info.engineVersion);
|
||
// 现在可以安全调用 API 了
|
||
});
|
||
```
|
||
|
||
### 2.3 销毁实例
|
||
当页面卸载时，为了避免内存泄漏，必须调用 `destroy()`。
|
||
```javascript
|
||
// 清除 DOM、注销所有监听事件并拒绝所有挂起的异步调用
|
||
map.destroy();
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 常用场景 API
|
||
|
||
### 3.1 楼层切换
|
||
切换楼层是**异步**的，SDK 会在后台销毁旧楼层 WebGL 显存，并加载新楼层模型。
|
||
```javascript
|
||
map.changeFloor(3).then((res) => {
|
||
console.log("成功切换至楼层: ", res.floorId);
|
||
}).catch(err => {
|
||
console.error("切换失败: ", err.message);
|
||
});
|
||
```
|
||
|
||
### 3.2 搜索与对焦
|
||
当用户在搜索栏查找到具体要素后，使镜头平滑飞至要素上方：
|
||
```javascript
|
||
// 通过 POI ID 对焦（推荐）
|
||
map.focusTo({ type: 'poiId', value: 10102 });
|
||
|
||
// 通过三维节点名称对焦
|
||
map.focusTo({ type: 'nodeName', value: 'Hall_DomeTheater' });
|
||
```
|
||
|
||
### 3.3 路线导航
|
||
起点与终点均支持绝对坐标或 POI ID。
|
||
```javascript
|
||
map.planRoute(
|
||
{ type: 'poiId', value: 8001 }, // 起点
|
||
{ type: 'poiId', value: 9005 }, // 终点
|
||
{ mode: 'walk' } // 选项：walk 或 accessible(无障碍)
|
||
).then((result) => {
|
||
if (result.success) {
|
||
console.log(`路径规划成功：总距离 ${result.distance} 米，预计步行 ${result.duration} 秒`);
|
||
// 基座会自动在 3D 场景中渲染青色流光折线
|
||
}
|
||
}).catch(err => {
|
||
if (err.code === 'ERR_NO_PATH') {
|
||
alert("抱歉，无法找到可达的路线。");
|
||
}
|
||
});
|
||
|
||
// 清除路线
|
||
map.clearRoute();
|
||
```
|
||
|
||
### 3.4 响应 POI 点击
|
||
游客在三维场景中点击任意可交互物体时，SDK 会派发 `poiClick` 事件。
|
||
```javascript
|
||
map.on('poiClick', (poi) => {
|
||
console.log(`用户点击了：${poi.name} (ID: ${poi.poiId})`);
|
||
// 业务侧可在此处弹出底部展品详情栏或抽屉
|
||
});
|
||
```
|
||
|
||
### 3.5 动态撒图钉 (Marker)
|
||
```javascript
|
||
// 添加一个悬浮图标
|
||
map.addMarker({
|
||
markerId: 'marker-user-1',
|
||
anchorNodeName: 'Hall_Dinosaur',
|
||
imageUrl: 'https://domain.com/user-avatar.png',
|
||
width: 64,
|
||
height: 64,
|
||
yOffset: 2 // 悬浮于物体上方 2 米
|
||
});
|
||
|
||
// 清除图钉
|
||
map.removeMarker('marker-user-1');
|
||
map.clearMarkers();
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 错误处理
|
||
|
||
SDK 采用 Promise 风格的异步响应，所有 `catch` 捕获的错误都遵循 `{ code, message }` 格式。
|
||
|
||
| 错误码 | 触发场景 |
|
||
|--------|----------|
|
||
| `ERR_TIMEOUT` | 网络拥塞或基座无响应，超出了构造时设置的超时时间 |
|
||
| `ERR_NOT_READY` | 在 `ready` 事件触发前，强行调用了 API |
|
||
| `ERR_NO_PATH` | 起点与终点之间没有连通的 NavMesh 物理网格 |
|
||
| `ERR_UNAUTHORIZED` | 通信双方跨域安全策略 (`targetOrigin`) 校验失败 |
|