js-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ArcGIS Maps SDK for JavaScript

Resolve the target first

先确定目标版本

Determine whether the app targets ArcGIS Online or a specific ArcGIS Enterprise version, then resolve the SDK version from the live Esri version matrix — https://developers.arcgis.com/javascript/latest/version-matrix/ — rather than assuming "latest." The Enterprise release pins the SDK version, which in turn pins Calcite.

先确定应用的目标是ArcGIS Online还是特定的ArcGIS Enterprise版本，然后从Esri实时版本矩阵（https://developers.arcgis.com/javascript/latest/version-matrix/）中确定SDK版本，而非直接默认使用“最新版”。Enterprise版本会固定SDK版本，进而固定Calcite的版本。

Know the generation boundaries

了解版本代际界限

These are not ordinary version steps — treat them as distinct products where noted:

3.x — retired 2024-07-01. Not a migration target.
4.x — a complete rewrite of 3.x, not an increment. Moving 3.x → 4.x is a rewrite.
5.x — continues 4.x under semantic versioning: minor bumps are backward-compatible, major bumps are breaking.
Migrating 3.x → 5.x is a rewrite, not an upgrade.

这些版本并非普通的版本迭代——必要时需将它们视为完全不同的产品：

3.x — 已于2024年7月1日停用，不适合作为迁移目标。
4.x — 是对3.x的完全重写，而非增量更新。从3.x迁移到4.x相当于重新开发应用。
5.x — 在4.x基础上遵循语义化版本规则：小版本更新向后兼容，大版本更新包含破坏性变更。
从3.x迁移到5.x属于重写，而非版本升级。

Use ES modules or components — the AMD path is dead

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

4.31 was the last release of the

arcgis-js-api

AMD npm package; its AMD TypeScript declarations and

@arcgis/cli

are retired. Build with

@arcgis/core

ES modules or the components packages. Do not scaffold AMD.

4.31是

arcgis-js-api

AMD npm包的最后一个版本；其AMD TypeScript声明和

@arcgis/cli

已停用。请使用

@arcgis/core

ES模块或组件包进行构建，不要搭建AMD项目架构。

Prefer components over widgets

优先使用组件而非小部件

Components are the recommended path. If you use widgets, or initialize

MapView

SceneView

programmatically, you must manually include the core API CSS stylesheet — omitting it renders the view broken.

组件是推荐的开发路径。如果使用小部件，或通过代码初始化

MapView

SceneView

，则必须手动引入核心API的CSS样式表——若省略该样式表，视图将无法正常渲染。

Pin Calcite

固定Calcite版本

Pin Calcite to the version the target SDK uses (from the version matrix above), or a greater compatible minor.

将Calcite版本固定为目标SDK所使用的版本（可从上述版本矩阵中获取），或更高的兼容小版本。

Settle the redirect URL before you choose a dev server

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

Local sign-in fails for environmental reasons far more often than code reasons, and the dev server is the hardest of those to change late. Redirect URLs are an allowlist stored on the OAuth credential item — only a registered value works, and nothing about the scheme, port, or path is guaranteed. Fix the accepted value first, then pick a server that can serve it.

You own the credential item — register the URL you intend to serve from, under Settings > Application > Redirect URLs on the item page, and serve exactly that.
Someone else owns it (a shared or training
```
client_id
```
) — you cannot read the registration from outside the org, but you can probe it. Request the authorize endpoint once per candidate:
```
400
```
means rejected,
```
200
```
means accepted. No credentials needed.
```
https://www.arcgis.com/sharing/oauth2/authorize
  ?client_id=<APP_ID>&response_type=code&redirect_uri=<CANDIDATE>
```
Probe both schemes and the exact port and path you plan to serve. Many orgs register only
```
https://localhost
```
, which rejects every
```
http://
```
form and every
```
127.0.0.1
```
form — and a plain-HTTP dev server (VS Code Live Preview,
```
http-server
```
,
```
python -m http.server
```
) cannot be retro-fitted with TLS. When only
```
https
```
is accepted, serve over HTTPS — Vite with
```
@vitejs/plugin-basic-ssl
```
is enough for a CDN-based app with no build step — and tell the user up front that they must click through the self-signed certificate warning once, or it reads as a failure.

