exb-widget

Experience Builder 自定义微件

Developer Edition 自定义微件开发工作。在编写微件代码前，先确定部署目标和编译版本；并在实际加载该微件的运行时中验证其行为。

编码前确定目标

1. 检查工作区和现有微件。确定这是新建微件还是修改现有微件、所需行为、数据／地图输入、目标用户和部署目标。只询问尚未提供且会影响决策的信息。
2. 区分本地 Developer Edition 微件、外部托管的完整体验和在 Enterprise 中注册的微件。使用 Enterprise 数据的 Developer Edition 应用不会因此受到门户微件编译限制。自定义微件无法安装到 ArcGIS Online 构建器中；使用 Online 内容的外部托管 Developer Edition 应用则属于不同的目标。请参阅微件和主题部署进行核实。
3. 阅读 client/package.json，确认已安装的 ExB 版本并检查扩展目录结构。遵循放置或注册说明前，先确认使用的是 Developer Edition 还是 Esri 源码检出版本。如果无法访问安装环境，请询问其版本和相关文件；将环境门槛标记为未解决，不要猜测。
4. 对于在 Enterprise 中注册的微件，记录所有承诺支持的 Enterprise 目标，并通过 VERSIONS.md 找到对应的 Developer Edition。每个门户目标都必须使用相同的 JS SDK 版本。基于最旧目标对应版本的 Developer Edition 构建单个制品，只能作为候选支持策略，并不保证向前兼容：必须测试每个承诺支持的目标。必要时使用特定目标的构建，或缩小支持范围。
5. 对于本地开发或外部托管体验，固定 Developer Edition 运行时，并验证其所用的 Online／Enterprise 服务。实现前记录选定的运行时、目标、源 URL、验证日期以及任何尚未解决的版本配对问题。

exbVersion 声明框架兼容性；降低该值不会回移植 API、依赖项或已编译代码。WidgetManifest 参考在 2026-09-24 核实后称，其检查目前尚未强制执行。请针对当前任务重新确认该状态；此字段和编译成功都不能证明运行时兼容性。

验证确切版本的工具链

安装依赖项或启动项目之前，使用 VERSIONS.md 确认该确切版本所需的 Node 范围、推荐的 Node 版本以及 npm/pnpm 安装方式。将这些信息与已安装的工具以及 client/server 软件包元数据和锁定文件进行比对。运行命令前解决不匹配问题；区分依赖项安装和脚本执行。

仅实现受影响的最小契约

• 新建微件： 确定清单、运行时，以及行为所需的设置／配置界面。参照已核实工作区中的相邻微件。
• 现有微件： 编辑前检查其运行时、设置、配置和相邻测试。保留公开配置和框架惯例。
• 影响范围： 对于本地行为更改，测试该行为；对于设置／数据／地图／操作更改，测试受影响的契约；对于已保存架构或运行时升级，加入迁移和目标运行时检查。验证范围应随影响范围扩大，不要进行无关重构。

需要实现指导时，请阅读实现指南中与相关界面对应的部分。先应用本技能的环境门槛，再遵循选定的实现指南，最后执行下方的验证。可选的配套工具不会替你选择目标运行时，也不能取代这些门槛。

保持清单不变量

遵循清单编写检查清单：name、type、version、exbVersion 和 translatedLocales。根据所选版本，验证组件类型、版本值、声明的依赖项/操作以及区域设置文件。name 必须唯一，且与组件文件夹名称完全一致。编写检查清单与 TypeScript 声明中的可选属性属于不同的检查；两者都要验证。

构建预期产物

• 开发循环： 从安装目录中确定客户端和服务端的启动脚本。验证扩展发现和重新加载行为；添加新文件或文件夹后，如有需要，重启客户端。
• 完整体验： 按照体验部署的说明发布/下载并托管整个应用。已编译的组件目录不是完整体验导出。
• 已编译组件： 检查安装目录中的构建脚本及其引用的构建配置，运行适用的生产构建，并验证实际输出。保留动态导入的 widgets/chunks 以及所需共享代码/代码块的预期相对布局。根据 VERSIONS.md 解决历史命令/输出差异；不要仅凭脚本名称推断输出目录。

部署已在 Enterprise 中注册的组件

仅当目标是此环境时，才针对 doc.arcgis.com 上对应 Enterprise 版本打开添加自定义组件；12.1 仅为示例，并非默认目标。执行此流程前，先确定并验证目标版本的 URL。

1. 确认组件托管位置可匿名访问，且使用 HTTPS 和有效证书。在组件托管服务器上通过 CORS 允许门户来源。验证 .json 以 application/json 格式提供，而不是 HTML 登录/错误页面。
2. 按预期路径部署已编译的组件、动态代码块、共享代码、区域设置文件及其他必需资源。获取清单及依赖资源，然后从门户来源检查浏览器加载情况；仅 HTTP 请求成功并不足够。
3. 请门户管理员注册每个组件的清单 URL，并与约定的受众共享项目。扩展/源代码检出注册不等同于门户注册。分别确认同一组织限制，以及预期的已认证/匿名应用访问权限与匿名代码托管。更改托管、注册或共享设置前，先取得授权。
4. 在所有承诺支持的目标门户中，按照预期受众的访问权限对组件进行冒烟测试。替换现有部署时，验证托管内容更新和缓存行为。

验证更改后的行为

确定并运行安装目录中适用的类型检查、构建和针对性测试脚本；确认这些脚本涵盖受影响的组件。使用组件现有的测试辅助工具；若无法使用，则参照官方单元测试指南进行独立测试。

• 针对与更改相关的情况，测试已配置、未配置、加载中、空和错误状态，包括设置持久化以及受影响的数据/操作契约。
• 对地图组件，测试视图变更和卸载；确认清理了侦听器、高亮、图形、临时图层和过期的异步回调。
• 对持久化架构变更，通过升级路径测试已有的已保存配置。根据兼容性指南和已安装的类型，选择适用于该版本的版本管理器。已保存配置迁移不同于跨运行时兼容性。
• 检查更改后的 UI 是否支持键盘操作、具有无障碍标签、已本地化并适用于窄屏布局。在选定的交付环境中验证构建产物，而不只是开发服务器。

完成标准

报告部署模式、已验证的版本/工具链证据、变更的契约、构件位置，以及适用的构建/测试/运行时/部署检查结果。每个承诺支持的运行时都必须有相应的测试证据。明确列出无法执行的检查和受阻的前置条件；仅通过类型检查或构建，不足以证明兼容性或部署情况。