我正在参加「掘金·启航计划」

相信很多搞 web 的前端同学一看到 arcgis js，脑子里的第一印象就是庞大、复杂、纯英文、晦涩难懂。但其实 arcgis js 并没有想象中的那么难以接触，本篇文章就以半科普半介绍的形式，让你对庞大的 arcgis js 库有个大致的了解，让你知道该怎么做、去哪才能找到你想要的知识、实现你想要的效果。

本文会以对 arcgis 官方文档的导读为基础，并穿插介绍对应的 arcgis 设计，让你对整个框架的 api 模型有个大致的了解。

不用担心会听不懂，这里不会出现复杂长篇的代码和烧脑的逻辑解读，拿着看科普读物的心对待这篇文章就好。那么我们废话少说，现在开始。

如何接触庞大的 arcgis js 库？

首先我们需要明确一个态度：有不懂的地方优先看官方文档，有很多同学被纯英文文档和层层嵌套的网站吓到了，刚点进去稍微看了两个链接就被吓跑，然后去百度各种 arcgis 中文教程去了。

你可能会觉得中文教程肯定比官网文档好懂一点，其实并不会，恰恰相反，这反而可能会让你学起来更艰难。

一方面中文文档受限于作者的水平，你有可能会了解到被扭曲甚至错误的知识，并且中文文档写好之后就很少会有人一直维护，所以你大概率会学到已经过时的技术。更何况 arcgis js 在当前的 4.0 版本进行了巨量的重构，而网上很多中文教程里还是 3.0 的写法。这就导致你在参阅官方文档时会出现更多的困惑。

另一方面，学习一门新技术一般分两种方式，学习后使用 和 使用中学习，有价值的中文文档一般都是成体系的学习，特别是 arcgis 这种大库，没个二三十课别想看完，这就是典型的学习后使用。这种方式可以让你避免产出屎山代码，但是只适合有大段空闲时间的人比如在校学生，而不是已经工作的人。

试想一下，老板给你两天时间，让你搞好一个包含 xx 功能和 yy 功能的地图。这时候你能先去花一个星期来系统的学习下 arcgis 么？这时候就应该在使用中学习，管他好不好，功能先实现了再说。

所以说，官方文档其实比那些良莠不齐的中文文档更适合急需开发功能的程序员使用，本文帮你解决文档不知道怎么看、不知道去哪看的问题，而看不懂英文的事，那我只能说装个划词翻译的浏览器插件就行，主要是不要怕，加油奥！

介绍 arcgis 文档

首先我们来介绍如何正确的找到 web 前端需要的 arcgis 文档，你可能会想啊这还用讲？欸，可别小瞧这一步，很多人都是在这一步迷失了自我。首先你百度到的网站可能会有下面这几种：

是不是有点晕了，不慌。实际上 ArcGIS 是一大堆东西的统称，这一堆的东西真的很多，但都是由 esri 这个公司主导的产品，所以你可能还会找到其他的 arcgis 网站。

这些网站大致可以分成三部分：

给客户用的在线服务：例如两个比较出名的 ArcGIS Enterprise 和 ArcGIS Online，前者可以独立部署，从而满足一些大客户的地图需求，例如航站楼导航地图、大型国家公园管理等，而后者则是由 esri 自己维护，需要使用地图的人直接注册并登录到对应的网站上就可以用。
给地理从业人员提供的专业桌面软件：这类软件有很多，比如地图编辑软件 arcMap、地理信息平台 arcgis pro，地图服务器 arcgis server 等，几乎都需要收费，但是可以破解，对使用者专业性要求较高。
给在应用里接入地图的开发者提供的第三方包：给 app 开发者用的，所以会面向各个平台，比如 web、java、.NET 或者 unity，同时也会提供一些工具来更方便、快速的生成地图应用。

了解了这些之后再回过头看一下上面三个网站，你现在能找到哪个是我们需要的么？

好吧就是第一个，ArcGIS Developers，官网文档链接在这里。进入网站之后点击左上角第一个标签 documentation，就可以看到一屏幕的 SDK 列表，而我们需要的 web 前端开发文档就在这里：

点进去之后就是本文的主角了，ArcGIS SDK - JavaScript 文档，我们一般简称 arcgis js（有不少人也叫做 arcgis web，但是这也能代指刚才提到的一些 esri 在线服务，容易有歧义，大家了解就好）：

先忽视正文内容，把目光放在右上角的次级导航上，可以看到一共包含五个标签：

