720yun-sdk-api.md

SDK 数据包获取

SDK 的使用包含【SDK 数据包】和【SDK 播放器】两部分，本文档以【SDK 播放器】的使用为主要内容，如何获取【SDK 数据包】请查阅 SDK 离线数据包同步到阿里云 OSS & 离线下载教程

SDK 文件引入

目前提供两种方式引入 SDK 文件：

通过 720 云 CDN 引入，地址为：https://ssl-sdk.720static.com/720yun-sdk/prod/720yun-sdk-latest。
通过自有地址引入，需要先将 SDK 下载到自己服务器/存储上进行部署（将整个压缩包解压后部署）后再引入，下载地址：https://ssl-sdk.720static.com/720yun-sdk/prod/720yun-sdk-latest.zip

初始化说明

引入 js 和 css 文件

<!-- 通过720云CDN引入 -->
<script src="https://ssl-sdk.720static.com/720yun-sdk/prod/720yun-sdk-latest/js/720yun_SDK.js"></script>
<link rel="stylesheet" href="https://ssl-sdk.720static.com/720yun-sdk/prod/720yun-sdk-latest/css/tour.css">

<!-- 通过自有地址引入，域名为示例域名 -->
<script src="https://www.example.com/720yun-sdk/js/720yun_SDK.js"></script>
<link rel="stylesheet" href="https://www.example.com/720yun-sdk/css/tour.css">

页面中放入一个 id 为 panoContainer 的 div 容器

<div id="panoContainer"></div>

初始化全景播放器

window.PanoPlayer.setup({
    sdkUrl: 'https://ssl-sdk.720static.com/720yun-sdk/prod/720yun-sdk-latest/', // SDK 路径，http/https 开头的完整路径，以 / 结束，这里以720云CDN为例
    baseUrl: 'https://ssl-sdk.720static.com/720yun-sdk/example/data/', //数据包路径，http/https 开头的绝对路径
    extendData: {}
}, {
    // 具体配置参考文档
    // startAnimation: 0, //关闭开场动画
    // logo: "https://example.com/logo.jpg", //显示自定义 logo
    // autoRotate: 0, //关闭自动旋转
    // description: 0, //关闭简介按钮
    // sceneList: 3, //显示场景切换按钮但默认隐藏场景列表
    // fullscreen: 0, //关闭全屏按钮
    // vr: 0, //关闭 VR 按钮
    // viewSwitch: 0, //关闭视角切换按钮
    // gyroscope: 0, //关闭陀螺仪按钮
    // dragMode: 1, //默认拖拽模式为正向
    // disableSandTable: 1, //关闭沙盘
}).then(player => {
    // 初始化完成
    console.log('player init complete', player);
    // 场景加载完成后的回调
    player.openApi.addSceneLoadedListener((partnerId, sceneId) => {
        console.log('scene load complete, ', 'partnerId:', partnerId, ', sceneId:', sceneId);
    });
    window.player = player;
}).catch(err => {
    console.error('player init error', err);
});

初始化接口

window.PanoPlayer.setup({baseUrl, sdkUrl, jsonData, extendData}, config) : Promise

