README

在Craft中利用Google自动补全API的力量。为Craft条目添加自动补全搜索框，允许对API进行地点和地址查询。使用lat、lng、location和placeid填充隐藏的Location字段，您可以在模板中获取这些信息以进行其他操作。

要求

• Craft CMS 3.0.0-beta.23或更高版本。
• Google API密钥，并启用Google Maps JavaScript API和Google Places API Web Service。

注意

Google已更新其API访问策略。请参阅https://cloud.google.com/maps-platform/user-guide/

安装

要安装插件，请按照以下说明操作。

1. 打开您的终端并转到您的Craft项目

    cd /path/to/project
   

2. 然后让Composer加载插件

    composer require swixpop/locate
   

3. 在控制面板中，转到设置→插件，并点击Locate的“安装”按钮，或从命令行进行

    ./craft install/plugin locate
   

4. 通过控制面板中的插件设置页面配置插件。

5. 您现在可以创建Location字段并将它们添加到您的条目中。

配置

转到设置 > 插件 > Locate。如果您已经有了，请输入您的Google API密钥；否则，请在此处获取。设置页面还允许您自定义自动补全框的行为。

自定义自动补全框

自动补全搜索框无需自定义。默认情况下，它适用于世界上所有地点类型（城市、地址、企业等）。默认情况下，API将尝试从用户的IP地址检测用户的位置，并将结果偏重于该位置。

但是，通过传递一些基本选项，可以实现高级筛选。您可以通过传递一个选项的JSON对象来修改默认行为。有关允许选项的完整列表，请参阅Google官方文档。

这些选项可以全局设置或按字段设置。单个字段的设置将覆盖全局选项。

选项对象必须格式正确，否则插件将抛出JavaScript错误！如果在阅读本文档后您对在选项框中输入什么不清楚，请将其保留为空白。

限制搜索地点类型

您可以指定一个types数组来限制自动补全框返回的结果。通常只允许一个类型。可能的值包括

• geocode
• address
• establishment
• (regions)
• (cities)

有关使用这些types如何限制您结果的详细信息，请参阅官方文档。

示例用法

限制结果到城市

"types": ["(cities)"]

限制结果到商业企业

"types": ["establishment"]

偏重于特定地理位置的搜索

您可以使用 bounds 属性来指定一个 google.maps.LatLngBoundsLiteral，并使搜索结果偏向于一个地理区域。这是一个指定 north（北）、east（东）、south（南）和 west（西）值的对象。自动完成框返回的结果将偏向于，但不仅限于，您指定的区域。

有关完整详情，请参阅LatLngBoundsLiteral 对象规范。

请注意，这些值是以 数字 而不是 字符串 的形式输入的。

示例用法

使搜索结果偏向于太平洋西北地区

"bounds": {
  "north": 50,
  "east": -122,
  "south": 48,
  "west": -123
}

按国家限制搜索

您可以使用 componentRestrictions 属性将结果限制为单个国家。国家必须以两个字符的、与 ISO 3166-1 Alpha-2 兼容的国家代码传递。

示例用法

将结果限制为加拿大

"componentRestrictions": {
  "country": "ca"
}

综合运用

使用上述示例，我们可以创建一个选项对象，将搜索限制在加拿大，最好是太平洋西北地区的商业机构（例如，位于温哥华的星巴克）。

"types": ["establishment"],
"bounds": {
  "north": 50,
  "east": -122,
  "south": 48,
  "west": -123
},
"componentRestrictions": {
  "country": "ca"
}

使用位置字段

位置字段返回 locationData、lat、lng、location 和 placeid。您可以在模板中使用这些信息并将其传递给 JavaScript。

• locationData 返回 Google API 的完整响应，并包含一个额外的 components 数组，该数组将 address_components 映射到具有组件类型作为键的数组。有关一些类型的列表，请参阅此处。（例如，您可以在 twig 中访问 locationData.components.country。您还可以将 _short 添加到任何组件键中，以访问该地址组件的 short_name，例如 locationData.components.country_short）。
• lat 返回地点的纬度
• lng 返回地点的经度
• location 返回自动完成查询
• placeid 返回一个文本标识符，该标识符唯一标识一个地点

您可以使用 placeid 来向 Google Maps API 发送额外的请求。使用 placeid，您可以发送地点详情请求来获取地址、电话号码、评论等信息。您还可以使用 placeid 来生成地图标记。有关如何使用 使用地点 ID 引用地点 的更多信息。

模板示例

使用上一节中的选项限制，我们可以在自动完成框中搜索 "Lucky's Donuts"。

<div class="yummy" data-place-id="{{ entry.myLocationFieldHandle.placeid }}" data-lat="{{ entry.myLocationFieldHandle.lat }}" data-lng="{{ entry.myLocationFieldHangle.lng }}">
  <span>You searched for: {{ entry.myLocationFieldHandle.location }}</span>
</div>

将生成以下内容

<div class="yummy" data-place-id="ChIJ0drOuuNzhlQRB8PCozmcz_4" data-lat="49.25915390000001" data-lng="-123.10084899999998">
  <span>You searched for: Lucky's Doughnuts, Main Street, Vancouver, BC, Canada</span>
</div>

然后，您可以通过加载 Google Maps JavaScript API 并在 JavaScript 中获取 placeid、lat 和 lng 来生成一个简单的地图

<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

var map,
    myLat = $('.yummy').attr('data-lat'),
    myLng = $('.yummy').attr('data-lng'),
    myPlaceId = $('.yummy').attr('data-place-id');

function initialize() {
  // Create a map centered at your location.
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: myLat, lng: myLng},
    zoom: 15
  });

  var myLatLng = new google.maps.LatLng({lat: myLat, lng: myLng});

  var marker = new google.maps.Marker({
    map: map,
    place: {
      placeId: myPlaceId,
      location: myLatLng
    }
  });
}

google.maps.event.addDomListener(window, 'load', initialize);

由 Isaac Gray 提供