从 3.X 迁移至 4.25

版本 4.x 是对 GeoScene Maps SDK for JavaScript 及其制图组件的重大改进。请考虑重写应用程序，而不是简单地尝试更新它们。

本主题旨在为开发人员提供使用 3.x API 帮助的现有应用程序来实现这一点。尽管对 API 进行了一系列更新，但下面列出了一些值得注意的更新：

对版本 4.0 进行了重大更改。进行这些更改是为了帮助开发人员在他们创建的任何应用程序上更高效地工作。这些更改可以在构造函数、属性和事件的处理方式中看到。

属性

在 4.0 之前，某些属性可以通过调用 getMethodName 或 setMethodName 来获取（读取）或设置（写入）。不再需要这些类型的方法，因为 API 支持以一种简单且一致的方法来获取和设置所有属性。

直接在对象上设置属性，例如 map.basemap = "oceans"。
直接从对象获取属性，例如 map.basemap.title。

例如，在 3.x 中，设置要素图层的 definitionExpression 类似于：

代码块使用深色复制
myFeatureLayer.setDefinitionExpression(expression); 

而以下行显示了如何在 4.0 中设置要素图层的 definitionExpression，

代码块使用深色复制
myFeatureLayer.definitionExpression = expression; 

使用 4.0，可以使用 .get() 访问类似于以下代码段的深层属性，

代码块使用深色复制
var basemapTitle = map.get("basemap.title"); 

监视属性更改

在 4.0 之前，属性更改是使用事件处理的。在 4.0 中，监视属性更改变得更加容易。这是通过 .watch(property, callback) 方法处理的。每次更改 property 时都会调用 callback，并允许您使用属性的新值、旧值和名称以及监视对象。

代码块使用深色复制
// Creates a new Map with a "streets-vector" basemap
var map = new Map({
  basemap: "tianditu-vector"
});

// watch handler: the callback fires each time the title of the map's basemap changes
var handle = map.watch("basemap.title", function(newValue, oldValue, property, object) {
  console.log("New value: ", newValue,      // The new value of the property
              "<br>Old value: ", oldValue,  // The previous value of the changed property
              "<br>Watched property: ", property,  // In this example this value will always be "basemap.title"
              "<br>Watched object: ", object);     // In this example this value will always be the map object
}); 

视图

在 4.0 版本中，地图可以通过 2D 或 3D 形式显示。因此，修改了绘制逻辑。现在，地图和图层不再处理绘制逻辑，而是由视图进行处理。

视图是版本 4.0 中引入的概念。视图可以是以下两种类型之一：

MapView - 适用于在 2D 模式下工作
SceneView - 适用于在 3D 模式下工作

视图专门用于可视化地图或场景中的数据。地图包含要显示的实际数据或图层，而视图则处理显示此数据。此数据的可视化或显示方式因您是在 2D 还是 3D 模式中工作而异。视图具有对地图的引用，例如 view.map。但地图没有对视图的引用。请务必注意，单个地图可由多个视图使用。

这是另一种思考方式：地图描述底图和要素，而视图是允许查看该地图的窗口。

以下语法显示了如何创建和使用 2D 视图 (MapView) 和 3D 视图 (SceneView)。

以下代码片段显示了使用 MapView 的 2D 制图，

代码块使用深色复制
function (Map, MapView){
  map = new Map({
    basemap: "tianditu-vector"
  });
  view = new MapView({
    container: "viewDiv",
    map: map,
    scale: 2400000
  });
} 

此代码段显示了使用 SceneView 的 3D 制图，

代码块使用深色复制
function (Map, SceneView){
  map = new Map({
    basemap: "tianditu-vector"
  });
  view = new SceneView({
    container: "viewDiv",
    map: map,
    scale: 2400000
  });
} 

特定地图和图层

对地图和图层进行了一些重大更新；下面列出了其中一些：

从 4.0 开始，在地图中，底图与业务图层是分开的。
现在，还可在 2D 或 3D 中旋转视图。
图形图层可以添加到地图图层集合中的任何位置。在 4.0 之前，它们必须始终位于非图形图层之上。
已添加 GroupLayer 类。

模块和包更新

有关详细信息，请参阅模块更新主题，以下是一些值得注意的内容：

更改了包名称，例如 geoscene/dijit 现在是 geoscene/widgets/。
更短、更清晰的模块名称，例如 TileLayer，而不是 ArcGISTiledMapServiceLayer。
模块名称大小写一致，现在所有模块都以大写字母开头，包括 Map、Graphic 和 Query。
支持类已移动到支持的文件夹中，以使参考手册更加有序，例如 geoscene/layers/support 和 geoscene/rest/support。
geoscene/config 的结构已发生变化esriConfig.defaults 的属性现在位于 esriConfig 中。例如，要设置默认几何服务，请执行以下操作：

代码块使用深色复制
// 3.x
geosceneConfig.defaults.geometryService = new GeometryService("http://yourdomain.com/geometryService");

// 4.x
geosceneConfig.geometryService = new GeometryService("http://yourdomain.com/geometryService"); 

3.x defaults.io 对象现在是 esriConfig.request。

代码块使用深色复制
// 3.x
geosceneConfig.defaults.io.timeout = 30000;

// 4.x
geosceneConfig.request.timeout = 30000; 

三个 *-all 遗留模块均已移除。在构建或使用 web 优化器中，这会处理得更好
构造函数不再支持 JSON，请改为使用 fromJSON() 方法。例如，Graphic.fromJSON()。(注：Beta 3 仍然包含一些使用 3.x 样式的构造函数)。
FeatureLayer 上没有图形。现在，LayerView 可渲染表示 FeatureLayer 中要素的图形。

WebMap 支持

可以读取版本 2.x 的 WebMaps。部分支持使用 WebMap。这意味着它依赖于 API 中的已有功能。例如，即使 WebMap 包含尚未实现的图层类型，也可以读取它们。在这些情况下，仅显示 API 支持的图层类型。从 4.14 版本开始，支持保存 web 地图。

本地化

在 4.x 中，从右到左 (RTL) 不再是将区域设置设置为“ar”或“he”的附带后果。

现在，您可以选择在任何地区使用 RTL。请参阅 RTL 支持。
您可以在 <html> 或 <body> 标记上指定方向。请参阅 RTL 支持。

模块

4.x AMD 和 ES 模块都支持。在 4.0 之前，您可以使用 AMD 以及 dojo.require 遗留模块。从 4.0 开始，仅支持 AMD 模块，且在 4.18 中引入了 ES 模块。有关 4.x 中不同模块类型的概述，请参阅工具简介指南主题。

弃用说明

从版本 3.13 开始，Geocoder 微件已弃用。它不是 4.0 的一部分。请改为使用搜索微件。