SDK 开发指南

快速开始

方式一：在 CIMPro孪大师 客户端中运行

适用于将网页嵌入 CIMPro孪大师 客户端内部运行的场景。

1. 引入 SDK（2 行）

通过 <script> 标签引入，注册全局变量 PiClientJS：

html 
<script src="./index.umd.js"></script>
<!-- 或使用 CDN（请将 @1.x.x 替换为实际版本号） -->
<script src="https://cdn.jsdelivr.net/npm/new-piclient.js@1.x.x/index.umd.js"></script>

注：index.umd.js 可直接重命名为 piclient.js，功能完全一致。

2. 初始化并等待场景就绪（6 行）

javascript 
const piclient = new PiClientJS.PiClient({ debug: true });

// 等待客户端场景对象加载完成
await piclient.pageReady().then((baseDb) => {
  console.log('场景加载完成', baseDb);
}).catch((err) => {
  console.error('加载失败:', err);
});

3. 发送事件与监听回调

javascript 
// 发送事件：设置天气为多云
piclient.emit('environment.setWeather', { weather: 3 });

// 监听对象点击事件
piclient.on('object.onClick', '', (res) => {
  console.log('对象被点击:', res);
});

// 全局监听所有事件
piclient.on('global', '', (res) => {
  console.log('全局事件:', res);
});

方式二：在浏览器中通过云渲染加载

适用于在浏览器中通过 WebRTC 像素流连接 CIMPro孪大师 客户端的场景。

1. 引入 SDK（同方式一）

html 
<!-- 请将 @1.x.x 替换为实际版本号，避免使用 @latest -->
<script src="https://cdn.jsdelivr.net/npm/new-piclient.js@1.x.x/index.umd.js"></script>

注：云渲染模式不支持原生 ES Modules 引入方式。

2. 配置云渲染参数并连接

javascript 
const piclient = new PiClient({ debug: true });

const initConfig = {
  $el: document.getElementById('container'),     // 渲染容器 DOM
  address: 'ws://192.168.3.73:9000/',           // 信令服务器地址
  appKey: '123',                                // AppKey（为空则使用云渲染）
  mode: 'pixelstreaming',                        // pixelstreaming | embed
  editorMode: false,
  showUI: false,
  initialSettings: {
    MatchViewportRes: true,
    WebRTCFPS: 30,
    WebRTCMaxBitrate: 8000,
  },
  onDisconnect: (msg) => {
    console.log('连接断开:', msg);
  }
};

// 如果已有连接，先销毁
if (connected) {
  piclient.cloudrender.destroy();
}

piclient.cloudrender.init(initConfig).then((baseDb) => {
  console.log('连接成功', baseDb);
  console.log('可用事件列表:', piclient.classEvents);

  // 进入播放模式并隐藏编辑器 UI
  piclient.emit('mode.enterPlayMode');
  setTimeout(() => {
    piclient.emit('ui.setClientUIVisible', { visible: 'hide' });
  }, 1000);
}).catch((err) => {
  console.error('初始化失败:', err);
});

使用构建工具（npm）

bash 
npm install new-piclient.js
typescript 
import { PiClient } from 'new-piclient.js'

const piclient = ref(null);

const connect = async () => {
  piclient.value = new PiClient({ debug: true });
  await piclient.value.pageReady().then((baseDb) => {
    console.log('场景加载完成', baseDb);
  });
};

onMounted(async () => {
  await connect();

  piclient.value.on('cloud.init', '', (res) => {
    console.log(JSON.stringify(res));
  });

  piclient.value.on('environment.setWeather', '', (res) => {
    console.log(JSON.stringify(res));
  });

  piclient.value.on('global', '', (res) => {
    console.log(`<全局> ${JSON.stringify(res)}`);
  });
});

TypeScript 支持

PiClient JS SDK 内置 TypeScript 类型定义，无需额外安装 @types 包。

类型声明

typescript 
// 从 npm 包导入时自动获得类型提示
import { PiClient } from 'new-piclient.js';

// 全局变量声明（CDN 引入方式）
declare global {
  interface Window {
    PiClientJS: {
      PiClient: new (options?: { debug?: boolean }) => PiClientInstance;
    };
  }
}

// 主要类型接口
interface PiClientInstance {
  emit(action: string, param?: Record<string, any>): Promise<any>;
  on(action: string, target: string, fn: (res: any) => void): void;
  once(action: string, target: string, fn: (res: any) => void): void;
  off(action: string, target?: string): boolean;
  pageReady(): Promise<any>;
  cloudrender: {
    init(config: CloudRenderConfig): Promise<any>;
    destroy(): void;
  };
  classEvents: string[];
}

interface CloudRenderConfig {
  $el: HTMLElement | null;
  address: string;
  appKey?: string;
  mode?: 'pixelstreaming' | 'embed';
  editorMode?: boolean;
  projectId?: string;
  showUI?: boolean;
  StreamerId?: string;
  initialSettings?: Record<string, any>;
  onProgress?: (percent: number) => void;
  onDisconnect?: (msg: string) => void;
}

版本要求

环境 最低版本 说明
TypeScript ≥ 4.5 支持 import type 和 satisfies 运算符
Node.js ≥ 16 配合构建工具使用

