JSF集成Google Maps加载失败问题求助

问题场景 #

使用JSF的<h:head>、<h:body>等标签开发时，将<div id="map">放在<h:form>标签内，Google Maps无法正常加载，报错：Uncaught (in promise) TypeError: Cannot read properties of null (reading 'appendChild')，且项目必须使用JSF核心标签。

错误原因 #

1. JSF表单自动重写ID：<h:form>会给内部元素自动生成带前缀的客户端ID（比如原map会变成formId:map），但初始化代码里仍用document.getElementById('map')查找元素，自然找不到，返回null导致报错。
2. 脚本执行时机不对：Google Maps的回调函数可能在JSF渲染完表单内元素之前就执行了，此时DOM中还没有map元素，同样会获取到null。

可行解决方案 #

方案1：禁用表单ID重写 #

给<h:form>添加prependId="false"属性，阻止JSF修改内部元素的ID，让map的ID保持不变。

修改后的JSF页面代码：

<!DOCTYPE html>
<html lang="en" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html">
   
    <h:head>
        <meta charset="UTF-8" />
        <meta http-equiv="X-UA-Compatible" content="IE-edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Prueba 01</title>
        <script src="../js/googleMaps.js"></script>
        <link rel="stylesheet" href="../css/style.css"/>
    </h:head>
   
    <h:body>
        <h1>Saludando</h1>
        <!-- 禁用表单ID前缀 -->
        <h:form prependId="false">
            <h:outputLabel>esto es una prueba</h:outputLabel>
            <div id="map"> </div>
        </h:form>
      
        <!-- 修正API URL参数错误，替换成你的密钥 -->
        <script
            src="https://maps.googleapis.com/maps/api/js?v=3&key=你的Google Maps API密钥&callback=initializeGMaps">
        </script>

    </h:body>

</html>

注：原代码的API URL存在格式错误（jsv=3应为v=3，MY_API_KEYkey=A是无效参数），已修正，记得替换成你自己的API密钥。

方案2：获取JSF生成的实际客户端ID #

如果不能禁用表单ID重写（比如页面有多个表单需要区分），可以通过JSF的EL表达式拿到元素的真实客户端ID，再传给初始化代码。

方法2.1：页面内动态传递ID

修改JSF页面，给地图容器添加JSF的id属性，然后用EL获取真实ID：

<h:form>
    <h:outputLabel>esto es una prueba</h:outputLabel>
    <!-- 用h:panelGroup生成带JSF ID的容器 -->
    <h:panelGroup id="map" layout="block" styleClass="map-container" />
</h:form>

<script>
    // 获取地图容器的真实客户端ID
    var mapId = '#{map.clientId}';
    function initializeGMaps(){
        var geocoder = new google.maps.Geocoder();
        var directionsService = new google.maps.DirectionsService();
        var directionsDisplay = new google.maps.DirectionsRenderer({draggable: true});
        
        var latlng = new google.maps.LatLng(37.09023980307208,-4.833984375);
        var map = new google.maps.Map(document.getElementById(mapId), {
            zoom: 4,
            center: latlng,
            mapTypeId: google.maps.MapTypeId.ROADMAP
        });
        directionsDisplay.setMap(map);
    };
</script>
<script src="https://maps.googleapis.com/maps/api/js?v=3&key=你的API密钥&callback=initializeGMaps"></script>

同时修改CSS为类选择器：

.map-container {
  width:650px;
  height:350px;
}

方法2.2：通过类选择器定位元素

不想修改太多代码的话，给地图容器加个类，初始化时用类选择器查找元素：

<h:form>
    <h:outputLabel>esto es una prueba</h:outputLabel>
    <div id="map" class="map-container"> </div>
</h:form>

<script src="../js/googleMaps.js"></script>
<script src="https://maps.googleapis.com/maps/api/js?v=3&key=你的API密钥"></script>
<script>
    // 等DOM完全加载后再初始化
    document.addEventListener('DOMContentLoaded', function() {
        var mapElement = document.querySelector('.map-container');
        // 重新初始化地图
        var latlng = new google.maps.LatLng(37.09023980307208,-4.833984375);
        map = new google.maps.Map(mapElement, {
            zoom: 4,
            center: latlng,
            mapTypeId: google.maps.MapTypeId.ROADMAP
        });
        directionsDisplay.setMap(map);
    });
</script>

方案3：确保脚本在DOM渲染完成后执行 #

把Google Maps的API脚本放在<h:body>最末尾，或者用DOMContentLoaded事件触发初始化，避免在元素未渲染时执行代码。

修改后的页面脚本部分：

<h:body>
    <h1>Saludando</h1>
    <h:form>
        <h:outputLabel>esto es una prueba</h:outputLabel>
        <div id="map"> </div>
    </h:form>

    <script src="../js/googleMaps.js"></script>
    <script src="https://maps.googleapis.com/maps/api/js?v=3&key=你的API密钥"></script>
    <script>
        // 等DOM全部渲染完再调用初始化函数
        document.addEventListener('DOMContentLoaded', initializeGMaps);
    </script>
</h:body>

同时修改googleMaps.js，去掉API的callback参数，改为手动触发：

var geocoder,
directionService,
directionDisplay,
map;

function initializeGMaps(){
   var rendererOptions = {draggable: true};
   geocoder = new google.maps.Geocoder();
   directionsService = new google.maps.DirectionsService();  
   directionsDisplay = new google.maps.DirectionsRenderer(rendererOptions);
        
   var latlng = new google.maps.LatLng(37.09023980307208,-4.833984375);
      
   var myOptions = {
       zoom: 4,
       center: latlng,
       mapTypeId: google.maps.MapTypeId.ROADMAP
   };
   map = new google.maps.Map(document.getElementById('map'), myOptions);
   directionsDisplay.setMap(map);
};

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