# @aws/address-form-sdk-js 中文文档

规范地址：https://npmcn.com/package/%40aws/address-form-sdk-js/

版本：1\.6\.1
npm 元数据更新时间：2026-11-06T17:20:53.727Z
中文译文更新时间：2026-11-07T15:31:16.954Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws/address-form-sdk-js
原文对照：https://npmcn.com/package/%40aws/address-form-sdk-js/?lang=original
项目主页：https://github.com/aws-geospatial/address-form-sdk-js#readme
源码仓库：https://github.com/aws-geospatial/address-form-sdk-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.6 MB，61 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0
- 首次发布：2025-11-03T23:13:18.241Z
- 最新版本发布：2026-11-06T17:20:53.269Z
- 近 30 天下载量：7708（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 9 个）

## 中文简介

Javascript 的地址表 SDK

## 安装

```sh
npm install @aws/address-form-sdk-js
```

也可以使用：`pnpm add @aws/address-form-sdk-js`、`yarn add @aws/address-form-sdk-js`、`bun add @aws/address-form-sdk-js`

## README

## 亚马逊地址表 SDK

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

## 开始

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

### 先决条件

您需要 API 密钥, 允许您调用以下动作 。 跟随 [用于创建 API 密钥的此指南](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html)。 。 。 .

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

| 行动 | 目的 | 需要时间 |
| --- | --- | --- |
| `GetTile` | 获取用于渲染交互式地图的地图牌 | 显示映射组件 |
| `Autocomplete` | 作为用户类型提供实时地址建议 | 使用自动完整 API 键入头功能 |
| `Suggest` | 作为用户类型提供实时地址建议 | 在打字头功能中使用建议 API |
| `ReverseGeocode` | 将坐标转换为地址 | 允许用户使用当前位置 |
| `GetPlace` | 获取选定地址的详细位置信息 | 使用打字头功能 |

### 安装

#### 反应

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

#### HTML/贾瓦脚本

在您的 HTML 代码中包含以下 SDK 的 CSS 和 JavaScript

