场景接口文档
概述
window.scene.api 是Geotwin APP对外暴露的 JavaScript API 接口，允许外部通过该接口控制和操作 3D 场景地图。外部系统（包括页面脚本、集成平台等）应统一通过 window.scene.api 调用相关功能。
初始化
当场景地图组件创建完成后，会自动将 API 挂载到 window.scene.api 上。可以通过监听 sceneReady 事件来确保 API 已就绪：
window.addEventListener('sceneReady', (event) => {
const { compositeViewer, viewer } = event.detail;
console.log('场景已准备就绪');
// 此时可以安全地使用 window.scene.api
});
API 方法
getCompositeViewer()
获取复合视图器实例。
返回值：
CompositeViewer - 复合视图器实例，包含场景的所有组件管理器
示例：
const compositeViewer = window.scene.api.getCompositeViewer();
const layerComponent = compositeViewer.componentManager.getComponent(LayerComponent);
getBookmark()
获取当前场景的书签列表。该方法会请求后端接口获取与当前场景 sceneId 相关联的书签数据。
注意：
- 依赖场景数据中的
sceneId 与地图组件配置中的 option.server（作为接口 baseURL）
- 如果当前未能获取到
sceneId 或 server，将返回一个被拒绝的 Promise
返回值：
Promise<any> - 书签列表接口返回的原始响应数据
示例：
window.scene.api.getBookmark()
.then((res) => {
// 具体结构取决于后端实现，这里给出一个典型用法
const rows = res.data?.data?.rows ?? [];
console.log('书签列表：', rows);
})
.catch((err) => {
console.error('获取书签失败：', err);
});
triggerSceneGraphDelta(delta)
触发场景图增量更新，用于对场景中的节点进行增删改操作。
参数：
delta: ISceneGraphDelta - 场景图增量数据对象
ISceneGraphDelta 类型：
1. 插入节点 (Insert)
{
type: "Insert",
delta: INodeData // 完整的节点数据
}
2. 修改节点 (Change)
{
type: "Change",
delta: {
guid: string, // 必需：节点的唯一标识符
// 其他要修改的属性（可选）
name?: string,
visible?: boolean,
// ... 其他 INodeData 属性
}
}
3. 删除节点 (Delete)
{
type: "Delete",
delta: {
guid: string, // 必需：要删除节点的唯一标识符
}
}
示例：
// 修改节点可见性
window.scene.api.triggerSceneGraphDelta({
type: "Change",
delta: {
guid: "node-guid-123",
visible: false
}
});
// 删除节点
window.scene.api.triggerSceneGraphDelta({
type: "Delete",
delta: {
guid: "node-guid-123"
}
});
genGUID()
生成GUID，确保在外部创建的实体与场景图中的实体使用同一套ID生成规则
返回值：
示例：
const guid = window.scene.api.genGUID()
flyTo(...args)
相机飞行到指定位置。
参数：
x: number - X 坐标y: number - Y 坐标z: number - Z 坐标（高度）heading?: number - 方位角（度）pitch?: number - 俯仰角（度）roll?: number - 翻滚角（度）duration?: number - 飞行持续时间（毫秒）
示例：
// 飞行到指定位置
window.scene.api.flyTo({
x: 0,
y: 0,
z: 1000,
heading: 0,
pitch: -45,
duration: 2000
});
flyToEntity(guid)
相机飞行到指定实体（图层）。
参数：
guid: string - 实体的唯一标识符 GUID
示例：
// 飞行到指定图层
window.scene.api.flyToEntity("layer-guid-123");
flyToGeometry(geometry)
相机飞行到指定的 GeoJSON 几何图形。
参数：
geometry: Geometry - GeoJSON 标准几何对象
GeoJSON Geometry 类型包括：
Point - 点LineString - 线Polygon - 多边形MultiPoint - 多点MultiLineString - 多线MultiPolygon - 多多边形
示例：
// 飞行到多边形区域
window.scene.api.flyToGeometry({
type: "Polygon",
coordinates: [
[
[116.3, 39.9],
[116.4, 39.9],
[116.4, 40.0],
[116.3, 40.0],
[116.3, 39.9]
]
]
});
// 飞行到点
window.scene.api.flyToGeometry({
type: "Point",
coordinates: [116.404, 39.915]
});
flyToBookmark(bookmark, duration)
根据书签数据飞行到指定视角位置。
参数：
bookmark: object - 书签数据对象，通常包含以下字段：
longitude: number - 书签经度（WGS84，经纬度坐标系 4326）latitude: number - 书签纬度（WGS84，经纬度坐标系 4326）height: number - 相机高度heading: number - 航向角（度）tilt: number - 俯仰角（度）
duration: number - 飞行持续时间（秒）
示例：
const bookmark = {
longitude: 116.404,
latitude: 39.915,
height: 500,
heading: 30,
tilt: -45,
};
// 在 3 秒内飞行到书签位置
window.scene.api.flyToBookmark(bookmark, 3);
translateCoord(options)
坐标转换工具方法，基于引擎内置的 CoordTransform.translate 实现，可在不同坐标系 / 投影之间进行转换。
参数：
options: object - 坐标转换配置对象，常用字段包括：
fromEPSG?: string - 源坐标系 EPSG 代码（例如 "4326"）toProj4?: string - 目标投影的 proj4 字符串（通常可从 viewer.proj4 获取）x: number - 源坐标 X（经度或平面 X）y: number - 源坐标 Y（纬度或平面 Y）
返回值：
number[] - 转换后的坐标数组，一般为 [x, y]
示例：
const cv = window.scene.api.getCompositeViewer();
const viewer = cv.viewer;
// 将 WGS84 经纬度转换到当前场景投影坐标
const [x, y] = window.scene.api.translateCoord({
fromEPSG: "4326",
toProj4: viewer.proj4,
x: 116.404,
y: 39.915,
});
console.log('投影坐标：', x, y);
setViewMode(mode)
设置视图模式。
参数：
mode: "2D" | "3D" - 视图模式
"2D" - 2D 平面视图"3D" - 3D 立体视图
示例：
// 切换到 2D 模式
window.scene.api.setViewMode("2D");
// 切换到 3D 模式
window.scene.api.setViewMode("3D");
backToTheNorth()
将相机方位角重置为正北方向（heading = 0），保持当前位置和俯仰角不变。
示例：
// 回到正北方向
window.scene.api.backToTheNorth();
getFlyControl()
获取飞行控制组件实例（FlyThroughComponent），用于实现更复杂的飞行路径控制等高级功能。
返回值：
FlyThroughComponent - 飞行控制组件实例，具体能力请参考 @gt-viewer/sdk 文档
示例：
const flyControl = window.scene.api.getFlyControl();
// 根据 SDK 文档使用 flyControl 实例进行自定义飞行控制
vectorHighlight 高亮控制
vectorHighlight 是挂载在 window.scene.api 下的一个子对象，用于控制矢量图层的高亮效果。
vectorHighlight.add(guid, ids)
为指定矢量图层添加高亮要素。
参数：
guid: string - 图层的 GUIDids: number[] - 需要高亮的要素 ID 数组
示例：
// 高亮图层中 ID 为 1、2、3 的要素
window.scene.api.vectorHighlight.add("layer-guid-123", [1, 2, 3]);
vectorHighlight.remove(guid, ids)
移除指定要素的高亮效果。
参数：
guid: string - 图层的 GUIDids: number[] - 需要取消高亮的要素 ID 数组
示例：
// 取消对要素 2、3 的高亮
window.scene.api.vectorHighlight.remove("layer-guid-123", [2, 3]);
vectorHighlight.clear(guid)
清除指定图层的所有高亮效果。
参数：
示例：
// 清除整个图层的高亮
window.scene.api.vectorHighlight.clear("layer-guid-123");
其他事件
sceneGraphChange 事件
当场景图发生变化时触发。
监听示例：
window.addEventListener('sceneGraphChange', (event) => {
const sceneData = event.detail.data;
console.log('场景图已更新', sceneData);
});
完整使用示例
// 等待场景准备就绪
window.addEventListener('sceneReady', (event) => {
console.log('场景已就绪');
// 获取复合视图器
const compositeViewer = window.scene.api.getCompositeViewer();
// 飞行到指定位置
window.scene.api.flyTo({
x: 0,
y: 0,
z: 5000,
heading: 0,
pitch: -60,
duration: 3000
});
// 3秒后切换到2D视图
setTimeout(() => {
window.scene.api.setViewMode("2D");
}, 3000);
// 6秒后回到正北方向
setTimeout(() => {
window.scene.api.backToTheNorth();
}, 6000);
});
// 监听场景图变化
window.addEventListener('sceneGraphChange', (event) => {
console.log('场景数据更新:', event.detail.data);
});
// 修改节点可见性
function toggleNodeVisibility(guid, visible) {
window.scene.api.triggerSceneGraphDelta({
type: "Change",
delta: {
guid: guid,
visible: visible
}
});
}
// 飞行到某个实体
function focusOnEntity(guid) {
window.scene.api.flyToEntity(guid);
}
// 飞行到北京天安门
function flyToTiananmen() {
window.scene.api.flyToGeometry({
type: "Point",
coordinates: [116.404, 39.915]
});
}
数据结构
INodeData
节点数据结构（简化版）：
interface INodeData {
guid: string; // 节点唯一标识符
type: string; // 节点类型：VIEWER | LAYER | FEATURE
name?: string; // 节点名称
visible?: boolean; // 是否可见
parentIndex?: number; // 父节点索引
render?: object; // 渲染数据
animation?: any[]; // 动画数据
meta?: object; // 元数据
}
注意事项
- API 可用性：确保在
sceneReady 事件触发后再使用 API
- GUID 格式：所有 GUID 参数应为有效的字符串标识符
- 坐标系统：坐标参数取决于场景使用的投影坐标系
- 角度单位：
flyTo 方法中的 heading、pitch、roll 参数单位为度（degree）
- 异步操作：飞行操作是异步的，如需在飞行完成后执行操作，请使用适当的延时或回调
版本信息
- 文档版本：1.1.0
- 更新日期：2026-02-28