1、获取 MapGIS Client for JavaScript（Video）开发包

MapGIS Client for JavaScript（Video）是 WebClient 面向视频图层与地图联动场景的插件包，承接 @mapgis/webclient-common 的通用接口，并基于 @mapgis/webclient-leaflet-plugin 完成地图叠加与视图适配。

该包提供视频在地图上的核心扩展能力，覆盖视频图层、视频标注、同步播放和空间位置联动等应用场景。

• 示例站点：http://webclient.smaryun.com

1.1、获取方式

1.1.1、npm 安装

推荐在现代工程中直接通过 npm 引入：

npm install @mapgis/webclient-common @mapgis/webclient-leaflet-plugin @mapgis/webclient-video-plugin

安装完成后，构建工具会解析插件运行时依赖；项目仍需要按 Leaflet 和视频播放运行时的要求引入相应资源。

1.1.2、静态资源引入

如果项目暂时不接入构建链，可以直接使用发布包中的静态资源：

如果需要通过 CDN 格式开发包或离线示例站点集成，可前往：http://smaryun.com/dev/download_detail.html#/download828。

• dist/esm/webclient-video-plugin.js
• dist/umd/webclient-video-plugin.min.js
• @mapgis/webclient-common 发布包中的 Common 运行时
• @mapgis/webclient-leaflet-plugin 发布包中的 Leaflet 运行时
• video.js 运行时脚本

常见做法是将 Common、Leaflet、Video 插件脚本和 video.js 运行时一并拷贝到项目静态资源目录，再通过 <script> 和 <link> 加载。

1.2、能力范围

• view：视频地图视图、视频与地图联动和视图交互
• layer：视频图层、视频源加载和视频图层视图
• tool：视频标注、草图编辑和辅助工具
• adapter：视频对象与 WebClient 通用模型桥接
• playback：MP4、HLS、RTMP 等视频播放与同步显示

2、引入方式

2.1、ESM 引入

现代工程建议使用 ESM 方式按需引入：

import { MapView } from '@mapgis/webclient-video-plugin'

const videoMapView = new MapView({
  viewId: 'videoMapView-container'
})

这种方式便于 tree-shaking，也更适合后续模块化维护。

2.2、全局引入

如果使用传统页面或旧工程，可直接挂载全局对象：

<link rel="stylesheet" href="/static/leaflet/leaflet.css" />
<script src="/static/leaflet/leaflet.js"></script>
<script src="/static/webclient-leaflet-plugin.min.js"></script>
<script src="/static/video/video.js"></script>
<script src="/static/webclient-video-plugin.min.js"></script>
<script>
  const { MapView, SketchEditor } = window.zondy.video
  const sketchEditor = new SketchEditor()
  const videoMapView = new MapView({
    viewId: 'videoMapView-container'
  })
  videoMapView.init({
    videoSource: {
      videoUrl: 'https://example.com/demo.mp4',
      protocol: 'mp4'
    },
    videoRegistrationParam: {
      videoID: 'demo-video',
      videoName: 'demo'
    }
  })
</script>

全局对象同时保留新命名空间 window.zondy 和兼容入口 window.Zondy，便于旧代码使用。

3、快速开始

下面示例展示视频地图视图的最小初始化方式。实际项目中，请将容器尺寸设置为可见区域高度。

3.1、创建视频地图视图

const { MapView } = zondy.video
const videoMapView = new MapView({
  viewId: 'videoMapView-container'
})
const data = {
  // 视频元数据、视频源和视频配准参数
}

videoMapView.init(data)
videoMapView.destroy()

3.2、传入视频标定数据

const { MapView } = zondy.video
const videoMapView = new MapView({
  viewId: 'videoMapView-container'
})

const data = {
  // 视频元数据、视频源和视频配准参数
}

videoMapView.init(data)
videoMapView.destroy()

3.3、使用草图编辑器

const { SketchEditor } = zondy.video.tool.sketch

const sketchEditor = new SketchEditor()
if (sketchEditor.destroy) {
  sketchEditor.destroy()
}

4、@mapgis/webclient-video-plugin 版本说明

v17.10.0

• 发布17.10.0版本