Run the redirect in a top-level browsing context. ArcGIS refuses to render its sign-in page in a frame, so in VS Code Simple Browser and other preview panels the sign-in button silently does nothing. Detect

window.top !== window.self

and tell the user to open a real tab.

When both an API key and user authentication are configured, the API key wins — a successful sign-in that still behaves like an anonymous session usually means a stray API key, not a broken flow.

本地登录失败通常是环境原因而非代码问题，且开发服务器的配置后期很难更改。重定向URL是存储在OAuth凭证项中的白名单——只有已注册的URL才能生效，其协议、端口或路径均无默认保证。请先确定可接受的URL值，再选择能提供该URL的服务器。

您拥有凭证项 — 在凭证项页面的“设置 > 应用 > 重定向URL”中注册您计划使用的服务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简易浏览器和其他预览面板中，登录按钮会无响应。请检测

window.top !== window.self

，并告知用户打开真实的浏览器标签页。

当同时配置了API密钥和用户认证时，API密钥优先级更高——若登录成功但仍表现为匿名会话状态，通常是因为存在多余的API密钥，而非登录流程故障。

Destroy credentials only on a user action

仅在用户操作时清除凭证

IdentityManager.checkSignInStatus()

rejects on every load with no session — including the load immediately after ArcGIS redirects back with an authorization code. That rejection is a normal state, not an error, so keep its handler to showing the signed-out UI. Calling

destroyCredentials()

there deletes the PKCE state the return leg needs (

sessionStorage

, key

esriJSAPIOAuth

, namespaced by page path), and the user signs in successfully only to land back on the sign-in screen, every time. Put

destroyCredentials()

behind an explicit Sign out or Reset button.

On the return leg, read

code

error

, and

error_description

from both

location.search

and

location.hash

before the SDK consumes them. When they are present but no credential results, show the reason on screen — a silent fall-through to the sign-in screen is indistinguishable from a dead button, and that is what makes this expensive to find. Strip them with

history.replaceState

only after

checkSignInStatus()

settles.

每次无会话加载页面时，

IdentityManager.checkSignInStatus()

都会返回拒绝——包括ArcGIS携带授权码重定向回来后的首次加载。这种拒绝是正常状态而非错误，因此只需在其处理程序中显示未登录UI即可。若在此处调用

destroyCredentials()

，会删除返回环节所需的PKCE状态（存储在

sessionStorage

中，键为

esriJSAPIOAuth

，按页面路径命名空间），导致用户登录成功后又回到登录界面。请将

destroyCredentials()

放在明确的“退出登录”或“重置”按钮之后。

在返回环节，需在SDK处理之前，从**

location.search

和

location.hash

中读取

code

、

error

和

error_description

**。当这些参数存在但未生成凭证时，请在屏幕上显示原因——若直接跳转到登录界面，会与按钮无响应的情况难以区分，排查成本极高。仅在

checkSignInStatus()

完成后，再通过

history.replaceState

移除这些参数。

Verify the signed-in state on the real page

在真实页面验证登录状态

A gate that covers the app until sign-in is the right shape when ArcGIS Online basemaps need a token, because there is nothing to draw before sign-in. Verify it on the real page: a token-free harness —

basemap: "osm"

against a public layer — proves the map, renderer, and legend without credentials and is worth building, but it omits the gate and therefore cannot prove sign-in works. A green harness is not a working app.

When the gate carries an author

display

rule (

display: grid

display: flex

), that rule overrides the user-agent

display: none

behind the

hidden

attribute, so

gate.hidden = true

changes nothing and the finished app sits behind the gate. Ship

[hidden] { display: none !important; }