baseUrl(string): 数据包路径，必须是 http/https 开头的绝对路径
sdkUrl(string): SDK 路径，必须是 http/https 开头的绝对路径
extendData(object): 扩展数据
- enableSnapshoot(boolean): 是否开启截图功能（开启截图功能会影响性能）
config(object): 全局配置
- entrySceneId(string | number): 开场场景Id，可使用 partnerId 或者场景id
- startAnimation(0 | 1): 开场动画,0 关闭, 1 开启
- logo(string): 自定义 logo，传空字符串""为关闭，否则传 logo 的完整 URL
- autoRotate(0 | 1 | 2): 自动旋转,0 关闭, 1 视角向右旋转,2 视角向左旋转
- sceneList(0 ｜ 1 | 2 | 3): 场景选择，0 关闭，1 显示列表和按钮， 2 隐藏按钮显示列表， 3 显示按钮隐藏列表
- description(0 | 1): 简介按钮，0 关闭，1 开启
- vr(0 | 1): 进入 VR 模式开关，0 关闭，1 开启
- fullscreen(0 | 1): 进入全屏按钮，0 关闭，1 开启（仅在支持全屏功能的浏览器有效）
- viewSwitch(0 | 1): 视角切换按钮，0 关闭，1 开启
- gyroscope(0 | 1 | 2): 陀螺仪开关，0 关闭，1 开启，2 自动进入陀螺仪模式（仅在支持陀螺仪的设备有效）
- dragMode(0 | 1): 操作模式，0 反向，1 正向（仅在鼠标操作设备生效）
- disableSubtitle(1): 禁用字幕功能
- disableSandTable(1): 禁用沙盘模块
- disablePanoSplicing(1): 禁用全景对比模块
- disableCustomButtons(1): 禁用自定义按钮
- disableZoom(1): 禁用图片缩放（仅针对矩阵图片有效）
- hideAllHotspots(1): 默认隐藏所有热点

完整示例

<!DOCTYPE html>
<html lang="zh-cn">

<head>
    <title>SDK Demo</title>
    <meta name="referrer" content="always">
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width,user-scalable=no,initial-scale=1,maximum-scale=1,minimum-scale=1,viewport-fit=cover">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <meta name="format-detection" content="telephone=no,address=no,email=no">
    <meta name="renderer" content="webkit">
    <meta name="robots" content="all">
    <!-- 引入 sdk  -->
    <link rel="stylesheet" href="https://ssl-sdk.720static.com/720yun-sdk/prod/720yun-sdk-latest/css/tour.css">
    <script src="https://ssl-sdk.720static.com/720yun-sdk/prod/720yun-sdk-latest/js/720yun_SDK.js"></script>
</head>

<body>
    <!-- 全景播放器容器 div -->
    <div id="panoContainer"></div>
    <script>
        // 初始化全景，会默认在 id 为 panoContainer 的 div 中渲染全景
        window.PanoPlayer.setup({
            sdkUrl: 'https://ssl-sdk.720static.com/720yun-sdk/prod/720yun-sdk-latest/', // SDK 路径，http/https 开头的完整路径，以 / 结束，这里以720云CDN为例
            baseUrl: 'https://ssl-sdk.720static.com/720yun-sdk/example/data/', //数据包路径，http/https 开头的绝对路径
            extendData: {}
        }, {
            // 具体配置参考文档
            startAnimation: 0, //关闭开场动画
            logo: "https://example.com/logo.jpg", //显示自定义 logo
            autoRotate: 0, //关闭自动旋转
            description: 0, //关闭简介按钮
            sceneList: 3, //显示场景切换按钮但默认隐藏场景列表
            fullscreen: 0, //关闭全屏按钮
            vr: 0, //关闭 VR 按钮
            viewSwitch: 0, //关闭视角切换按钮
            gyroscope: 0, //关闭陀螺仪按钮
            dragMode: 1, //默认拖拽模式为正向
            disableSandTable: 1, //关闭沙盘
        }).then(player => {
            // 初始化完成
            console.log('player init complete', player);
            // 场景加载完成后的回调
            player.openApi.addSceneLoadedListener((partnerId, sceneId) => {
                console.log('scene load complete, ', 'partnerId:', partnerId, ', sceneId:', sceneId);
            });
            window.player = player;
        }).catch(err => {
            console.error('player init error', err);
        });
    </script>
</body>

</html>

接口说明

所有接口均暴露在 player 的 openApi 上，调用时直接使用 player.openApi.{接口名称}。

接口列表

更新当前视角

updateView({ fov, vlookat, hlookat })
- fov(number): 视角 FOV，取值 [0,180]
- vlookat(number): 垂直偏移，取值 [-90,90]
- hlookat(number): 水平偏移，任意值，一般使用 0-360
```
player.openApi.updateView(
 {
  fov: 85,
  hlookat: 22,
  vlookat: 40
 }
);
```

