本技能用于指导开发者使用 ArcGIS Maps SDK for JavaScript 构建基于 Web GIS 的地图应用。适用场景包括网页地图、可视化、编辑、数据采集和空间分析。
一、主要能力
- 核心 API(@arcgis/core):提供地图、Web 地图(2D)、Web 场景(3D)、链接图(知识图谱)、图层、可视化、认证、身份管理以及客户端分析等类、方法、属性和事件。
- 组件包:包括 Map Components(@arcgis/map-components)、AI Components(@arcgis/ai-components)、Charts Components(@arcgis/charts-components)、Coding Components(@arcgis/coding-components)、Common Components(@arcgis/common-components)和 Embeddable Components(@arcgis/embeddable-components),以 Web 组件形式供声明式使用。
- 组件基于 Calcite Design System(@esri/calcite-components),用于构建一致、响应式、可访问的 UI。
- 推荐基于 Web GIS 方式,优先加载已配置的 web map、web scene 和图层,而非完全通过命令式代码从零构建。
二、账户与认证要求
- 开发者需具备以下 ArcGIS 账户之一:ArcGIS Location Platform(免费)、ArcGIS Online,或用户类型为 Creator、Professional、Professional Plus 的 ArcGIS Enterprise。账户的用户类型、角色和权限决定可访问的资源和操作。
- 认证是必读内容,需参考 follow-arcgis-authentication-patterns 技能,根据受众、用例和应用类型选择合适的认证方式。
三、新建应用
- 可通过以下命令查看可用模板:npx -y @arcgis/create --help。
- 指定模板和名称以非交互方式创建:npx -y @arcgis/create --name <app-name> --template <template-name>。
- 若无 npx,可使用 jsapi-resources 模板中对应模板。
四、现有应用适配 在给出具体指导前,需检查应用类型(包管理或 CDN)、框架与语言(JavaScript 或 TypeScript)、SDK 版本、平台(ArcGIS Online、Enterprise 或 Location Platform)、门户配置、SDK 使用方式、全局设置、本地资源等细节,避免将 CDN 指引用于包管理应用,或混淆不同框架和版本的用法。更新现有应用时,可参考 Get started、Vite、React、Angular、TypeScript 等匹配指南,并查阅发布说明。
五、文档查询
- 可接入 Esri MCP 服务器(https://developers-mcp.arcgis.com/mcp)查询开发者文档。
- 使用 search_esri_developer_docs 工具时,将 focus_area 设为 javascript-sdk;使用 fetch_esri_developer_docs 工具可获取页面 Markdown 全文。
六、使用模式与验证
- 根据应用的交付模型选择包管理或 CDN 方式,只读取一种匹配参考。
- 直接导入模块中的类、函数和类型,类型导入使用 import type,避免使用已弃用的 __esri 类型。
- 当组件包已提供等效方案时,避免生成过于复杂的 @arcgis/core 实现。
- 编码前检查现有应用加载的 item 和图层;编码后运行应用、测试主要工作流并修复问题。对包管理应用运行构建和类型检查,启动开发服务器并确认应用可加载;对 CDN 应用需对照 npmjs.com 上匹配 SDK 包的声明检查 API 和类型用法。
- 使用浏览器工具(如 Chrome DevTools、Playwright、Puppeteer)打开运行中的应用,等待 UI、地图、图层和数据渲染,不能仅以服务器运行作为应用可用的依据。
- 从已加载的应用中读取 item 和图层详情,而非根据源码或标题推断;displayField 可能为空,应优先使用 popupTemplate.title、attributeTableTemplate 首列、labelingInfo 字段,再考虑 displayField 和 objectIdField。
- 检查控制台错误时,需先确认在生产构建中是否复现,再判断是否为代码缺陷。
七、适用场景与限制 适用于使用 ArcGIS Maps SDK for JavaScript 进行前端地图应用开发的场景,包括 2D/3D 地图、可视化、编辑、数据采集、空间分析、认证与门户集成。限制包括:需要有效的 ArcGIS 账户;部分功能依赖 SDK 版本和平台(如 API key 认证适用于 Location Platform、Online 和 Enterprise 11.4 及以上);文档查询依赖 Esri MCP 服务器是否可用;具体收费、价格和平台细节暂未提供。