Vue 框架集成

以下示例基于 Vue 3 Composition API，使用 <script setup> 语法。Vue 2 用户请参考 Options API 版本。

Vue 3 Composition API（推荐）

vue 
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { PiClient } from 'new-piclient.js';

const piclient = ref<InstanceType<typeof PiClient> | null>(null);
const connected = ref(false);

const connect = async () => {
  piclient.value = new PiClient({ debug: true });
  await piclient.value.pageReady();
  connected.value = true;
};

const sendEvent = () => {
  if (!piclient.value) return;
  piclient.value.emit('environment.setWeather', { weather: 1 });
};

onMounted(() => {
  connect();
  piclient.value?.on('object.onClick', '', (res) => {
    console.log('点击:', res);
  });
});
</script>

Vue 2 Options API

vue 
<script>
export default {
  data() {
    return {
      piclient: null,
      connected: false
    };
  },
  async mounted() {
    const { PiClient } = window.PiClientJS;
    this.piclient = new PiClient({ debug: true });
    await this.piclient.pageReady();
    this.connected = true;

    this.piclient.on('object.onClick', '', (res) => {
      console.log('点击:', res);
    });
  },
  methods: {
    sendEvent() {
      if (!this.piclient) return;
      this.piclient.emit('environment.setWeather', { weather: 1 });
    }
  }
};
</script>

事件交互 API

emit — 触发事件

向 CIMPro孪大师 客户端发送指令，支持 API 列表中的预定义事件或动态事件。

typescript 
piclient.emit(action: string, param?: object): Promise<any>
参数 类型 必填 说明
action string 是 事件名称，如 object.visible
param object 否 事件参数对象

常用示例：

javascript 
// 对象显隐
piclient.emit('object.visible', {
  target: 'SceneMeshObject_0',
  visible: 'toggle'   // show | hide | toggle
});

// 相机飞行到对象
piclient.emit('camera.fly', {
  target: 'ObjectId',
  time: '3.0'         // 飞行时长（秒）
});

// 设置时间
piclient.emit('environment.setTime', {
  hour: 15,
  minute: 30
});

// 设置天气
piclient.emit('environment.setWeather', {
  weather: 3          // 3=多云，详见 API 手册
});

on — 绑定事件监听

监听客户端推送的事件，支持自定义回调和全局事件。

typescript 
piclient.on(action: string, target: string, fn: (res: any) => void): void
参数 类型 必填 说明
action string 是 监听的事件名称
target string 是 目标对象 ID（全局监听传空字符串）
fn function 是 回调函数

常用示例：

javascript 
// 监听云渲染初始化完成
piclient.on('cloud.init', '', (res) => {
  console.log('云渲染初始化:', res);
});

// 监听对象点击（全局）
piclient.on('object.onClick', '', (res) => {
  console.log('对象被点击:', res);
});

// 监听特定对象点击
piclient.on('object.onClick', 'SceneMeshObject_0', (res) => {
  console.log('特定对象被点击:', res);
});

// 全局监听所有事件
piclient.on('global', '', (res) => {
  console.log('全局事件:', res);
  // 输出示例：
  // {"action":"object.onUnSelect","target":"SceneMeshObject_0","params":{"objects":["SceneMeshObject_0"]}}
});

once — 单次监听

同 on，但仅触发一次后自动解绑。

javascript 
// 只监听一次对象点击
piclient.once('object.onClick', 'SceneMeshObject_0', (res) => {
  console.log('首次点击:', res);
  // 再次点击不再触发
});

off — 解绑监听

typescript 
piclient.off(action: string, target?: string): boolean
javascript 
// 解绑特定对象的点击事件
piclient.off('object.onClick', 'SceneMeshObject_0');

// 解绑所有对象的点击事件
piclient.off('object.onClick');

事件速查表

事件名 说明 触发时机
cloud.init 云渲染初始化 云渲染连接成功
object.onClick 对象点击 鼠标点击场景对象
object.onDoubleClick 对象双击 鼠标双击场景对象
object.onMoved 对象移动 对象位置发生变化
object.onVisible 对象显隐 对象显示/隐藏状态变化
object.onCreate 对象创建 新对象被创建
object.onDestroy 对象销毁 对象被销毁
pathfollow.onCheck 巡检检查 巡检路线到达检查点
global 全局事件 所有事件的聚合通道

完整事件列表请参考 客户端API手册 - 事件清单。

常见问题

Q：CDN 引入后 PiClientJS 未定义？

确认脚本已正确加载，可通过以下方式检测：

javascript 
if (window.PiClientJS && window.PiClientJS.PiClient) {
  console.log('SDK 加载成功');
} else {
  console.error('SDK 未加载，请检查网络或路径');
}

Q：云渲染连接失败？

  • 检查信令服务器地址是否正确（格式 ws://ip:port/）
  • 确认 PiStudio 客户端已启动并处于等待连接状态
  • 检查浏览器是否支持 WebRTC

Q：Vue 3 中使用 ref 报错？

确保使用 ref 导入自 vue，而非原生 DOM API：

typescript 
import { ref } from 'vue';  // ✅ 正确
// const ref = document.querySelector;  // ❌ 错误

🐛 问题反馈：提交 Issue