```html
...
<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 键的区域.

#### 反应

```jsx
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
<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 参考](https://npmcn.com/package/%40aws/address-form-sdk-js/#readme-api-reference) 用于完整的定制选项.

### 支助国

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

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

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

## API 参考

### 地址格式

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

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

#### 道具

| 财产 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `apiKey` | `string` | 对 | \- 说吧 | 亚马逊定位服务 API 密钥用于认证请求. |
| `region` | `string` | 对 | \- 说吧 | 亚马逊定位服务所在的AWS区域(例如"us-east-1") |
| `language` | `string` | 没有 | \- 说吧 | [语言代码](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) 用于本地地址建议(例如“en”、“es”) |
| `politicalView` | `string` | 没有 | \- 说吧 | 处理结果的政治观点,影响有争议领土的展示 |
| `showCurrentCountryResultsOnly` | `boolean` | 没有 | `false` | 将自动填充建议限制在 `Country` 字段 |
| `allowedCountries` | `string[]` | 没有 | \- 说吧 | ISO国家代码(alpha-2或alpha-3)组合以限制地址建议. 见 [国家.ts](https://npmcn.com/package/%40aws/address-form-sdk-js/lib/data/countries.ts) 用于α-2 参考 |
| `placeTypes` | `AutocompleteFilterPlaceType[]` | 没有 | \- 说吧 | 矩阵 [位置类型](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_AutocompleteFilter.html#location-Type-geoplaces_AutocompleteFilter-IncludePlaceTypes) 以过滤结果(例如“本地性”、“后编码”) |
| `initialMapCenter` | `[number, number]` | 没有 | \- 说吧 | 初始地图中心为\[经度,纬度\]坐标. 如果未提供,并在 `allowedCountries`地图以该国的首都为中心 |
| `initialMapZoom` | `number` | 没有 | 变数 | 初始地图缩放级别 。 默认: 10 当 `initialMapCenter` 提供,5在以单一允许的国家为中心时,1个 |
| `centerBounds` | `[[number, number], [number, number]]` | 没有 | \- 说吧 | 支持的区域框为 `[[west, south], [east, north]]` \[经,纬 。 设定时,搜索会停留在区域内(按键偏差被夹入框中,因此即使用户将地图压出,结果也会停留在区域内);从框外的设备上点击当前位置按钮显示警告并留下字段未被移动,而不是返回最近的区域内地址;可调整的指针会保留在区域内:如果用户将指针拖出框外,则地图的调整栏会显示出区域外的警告,其"Undo调整"动作返回指针,格式提交会被屏蔽,直到返回区域内. 用于只覆盖世界部分地区的数据提供者(如东南亚的GrabMaps). |
| `onSubmit` | `(getData) => void` | 没有 | \- 说吧 | 接收 `getData` 检索的async 函数 [窗体数据](https://github.com/aws-geospatial/address-form-sdk-js/blob/30fd74fcad353249ad54cc69c4bc5dd39fda7680/README.md?plain=1#L219) 带有预期使用参数 |

#### 表格提交数据

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

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

**重要内容:** 使用 `"Storage"` 如果你打算存储或缓存结果。 这确保遵守亚马逊定位服务 [预定用途要求](https://docs.aws.amazon.com/location/latest/developerguide/places-intended-use.html)。 。 。 .

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

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `placeId` | `string` | 来自 Amazon 位置服务处的 Place ID( 仅在从 typeahead 或 位置 按钮中选择地址时显示) |
| `addressLineOne` | `string` | 主地址线(街道地址) |
| `addressLineTwo` | `string` | 二级地址线(公寓、套房等) |
| `city` | `string` | 城市名称 |
| `province` | `string` | 国家或省 |
| `postalCode` | `string` | 邮政或ZIP代码 |
| `country` | `string` | 国家代码(ISO 3166-1 alpha-2) |
| `originalPosition` | `string` | API响应的原始坐标(经度,纬度) |
| `adjustedPosition` | `string` | 如果移动了地图指针(经度、纬度),则按用户调整坐标 |
| `addressDetails` | `Address` | 亚马逊定位服务API的完整地址对象( GetPlace/ ReverseGeocode 响应) |

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

### 窗体输入字段

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

#### 常见输入属性

| 财产 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | 没有 | 自定义输入字段的标签 |
| `placeholder` | `string` | 没有 | 输入的占位符文本 |
| `className` | `string` | 没有 | 用于自定义样式的 CSS 类名称 |

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

带有自动填充功能的主地址输入 。 见 [支助国](https://npmcn.com/package/%40aws/address-form-sdk-js/#readme-supported-countries) 用于了解不同国家的地址域分析行为.

| 财产 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | "定居" | 字段标签 |
| `placeholder` | `string` | "进入地址" | 占位符文本 |
| `data-api-name` | `string` | "建议" | API 类型 : `autocomplete` 或者说 `suggest`启用 `suggest` 返回两个指令并处理建议,以及 `autocomplete` 返回仅地址的建议 |
| `data-show-current-location` | `string` | "对" | 使用浏览器的地理定位 API 启用当前位置功能 。 这将促使用户获得访问其位置的许可 |

#### 其他输入字段

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

### 窗体按钮

#### 提交按钮

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

#### 重置按钮

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

### 地址论坛. 地图

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

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

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

#### 道具

| 反应属性 | 反应类型 | HTML/Java脚本属性 | HTML/Java脚本类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `mapStyle` | `array` | `data-map-style` | `string` | 对 | \- 说吧 | 地图样式配置 |
| `showNavigationControl` | `boolean` | `data-show-navigation-control` | `string` | 没有 | `true` | 显示地图导航控制 |
| `adjustablePosition` | `boolean` | `data-adjustable-position` | `string` | 没有 | `true` | 允许用户调整地址位置 |

#### 映射样式选项

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

| 反应执行( 阵列格式) | HTML/Java脚本执行( 样式) |
| --- | --- |
| `['Standard', 'Light']` | `"Standard,Light"` |
| `['Standard', 'Dark']` | `"Standard,Dark"` |
| `['Monochrome', 'Light']` | `"Monochrome,Light"` |
| `['Monochrome', 'Dark']` | `"Monochrome,Dark"` |
| `['Hybrid']` | `"Hybrid"` |
| `['Satellite']` | `"Satellite"` |

每种地图样式和颜色图案的详细说明见 [AWS 地图样式和定制](https://docs.aws.amazon.com/location/latest/developerguide/map-styles.html)。 。 。 .

## 捐款

我们欢迎社区的贡献并征求他们的意见。 见 [捐款](https://npmcn.com/package/%40aws/address-form-sdk-js/CONTRIBUTING.md) 关于如何建立开发环境的信息,并提交代码.

## 警卫

见 [捐款](https://npmcn.com/package/%40aws/address-form-sdk-js/CONTRIBUTING.md#security-issue-notifications) 更多信息.

## 许可证

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

## 常见问题

### @aws/address-form-sdk-js 是什么？

Javascript 的地址表 SDK

### 如何安装 @aws/address-form-sdk-js？

在项目目录运行 npm install @aws/address-form-sdk-js，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws/address-form-sdk-js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws/address-form-sdk-js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws/address-form-sdk-js 可以商用吗？

@aws/address-form-sdk-js 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @aws/address-form-sdk-js 的下载量有多少？

根据 npm 官方下载统计，@aws/address-form-sdk-js 在 2026/10/08 – 2026/11/06 这 30 天内被下载 7,708 次，日均约 257 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws/address-form-sdk-js 还在维护吗？

最新版本 1\.6\.1 发布于 2026/11/07（1 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 9 个；首次发布于 2025/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。