技能介绍

要解决的问题

从 ArcGIS Maps SDK for JavaScript 5.0 开始，官方主推基于 Web Components 的声明式开发，原本 new SceneView(...)、new Sketch(...) 这类命令式写法逐步让位于 <arcgis-scene>、<arcgis-sketch> 等自定义元素。迁移时最容易踩的坑集中在三处：CDN 版本不匹配导致自定义元素根本没注册；组件属性、referenceElement、viewOnReady() 的先后顺序错了，结果图层创建失败或事件不触发；旧代码里的 view.map = map 悄悄重置了相机，3D 场景直接飞回初始视角。这个技能专门把这些失败路径整理成可执行的开发规范。

技能如何工作

核心能力是把组件化开发的关键点拆成可照抄的模式：

统一使用 5.0 CDN：资源地址为 https://js.arcgis.com/5.0/，避免 4.x 环境下组件不可用。
声明式视图：用 <arcgis-scene> 替代 new SceneView({...})，通过 viewElement.view 获取 view 对象。
referenceElement 优先：组件之间通过 referenceElement 关联，不直接传递 view 对象，减少耦合。
严格初始化顺序：arcgis-sketch 的 layer、referenceElement、defaultGraphicsLayerDisabled、creationMode 都要在 view.viewOnReady() 之前完成；相机定位改到 view 就绪后用 view.goTo()。
底图与地形模板：提供天地图瓦片封装，type 可取 img_w、vec_w、cva_w，分别对应影像、矢量和中文注记；返回 .base 与 .anno，组合进 basemap.baseLayers。3D 场景额外提供 ElevationSampler 地形初始化。
组件速查表：覆盖 arcgis-scene、arcgis-map、arcgis-sketch，以及 zoom、compass、home、search、layer-list、legend、basemap-switcher、expandable-panel 等常用控件，并附官方 API 与入门教程入口。

适用边界与注意点

这个技能只服务 5.0+ 的组件化写法，不覆盖 4.x 时代的 widget 生命周期与本地 CDN 调法，也不能用来扩展 SDK 之外的地图引擎。组件属性和就绪时序是硬约束：先设属性再等就绪，不要把 view.map = map 当作相机定位手段。使用 arcgis-sketch 时，defaultGraphicsLayerDisabled 必须为 true，并自建 GraphicsLayer；图层坐标系要和 arcgis-scene camera 保持一致，3D 下还需 elevationInfo: { mode: "on-the-ground" }。遇到 Failed to create layerview for layer 'Sketch Layer'、事件不触发、交叉多边形检测失效等问题，先检查等待顺序与 event.detail 取值。所有示例都基于官方组件文档，不引入不存在的类或工具。