ArcGIS API for JavaScript 3.23汉化

1简介

ArcGIS API for JavaScript （JavaScript API）是ESRI根据JavaScript技术实现的调用ArcGIS Server REST API接口的一组脚本。当前的最新版本是Version 4.60。
通过ArcGIS API for JavaScript可将ArcGIS Server提供的地图资源嵌入到Web应用中。ArcGIS API for JavaScript是基于Dojo框架的，使用了大量的Dojo技术，因此要想熟练掌握API用法，先要对Dojo框架有个深入的了解！
Dojo与我们常使用的Jquery都是封装好的JavaScript库，不同点在于Dojo属于重量级开发框架，由**框架核心（dojo）、基本控件库（dijit）、扩展包（dojox）**组成的，三部分都是由dojo官方提供。简单来说Dojo更像一个类库，不同功能封装到不同模块形成一个独立的js文件，如果使用该功能再进行引入。
而jQuery属于轻量级框架，本身仅包含框架核心。

2教程

建立你的第一个应用：Build your first application
使用ArcGIS.com webmap：Use an ArcGIS.com webmap
移动专用应用程序Mobile-specific application
路线小部件Directions widget
搜索小部件Search widget
标签功能客户端Labeling features client-side
写一个类Write a class
创建一个可重复使用的小部件Create a re-usable widget
共享安全地图 Share maps with secure layers

关于API、js脚本、Dojo、JQuery

About the API：
Get Started、Get the API
Localization 本地部署
Required CSS 必要的CSS
Supported Browsers 支持的浏览器 、Community社区

Dojo与我们常使用的Jquery都是封装好的JavaScript库*，不同点在于Dojo属于重量级开发框架，由框架核心（dojo）、基本控件库（dijit）、扩展包（dojox）组成的，三部分都是由dojo官方提供。而jQuery属于轻量级框架，本身仅包含框架核心。简单来说Dojo更像一个类库，不同功能封装到不同模块形成一个独立的js文件，如果使用该功能再进行引入。
Dojo：
Work with Dojo、Get Dojo
Dijits基本控件库
Dojo and AMD :Asynchronous Module Definition，https://kb.cnblogs.com/page/96890/
Dojo Layouts：Dojo布局
Additional resources、Why Dojo?

细节补充

1.Dojo已包含在ArcGIS JavaScript API中
因此无需托管/引用/安装它。
当您引用ArcGIS JavaScript API的脚本标记时，您可以访问完整的Dojo工具包版本。

2.ArcGIS API for JavaScript构建于Dojo之上：
创建ArcGIS API for JavaScript的Esri开发人员使用Dojo来简化他们的开发过程，并确保您构建的应用程序在不同的浏览器中表现相同。 例如，地图缩放和平移动画使用Dojo，图形层也是如此。

此外，您在JavaScript API映射中看到的缩放级别滑块和信息窗口是Dojo小部件（dijits）。 滑块dijit随Dojo一起提供，信息窗口是由Esri为ArcGIS API for JavaScript创建的自定义dijit。

3.为了使用ArcGIS API for JavaScript，我需要知道多少关于Dojo？
使用ArcGIS API for JavaScript时使用的Dojo取决于您，但至少会使用几个常用功能：

dojo.require
dojo.require is similar to the “script” include tag on an HTML page
它将资源导入您的JavaScript页面。

    // AMD 一种新规范
    require(["esri/map", ... ], function(Map, ... ){ ... });
    // legacy 传统的方式
    dojo.require("esri.map");

dojo.ready
dojo.ready (or dojo.addOnLoad) is similar to “ body οnlοad="" ”
它在页面加载完成后注册一个初始化块。

// AMD
require(["dojo/ready"], function(ready){
  ready(function(){
    // This function won't run until the DOM has loaded and other modules that register have run.
  });
});
// legacy
dojo.ready(init);

dojo.connect
dojo.connect is similar to Element.addEventListener and Element.attachEvent JavaScript functions.
它注册一个侦听器来侦听页面上的Object或元素上的特定事件，并返回函数的结果。

// AMD
require(["esri/map", "dojo/on"], function(Map, on) {
  //...
  on(myMap, "load", callback);
});

dojo.byId
dojo.byId is similar to the document.getElementById() JavaScript function.
该函数搜索并返回带有参数ID的第一个HTML元素。

dojo.byId("myInputField").value = myMap.id;

其他
Taking advantage of full Dojo toolkit
When writing your ArcGIS JavaScript applications, you can take advantage of the full Dojo toolkit, which includes buttons, grids, tree views, charts, and other widgets. The toolkit is divided into three parts:

