技能介绍

要解决的问题

在 ArcGIS JS API 4.x 项目中，工具的实现高度依赖命令式 Widget API：开发者通过 new Widget({ container, view, ... }) 创建实例，再通过 widget.prop = value 赋值、widget.on("event", handler) 绑定事件。这种模式的问题在于 Widget 与具体 DOM 容器强绑定，属性赋值散落在初始化代码中，事件监听分散在业务逻辑里，导致代码难以复用和测试。

迁移到 5.0 声明式 Web Components 并非简单的 API 替换：container 参数被 HTML 元素取代，view 绑定改为 referenceElement，widget.on() 需要映射为 component.addEventListener("arcgisEventName")，方法调用（如 widget.play()）部分需要兼容性检查，初始化时序也需要重新排序。这些转换如果手工完成，容易遗漏步骤或引入隐蔽 bug。

核心能力与工作流

本技能提供一套标准化的转换流程，确保每次迁移遵循一致的范式：

源码分析 — 提取 Widget 的初始化代码、属性赋值、方法调用、事件监听、View 绑定和模块导入信息
组件映射 — 通过 references/conversion-mapping.md 查找目标 Component，支持 TimeSlider、Sketch、Search、Zoom 等常见 widget 的映射
结构化转换 — 按 9 个子步骤逐项处理：CDN 替换（4.x 本地 → 5.0 在线）、SceneView/MapView 替换为 <arcgis-map> / <arcgis-scene> 视图组件、Widget 容器替换为自定义元素、构造函数参数转为属性赋值、view 绑定转为 referenceElement、事件监听映射（事件名加 arcgis 前缀 + camelCase）、方法调用兼容性检查、初始化时序调整（viewOnReady() → goTo() → componentOnReady()）、状态管理与 DOM 解耦
验证清单 — 完成后逐项检查模块导入、容器属性、view 绑定、事件格式、初始化时序和 CDN 路径

适用边界

不处理组件开发 — 本技能专注 Widget → Component 的转换流程，组件开发的基础知识需配合 arcgis-js-component 技能使用
依赖映射表准确性 — 新 widget 的转换需要先在 references/conversion-mapping.md 中补充映射关系，否则无法确定目标组件
特殊场景需参考案例 — VoxelSliceSketch 等复杂 widget 的转换涉及自定义逻辑提取和 VoxelWasm → hitTest 替换，需查阅 references/voxel-silcesketch-example.md