stxcloudutil

AirCity 云渲染 API 封装库 - 简化数字孪生三维场景开发

特性

• 一键启动 - startDigitalTwin() 自动加载 SDK 并初始化
• 链式调用 - 流式 API，内置合理默认参数
• 实例管理 - 自动追踪所有实体，支持批量操作和分组
• 原生 API 劫持 - __g.marker.add() 等原生调用也会被自动管理
• 原始 API 访问 - cloud.api 或 useAPI() 获取带类型提示的原始 __g
• 组织树操作 - TreeHelper 提供模型树的查询、显隐、聚焦等便捷方法
• TypeScript - 完整的类型定义，__g / fdapi 全局变量自动获得类型提示
• ESM + CJS - 双格式输出，兼容所有环境

安装

npm install stxcloudutil

全局类型提示

安装后，__g 和 fdapi 全局变量自动获得完整类型提示，无需额外配置。

在 TypeScript 项目中，确保 tsconfig.json 包含：

{
  "compilerOptions": {
    "types": ["stxcloudutil"]
  }
}

之后即可直接使用带类型提示的全局变量：

// 直接使用 __g，有完整的智能提示
__g.marker.add({ id: 'm1', coordinate: [0, 0, 0] });
__g.camera.set({ x: 100, y: 200, z: 50, pitch: -45, yaw: 0 });

// window.__g 同样有类型提示
window.__g.weather.setRain(0.5);

// fdapi 也支持
fdapi.polygon.add({ id: 'p1', coordinates: [[0,0,0],[100,0,0],[100,100,0]] });

快速开始

一键启动（推荐）

import { startDigitalTwin } from 'stxcloudutil';

const cloud = await startDigitalTwin({
  host: '19.1.1.23:8081',
  domId: 'player',
});

cloud.marker.create('m1').setText('Hello').show();

手动初始化

播放器就绪后手动初始化：

import { initCloudAPI, useCloudAPI } from 'stxcloudutil';

initCloudAPI(__g);

// 任意位置使用
const cloud = useCloudAPI();
cloud.marker.create('marker-1').setText('我的标记').show();

配置选项

initCloudAPI(__g, {
  hookNativeAPI: true,   // 是否劫持原生 API，默认 true
  autoInitTree: true,    // 是否自动初始化组织树，默认 true
});

核心 API

实体操作

所有实体均支持链式调用和延迟提交（show() / update() 时才发送请求）：

Marker（标记点）

cloud.marker
  .create('m1')
  .setText('我的标记')
  .setCoordinate([100, 200, 50])
  .setFontColor('RGB(255, 0, 0)')
  .show();

// 获取已有实例
cloud.marker.get('m1')?.setText('新文本').update();

Polygon（多边形）

cloud.polygon
  .create('p1')
  .setCoordinates([[0, 0, 0], [100, 0, 0], [100, 100, 0], [0, 100, 0]])
  .setColor('RGBA(255, 0, 0, 0.5)')
  .show();

Polyline（折线）

cloud.polyline
  .create('l1')
  .setCoordinates([[0, 0, 0], [100, 100, 50]])
  .setColor('RGB(0, 255, 255)')
  .setFlowRate(0.8)
  .show();

其他实体

// Polygon3D（拉伸多边形）
cloud.polygon3d.create('p3d-1').setCoordinates([...]).setHeight(100).show();

// Beam（光流）
cloud.beam.create('beam-1').setCoordinates([...]).setColor('RGB(255,255,0)').show();

// RadiationPoint（辐射圈）
cloud.radiationPoint.create('rp-1').setCoordinate([...]).setRadius(100).show();

延迟更新

setter 方法只修改本地数据，调用 show() 或 update() 时才提交到引擎：

cloud.marker
  .create('m1')
  .setText('文本')       // 不发送请求
  .setCoordinate([...])  // 不发送请求
  .show();               // 只发送一次请求

批量操作

// 按分组操作
cloud.marker.getByGroupId('group-a');

// 清空所有实体
await cloud.clearAll();

// 批量删除
await cloud.marker.deleteMany(['m1', 'm2', 'm3']);

原始 API 访问

通过 cloud.api 或 useAPI() 获取带完整类型提示的 __g：

// 方式一：通过 cloud 实例
cloud.api.camera.set(x, y, z, pitch, yaw);
cloud.api.weather.setRain(0.5);

// 方式二：便捷函数
import { useAPI } from 'stxcloudutil';
useAPI().marker.add({ id: 'm1', coordinate: [0, 0, 0] });

CloudAPI 还提供了常用模块的快捷访问：

cloud.camera   // 相机操作
cloud.weather  // 天气操作
cloud.infoTree // 信息树操作
cloud.settings // 设置操作
cloud.tools    // 工具操作

原生 API 劫持

默认开启劫持，原生方法创建的实体也会被自动管理：

__g.marker.add({ id: 'native-1', coordinate: [0, 0, 0] });
cloud.marker.get('native-1'); // ✅ 可获取

关闭劫持：

initCloudAPI(__g, { hookNativeAPI: false });

组织树操作

cloud.tree 提供模型组织树的便捷操作（初始化时默认自动加载树数据）：

// 手动初始化（autoInitTree: false 时需要）
await cloud.tree.init();

// 按名称查找
cloud.tree.getNodesByName('会议室');

// 显示/隐藏
cloud.tree.showByName('会议室');
cloud.tree.hideByName('临时建筑');

// 按路径查找
cloud.tree.getNodesByPath('园区>建筑A>1层');

// 聚焦
cloud.tree.focusByName('会议室');

// 统计
const stats = cloud.tree.getStats();
console.log(stats.totalNodes, stats.visibleNodes);

跨组件访问

无需传递 cloud 实例，通过便捷函数直接获取实体：

import { useMarker, usePolygon } from 'stxcloudutil';

const marker = useMarker('m1');
marker?.setText('新文本').update();

可用的便捷函数：

| 函数 | 返回类型 | |------|---------| | useCloudAPI() | CloudAPI | | useAPI() | DigitalTwinAPI（即 __g） | | useMarker(id) | MarkerInstance \| undefined | | usePolygon(id) | PolygonInstance \| undefined | | usePolyline(id) | PolylineInstance \| undefined | | usePolygon3D(id) | Polygon3DInstance \| undefined | | useBeam(id) | BeamInstance \| undefined | | useRadiationPoint(id) | RadiationPointInstance \| undefined |

导出总览

// 核心类
export { CloudAPI, MarkerManager, MarkerInstance, ... }

// 全局单例
export { initCloudAPI, useCloudAPI }

// 便捷函数
export { useAPI, useMarker, usePolygon, ... }

// 一键启动
export { startDigitalTwin }

// 组织树
export { TreeHelper, ModelTreeUtil, type TreeNode, ... }

License

MIT