本文详解如何通过 componentRestrictions 选项精准限制 Google Maps Places Autocomplete 的搜索范围至单一国家（如多米尼加共和国），并提供原生 JavaScript 和 React 双版本可运行代码，涵盖初始化、事件监听与常见坑点说明。

本文详解如何通过 componentrestrictions 选项精准限制 google maps places autocomplete 的搜索范围至单一国家（如多米尼加共和国），并提供原生 javascript 和 react 双版本可运行代码，涵盖初始化、事件监听与常见坑点说明。

Google Maps JavaScript API 的 Places Autocomplete 功能默认在全球范围内提供地址建议，但实际业务中常需限定地理范围（例如仅支持某国用户输入）。核心解决方案是使用 componentRestrictions 配置项，配合正确的国家代码（ISO 3166-1 alpha-2 格式）实现强制地域过滤。

✅ 关键要点：

google-sheets-soha

读取并分析Google表格数据。当用户提到“Google表格”、“电子表格”、“表格”，或发送 docs.google.com/spreadsheets 链接时触发。

下载

• 国家代码必须为小写双字母格式，多米尼加共和国的正确代码是 'do'（非 'DOM' 或 'DR'）；
• componentRestrictions 仅对 geocode、(cities)、(regions) 等地理类型生效，不适用于 establishment 等商业类型；
• 若同时设置 types: ['(cities)', 'geocode']，部分地址可能因类型匹配模糊而绕过国家限制——推荐明确指定单一类型（如仅 'cities'），以提升过滤可靠性。

以下是两种主流使用场景的完整实现：

✅ 原生 JavaScript（HTML + CDN）

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <title>DOM Autocomplete</title>
  <!-- 替换 YOUR_GOOGLE_MAPS_API_KEY 为你的有效密钥 -->
  <script 
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_MAPS_API_KEY&libraries=places&callback=initAutocomplete" 
    async 
    defer
  ></script>
  <style>
    .container { max-width: 400px; margin: 2rem auto; padding: 0 1rem; }
    #autocomplete {
      width: 100%;
      padding: 10px;
      font-size: 16px;
      border: 1px solid #ccc;
      border-radius: 4px;
    }
  </style>
</head>
<body>
  <div class="container">
    <h2>? 多米尼加共和国专属搜索</h2>
    <input id="autocomplete" type="text" placeholder="输入城市名（如 Santo Domingo）..." />
  </div>

  <script>
    let autocomplete;

    function initAutocomplete() {
      const input = document.getElementById('autocomplete');

      // 严格限定：仅返回多米尼加共和国的城市建议
      autocomplete = new google.maps.places.Autocomplete(input, {
        types: ['(cities)'], // 推荐仅用 '(cities)' 提升过滤精度
        componentRestrictions: { country: 'do' }
      });

      autocomplete.addListener('place_changed', () => {
        const place = autocomplete.getPlace();
        if (place.geometry && place.address_components) {
          console.log('✅ 有效选择：', place.formatted_address);
          // 示例：提取城市名和行政区
          const city = place.address_components.find(c => c.types.includes('locality'))?.long_name || '';
          const region = place.address_components.find(c => c.types.includes('administrative_area_level_1'))?.long_name || '';
          console.log(`城市：${city}，省份：${region}`);
        } else {
          console.warn('⚠️ 未获取到有效地理位置，请检查输入');
        }
      });
    }
  </script>
</body>
</html>

✅ React 函数组件（Hooks 实现）

import React, { useEffect, useRef } from 'react';

export function DominicanAutocomplete() {
  const inputRef = useRef<HTMLInputElement>(null);
  const autocompleteRef = useRef<google.maps.places.Autocomplete | null>(null);

  useEffect(() => {
    // 确保 Google Maps API 已加载
    if (!window.google || !window.google.maps || !window.google.maps.places) {
      console.error('❌ Google Maps Places library not loaded');
      return;
    }

    if (inputRef.current) {
      autocompleteRef.current = new window.google.maps.places.Autocomplete(
        inputRef.current,
        {
          types: ['(cities)'], // 关键：避免混合类型干扰过滤
          componentRestrictions: { country: 'do' }
        }
      );

      autocompleteRef.current.addListener('place_changed', () => {
        const place = autocompleteRef.current?.getPlace();
        if (place?.geometry?.location) {
          console.log('? 选中地点：', {
            name: place.name,
            address: place.formatted_address,
            lat: place.geometry.location.lat(),
            lng: place.geometry.location.lng()
          });
        } else {
          console.log('? 未返回有效地理坐标');
        }
      });
    }

    // 清理：销毁实例防止内存泄漏
    return () => {
      if (autocompleteRef.current) {
        // 注意：Autocomplete 实例无显式 destroy 方法，但移除监听器是良好实践
        google.maps.event.clearInstanceListeners(autocompleteRef.current);
      }
    };
  }, []);

  return (
    <div style={{ maxWidth: '400px', margin: '2rem auto', padding: '0 1rem' }}>
      <h2>? 多米尼加共和国城市搜索</h2>
      <input
        ref={inputRef}
        type="text"
        placeholder="例如：Santiago de los Caballeros..."
        style={{
          width: '100%',
          padding: '10px',
          fontSize: '16px',
          border: '1px solid #ddd',
          borderRadius: '4px'
        }}
      />
    </div>
  );
}

⚠️ 注意事项与调试建议

• API 密钥权限：确保在 Google Cloud Console 中已启用 Maps JavaScript API 和 Places API，并为密钥配置了 HTTP 引用白名单（如 localhost 或你的域名）；
• 延迟加载风险：若 initAutocomplete 在 google.maps 未就绪时调用，会报错。React 中建议加 if (window.google...) 守卫；HTML 中依赖 callback=initAutocomplete 参数确保异步加载完成后再执行；
• 类型冲突问题：避免使用 types: ['(cities)', 'geocode'] —— 混合类型可能导致部分 geocode 结果忽略 componentRestrictions。如需地址级搜索，可改用 types: ['address'] 并仍保留 country: 'do'，但需测试实际效果；
• 移动端适配：添加 viewport meta 标签，并在 CSS 中为 <input> 设置 width: 100% 以保证响应式体验。

通过以上配置，你的搜索框将稳定、可靠地只返回多米尼加共和国境内的城市或地址建议，显著提升用户体验与数据准确性。