cesiumjs学习笔记之三——cesium-navigation插件

最新推荐文章于 2026-05-30 08:47:03 发布

翻译最新推荐文章于 2026-05-30 08:47:03 发布 · 2.2w 阅读

Cesium Navigation 是一个为 Cesium 提供指南针、导航仪和距离刻度等功能的插件。它支持不同版本的 Cesium，并且可以根据需求启用或禁用特定功能。插件分为独立版和 AMD 兼容版。

插件源码地址：https://github.com/alberto-acevedo/cesium-navigation

cesium-navigation

cesium-navigation是一个cesium的插件，提供指南针、导航仪和距离刻度用户图形界面。

1、为什么你建立cesium-navigation插件？

首先，所有的Cesiumjs sdk 不包括罗盘，导航仪（放大/缩小）和距离刻度。您可以使用鼠标在地图上导航，但这个导航插件可为用户提供更多的导航控制和功能。其中一些功能是：将罗盘重置为指向北部，重置轨道，并将视图重置为默认边界。

2、怎么建立cesium-navigation插件？

cesium-navigation插件基于优秀的罗盘，导航仪（放大/缩小）和距离terriajs开源库的距离刻度。来自terriajs的导航UI不能在铯中开箱即用，因为cesium使用带有RequireJS的CommonJS模块，terriajs使用commonjs和Browserify，因此您不能将源文件复制到铯和构建中。cesium-navigation插件的工作包括调整代码在cesium作为插件工作如下：

1) 将所有模块从Browserify转换为requirejs；

2)使用gulpjs来编译和缩小较少的文件，捆绑和最小化所有模块，并将源依赖关系打包成一个文件。作为构建过程的一部分，用almondjs替换requirejs，以减少插件中使用的AMD加载器的占用空间。almondjs库也在插件内绑定，使插件像铯中的即插即用一样简单；

3)使用nodejs和requirejs优化器以及almondjs，整个插件被构建并捆绑在单个文件中，甚至CSS样式也放在这个文件中；

4）该插件可以用作独立脚本或通过AMD加载程序（使用requirejs进行测试）。即使在使用AMD而不是cesium的特殊情况下，插件也可以轻松使用。

3、怎么使用cesium-navigation插件？

cesium-navigation插件有两个版本，一个独立版和一个AMD兼容版本：

1）什么时候用什么版本？

a. 如果您正在加载没有requirejs的铯（即，您有全局变量铯），则使用独立版本。如果您使用requirejs（但不适用于铯），此版本也是适用的。

导入脚本：

<head>
  <!-- other stuff -->

  <script src="path/to/Cesium.js"></script>
  <!-- IMPORTANT: because the cesium navigation viewer mixin depends on Cesium be sure to load it after Cesium -->
  <script src="path/to/standalone/viewerCesiumNavigationMixin.js"></script>

  <!-- other stuff ... -->
</head>

然后扩展viewer：

 // create a viewer assuming there is a DIV element with id 'cesiumContainer'
	var cesiumViewer = new Cesium.Viewer('cesiumContainer');

	// extend our view by the cesium navigaton mixin
	cesiumViewer.extend(Cesium.viewerCesiumNavigationMixin, {});

或者一个部件：

 // create a widget assuming there is a DIV element with id 'cesiumContainer'
    var cesiumWidget = new Cesium.CesiumWidget('cesiumContainer');

	// extend our view by the cesium navigaton mixin
	Cesium.viewerCesiumNavigationMixin.mixinWidget(cesiumWidget, {});

可以通过一下方式获取新创建的实例：

 // if using a viewer
	var cesiumNavigation = cesiumViewer.cesiumNavigation;

	// if using a widget
	var cesiumNavigation = cesiumWidget.cesiumNavigation;

另外一个例子：

b. 如果除了cesium之外，你使用了requirejs ，则要使用：

<head>
  <!-- other stuff... -->

  <script src="path/to/Cesium.js"></script>
  <!-- 重要！加载requirejs在cesium之后 -->
  <!-- viewerCesiumNavigationMixin the global variable Cesium is already set -->
  <script type="text/javascript" src="path/to/require.js"></script>
  <script type="text/javascript">
    require.config({
      // your config...
    });
  </script>

  <!-- other stuff... -->
</head>

加上：

// IMPORTANT: be sure that Cesium.js has already been loaded, e.g. by loading requirejs AFTER Cesium
  require(['path/to/standalone/viewerCesiumNavigationMixin'], function(viewerCesiumNavigationMixin) {
    // like above code but additionally one can directly access
    // viewerCesiumNavigationMixin
    // instead of
    // Cesium.viewerCesiumNavigationMixin
  }

c. 如果您正在为整个项目（包括cesium）使用requirejs，那么您必须使用AMD兼容版本。

<head>
  <!-- other stuff... -->

  <script type="text/javascript" src="path/to/require.js"></script>
  <script type="text/javascript">
    require.config({
        // your config...
		paths: {
		    // your paths...
		    // 重要！这里必须设置，因为viewerCesiumNavigationMixin 使用Cesium/...依赖
			'Cesium': 'path/to/cesium/Source'
		}
    });
  </script>

  <!-- other stuff... -->
</head>

加上：

require([
  'Cesium/Cesium',
  'path/to/amd/viewerCesiumNavigationMixin'
], function(
  Cesium,
  viewerCesiumNavigationMixin) {

  // like above but now you cannot access Cesium.viewerCesiumNavigationMixin
  // but use just viewerCesiumNavigationMixin
});

或者：

require([
  'Cesium/Core/Viewer',
  'path/to/amd/viewerCesiumNavigationMixin'
], function(
  CesiumViewer,
  viewerCesiumNavigationMixin) {

  // like above but now you cannot access Cesium.viewerCesiumNavigationMixin
  // but use just viewerCesiumNavigationMixin
});

设置插件选项

defaultResetView - >用于在使用重置导航重置地图视图时设置默认视图控制。接受的值是Cesium.Cartographic 和 Cesium.Rectangle.
enableCompass - >用于启用或禁用罗盘。true是启用罗盘，false是禁用罗盘。默认值为true。如果将选项设置为false，则罗盘将不会添加到地图中。
enableZoomControls - >用于启用或禁用缩放控件。true是启用，false是禁用。默认值为true。如果将选项设置为false，则缩放控件将不会添加到地图中。
enableDistanceLegend - >用于启用或禁用距离图例。true是启用，false是禁用。默认值为true。如果将选项设置为false，距离图例将不会添加到地图中。
enableCompassOuterRing - >用于启用或禁用指南针外环。true是启用，false是禁用。默认值为true。如果将选项设置为false，则该环将可见但无效。
更多选项将在未来的插件版本中设置。

没有requirejs加载cesium时设置选项的例子：

var options = {};
options.defaultResetView = Cesium.Rectangle.fromDegrees(71, 3, 90, 14);
// Only the compass will show on the map
options.enableCompass= true;
options.enableZoomControls= false;
options.enableDistanceLegend= false;
options.enableCompassOuterRing= true;
cesiumViewer.extend(Cesium.viewerCesiumNavigationMixin, options);

仍然有问题，请查看例子。

删除导航插件并释放资源使用：