js-sdk

ArcGIS Maps SDK for JavaScript

先确定目标

确定应用面向的是 ArcGIS Online，还是 特定版本的 ArcGIS Enterprise，然后从 Esri 实时版本矩阵中查找对应的 SDK 版本 — https://developers.arcgis.com/javascript/latest/version-matrix/ — 不要想当然地选择“最新”版本。Enterprise 版本决定 SDK 版本，而 SDK 版本又决定 Calcite 版本。

了解各代产品的边界

以下并非普通的版本迭代 — 请将标注的版本视为不同产品：

• 3.x — 已于 2024-07-01 结束支持，不适合作为迁移目标。
• 4.x — 对 3.x 的完整重写，并非增量更新。从 3.x 迁移到 4.x 需要重写。
• 5.x — 按语义化版本规范延续 4.x：次版本更新向后兼容，主版本更新会带来破坏性变更。
• 从 3.x → 5.x 迁移需要重写，而非升级。

使用 ES 模块或组件 — AMD 路线已弃用

4.31 是 arcgis-js-api AMD npm 包的最后一个版本；其 AMD TypeScript 声明和 @arcgis/cli 均已弃用。请使用 @arcgis/core ES 模块或组件包进行构建。不要使用 AMD 脚手架。

优先使用组件，而非微件

推荐使用组件。如果使用微件，或以编程方式初始化 MapView/SceneView，就必须手动引入核心 API CSS 样式表；否则视图会显示异常。

固定 Calcite 版本

将 Calcite 固定为目标 SDK 使用的版本（见上方版本矩阵），或使用兼容的更高次版本。

选择开发服务器前，先确定重定向 URL

本地登录失败通常是环境问题，而非代码问题；开发服务器也是最难在后期更换的环境因素。重定向 URL 是存储在 OAuth 凭据项中的允许列表 — 只有已注册的值才有效，协议、端口或路径都不能想当然。先确定获准使用的值，再选择能够提供该 URL 的服务器。

• 凭据项由你管理 — 在项目页面的 Settings > Application > Redirect URLs 下，注册你计划提供的 URL，并确保实际提供的 URL 与其完全一致。

• 凭据项由他人管理（共享或培训用的 client_id）— 你无法从组织外部查看注册信息，但可以探测。针对每个候选 URL 向授权端点发送一次请求：400 表示被拒绝，200 表示已接受。无需凭据。

  https://www.arcgis.com/sharing/oauth2/authorize
    ?client_id=<APP_ID>&response_type=code&redirect_uri=<CANDIDATE>
  

  探测你计划使用的两种协议，以及准确的端口和路径。许多组织只注册了 https://localhost，因此所有 http:// 形式和所有 127.0.0.1 形式都会被拒绝 — 而纯 HTTP 开发服务器（VS Code Live Preview、http-server、python -m http.server）无法事后补加 TLS。如果只接受 https，请通过 HTTPS 提供服务 — 对于无需构建步骤、基于 CDN 的应用，使用 Vite 和 @vitejs/plugin-basic-ssl 就足够了 — 并提前告知用户，他们必须点击一次自签名证书警告才能继续，否则他们会以为操作失败了。

请在顶层浏览上下文中打开重定向。ArcGIS 不允许在框架中渲染登录页面，因此在 VS Code Simple Browser 和其他预览面板中，登录按钮会无声无息地失效。检测 window.top !== window.self，并提示用户在实际标签页中打开。

同时配置 API 密钥和用户身份验证时，API 密钥优先 — 登录成功后仍表现得像匿名会话，通常意味着遗留了 API 密钥，而非登录流程出错。

仅在用户操作时销毁凭据

没有会话时，IdentityManager.checkSignInStatus() 每次加载都会拒绝，包括 ArcGIS 重定向回来并带有授权码后的那次加载。此类拒绝是正常状态，并非错误，因此应让处理程序只显示已退出状态的界面。在那里调用 destroyCredentials() 会删除 返回流程 所需的 PKCE 状态（sessionStorage 中以页面路径为命名空间的键 esriJSAPIOAuth），导致用户成功登录后又回到登录界面，如此反复。应将 destroyCredentials() 放在明确的“退出”或“重置”按钮后。

在返回流程中，在 SDK 使用这些参数之前，先从 location.search 和 location.hash 中读取 code、error 和 error_description。如果这些参数存在，但没有生成凭据，应在屏幕上显示原因——静默地退回登录界面，无法与失效的按钮区分，这也是问题难以排查的原因。只有在 checkSignInStatus() 执行完毕后，才使用 history.replaceState 移除这些参数。

在实际页面上验证已登录状态

如果 ArcGIS Online 底图需要令牌，那么用登录门禁覆盖应用是正确的做法，因为登录前没有内容可绘制。应在实际页面上验证：不需要凭据的测试框架使用 basemap: "osm" 和公共图层，可以验证地图、渲染器和图例，值得构建，但它省略了门禁，因此无法证明登录有效。测试框架通过不代表应用可用。

如果门禁带有作者定义的 display 规则（display: grid、display: flex），该规则会覆盖 hidden 属性背后的用户代理样式 display: none，因此 gate.hidden = true 不会产生任何效果，最终应用仍会被门禁挡住。请部署 [hidden] { display: none !important; }。

提议 API 前先验证

提议任何类、方法或属性前，都应通过 arcgis-docs-lookup 确认其在指定版本中存在。切换版本时，应阅读破坏性变更指南，而不是假定某个方法仍然存在。

防范破坏性编辑

在输出任何会删除或覆盖数据的代码之前——例如带有删除操作的 FeatureLayer.applyEdits、deleteFeatures，或连接到实时图层的编辑器微件——先停下来，并按顺序满足以下每一点。此要求仅涵盖不可逆的数据操作，不包括凭据或组织的卫生维护。

1. 明确目标。 说明操作针对的组织/门户，以及确切的项目或图层 ID。目标不明确时必须停止。
2. 展示目标信息。 显示图层的标题、类型和要素数量，让用户清楚了解即将失去什么。
3. 确认目标不是生产环境。 明确说明这一点，并在继续前取得用户确认。
4. 优先提供可撤销的方式。 先提供只读查询或计数，以便在运行破坏性调用前了解影响范围。
5. 绝不盲目输出。 在满足第 1 至 4 点并得到用户确认之前，不得提供破坏性调用——即使用户听起来十分确定。

此 SDK 的防护方式：检查图层 URL 是硬编码的还是由配置驱动，以及它当前是否指向生产环境，并确保在写入执行前，应用流程中包含确认步骤。

完成标准

已根据矩阵确定目标和 SDK 版本；不再保留 AMD 脚手架；已审慎选择组件（或包含 CSS 的微件）；Calcite 已固定到兼容版本；所有提议的 API 均已在指定版本中验证；任何破坏性编辑都已通过防护流程。对于需要登录的应用：已注册或探测重定向 URL，而非想当然地认为它可用；开发服务器提供的正是该 URL；destroyCredentials() 只能通过用户操作触发；并且已在实际页面上完成登录流程，确认应用显示已登录状态。