正确传递 Leaflet 地图实例给子组件的实践指南

，这使其始终指向 DOM 容器节点——而 L.marker(…).addTo(map) 等所有 Leaflet 方法要求的 map 参数，必须是 L.map(domNode) 返回的 JavaScript 对象，而非原始 DOM 元素。

例如，以下代码看似合理，实则存在根本性类型错误：

// ❌ 错误：mapRef.current 是 DOM 元素，不是 L.Map 实例 const map = props.mapRef.current; // e.g., 
 L.marker([51.6, -0.09]).addTo(map); // TypeError: map.addLayer is not a function

这是因为 L.marker().addTo() 内部会调用 map.addLayer()，而原生 DOM 元素没有该方法；只有 L.map() 返回的地图实例才具备完整的 Leaflet API。

✅ 正确做法是：分离职责，用两个独立的 useRef 分别管理 DOM 容器与地图实例对象：

• mapContainerRef: 指向
  容器（用于 L.map() 初始化）；

• mapObjectRef: 存储 L.map(…) 返回的地图实例（供子组件安全调用）。

以下是重构后的完整示例：

// Map.jsx import L from 'leaflet'; import 'leaflet/dist/leaflet.css'; import { useEffect, useRef } from 'react'; import DrawFToolbar from './DrawFToolbar';  function Map() {   const mapContainerRef = useRef(null); // ? DOM 容器引用   const mapObjectRef = useRef(null);     // ? Leaflet 地图实例引用    useEffect(() => {     if (!mapContainerRef.current) return;      // ✅ 创建地图实例，并存入 mapObjectRef     const map = L.map(mapContainerRef.current).setView([51.505, -0.09], 13);     mapObjectRef.current = map;      // 添加底图     L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {       attribution: '© OpenStreetMap contributors',       maxZoom: 18,     }).addTo(map);      // 清理：卸载地图实例     return () => {       if (map && !map._container) return; // 防止重复移除       map.remove();     };   }, []);    return (     
       {mapObjectRef.current && }     
   ); }  export default Map;

// DrawFToolbar.jsx import { useEffect } from 'react'; import L from 'leaflet';  function DrawFToolbar({ mapRef }) {   useEffect(() => {     const map = mapRef.current;     if (!map) return;      console.log('✅ DrawFToolbar 已获取有效 L.Map 实例:', map);      // ✅ 现在可安全调用所有 Leaflet 方法     const marker = L.marker([51.6, -0.09])       .bindPopup('这是一个通过子组件添加的标记')       .addTo(map);      // 示例：后续也可执行 map.removeLayer(marker) 或 map.fitBounds(...)      // ⚠️ 注意：若需在组件卸载时清理图层，请在此处保存引用并返回清理函数     return () => {       if (marker && map.hasLayer(marker)) {         map.removeLayer(marker);       }     };   }, [mapRef]);    return null; }  export default DrawFToolbar;

? 关键注意事项：

• 永远不要对 ref.current 做类型假设：useRef(null) 初始值为 null，且其内容由你手动赋值；务必在使用前校验 if (mapRef.current)。
• 避免内存泄漏：在 useEffect 清理函数中显式调用 map.remove()（主组件）或 map.removeLayer()（子组件），尤其当图层动态增删时。
• 不推荐通过 props 传递地图实例：虽然可行，但易引发不必要的重渲染；使用 useRef 共享实例更符合 React + Leaflet 的最佳实践。
• 扩展性提示：若需支持多个地图或异步加载场景，可将 mapObjectRef 封装为自定义 Hook（如 useLeafletMap），进一步提升复用性。

遵循上述模式，即可彻底规避 map.xxx is not a function 类型错误，构建稳定、可维护的 Leaflet + React 地图应用架构。