分别是：

Overview 概览教程：会循序渐进的让你了解 arcgis js 的使用方法。
Sample Code 示例 DEMO：一大堆按需求分类的 demo，就像 echarts 的在线示例一样。
API Reference API 详细文档：arcgis js 的详细介绍与说明。
Showcase 陈列柜：这里包含一些很有特点的地图实现，个数不多，有兴趣可以瞅瞅。
Blogs 博客：由官方或者其他人写的技术随笔。

有些人可能迫不及待的就从 Overview 开始看起了，这套教程确实不错，但是要记得，老板明天就要我们做好功能，不然就只能去下个公司读文档了，所以说我们只能暂且搁置。不过我还是很推荐如果有时间的话可以完整读一遍，会了解到很多小技巧和没注意到的细节。如果你对 arcgis 有持续的深度使用需求的话，那我也很推荐你经常关注一下这个博客页面，阅读有一定的门槛，但是真的收益颇丰。

你也可能找到长这样的网站：

这个是老版本的，如果你不需要维护之前代码的话，那么就不用看这个了。

收费与定价

这里顺便提一句收费标准，相信很多新手最关心的问题就是这个。首先要明确的是：arcgis js 是不要钱的。arcgis 的定价标准在这里：Developer subscriptions | ArcGIS Developers，你在里边是找不到 arcgis js 的收费项的，所以不必担心。

还有另一个收费标准是这个 Pricing | ArcGIS Developers，这里包含的是 arcgis 的在线服务，类似于百度地图的 poi 搜点、导航信息之类的服务，国内用的不多，所以就不提了。

但是！虽然 arcgis js 不收钱，但是依旧有其他的风险，例如地图下面这些信息，虽然可以隐藏，但是可能会造成一些版权问题：

并且，如果你使用了 arcgis js，那 esri 就可以很轻松的得知你通过 arcgis js 连接了哪些地图服务，毕竟这玩意也没开源。如果你恰好部署了一个盗版的 arcgis server（或者其他盗版的软件设施），那可就要小心律师函警告了。这种秋后算账的手段很常用，等你在这个技术上写了很多代码，也积累了很多用户时，突然给你发函，要么买他的许可，要么停掉业务。

不过这个问题不是咱们开发需要关心的，你只需要把这个风险点反馈给上面就好了。

API 文档导读

本文的重点是示例 DEMO 和 API 文档，我会把这两者的目录过一遍，这样你就可以对 arcgis 有个初始印象，同时也能了解到该去哪找到自己想要做的功能。

咱们首先来看一下 API 文档，通过右边 API Reference 点进去就可以看到：

导航分两部分，左边更详细，并严格按照模块命名，中间则是按类别大致分了一下，方便快速查阅：

1、基础地图对象

我们先从中间的第一部分开始，这里我大致圈了一下：

其中核心是第一个 Map：它就是一个纯数据、纯逻辑、不包含任何视图功能的地图核心，包含了诸如图层、底图之类的管理功能，绝大多数的地图都是从实例化这个对象开始的。

然后是 MapView 和 SceneView，这两个是负责视图层的，会把上面纯数据的 Map 转换成咱能看到的画面。MapView 是把 Map 渲染成 2D 地图，而 SceneView 则是把 Map 渲染成 3D 地图。所以这俩玩意必须接受一个 Map 对象作为参数，不然绘制谁呢。

后面的 WebMap 和 WebScene 和前面的 Map 类似，这两个是用来绑定 arcgis 官方的在线地图的。

什么意思呢？还记得我们上面提到的 ArcGIS Enterprise 和 ArcGIS Online 么，这两个平台可以在线创建地图，类似于低码平台，可以通过配置项，点点点就能做出一个地图来，这类在线地图被叫做 portal，你在文档里看到 portal 这个词就可以往这上面联想。这种在线地图会有一个唯一 id，把这个 id 传递给 WebMap 和 WebScene 就可以生成你之前配置好的地图，类似于下面这样，很方便：

const webmap = new WebMap({
    portalItem: { // autocasts as new PortalItem()
        id: "e691172598f04ea8881cd2a4adaa45ba"
    }
});

而 WebMap 就是用来实例化 2D 在线地图，WebScene 用于实例化 3D 在线地图。这个实例化之后，也是和 Map 一样，需要传递给 MapView 和 SceneView 才能渲染出来。

