@googlemaps/markerclusterer报ClusterIconStyle不存在如何解决

升级@types/google.maps至3.49.2版本、配套使用@googlemaps/markerclusterer@2.0.7时，编译抛出Cannot find name 'ClusterIconStyle'类型错误。原有用于自定义聚合点图标的ClusterIconStyle接口无法找到，原样式配置中的textColor属性也不再被识别。
原有实现代码：

markerClusterIconStyles: ClusterIconStyle[] = [
    {
      textColor: 'white',
      url: 'https://assets.my-folder.com/images/maps/m/m1.png',
      height: 42,
      width: 42,
    },
    {
      textColor: 'white',
      url: 'https://assets.my-folder.com/images/maps/m/m2.png',
      height: 42,
      width: 42,
    }
]

<map-marker-clusterer [zoomOnClick]="true" [gridSize]="20" [styles]="markerClusterIconStyles">
  <!-- 业务标记逻辑 -->
</map-marker-clusterer>

@googlemaps/markerclusterer 2.x版本做了不兼容的API重构，正式移除了旧版本的ClusterIconStyle接口，同时废弃了直接传入样式数组配置聚合图标外观的逻辑，原先在样式数组中配置textColor等文本属性的写法不再被支持。

方案1：补全本地类型声明（改动最小） #

如果暂时不想调整原有业务代码，可以在项目全局类型声明文件（一般为src/typings.d.ts）中手动补全接口定义，绕过TS编译校验：

declare interface ClusterIconStyle {
  url: string;
  height: number;
  width: number;
  textColor?: string;
  textSize?: number;
  backgroundPosition?: string;
  anchor?: [number, number];
  textLineHeight?: number;
  fontFamily?: string;
  fontWeight?: string;
  fontStyle?: string;
}

该方案仅解决编译层报错，如果使用的是Angular Google Maps这类第三方封装库，需要确认对应封装库版本是否适配2.x版本markerclusterer的内部逻辑，否则可能出现运行时样式不生效的问题。

方案2：使用官方自定义Renderer实现样式配置（官方推荐） #

2.x版本开放了Renderer扩展能力，自定义聚合样式不再依赖固定的styles配置项，通过自定义渲染器可以完全控制聚合点的图标、文本样式，实现原有配置的同等效果：

1. 移除模板中硬编码的[styles]绑定
2. 初始化MarkerClusterer时传入自定义renderer配置，参考代码：

import { MarkerClusterer, Renderer } from '@googlemaps/markerclusterer';

const customRenderer: Renderer = {
  render: ({ count, position }) => {
    // 根据聚合数值匹配对应图标
    const iconPath = count < 10 
      ? 'https://assets.my-folder.com/images/maps/m/m1.png'
      : 'https://assets.my-folder.com/images/maps/m/m2.png';
    
    return new google.maps.Marker({
      position,
      icon: {
        url: iconPath,
        scaledSize: new google.maps.Size(42, 42),
      },
      label: {
        text: String(count),
        color: 'white', // 对应旧配置的textColor属性
        fontSize: '14px',
      },
      zIndex: Number(google.maps.Marker.MAX_ZINDEX) + count,
    });
  }
};

// 初始化聚合实例时传入自定义渲染器
const clusterer = new MarkerClusterer({
  map,
  markers,
  renderer: customRenderer,
  gridSize: 20,
  zoomOnClick: true,
});

如果使用的是框架封装的地图组件，需要确认组件是否支持传入自定义renderer配置，暂未适配的场景下可以暂时将@googlemaps/markerclusterer回退至1.x版本，搭配3.48.x及以下版本的@types/google.maps即可正常使用旧版ClusterIconStyle配置。

内容的提问来源于stack exchange，提问作者Raphaël Balet