更新当前视角限制

updateViewLimit({ fovMin, fovMax, vlookatMin, vlookatMax, hlookatMin, hlookatMax })
- fovMin(number): 视角最小值，取值 0-180
- fovMax(number): 视角最大值，取值 0-180
- vlookatMin(number): 垂直偏移最小值，取值 [-90,90]
- vlookatMax(number): 垂直偏移最大值，取值 [-90,90]
- hlookatMin(number): 水平偏移最小值
- hlookatMax(number): 水平偏移最大值
```
player.openApi.updateViewLimit(
 {
  fovMin: 50,
  fovMax: 120,
  hlookatMin: 20,
  hlookatMax: 280,
  vlookatMin: -45,
  vlookatMax: 45
 }
);
```

视角改变回调监听

addViewChangedListener(callback)
- callback(function(view:{fov, hlookat, vlookat})): 视角改变回调监听，其中 fov hlookat vlookat 为回调参数：
  - fov(number): 视角 FOV
  - vlookat(number): 垂直偏移
  - hlookat(number): 水平偏移
```
player.openApi.addViewChangedListener(
 (view) => {
  console.log('view changed:', view);
 }
);
```

全景点击回调监听

addPlayerClickListener(callback)
- callback(function(pos:{ath, atv})): 全景点击回调监听，其中 ath atv 为回调参数：
  - ath(number): 水平坐标，对应视角中的 hlookat
  - atv(number): 垂直坐标，对应视角中的 vlookat
```
player.openApi.addPlayerClickListener(
 (pos) => {
  console.log('player clicked:' pos);
 }
);
```

全景中加入图片标记

addImageHotspot({ id, url, ath, atv, scale, edge, onClick })
- id(string): 标记 id，以字母开头的字符串
- url(string): 图片 url，http/https 开头的绝对路径
- ath(number): 水平坐标
- atv(number): 垂直坐标
- scale(number): 缩放值,默认 1
- edge(string): 缩放标准点位置，取值（topleft,top,topright,left,center,right,bottomleft,bottom,bottomright），默认 center
- onClick(function(id)): 点击回调
```
player.openApi.addImageHotspot(
 {
  id:'a123',
  url:'https://img.com/abc.png',
  ath: 10,
  atv: -13,
  scale: 0.5,
  edge: 'bottom',
  onClick: (pos) => {
   console.log('hotspot clicked:', pos);
  }
 }
);
```

删除图片标记

removeImageHotspot(id)
- id(string): 标记 id，以字母开头的字符串
```
player.openApi.removeImageHotspot('a123');
```

加入截图回调监听

addSnapshootListener(callback)
- callback(function(base64Image)): 截图成功回调，其中 base64Image 为回调参数：
  - base64Image(string): 全景截图的 base64 编码数据
```
player.openApi.addSnapshootListener(
 (imageBase64) => {
  console.log('snapshoot complete:', imageBase64);
 }
);
```

开始截图

makeSnapshoot({ showHotspotTitle })
- showHotspotTitle(boolean): 截图时渲染热点标题
截图前需要先添加截图回调，并且在播放器初始化时传入 enableSnapshoot: true 参数到 extendData 中
```
player.openApi.makeSnapshoot();
```

获取场景列表信息

getSceneList()
- return Array<{id, partnerId, name, thumbUrl, type }>
  - id(number): 场景 ID
  - partnerId(string): 第三方 ID
  - name(string): 场景名称
  - thumbUrl(string): 缩略图 Url
  - type(number): 场景类型(0 全景视频，1 全景图片，2 高清矩阵)

获取场景分组信息

getSceneGroupList()
- return Array<{id, partnerId, name, thumbUrl, type }>
  - name(string): 分组名称
  - scenes(Array): 分组下场景 ID 列表
  - subGroup(Array<{name:string, scenes:Array}>): 二级分组信息