不过这俩用的也不多（毕竟要钱还是国外服务），一般都是从自己或地图商的 arcigs server 掏数据，配合 Map + MapView 做 2D 的地图展示。

至于最后一个 View 不用太关系，这个是 MapView 和 SceneView 的基类，平时不怎么接触的到。

2、图层 Layer

然后是第二部分，图层：

有些同学一看我超这么多，慌了。不慌！里边最常用的就两个：FeatureLayer 和 TileLayer。

FeatureLayer（要素图层）：这个图层是用于存放地图上那些元素，比如各种点（最常用），线（道路、铁路），面（各种区域，房屋、公园...）
TileLayer（瓦片图层）：一般用于引入底图，大多配合 arcgis server 使用。

对于绝大多数的场景，都是先搞个 TileLayer 加载个 2D 底图，再搞个 FeatureLayer 在底图上撒点。没了，就这么简单。

所以说如果这两者已经覆盖到你的需求的话，剩下的图层你就不用关心了。如果不满足，好我们继续讲一下：

上面这个图里可以看到 Layer 们被分成两部分，上面的用于显示 不同类型 的地图元素，下面的图层用于加载 不同来源 的地图数据。

这些里相对比较常用的是下面几个：

StreamLayer 流图层：用于加载持续性的数据，例如风向、河流流向，就跟直播似的。
ImageryLayer 影像图层：用于叠加图片，比如气压图、温度图。
RouteLayer 导航图层：用于显示导航路径，你给他塞一堆点，然后让它找到最合适的导航路径。
BuildingSceneLayer 3D 房子图层，用于显示一栋（或一层）拥有复杂内部细节的建筑设施。
PointCloudLayer 点云图：显示千万或者亿级点位，3D 图层，一般用来显示激光扫描出来的街景。

CSVLayer：从一个 csv 文档里加载数据
GeoJSONLayer：从一个geoJson 文档里加载数据

开始开发一个地图，首先就是选择合适场景的图层，优先考虑 FeatureLayer 和 StreamLayer，这两者满足不了再考虑其他的。所以你可以先去问一下客户，地理数据怎么提供，然后根据数据类型的不同再来挑选合适的图层。

我个人比较常用的就是拿到地理数据，如果是静态的就烘焙成 arcgis server 的瓦片图层，如果是动态的就入个地理数据库，比如 postgresql，然后再通过 arcgis server 暴露服务，最后通过 FeatureLayer 或 StreamLayer 展示数据。把消耗大的工作都交给 server 层处理，前端的性能就会好一点。

不过如果时间要求比较紧急来不及做这种处理的话，也可以让你们的后端拉张表存点位数据，然后前端请求到之后在本地创建 FeatureLayer。

3、窗口组件 Widgets

这部分主要是显示在 UI 上的一些功能组件，用于提供各种功能：

上面我已经圈出来几个比较常用的了，比如：

locate：定位当前位置按钮
Print：打印地图按钮
Search：地图搜点框
Zoom：地图缩放按钮
Sketch：交互图形

说白了就是很多小功能，你实例化对应的组件，然后传递给 view 对象就可以在地图上对应位置画个按钮。

这里要重点提一下 Sketch，这个很重要，它可以往地图上绘制一个图形，比如折线、绘制多边形、拖动图形之类的，基本上很多地图交互都需要它来实现，比如划线查距离，框选查询，范围查询等等。

其实如果你刚上手的话，Widgets 的优先级是比较低的，特别是你的前端已经使用了 vue、react 之类的现代化前端框架。例如图例、弹框、表格、图表分析。实在不行你自己搞个前端组件画一下也完全可以。只有在和地图有很高的交互程度，比如跟着地图拖动走，或者对地理数据分析有很高的要求，数据又很多，这时候再来研究这些 Widgets 也不迟。

4、几何 Geometry

这一部分很重要！一个功能的开发里很多时候都是在跟各种 Geometry 打交道，所以别看它数量少，优先级反而很高：

其中最常用的就是上面标出来的四个：圆（Circle）、点（Point）、多边形（Polygon）、折线（Polyline），地图上的要素基本都是通过这几种类型显示出来的。

这个我们稍后会详细介绍下，我们现在只需要知道它们是用来存放各种类型的几何信息的就可以了。

最后面的 SpatialReference 也要强调一下，这是个很重要的属性，用于说明一个对象是基于什么坐标系的，所以很多对象上都有这个属性，比如图层或各种 Geometry。不过有时候也可能会空，比如手动创建的、或者 acrigs server 里没有配置这个参数。

