Declaration merging失效：无法访问ArcGIS Map未声明的itemInfo属性

我之前也碰到过一模一样的情况！ArcGIS JS API的官方TypeScript声明偶尔会漏掉一些实际运行时存在的属性，尤其是像itemInfo这种只有当Map从Portal Item加载时才会有的属性。下面给你几种靠谱的解决办法：

1. 快速临时方案：类型断言 #

如果已经确认itemInfo在运行时肯定存在，最快的解决方式就是用类型断言绕过TypeScript的检查。你可以用any，也可以定义更精确的类型来保留部分类型提示：

import Map = require("esri/map");

private static obtainMapLayers(map: Map) {
  // 最简单的方式：用any断言
  let info = (map as any).itemInfo;

  // 更精确的方式：扩展Map类型
  interface MapWithItemInfo extends Map {
    // 如果知道itemInfo的具体类型，可以替换成对应的类型，比如esri/portal/Item
    itemInfo: any;
  }
  let preciseInfo = (map as MapWithItemInfo).itemInfo;
}

这种方式的优点是快，缺点是会丢失部分类型检查，适合临时调试或者已经明确属性结构的场景。

2. 根本解决：正确的声明合并 #

你之前尝试声明合并没成功，大概率是因为声明的位置或者方式不对。要确保你的扩展声明和原esri/map模块的声明在同一个命名空间下：

// 首先扩展esri/map模块的Map类型
declare module "esri/map" {
  import ItemInfo = require("esri/portal/ItemInfo"); // 如果有对应的类型，先导入

  interface Map {
    // 替换成实际的类型，不要用any（如果能找到的话）
    itemInfo: ItemInfo;
  }
}

// 然后在你的业务代码里正常使用
import Map = require("esri/map");

private static obtainMapLayers(map: Map) {
  let info = map.itemInfo; // 现在TypeScript不会报错了！
}

注意：如果你的代码是在一个模块中（包含import/export），这个扩展声明必须放在同一个模块里，或者确保它能被TypeScript正确识别到。另外，一定要确认你导入的类型和实际运行时的itemInfo结构匹配。

3. 检查版本匹配问题 #

有时候这种问题是因为你安装的@types/arcgis-js-api版本和实际使用的ArcGIS JS API版本不匹配导致的。比如你用的是4.25版本的JS API，但@types包是4.20的，就可能出现属性缺失的情况。去package.json里检查一下版本号，确保两者对应。

内容的提问来源于stack exchange，提问作者Jerry