[
    {
        "name": "默认一级分组",
        "scenes": [],
        "subGroups": [
            {
                "name": "二级分组-1",
                "scenes": [
                    29388,
                    38922
                ]
            },
            {
                "name": "二级分组-2",
                "scenes": [
                    38921
                ]
            }
        ]
    },
    {
        "name": "新建一级分组",
        "scenes": [
            29389
        ],
        "subGroups": []
    }
]

跳转到指定 ID 场景

loadSceneById(sceneId)

sceneId(number): 场景 ID

player.openApi.loadSceneById(32321);

跳转到指定第三方 ID 的场景

loadSceneByPartnerId(partnerId)
- partnerId(string): 第三方 ID
```
player.openApi.loadSceneByPartnerId("partnerId001");
```

场景准备完成（开始显示）监听

addSceneReadyListener(callback)
- callback(function(partnerId, sceneId)): 场景准备完成回调
  - partnerId(string): 场景绑定的第三方 ID
  - partnerId(string): 场景 ID
```
player.openApi.addSceneReadyListener(
 (partnerId, sceneId) => {
  console.log('scene load complete, ', 'partnerId:', partnerId, ', sceneId:', sceneId);
 }
);
```

场景加载完成监听

addSceneLoadedListener(callback)
- callback(function(partnerId, sceneId)): 场景加载完成回调
  - partnerId(string): 场景绑定的第三方 ID
  - partnerId(string): 场景 ID
```
player.openApi.addSceneLoadedListener(
 (partnerId, sceneId) => {
  console.log('scene load complete, ', 'partnerId:', partnerId, ', sceneId:', sceneId);
 }
);
```

暂停视频讲解

pauseSceneVideo()
```
player.openApi.pauseSceneVideo();
```

恢复视频讲解

resumeSceneVideo()
```
player.openApi.resumeSceneVideo();
```

暂停语音讲解

pauseSceneVoice()
```
player.openApi.pauseSceneVoice();
```

恢复语音讲解

resumeSceneVoice()
```
player.openApi.resumeSceneVoice();
```

暂停全景视频

pausePanoVideo()
```
player.openApi.pausePanoVideo();
```

恢复全景视频

resumePanoVideo()
```
player.openApi.resumePanoVideo();
```

暂停嵌入视频

pauseEmbedVideo()
```
player.openApi.pauseEmbedVideo();
```

恢复嵌入视频

resumeEmbedVideo()
```
player.openApi.resumeEmbedVideo();
```

暂停自动巡游

pauseAutoRotate()
```
player.openApi.pauseAutoRotate();
```

恢复自动巡游

resumeAutoRotate()
```
player.openApi.resumeAutoRotate();
```

暂停字幕滚动

pauseSubtitleScrolling()

player.openApi.pauseSubtitleScrolling();

恢复字幕滚动

resumeSubtitleScrolling()

player.openApi.resumeSubtitleScrolling();

暂停背景音乐

pauseBgMusic()
```
player.openApi.pauseBgMusic();
```

恢复背景音乐

resumeBgMusic()
```
player.openApi.resumeBgMusic();
```

关闭音频热点播放

closeHotspotAudio()
```
player.openApi.closeHotspotAudio();
```

更新多边形热点

updatePolygonHotspot(data)

data(object): 需要更新的多边形热点数据（ partnerId 和 id 至少传一个）
- partnerId(string): 热点绑定的第三方 ID
- id(string): 热点 ID
- visible(boolean): 是否可见
- fillColor(string): 多边形热点填充颜色, hex格式，例如 #ffffff
- fillAlpha(number): 多边形热点填充颜色透明度, 0-1
- borderWidth(number): 多边形热点描边粗细
- borderColor(string): 多边形热点描边颜色
- borderAlpha(number): 多边形热点描边颜色透明度
- overFillColor(string): 鼠标经过时边形热点填充颜色
- overFillAlpha(number): 鼠标经过时多边形热点填充颜色透明度
- overBorderWidth(number): 鼠标经过时多边形热点描边粗细
- overBorderColor(string): 鼠标经过时多边形热点描边颜色
- overBorderAlpha(number): 鼠标经过时多边形热点描边颜色透明度

