build-with-arcgis-and-openlayers

使用 OpenLayers 和 ArcGIS 构建应用

OpenLayers（OL）可在浏览器中使用 ArcGIS 服务渲染地图。使用 ol（地图／图层）、ol-mapbox-style（ArcGIS Basemap Styles v2）和 ArcGIS REST JS（@esri/arcgis-rest-*；用于身份验证、查询和位置服务）。

OpenLayers 不是 ArcGIS Maps SDK：它没有 FeatureLayer／WebMap 类，也不会解析 ArcGIS 弹出窗口模板或渲染器。请明确解析端点并转换 ArcGIS JSON。

ArcGIS 帐户要求

开发者必须拥有以下其中一种 ArcGIS 帐户才能创建应用：ArcGIS Location Platform（免费），或具有 Creator、Professional 或 Professional Plus 用户类型的 ArcGIS Online 或 ArcGIS Enterprise 帐户。帐户的用户类型、角色和权限决定了可访问的资源和操作。

身份验证

请勿跳过：请参阅 follow-arcgis-authentication-patterns 技能，了解 ArcGIS 身份验证要求，包括针对不同受众、用例和应用类型选择适当的身份验证方式。如果无法使用该技能，请搜索项目中是否有现成的身份验证模式；如果没有，请通过文档 MCP 查询身份验证最佳实践。

安装和设置

使用 ol-mapbox-style 创建矢量底图，使用 REST JS 实现地理编码、路径规划、高程、地理信息丰富化和身份验证等位置服务。加载 OpenLayers CSS，为地图容器指定非零的明确宽度和高度，通过 HTTP(S) 提供服务，切勿使用 file://，并确认 API 和版本为当前版本。

新建应用

根据提示／项目推断需求；在搭建脚手架前先澄清不确定之处。

使用 CDN 新建应用

使用当前的 ArcGIS OpenLayers 示例：将 ol.css 作为样式表引入；加载 dist/ol.js，并按依赖顺序加载所需的 REST JS UMD 脚本。这些代码包会暴露全局变量；不要将其作为 ESM 加载。通过 MCP 检查 URL／版本。大多数 ArcGIS 文档都展示 CDN 导入方式；请在测试、演示、教程、示例和轻量级快速入门中使用。

使用 npm 新建应用

使用 npm create ol-app my-app 或 Vite，除非已指定框架。安装 ol、ol-mapbox-style 以及任何必需的 @esri/arcgis-rest-* 包（request、feature-service、geocoding、routing、places）。使用 ESM 导入，并通过打包工具导入 ol/ol.css；根据 ol-mapbox-style 的说明固定兼容的版本。生产环境、大型应用或框架应用优先采用此方式；使用项目的包管理器。React、Angular、Vue 和 Svelte 均为受支持的框架。如果使用 create ol-app 之外的框架专用模板，请移除所有与用户请求无关的模板文件（例如 counter.js）。

现有应用

安装前，先确认包管理器／锁文件、框架、使用 CDN 还是模块、TypeScript／ESLint 配置以及打包工具。遵循现有约定；只添加所需的 ol、ol-mapbox-style 和 REST JS 包。保留凭据／环境变量约定，导入 ol/ol.css，设置地图尺寸，并在升级前检查兼容性。

如何查询文档

可以使用 Esri 开发者文档服务器的 MCP 查询文档：

https://developers-mcp.arcgis.com/mcp

使用 search_esri_developer_docs 工具查找权威文档页面，并将 openlayers 设为 focus_area 参数，同时指定 search_term；查询 ArcGIS REST JS 时，将 focus_area 设为 arcgis-rest-js。使用 fetch_esri_developer_docs 工具，并将 page_url 参数设为相应网址，以 Markdown 格式返回文档页面的完整内容。

请明确指出任何并非基于官方文档的建议和假设。如果无法使用 MCP，请查阅下方的官方文档 URL。

文档链接