5、常用类

这一部分里列举了一些常用的杂项内容：

这里介绍一下：

config：arcgis 的全局配置项，类似静态资源、字体文档的加载链接都可以在这里修改。
geometryEngine：几何工具：提供了基于坐标系对元素进行相对位置、距离、是否包含、是否相交之类的工具，挺常用，但是如果坐标系是 CGCS2000（国内常见坐标系）的话，这里很多工具就用不了了。
Graphic：图形，用于描述地图的各种要素，比如这个要素的样子、位置信息、是点还是线条等。
Renderer：渲染器，每个 Layer 都可以配置一个渲染器，用于把自己的要素信息通过各种方式渲染出来，比较常用的是区分显示器（UniqueValueRenderer），用于根据要素的属性不同显示不同的样子（比如设备类型、是否在线等）
SimpleMarkerSymbol：最最基础的点位显示符号，可以在地图上显示一个点。

这里你就了解上面加粗的三个东西就行了，这三个属于用的不多，但几乎每个项目都要用到的东西。

而 Graphic 和 SimpleMarkerSymbol，并不是说他们不重要，恰恰相反，它们太重要了，以至于需要单独介绍一下。

核心三剑客：Graphic、Symbol 与 Geometry

这三者可以说是 arcgis 的一个比较难以理解的核心概念。有很多人会觉得这仨很像啊，感觉有区别但又不知道哪里有区别。开发的时候就经常搞混，这里咱们就介绍一下，破除这个障碍。

首先，Graphic 包含 Symbol 与 Geometry，这两者是 Graphic 的同级属性。如果你前端八股还没忘干净的话，应该记得浏览器中 DOM 元素包含两种属性，分别是控制布局的几何属性，和控制外观的样式属性。而 Geometry 就是几何属性，Symbol 则是样式属性。

Geometry 描述了一个地图元素的几何信息，比如它的坐标，它的类型是点还是线还是面。也就是说，Geometry 是一个基类，派生出了 Point , Polygon , Polyline 等子类，用于描述不同类型的几何信息。而 Circle 比较特殊，它是多边形的一个子类：

而 Symbol 则描述了一个元素长什么样子，比如颜色、边框、大小、字体等等，Symbol 作为一个基类，派生出了 MarkerSymbol，LineSymbol，FillSymbol 三个子类用于显示点、线、面三种几何信息。

除此之外还有一个子类 TextSymbol 用于渲染纯文字标签，以及一个 Symbol3D 子类，这个 Symbol3D 类又派生出了三种子类，用于渲染 3D 视图下的点、线、面，这里不再赘述：

最后面派生出的子类大致可以分为两种：Simple 和 Picture，Simple 是指通过配置来创建一个符号，比如边框粗细、颜色，填充颜色等等。而 Picture 就是传入一个图片文件，然后把这个图片贴在地图上。所以 PictureMarkerSymbol 很常用，UI 提供设计好的点位图标，前端就用这个符号显示出来。

讲完了这两个属性，剩下的 Graphic 就简单了，所有在地图上显示的元素，最终都可以归结为一个 Graphic，无论你长什么样，什么颜色，位置在哪，都是一个 Graphic，只不过上面的属性不同。我们可以简单看一下它的属性 Graphic | API Reference：

除了刚才讲过的 geometry 和 symbol 之外，还有一些常用的属性比如 attributes：里边包含了这个要素的特征（字段），以及 layer 代表了所在的图层，visible 代表是否显示。更细节的就不过多展开，有机会下次再开文讲下。

arcgis js 对象模型

了解了上面三个核心对象之后，我们就可以描绘出一个基础的对象模型了：

小结

其实原本打算一口气讲完的，结果不知不觉已经五千多字了，为了不给大家的理解造成负担，就分为上下两部分来讲好了，如果有帮助还希望能点个收藏。

到现在为至，我们介绍了一些关于 arcgis 的基础知识，同时把 arcgis 的 API 按照分类大致讲了一遍。如果你脑子里已经对 arcgis 有个大致的印象，那说明我们已经成功一半了。本文算是先打个基础，下篇文章我们会接着介绍 API 文档的详情，并配合 DEMO，让你能把对 arcgis 的大致印象转换成实际的开发能力，链接在这里：

arcgis js 入门：科普介绍与文档导读（中） - 掘金 (juejin.cn)