README

在Craft中利用Google自动补全API的强大功能。为Craft条目添加自动补全搜索框，允许对API进行地点和地址查询。使用模板获取lat、lng、location和placeid，以填充隐藏的位置字段。

要求

Craft CMS 4.3.0或更高版本。
Google API密钥，已启用Google Maps JavaScript API、地点API和地理编码API。

注意

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

安装

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

打开您的终端并转到您的Craft项目
```
 cd /path/to/project
```
然后告诉Composer加载插件
```
 composer require vaersaagod/locate
```
在控制面板中，转到设置→插件，点击“安装”按钮为Locate，或在命令行中
```
 ./craft plugin/install locate
```
通过控制面板中的插件设置页面配置插件。
您现在可以创建位置字段并将其添加到条目中。

配置

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

配置设置

`googleMapsApiKey`

`apiLanguage`

`apiRegion`

`autocompleteOptions`

自定义自动补全框

自动补全搜索框无需自定义。它默认为全球所有地点类型（城市、地址、企业等）。默认情况下，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);

价格、许可证和支持

该插件采用 MIT 许可证发布。它是为 Værsågod 和朋友们制作的，不提供支持。提交的问题如果能够解决痒点，则会得到解决。

变更日志

请参阅 CHANGELOG.MD。

鸣谢

由 Værsågod 提供

vaersaagod / locate

维护者

详情

README

要求

注意

安装

配置

配置设置

`googleMapsApiKey`

`apiLanguage`

`apiRegion`

`autocompleteOptions`

自定义自动补全框

限制搜索地点类型

示例用法

向地理区域倾斜搜索

示例用法

按国家限制搜索

示例用法

整合以上内容

使用位置字段

模板示例

价格、许可证和支持

变更日志

鸣谢