• ArcGIS OpenLayers
• OpenLayers API
• ol-mapbox-style
• REST JS
• 归属信息

模式与指南

身份验证集成

• 验证服务特定的账户支持情况：仅凭 Enterprise 凭据无法授权使用 ArcGIS Location Services；使用这些服务时，请使用受支持的 Location Platform/Online 凭据。
• API 密钥：使用 @esri/arcgis-rest-request 中的 ApiKeyManager.fromKey(apiKey) 作为 REST JS authentication。授予最低限度的权限/项目访问权限；通过来源站点限制浏览器密钥。即使通过构建时环境变量设置，浏览器密钥仍然可见。切勿暴露客户端密钥。
• OAuth：通过 PKCE 和精确的重定向 URI，使用 REST JS ArcGISIdentityManager。
• 原生 OL 数据源：REST JS 不会直接集成。请在数据源加载器或 tileLoadFunction 中附加/刷新凭据；切勿暴露客户端密钥或记录包含令牌的 URL。
• 请参阅 arcgis-rest-js 和 follow-esri-authentication-patterns 技能。

底图、样式与归属信息

• 对专用的 LayerGroup 使用 ol-mapbox-style 的 apply(layerGroup, styleUrl) 应用 Basemap Styles v2，然后将其添加到地图中。
• 添加依赖图层前，请等待样式应用完成，并处理失败情况。切换样式时，只替换此组。
• 保留可见的 Powered by Esri 以及每个数据项要求的归属信息/致谢；不要覆盖源数据的署名信息。

图层与数据源选择

• 要素服务：使用 REST JS 查询图层端点（FeatureServer/<layerId>）。使用 EsriJSON/GeoJSON 解析，并添加到 VectorSource。将读取选项 dataProjection 设为响应坐标参考系，将 featureProjection 设为视图坐标参考系。使用 ol/loadingstrategy.js 中的 bbox 按视口加载；根据服务对象 ID 分配稳定的要素 ID，以避免重复。加载器失败时，removeLoadedExtent(extent) 可允许重新加载，但不会触发重新加载；请在后续加载周期或通过主动触发来重试，并限制重试次数。
• 要素样式：检查图层元数据（drawingInfo.renderer）；将相关符号、唯一值/分级规则和比例尺限制转换为 OpenLayers 样式。确保图例与渲染的符号一致。对于不受支持的渲染器详情，应予以说明，而不要声称已忠实复现。
• 编辑：检查功能和权限。使用 REST JS applyEdits 提交 ArcGIS 几何/属性，而非 OpenLayers 要素对象。检查每项新增/更新/删除操作的结果；请求成功返回时，其中仍可能包含失败的编辑。仅更新/刷新成功的编辑，并显示失败信息。
• 矢量切片：大规模数据/命中检测使用 VectorTileLayer + VectorTileSource（ol/format/MVT）。对于已发布的样式，使用 ol-mapbox-style 和服务的样式 JSON；若要有意覆盖样式，则使用显式的 OpenLayers 样式。属性会因切片/缩放级别而异；如需完整查询/编辑，请使用要素服务。
• 缓存切片：使用 /MapServer/tile/{z}/{y}/{x} 配置 TileLayer + XYZ。检查 tileInfo 和服务空间参考；在假设其采用标准 XYZ 网格前，先验证切片大小、原点、分辨率和级别 ID。必要时配置匹配的切片网格和级别映射。进行画布导出时，设置 crossOrigin: "anonymous" 并验证服务 CORS；仅设置此选项并不足够。
• 动态地图服务：对于导出的 MapServer 图像，使用 ImageLayer + ImageArcGISRest 或 TileLayer + TileArcGISRest。
• 弹出窗口：将属性视为不可信内容。优先使用 DOM textContent；任何 HTML 都必须经过清理。

坐标系和几何处理

