@aws/address-form-sdk-js

亚马逊地址表 SDK

地址表SDK简化了自动填充地址表的开发. 当用户输入他们的地址时,表格会显示相关的建议. 选择一个建议将包含随后的字段,包括街道、城市、州和邮政编码。 这个智能特性通过去除手动打字来减少出错并节省时间. 用户可以在地图上预览所选地址并调整位置指针.

开始

地址表SDK可以在React App内部使用,也可以在独立的HTML和JavaScript页面中使用. 从下面的指令开始, 或使用我们控制台的一步向导来配置地址表单 .

先决条件

您需要 API 密钥, 允许您调用以下动作 。 跟随 用于创建 API 密钥的此指南。 。 。 .

使用地址表需要您的 API 密钥允许以下动作 :

安装

反应

通过运行在您的 React app 中安装 SDK : npm install @aws/address-form-sdk-js

HTML/贾瓦脚本

在您的 HTML 代码中包含以下 SDK 的 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>
...

使用 SDK

在您的 React app 中执行以下代码 。 替换 AMAZON_LOCATION_API_KEY 使用您的 API 密钥值以及 AMAZON_LOCATION_REGION 与 API 键的区域.

反应

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 data-type="address-form" type="submit">
              Submit
            </button>
            <button data-type="address-form" type="reset">
              Reset
            </button>
          </Flex>
        </Flex>
        <AddressForm.Map mapStyle={["Standard", "Light"]} />
      </Flex>
    </AddressForm>
  );
}

HTML/贾瓦脚本

<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="aws-address-form aws-flex-row aws-flex-1">
      <div class="aws-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="aws-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 src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"></script>
    <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>

自定义

表格是完全自定义的 - 添加、去除或重排您使用时所需的元素 。 替换 Flex 使用您的 CSS 框架或自定义样式的组件。 您可以通过组件道具/属性控制地址表的其他功能. 见 API 参考 用于完整的定制选项.

支助国

地址表SDK支持通过亚马逊定位服务在全世界自动填充地址. 下列国家完全支持对地址进行实地分析,将每个地址部分纳入各自的领域:

• 澳大利亚
• 加拿大
• 法国
• 香港
• 爱尔兰
• 新西兰
• 菲律宾
• 新加坡
• 联合王国
• 美国

其他国家处于预览阶段,其中 addressLineOne 字段显示完整的地址,而不只是街道地址部分。 未来发行会改善这种行为.

API 参考

地址格式

反应 : 将地址窗体功能包起来的主要组件. <AddressForm>

HTML/贾瓦脚本 : 在页面上渲染地址表的功能 AddressForm.render({ ... })

道具

表格提交数据

提交表格时 onSubmit 回调收到一个 getData async 函数。 用一个 intendedUse 获取窗体数据的参数 :

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

重要内容: 使用 "Storage" 如果你打算存储或缓存结果。 这确保遵守亚马逊定位服务 预定用途要求。 。 。 .

返回的数据对象包含下列属性:

说明: 这个 addressDetails 属性包含 Amazon Location Service 的完整 API 响应,并且仅在地址通过我们的 API 地址( 类型头选择或定位按钮) 被覆盖时才存在. 用户手动输入的地址不会包含此属性 .

窗体输入字段

所有输入字段都使用 data-type="address-form" 属性与a name= 属性。 支持以下共同属性:

常见输入属性

地址行 1 (name="addressLineOne"(中文(简体) )

带有自动填充功能的主地址输入 。 见 支助国 用于了解不同国家的地址域分析行为.

其他输入字段

• 地址行2 (单位:千美元)name="addressLineTwo":默认标签"地址2号线",占位符"公寓,套房等"
• 城市 (单位:千美元)name="city": 默认标签"City"
• 省/州 (单位:千美元)name="province": 默认标签"省/州"
• 邮政编码 (单位:千美元)name="postalCode": 默认标签"邮政/Zip代码"
• 国家 (单位:千美元)name="country": 默认标签"国家"

窗体按钮

提交按钮

<button data-type="address-form" type="submit">Submit</button>

重置按钮

<button data-type="address-form" type="reset">Reset</button>

地址论坛. 地图

用于显示和调整地址位置的地图组件.

反应 : 用于显示和调整地址位置的地图组件. <AddressForm.Map mapStyle={...}>

HTML/贾瓦脚本 : 用于显示和调整地址位置的地图元素.<div data-type="address-form" data-map-style="...">

道具

映射样式选项

地图样式由两部分组成: 地图样式名称 编辑 颜色方案. 地图样式名称决定了视觉主题(标准、单色、混合或卫星),而色彩方案则在适用的情况下指定了亮度变体(光或暗).

每种地图样式和颜色图案的详细说明见 AWS 地图样式和定制。 。 。 .

捐款

我们欢迎社区的贡献并征求他们的意见。 见 捐款 关于如何建立开发环境的信息,并提交代码.

警卫

见 捐款 更多信息.

许可证

这个项目根据Apache-2.0许可证获得许可证.