STX CloudUtil

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

特性

🚀 一键启动 - startDigitalTwin() 自动加载 SDK 并初始化
🎯 简化 API - 链式调用，内置默认参数
📦 实例管理 - 自动追踪所有实体，支持批量操作
🎣 API 劫持 - 原生 API 调用也会被自动管理
📘 TypeScript - 完整的类型定义
🔄 ESM + CJS - 双格式输出，兼容所有环境

安装

npm install stxcloudutil

快速开始

一键启动（推荐）

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();

核心实体

Marker（标记点）

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

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)')
  .show();

其他实体

cloud.polygon3d.create('p3d-1').setCoordinates([...]).show();
cloud.beam.create('beam-1').setCoordinates([...]).show();
cloud.radiationPoint.create('rp-1').setCoordinate([...]).show();

跨组件访问

import { useMarker, usePolygon } from 'stxcloudutil';

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

组织树操作

await cloud.tree.init();

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

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

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

延迟更新

setter 方法采用延迟更新，show() 或 update() 时才发送请求：

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

原生 API 劫持

默认劫持原生方法，自动管理所有实体：

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

关闭劫持：

initCloudAPI(__g, { hookNativeAPI: false });

License

MIT