本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 地址表单 SDK
<a name="address-form-sdk"></a>

地址表单 SDK 简化了智能地址输入表单的构建。当用户开始键入内容时，使用 SDK 构建的地址表单会提供相关的地址建议。当用户选择建议时，地址表单会自动填写城市、州和邮政编码等字段。这样可以最大限度地减少手动输入，从而减少错误并加快数据输入速度。用户还可以在地图上预览所选地址，并调整其位置图钉以指示特定的入口或上车地点，从而显著提高准确性。

![显示自动完成功能的地址表单 SDK 演示](http://docs.aws.amazon.com/zh_cn/location/latest/developerguide/images/address-form-demo.gif)


## 试试看
<a name="address-form-try-it"></a>

### 演示
<a name="address-form-demo"></a>

试试功能齐全[的地址表演示](https://aws-geospatial.github.io/address-form-sdk-js/)。

### 自己动手
<a name="address-form-builder"></a>

跳转[开始使用](#address-form-getting-started)到开始使用地址表单 SDK 实现地址表单，或者使用 Location Service 的 WYSIWYG [地址表单生成器向导尝试无代码方法，该向导](https://console.aws.amazon.com/location/solution-builder/home#/address-form)由此 SDK 提供支持，可在亚马逊定位服务控制台中访问，网址为。[https://console.aws.amazon.com/location/](https://console.aws.amazon.com/location/)此交互式向导允许您创建带有预测性建议、自动字段填充和灵活布局的自定义表单。开发人员可以下载 React JavaScript TypeScript、React 或独立版本 HTML/JavaScript 的 ready-to-use软件包，无需编写任何代码即可轻松集成。

## 主要功能
<a name="address-form-features"></a>

地址表 SDK 的主要功能包括：
+ 为地址提供内置的预输入建议 POIs，并加快数据输入速度。
+ 启用可配置的地点类型搜索（例如邮政编码、地点），以获得更精确的结果。
+ 提供自动浏览器位置检测，让用户快速集中在当前区域。
+ 显示内置的地图可视化效果以提高清晰度和背景信息。
+ 允许在不丢失系统提供的位置的情况下调整地图上的地址位置，从而确保准确性和可控性。
+ 包括无需编码的 WYSIWYG 生成器工具，可节省时间和精力。
+ 为预输入实现去抖和缓存， APIs 以优化性能并降低成本。
+ 支持自定义样式，以匹配应用程序的品牌和用户体验。

它使用以下 Amazon Location Service API 操作来提供地址信息来填写表格：

**[GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html)**  
检索用于渲染交互式地图的地图块，以可视化地址的位置并调整地址的位置。

**[Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html)**  
在用户键入时提供实时地址建议。

**[Suggest](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Suggest.html)**  
在用户键入时提供实时地址和 POI 建议。

**[ReverseGeocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_ReverseGeocode.html)**  
如果用户选择根据当前位置自动填写地址，则将用户的当前位置转换为最近的已知地址地址。

**[GetPlace](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html)**  
从 “自动补全” 或 “建议” API 的结果中选择地址后，检索所选地址的详细地点信息。

## 定价
<a name="address-form-pricing"></a>

该软件开发工具[包在 Apache-2.0 许可下是免费和开源](https://github.com/aws-geospatial/address-form-sdk-js)的。您只需为 API 的使用付费。请查阅 [Amazon Location Service 定价页面](https://aws.amazon.com/location/pricing/)。

## 开始使用
<a name="address-form-getting-started"></a>

地址表单 SDK 可以在 React 应用程序中使用，也可以在独立的 HTML 和 JavaScript 页面中使用。请按照以下说明开始操作。

### 先决条件
<a name="address-form-prerequisites"></a>

**注意**  
地址表单 SDK 需要具有所需权限的 API 密钥才能正常工作。使用 Amazon Location Service 控制台中的[地址表单 SDK 生成器向导](https://console.aws.amazon.com/location/solution-builder/home#/address-form)创建具有以下权限的 API 密钥，或者按照以下说明手动创建 API 密钥。

使用地址表单 SDK 需要在 API 密钥策略中允许执行以下操作：
+ `geo-maps:GetTile`-这在显示地图组件时是必需的。请参阅 [GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html)API 参考文档。
+ `geo-places:Autocomplete`-使用该`Autocomplete`操作实现预输入功能时必须这样做。请参阅[自动补全](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html) API 参考。
+ `geo-places:Suggest`-使用该`Suggest`操作实现预输入功能时必须这样做。请参阅[建议](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Suggest.html) API 参考。
+ `geo-places:ReverseGeocode`-当允许用户使用浏览器的地理定位 API 提供其当前位置时，这是必需的。请参阅 [ReverseGeocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_ReverseGeocode.html)API 参考文档。
+ `geo-places:GetPlace`-使用预输入功能时，这是必需的。请参阅 [GetPlace](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html)API 参考文档。

按照[使用 API 密钥进行身份验证](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html)指南创建具有必要权限的 Amazon Location Service API 密钥。

具有所需权限的 [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html)API 的密钥策略示例：

#### CreateKey 申请地址表权限
<a name="createkey-example"></a>

```
{
  "KeyName": "ExampleKey",
  "ExpireTime": "YYYY-MM-DDThh:mm:ss.sss",
  "Restrictions": {
    "AllowActions": [
      "geo-maps:GetTile",
      "geo-places:Autocomplete",
      "geo-places:Suggest",
      "geo-places:GetPlace",
      "geo-places:ReverseGeocode"
    ],
    "AllowResources": [
      "arn:aws:geo-maps:<Region>::provider/default",
      "arn:aws:geo-places:<Region>::provider/default"
    ]
  }
}
```

### 安装
<a name="address-form-installation"></a>

#### HTML/ JavaScript
<a name="address-form-html-js-install"></a>

在你的 HTML 代码中加入 JavaScript 以下 CSS 和 SDK 的内容

```
...
<head>
...
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
/>
...
</head>
...
<body>
...
<script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"></script>
</body>
...
```

#### React
<a name="address-form-react-install"></a>

从 npm 安装软件开发工具包：`npm install @aws/address-form-sdk-js`

### 使用 SDK
<a name="address-form-use-sdk"></a>

将以下代码添加到你的 React 应用程序中。`AMAZON_LOCATION_API_KEY`使用您的 API 密钥`AMAZON_LOCATION_REGION`和创建 API 密钥的区域进行更新。提交表单时，`onSubmit`回调函数会提供一个`getData`异步函数。使用`intendedUse`值调用此函数以检索表单数据。

```
onSubmit: async (getData) => {
  const data = await getData({
    intendedUse: "SingleUse", // or "Storage"
  });
};
```

**注意**  
`"Storage"`如果您需要存储或缓存结果，请使用。这样可以确保遵守亚马逊定位服务（Amazon Location Service）的[预期使用要求](https://docs.aws.amazon.com/location/latest/developerguide/places-intended-use.html)。

------
#### [ HTML/JavaScript ]

```
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Address Form</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
    />
  </head>
  <body>
    <form
      id="amazon-location-address-form"
      class="address-form flex-row flex-1"
    >
      <div class="flex-column">
        <input
          data-type="address-form"
          name="addressLineOne"
          data-api-name="suggest"
          data-show-current-location="true"
        />
        <input data-type="address-form" name="addressLineTwo" />
        <input data-type="address-form" name="city" />
        <input data-type="address-form" name="province" />
        <input data-type="address-form" name="postalCode" />
        <input data-type="address-form" name="country" />
        <div class="flex-row">
          <button data-type="address-form" type="submit">Submit</button>
          <button data-type="address-form" type="reset">Reset</button>
        </div>
      </div>
      <div data-type="address-form" data-map-style="Standard,Light"></div>
    </form>
    <></script>
script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"
    <script>
      AddressFormSDK.render({
        root: "#amazon-location-address-form",
        apiKey: "AMAZON_LOCATION_API_KEY",
        region: "AMAZON_LOCATION_REGION",
        showCurrentCountryResultsOnly: true,
        onSubmit: async (getData) => {
          // Get form data with intendedUse parameter
          // Use "SingleUse" for one-time display only
          // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
          const data = await getData({ intendedUse: "SingleUse" });
          console.log(data);
        },
      });
    </script>
  </body>
</html>
```

------
#### [ React ]

```
import React from 'react';
import { AddressForm, Flex } from "@aws/address-form-sdk-js";

export default function App() {
  return (
    <AddressForm
      apiKey="AMAZON_LOCATION_API_KEY"
      region="AMAZON_LOCATION_REGION"
      onSubmit={async (getData) => {
        // Get form data with intendedUse parameter
        // Use "SingleUse" for one-time display only
        // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
        const data = await getData({ intendedUse: "SingleUse" });
        console.log(data);
      }}
    >
      <Flex
        direction="row"
        flex
      >
        <Flex direction="column">
          <input
            data-api-name="autocomplete"
            data-type="address-form"
            name="addressLineOne"
            placeholder="Enter address"
          />
          <input
            data-type="address-form"
            name="addressLineTwo"
          />
          <input
            data-type="address-form"
            name="city"
            placeholder="City"
          />
          <input
            data-type="address-form"
            name="province"
            placeholder="State/Province"
          />
          <input
            data-type="address-form"
            name="postalCode"
          />
          <input
            data-type="address-form"
            name="country"
            placeholder="Country"
          />
          <Flex direction="row">
            <button address-form="submit">
              Submit
            </button>
            <button address-form="reset">
              Reset
            </button>
          </Flex>
        </Flex>
        <AddressFormMap
          mapStyle={[
            'Standard',
            'Light'
          ]}
         />
      </Flex>
    </AddressForm>
  );
}
```

------

## 支持的国家/地区
<a name="address-form-supported-countries"></a>

地址表单 SDK 支持使用 Amazon Location Service 在全球范围内自动填写地址。以下国家/地区完全支持地址字段解析，即每个地址组成部分都填充到各自的字段中：
+ 澳大利亚（AU）
+ 加拿大 (CA)
+ 法国（FR）
+ 中国香港（HK）
+ 爱尔兰（IE）
+ 新西兰（NZ）
+ 菲律宾（PH）
+ 新加坡（SG）
+ 英国（GB）
+ 美国（US）

所有其他国家/地区均处于预览状态。预览国家/地区在`addressLineOne`字段中显示完整的地址，不使用特定国家/地区的格式。未来的版本将改善这种行为，您可以使用最新版本的 SDK 来访问这些改进。

## 支持的 AWS 区域
<a name="address-form-supported-aws-regions"></a>

地址表单软件开发工具包和地址表单生成器向导可在运营Amazon Location Service的所有 AWS 地区使用，使用其`Current`版本 APIs。查看 [Amazon Location 支持区域中支持的区域](https://docs.aws.amazon.com/location/latest/developerguide/location-regions.html)的完整列表。

## API 参考
<a name="address-form-api-reference"></a>

请参阅[自述文件 API 参考](https://github.com/aws-geospatial/address-form-sdk-js#api-reference)。