player.openApi.updatePolygonHotspot(
  {
    partnerId: "partnerID_xxx",
    fillColor: "#ff0000",
    visible: true
  }
);

更新图片热点

updateImageHotspot(data)

data(object): 需要更新的图片热点数据（ partnerId 和 id 至少传一个）
- partnerId(string): 热点绑定的第三方 ID
- id(string): 热点 ID
- imageUrl(string): 图片Url
- visible(boolean): 是否可见

player.openApi.updateImageHotspot(
  {
    partnerId: "partnerID_xxx",
    imageUrl: "https://example.com/abc.png",
    visible: true
  }
);

player.openApi.updateImageHotspot(
  {
    partnerId: "partnerID_xxx",
    visible: false
  }
);

更新热点，可统一更新任意类型的热点

updateHotspot(data)

data(object): 需要更新的热点数据（ partnerId 和 id 至少传一个）
- partnerId(string): 热点绑定的第三方 ID
- id(string): 热点 ID
- visible(boolean): 是否可见

player.openApi.updateImageHotspot(
  {
    partnerId: "partnerID_xxx",
    visible: true 
  }
);

切换热点分组

switchToHotspotGroup(id)

id(string): 热点分组 ID

player.openApi.switchToHotspotGroup(123);

当前热点分组ID

currentHotspotGroupId()

return string

console.log("current hotspot group id:", player.openApi.currentHotspotGroupId());

全景视频准备播放监听

addVideoReadyListener(callback)
- callback(function()): 全景视频准备播放回调
```
player.openApi.addVideoReadyListener(
 () => {
  console.log('Pano video ready. ');
 }
);
```

全景视频开始播放监听

addVideoPlayListener(callback)
- callback(function()): 全景视频开始播放回调
```
player.openApi.addVideoPlayListener(
 () => {
  console.log('Pano video start Play. ');
 }
);
```

全景视频暂停播放监听

addVideoPausedListener(callback)
- callback(function()): 全景视频暂停播放回调
```
player.openApi.addVideoPausedListener(
 () => {
  console.log('Pano video paused. ');
 }
);
```

全景视频播放完成监听

addVideoCompleteListener(callback)
- callback(function()): 全景视频播放完成回调
```
player.openApi.addVideoCompleteListener(
 () => {
  console.log('Pano video play complete. ');
 }
);
```

SDK 数据包获取

SDK 文件引入

初始化说明

初始化接口

window.PanoPlayer.setup({baseUrl, sdkUrl, jsonData, extendData}, config) : Promise

完整示例

接口说明

所有接口均暴露在 player 的 openApi 上，调用时直接使用 player.openApi.{接口名称}。

接口列表

updateView({ fov, vlookat, hlookat })

updateViewLimit({ fovMin, fovMax, vlookatMin, vlookatMax, hlookatMin, hlookatMax })

addViewChangedListener(callback)

addPlayerClickListener(callback)

addImageHotspot({ id, url, ath, atv, scale, edge, onClick })

removeImageHotspot(id)

addSnapshootListener(callback)

makeSnapshoot({ showHotspotTitle })

getSceneList()

getSceneGroupList()

loadSceneById(sceneId)

loadSceneByPartnerId(partnerId)

addSceneReadyListener(callback)

addSceneLoadedListener(callback)

pauseSceneVideo()

resumeSceneVideo()

pauseSceneVoice()

resumeSceneVoice()

pausePanoVideo()

resumePanoVideo()

pauseEmbedVideo()

resumeEmbedVideo()

pauseAutoRotate()

resumeAutoRotate()

pauseSubtitleScrolling()

resumeSubtitleScrolling()

pauseBgMusic()

resumeBgMusic()

closeHotspotAudio()

updatePolygonHotspot(data)

updateImageHotspot(data)

updateHotspot(data)

switchToHotspotGroup(id)

currentHotspotGroupId()

addVideoReadyListener(callback)

addVideoPlayListener(callback)

addVideoPausedListener(callback)

addVideoCompleteListener(callback)