Core - Essential functions like those listed above
Dijit - Themeable widgets such as trees, menus, and buttons
DojoX- Extension projects in various stages of development, such as graphics, grids, and charts

As stated previously, you can start building ArcGIS API for JavaScripts apps with minimal dojo knowledge. But, the more dojo you know, the more you’ll be able to accomplish. Dojotoolkit.org’s tutorials and documentation are a fantastic place to start.

Required CSS：
从ArcGIS API for JavaScript 3.2版开始，开发人员必须包含一个额外的 级联样式表（CSS）文件： esri.css。
该esri.css文件包含各种小部件的CSS，包括地图的CSS。（因为所有CSS都在一个文件中，所以检索API的CSS是在一个请求中完成的。减少http请求的数量是应用程序提高性能的一种方式。）
大多数应用程序将使用最佳性能esri.css。大多数路径和文件名准确地描述了它们样式化的API组件。例外情况是jsapi.css，地图的样式，属性窗口小部件以及可用于地图缩放滑块的各种滑块选项。（ Most paths and file names accurately describe the component of the API they style. The exception is jsapi.css, which styles the map, the attribution widget and the various slider options available for use with a map’s zoom slider.）

3具体使用

Work with the API：使用API
一、Default API configurations 默认API配置
Default API strings 默认API字符串
三、Retrieve data from a web server 从Web服务器检索数据
Map navigation 地图导航
五、Events（活动）事件
Set Extents 设置范围
Editing 编辑
Arcade 表达式语言
Time aware data 时间感知数据
Adding a task 添加任务
Using QueryTask 使用QueryTask
Creating custom layer types 创建自定义图层类型
Web maps 网络地图
Working with Analysis Widgets 使用Analysis小部件
Working with the Search Widget 使用搜索小组件
Working with the Directions Widget 使用Directions Widget
Working with GeoEnrichment Widgets 使用GeoEnrichment小部件
Working with DataReviewer 使用DataReviewer
Location Providers (beta） 位置提供（测试版）
Graphics and feature layers图形和要素图层
Graphics overview
Feature layer overview
Symbols and renderers
Data Visualization
Styling features with CSS
Popups and Info Windows 弹出窗口和信息窗口
Info windows and graphics
Format info window content
Customize info windows
Popup overview
Format popup content
Customize popup
Geoprocessor 地理处理器
Geoprocessing overview
Creating the geoprocessor
Geoprocessor parameters
Geoprocessing results
Operations Dashboard操作仪表板
Overview
Get started
Create extensions
Test and debug
Deploy。。。。。。

4更为具体

一、Default API configurations 默认API配置
所有配置选项的默认值都存储在esri/config模块中。要修改默认值，请加载该模块，

require （[ “esri / config” ]，function （esriConfig ）{ //在此更新esriConfig属性以覆盖默认值}）;  

1.修改用于地图缩放框的符号。在下面的代码中，创建一个新符号，转换为JSON对象，然后设置为地图的默认缩放符号。

// AMD
require([
  "esri/config",
  "esri/symbols/SimpleFillSymbol", "esri/symbols/SimpleLineSymbol", "dojo/_base/Color"
], function(
  esriConfig,
  SimpleFillSymbol, SimpleLineSymbol, Color
) {
  var lineColor = new Color([0,0,255]);
  var fillColor = new Color([255,255,0,0.5]);
  var zoomSymbol = new SimpleFillSymbol(
    SimpleFillSymbol.STYLE_SOLID,
    new SimpleLineSymbol(SimpleLineSymbol.STYLE_DASHDOT, lineColor, 2), 
    fillColor
  );
  esriConfig.defaults.map.zoomSymbol = zoomSymbol.toJson();
});

JavaScript API的其他的配置属性名称和默认值：
2.关于 网络、域名、跨域、代理、等详见手册。
3.
esriConfig.defaults.map.panDuration
地图从一个范围平移到另一个范围所用的时间长度（以毫秒为单位）。
默认值： 350
示例： 自定义平移动画
4
esriConfig.defaults.map.panRate地图在平移到下一个范围时将刷新的时间长度
默认值： 25
示例： 自定义平移动画
5
esriConfig.defaults.map.slider 用于定义滑块的位置，大小和方向的参数。
从版本3.3开始，推荐的方法是使用CSS和地图构造函数选项的组合来自定义地图的滑块或缩放按钮。
默认值： {left：“30px”，top：“30px”，width：null，height：“200px”}
示例： 更改滑块方向
6等等…

三、Retrieve data from a web server 从Web服务器检索数据
esriRequest是一种从Web服务器检索数据的实用方法。
数据可以是静态的（存储在Web服务器上的文件中），
也可以是动态的（由Web服务按需生成）。
esriRequest可以处理以下格式：纯文本、XML、JSON、JSONP或“带填充的JSON”

在提出请求之前，需要一些信息：

• 数据的位置，即URL
• 对于Web服务，任何必需的参数和适当的值
• 数据格式

使用esriRequest：导入具有该函数源代码的模块。如果需要，请指定代理的位置。

 var request = esriRequest({
          // Location of the data
          url: "<String>",
          // Service parameters if required, sent with URL as key/value pairs
          content: {
            parameter1: <value>,
            parameter2: <value>
          },
          // Data format
          handleAs: "<String>"
        });

在上面的代码中，esriRequest不返回实际数据。如果它要返回实际数据，则必须等待下载数据 - 这通常需要一些时间，具体取决于网络流量，可用带宽和远程服务器上的负载。在此之前，应用程序将被冻结 - 不允许您与之交互。这称为synchronous行为。
相反，为使应用程序保持响应，esriRequest始终返回一个request对象，该对象代表您刚刚发出的请求，并在以后下载时使您可以使用这些数据。这称为asynchronous行为。

要在下载数据后访问数据，即callbacks“回调”。
如果检索到的数据没有错误，将执行第一个函数（在下面的示例代码中命名为requestSucceeded，函数名由开发人员决定）。
如果由于某种原因数据下载失败，将执行第二个函数（名为requestFailed）。

function requestSucceeded(data) {
  console.log("Data: ", data); // print the data to browser's console
}  
function requestFailed(error) {
  console.log("Error: ", error.message);
}    
request.then(requestSucceeded, requestFailed);

回调也可以内联定义：

request.then(
  function (data) {
    console.log("Data: ", data);
  },
  function (error) {
    console.log("Error: ", error.message);
  }
);

附加信息和使用案例
上传一个文件
esriRequest主要用于下载数据。但它也可用于将文件从用户的计算机上载到Web服务器。该文件可以是任何类型：Word文档，Excel表格，CSV，PDF，JPEG，PNG等。

要构建能够上载文件的应用程序，需要以下内容：

1. 导入相关的源代码。
2. 为应用程序设置代理
3. 使用文件输入控件创建HTML表单。用户可以单击此文件输入控件并从其计算机中选择一个文件
4. 调用esriRequest上传所选文件

关于代理与CORS规范 详见手册

五、Events（活动）事件
在ArcGIS API for JavaScript中，监听事件的推荐方法是使用on。也可以使用dojo / aspect或旧的dojo / _base / connect模块来监听或响应事件。
从版本3.6开始，ArcGIS API中的所有模块都支持事件on（）样式事件侦听器。
常见事件：

1.地图加载Map"load"
将地图添加到页面时，在添加第一个图层之前不能使用它。
向地图添加图层会初始化图形并触发onLoad事件。此时，您可以与地图进行交互。
此规则的一个例外是setExtent方法。您可以在地图的构造函数中设置地图的初始范围，也可以在添加第一个图层之前调用setExtent。

  require(["esri/map", ...], function(Map, ...) {
    			var map = new Map("mapDiv"),
    			mapOnLoad = map.on("load", configNavigation);
    			map.addLayer(...);	
    		function configNavigation(evt) {
    			evt.map.disableMapNavigation();
    			}
    });

2.ArcGISDynamicMapServiceLayer “load” and ArcGISTiledMapServiceLayer "load"
esri.layers.ArcGISDynamicMapServiceLayer和esri.layers.ArcGISTiledMapServiceLayer使用ArcGIS Server REST服务端点工作。
首次创建图层时，需要向ArcGIS Server发出请求以获取服务信息。
在与图层交互之前，您应该等到图层的onLoad事件被触发。
以下代码仅在onLoad触发后才使用事件处理程序访问初始范围属性。

require(["esri/layers/ArcGISDynamicMapServiceLayer", ... ], function(ArcGISDynamicMapServiceLayer, ... ){
  var layer = new ArcGISDynamicMapServiceLayer(...);
  layer.on("load", printInitialExtent);

  function printInitialExtent(evt) {
    alert(evt.layer.initialExtent);
  }
});

注意：在Internet Explorer中，由于资源缓存，一旦构造了图层，就会触发onLoad事件。因此，在为“load”事件注册侦听器之前，应检查图层的已加载属性是否为true：

require(["esri/layers/ArcGISDynamicMapServiceLayer", ...
], function(ArcGISDynamicMapServiceLayer, ... ) {
  var layer = new ArcGISDynamicMapServiceLayer(...);
  if(layer.loaded){
    printInitialExtent({"layer":layer});
  } else {
    layer.on("load", printInitialExtent);
  }

  function printInitialExtent(evt) {
    console.log(evt.layer.initialExtent);
  }
});

但是，on有一个伴侣功能，emit发射。 我们可以使用emit强制事件触发，而不是直接调用事件处理程序：

require(["esri/layers/ArcGISDynamicMapServiceLayer", ... ], function(ArcGISDynamicMapServiceLayer, ... ) {
  var layer = new ArcGISDynamicMapServiceLayer(...);
  layer.on("load", printInitialExtent);
  if(layer.loaded){
    layer.emit("load",{
      "layer":layer
    });
  }

  function printInitialExtent(evt) {
    console.log(evt.layer.initialExtent);
  }
});

3.地图和图形上的鼠标事件 Mouse events on maps and graphics
The ArcGIS JavaScript API map and graphics layer provide a large set of mouse events users can use to interact with these objects. To register to listen to a map’s onClick event:

require(["esri/map", ...], function(Map, ...) {
  var map = new Map("mapDiv"),
  map.on("click", myClickHandler);
  map.addLayer(...);

  function myClickHandler(evt) {
    ...
  }
});

当用户单击地图时，将生成鼠标事件并调用所有已注册的点击处理程序。mouse事件作为参数传递给每个处理程序。除了浏览器填充的所有属性外，还包含mapPoint和screenPoint作为事件的属性。
mapPoint表示地图坐标中单击的坐标，screenPoint表示屏幕坐标中单击的坐标。

function myClickHandler(event) {
  alert("User clicked at " +
    event.screenPoint.x + ", " + event.screenPoint.y +
    " on the screen. The map coordinate at this point is " +
    event.mapPoint.x + ", " + event.mapPoint.y
  );
}

除了mapPoint和screenPoint属性之外，返回的事件还包括一个图形属性，它是接收事件的esri.Graphic对象。
下面的代码显示了如何处理地图的onClick事件以报告用户点击的图形。
请注意，onClick事件的侦听器仅在Map的onLoad事件触发后才会生效。在这种情况下，侦听器依赖于另一个侦听器。

require(["esri/map", ...], function(Map, ...) {
  var map = new Map("mapDiv"),
  mapOnLoad = map.on("load", function(){
    map.graphics.on("click", myGraphicsClickHandler);
  });
  map.addLayer(...);

  function myGraphicsClickHandler(evt) {
    alert("User clicked on " + evt.graphic);
  }
});

4.地图“鼠标滚轮”Map "mouse-wheel"

鼠标滚轮事件已标准化，可在所有浏览器中使用。将值属性添加到MouseScroll / Wheel事件（Firefox）或MouseWheel事件（Internet Explorer / Safari / Chrome / Opera）。
正数表示鼠标滚轮向上滚动，负数表示鼠标滚轮向下滚动：

map.on("mouse-wheel", myMouseWheelHandler);

5.事件传播（冒泡）Event propagation (bubbling)
Internet Explorer事件模型有时会导致在页面中的多个元素上发生相同的事件。如果元素重叠，则会发生这种情况。要防止事件从一个元素传播（冒泡）到另一个元素，您可以停止该事件。

例如：假设您有一个应用程序，用户可以在其中单击地图以执行查询。用户还可以单击任何图形以在点击位置重新定位地图。假设图形具有点几何：如下

require(["dojo/_base/event",
  "esri/map", "esri/tasks/Query", "esri/tasks/QueryTask" ...],
  function(event, Map, Query, QueryTask, ...) {
    var map = new Map("mapDiv"),
    mapOnClick = map.on("click", executeQuery),
    mapOnLoad = map.on("load", function(){
      map.graphics.on("click", recenterMap);
    }),
    queryTask = new QueryTask(...);
    map.addLayer(...);

    function executeQuery(event) {
      var query = new Query({
        geometry: event.mapPoint
      });
      queryTask.execute(query, ...);
    }

    function recenterMap(event) {
      map.centerAt(event.mapPoint);
    }
});

在Internet Explorer中，当用户单击以重新定位地图时，上述代码可能会执行不需要的查询。这是因为click事件不仅在图形容器上触发，而且在map div上触发。要确保事件不会传播到map div，可以通过将以粗体显示的行添加到recenterMap函数来停止事件：

function recenterMap(evt) {
  // event is an alias for dojo/_base/event
  event.stop(event);
  map.centerAt(evt.mapPoint);
}