当ArcGIS Online底图需要令牌时，在登录前覆盖整个应用的登录网关是合理的设计，因为登录前没有内容可渲染。请在真实页面验证该功能：使用无令牌测试环境（如针对公共图层设置

basemap: "osm"

）可以验证地图、渲染器和图例无需凭证即可工作，但该环境不包含登录网关，因此无法验证登录功能是否正常。测试环境正常不代表应用正常。

当登录网关使用了

display

规则（如

display: grid

、

display: flex

），该规则会覆盖用户代理在

hidden

属性后的

display: none

样式，因此设置

gate.hidden = true

不会产生任何效果，最终应用会被网关遮挡。请添加样式

[hidden] { display: none !important; }

。

Verify before you propose API

在推荐API前先验证

Before proposing any class, method, or property, confirm through

arcgis-docs-lookup

that it exists at the pinned version. When moving between versions, read the breaking-changes guide rather than assuming a method still exists.

在推荐任何类、方法或属性之前，请通过

arcgis-docs-lookup

确认其在固定版本中存在。在版本间迁移时，请阅读破坏性变更指南，不要假设方法仍然存在。

Guard destructive edits

保护破坏性编辑操作

Before emitting any code that deletes or overwrites data —

FeatureLayer.applyEdits

with deletes,

deleteFeatures

, or an editor widget wired to a live layer — stop and satisfy every point in order. This covers irreversible data operations only, not credentials or org hygiene.

Name the target. State the org/portal and the exact item or layer id the operation hits. An unnamed target is a stop.
Show what it is. Display the layer's title, type, and feature count so the user sees what they are about to lose.
Confirm it is not production. Say so explicitly and get the user's confirmation before proceeding.
Prefer the reversible form first. Offer a read-only query or a count so the blast radius is known before the destructive call runs.
Never emit blind. Withhold the destructive call until 1–4 are satisfied and the user confirms — even when the user sounds certain.

Enforcement shape for this SDK: check whether the layer URL is hardcoded or config-driven and whether it currently points at production, and place the confirmation in the app flow before the write runs.

在生成任何删除或覆盖数据的代码之前（如包含删除操作的

FeatureLayer.applyEdits

、

deleteFeatures

，或连接到实时图层的编辑器小部件），请按顺序完成以下所有步骤。此规则仅适用于不可逆的数据操作，不适用于凭证或组织管理操作。

明确目标。说明操作涉及的组织/门户以及具体的项或图层ID。未明确目标的操作必须停止。
展示目标信息。显示图层的标题、类型和要素数量，让用户清楚他们即将失去的内容。
确认非生产环境。明确说明当前环境并非生产环境，并在操作前获得用户确认。
优先使用可逆形式。先提供只读查询或计数功能，让用户在执行破坏性操作前了解影响范围。
绝不盲目生成代码。在完成1-4步骤并获得用户确认之前，不要生成破坏性操作代码——即使用户看起来非常确定。

针对此SDK的执行方式：检查图层URL是硬编码还是配置驱动，以及当前是否指向生产环境，并在写入操作前的应用流程中添加确认步骤。

Done when

完成标准

The target and SDK version are resolved from the matrix; no AMD scaffolding remains; components (or CSS-included widgets) are chosen deliberately; Calcite is pinned to a compatible version; every proposed API is verified at the pinned version; and any destructive edit has passed through the guard. Where the app signs in: the redirect URL was registered or probed rather than assumed, the dev server serves that exact URL,

destroyCredentials()

is reachable only from a user action, and the app was driven through sign-in on the real page and seen in its signed-in state.

已从版本矩阵中确定目标版本和SDK版本；已移除所有AMD项目架构；已有意选择组件（或引入CSS的小部件）；已将Calcite固定为兼容版本；所有推荐的API均已在固定版本中验证；所有破坏性编辑操作均已通过保护流程。若应用包含登录功能：已注册或探测重定向URL而非默认假设；开发服务器提供的URL与注册内容完全一致；

destroyCredentials()

仅可通过用户操作触发；已在真实页面完成登录流程并验证登录状态。