• OpenLayers 的默认视图投影是 Web Mercator（EPSG:3857）。许多 ArcGIS 位置服务示例使用 WGS 84（EPSG:4326）坐标，顺序为 [longitude, latitude]，但支持的输入和输出空间参考因服务和操作而异。请检查服务要求，并在地理坐标与地图视图投影之间转换时使用 fromLonLat / toLonLat。对于非默认视图，请按需注册不受支持的投影，并将实际视图投影传给 fromLonLat/toLonLat 和 ol/sphere 测量函数。
• 将查询 inSR 设为输入几何的空间参考，将 outSR 设为所需的输出 CRS；对于非 Web Mercator 视图，不要将 3857 硬编码为投影。
• 匹配响应格式（EsriJSON/GeoJSON）；设置读取器的 dataProjection 和 featureProjection。
• 使用 ol/sphere 计算实际距离/面积；Web Mercator 平面测量会产生变形，在高纬度地区尤其明显。

查询、分页和性能

• 检查 ?f=pjson，了解 maxRecordCount 和功能支持情况。
• 遇到 exceededTransferLimit 时，仅在支持的情况下使用 resultOffset/resultRecordCount，并在支持时采用稳定排序；否则，先获取对象 ID，再分批查询。请参阅查询文档。
• 仅请求所需的 outFields；对于仅查询属性的请求，将 returnGeometry: false。
• 对于大型数据集，请限制请求并发数，并在合适的缩放级别查询。bbox 加载会在用户平移时保留要素；请选择有界缓存或替换视口内容。保持已加载范围的记录与要素驱逐逻辑一致，以便用户再次访问某区域时重新加载缺失数据。
• 根据已知字段构造 where 子句，并验证或转义字段值；切勿直接使用未经处理的用户输入。
• 在 forEachFeatureAtPixel 中使用 layerFilter 限制弹出窗口的命中测试范围。
• 对地理编码请求进行防抖；避免显示过时结果。显示加载、空结果和错误状态；不要将失败当作空数据处理。

框架生命周期和弹性

• 在 React/Vue/Angular 中，在 DOM 挂载后通过生命周期钩子（useEffect、onMounted、ngAfterViewInit）初始化；将地图保存在 ref/服务中，而非响应式状态中。
• 卸载时，使用 unByKey 移除监听器，移除控件/覆盖层，取消待处理的任务/观察器，并调用 map.setTarget(undefined) 分离地图。拆除后忽略迟到的异步结果。
• 容器大小改变或变为可见时，调用 map.updateSize()。
• 处理被拒绝的请求和数据源加载错误（tileloaderror、imageloaderror、featuresloaderror）；让错误信息具有可操作性，同时避免泄露令牌。
• 控件必须有标签、支持键盘操作；状态消息必须易于访问；布局应适合触控；重要结果应提供替代列表/表格。
• 为地图容器设置明确的高度，并确认渲染后的视口尺寸非零。

验证流程

• 兼容的软件包可以安装并构建。
• 已设置 CSS/容器尺寸；地图能够渲染，不会因布局问题而塌陷。
• 身份验证成功，且浏览器代码中不包含客户端密钥。
• 底图/图层能够渲染，并提供所需的 Esri 和数据署名。
• 要素样式和图例符合预期的渲染规则；不受支持的细节已记录。
• 查询使用正确的 inSR/outSR，请求所需数据，处理数量限制，并正确渲染。
• 反复平移时，请求/要素数量保持在合理范围内；被驱逐区域会重新加载，失败的加载可以重试。
• 交互能够处理空结果/错误结果、部分编辑失败和过时响应，且不会使用不安全的 HTML，也不会产生未处理的拒绝。
• 拆除时会移除监听器、分离地图，并处理 updateSize()。
• 控件/结果支持键盘和触控操作，状态消息易于访问，布局能适应小屏幕。
• 浏览器冒烟测试涵盖渲染、服务请求、交互、调整大小和拆除；检查控制台/网络错误。如果无法进行浏览器测试，请报告尚未验证的内容。