本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

地址表單 SDK 可簡化建置智慧型地址輸入表單。使用 SDK 建置的地址表單會在使用者開始輸入時提供相關的地址建議。當使用者選取建議時，地址表單會自動填入城市、州和郵遞區號等欄位。這可透過將手動輸入降至最低，減少錯誤並加快資料輸入速度。使用者也可以在地圖上預覽選取的地址，並調整其位置 pin 以指出特定的入口或接收位置，大幅提高準確性。

![顯示自動完成功能的地址表單 SDK 示範](http://docs.aws.amazon.com/zh_tw/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 技術，並可在 Amazon Location Service 主控台中存取，網址為 https：//[https://console.aws.amazon.com/location/](https://console.aws.amazon.com/location/)。此互動式精靈可讓您建立具有預測建議、自動欄位人口和彈性配置的自訂表單。開發人員可以在 React JavaScript、React TypeScript 或獨立 HTML/JavaScript 中下載ready-to-use套件，以便輕鬆整合，而無需撰寫任何程式碼。

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

地址表單 SDK 的主要功能包括：
+ 為地址和 POIs 提供內建預先分類建議，加速資料輸入。
+ 啟用可設定的位置類型搜尋 （例如郵遞區號、地區），以獲得更精確的結果。
+ 提供自動瀏覽器位置偵測，以快速將使用者集中在其目前區域。
+ 顯示內建地圖視覺效果，以提升清晰度和內容。
+ 允許在地圖上調整地址位置，而不會遺失系統提供的位置，以確保準確性和控制。
+ 包含不需要編碼的 WYSIWYG 建置器工具，可節省時間和精力。
+ 實作 typeahead APIs 的解引導和快取，以最佳化效能並降低成本。
+ 支援樣式自訂，以符合應用程式的品牌和使用者體驗。

它使用以下 Amazon Location Service API 操作來提供地址資訊以定址表單：

**[GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html)**  
擷取用於轉譯互動式地圖的地圖圖磚，以視覺化地址的位置並調整地址的位置。

**[自動完成](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html)**  
以使用者類型提供即時地址建議。

**[建議](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)**  
從 Autocomplete 或建議 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 Builder 精靈](https://console.aws.amazon.com/location/solution-builder/home#/address-form)建立具有下列許可的 API 金鑰，或依照下列指示手動建立金鑰。

使用 地址表單 SDK 需要在 API 金鑰政策中允許下列動作：
+ `geo-maps:GetTile` - 顯示地圖元件時需要此項目。請參閱 [GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html) API 參考。
+ `geo-places:Autocomplete` - 對 typeahead 功能使用 `Autocomplete`操作時，這是必要的。請參閱 [Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html) API 參考。
+ `geo-places:Suggest` - 對 typeahead 功能使用 `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` - 使用 typeahead 功能時需要此項目。請參閱 [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 程式碼中包含開發套件的下列 CSS 和 JavaScript 

```
...
<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>
...
```

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

從 npm 安裝 SDK： `npm install @aws/address-form-sdk-js`

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

將下列程式碼新增至您的 React 應用程式。`AMAZON_LOCATION_API_KEY` 使用您的 API 金鑰和建立 API 金鑰`AMAZON_LOCATION_REGION`的區域進行更新。提交表單時，回`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)
+ 紐西蘭 (紐西蘭)
+ 菲律賓 (PH)
+ 新加坡 (SG)
+ 英國 (GB)
+ 美國 (US)

所有其他國家/地區都處於預覽狀態。預覽國家/地區會在`addressLineOne`欄位中顯示完整的地址，而不需要國家/地區特定的格式。未來的版本將改善此行為，您可以使用最新版本的 SDK 來存取這些改進項目。

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

地址表單 SDK 和地址表單建置器精靈可在 Amazon Location Service 運作的所有 AWS 區域使用其 APIs的`Current`版本。檢視 [Amazon Location 支援區域中支援區域](https://docs.aws.amazon.com/location/latest/developerguide/location-regions.html)的完整清單。

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

請參閱 [README API 參考](https://github.com/aws-geospatial/address-form-sdk-js#api-reference)。