@geoapify/geocoder-autocomplete

中文文档
3.1.0发布于 2026/07/28MITTypeScriptESM + CJS零依赖近 30 天下载 4.8万

一个JavaScript地址自动完成输入,兼容Leaflet,MapLibre,OpenLayers等地图库,用于高效的位置搜索和地理编码.

中文使用文档
文档目录13 节
  1. 目录
  2. 特征
  3. 快速启动
  4. 1. 获取地理化 API 密钥
  5. 2. 选择安装方法
  6. 3. 聆听活动
  7. 4. 清理
  8. 文档
  9. 试试现在
  10. 地址 自动完整游戏场
  11. 现场演示收藏
  12. JS小调节奏
  13. 捐款和支助

地理编码自动完成

Docs

轻量级 TypeScript/ JavaScript 库 地址自动补全 用于构建 地址自动填充 工作流程. 它的动力来自 地理化地址自动完成 API 并支持过滤器、偏差、类别搜索和自定义请求功能.

Geocoder Autocomplete

目录

特征

  • 自定义地址输入 ——易地嵌入地址自动完成字段在您网络应用程序的任何地方. 将它们附入任何 HTML 容器(例如 a) DIV自由地对待他们.
  • 由Geoapify APIs提供动力 - 连接到 地理化地址自动完成 API 用于实时地址建议。 自定义请求函数可以连接一个代理或另一个相容的数据源.
  • 高级搜索自定义 ——精细调整自动完成行为,具有灵活的滤波器和偏差设置(国,圆,矩,相近),用于高度相关和本地化的结果.
  • 结构化地址表 - 使用 type 参数用于构建结构化输入字段(例如:国家、城市、邮政编码、街道或便利),用于报到或登记表格.
  • 类别 & POI 搜索 ——启用餐馆,酒店,加油站等基于类别的查询. 当活动时,分类建议与处理结果一起出现,以便进行更丰富、更了解上下文的搜索.
  • 内建地点列表 —— 直接在界面中显示分类位置与来自 地理化地点 API。清单包括名称、地址和开放时间,加上人工或滚动加载,以获得更多结果.
  • 地点细节集成 - 选择性地从秘书处获取补充资料和地理图 地理化地点细节 API ——用于显示边界,多边形,或丰富地上下文的理想.
  • 自定义外观和感觉 ——从四个内置的光/暗主题中选择,或覆盖所记录的CSS类.
  • 无依赖 ——不需要外部图书馆. 清洁,轻量级, 和框架的不可知性通过设计.

快速启动

1. 获取地理化 API 密钥

访问 Geoapify.com (英语) 报名并获得你的 免费 API 密钥。 。 。 .

地理化提供 免费计划 包括最多 每天3 000个地址查询请求,使其成为测试,原型,和小项目的理想.

你可以探索所有可用的计划和使用限制 地理化定价页面。 。 。 .

2. 选择安装方法

使用包管理设置或CDN设置.

npm 或 Yarn 数据

安装软件包 :

npm install @geoapify/geocoder-autocomplete
# or
yarn add @geoapify/geocoder-autocomplete

添加容器 :

<div id="autocomplete"></div>

然后导入构造器和被包装的主题之一:

import { GeocoderAutocomplete } from '@geoapify/geocoder-autocomplete';
import '@geoapify/geocoder-autocomplete/styles/minimal.css';

const addressAutocomplete = new GeocoderAutocomplete(
  document.getElementById('autocomplete'),
  'YOUR_API_KEY',
  {
    placeholder: 'Enter address...',
    lang: 'en',
    limit: 5
  }
);

光盘N

对于没有构建步骤的页面,请使用此完整的 HTML 设置 :

<link rel="stylesheet" href="https://unpkg.com/@geoapify/geocoder-autocomplete@3/styles/minimal.css" />
<script src="https://unpkg.com/@geoapify/geocoder-autocomplete@3/dist/index.min.js"></script>

<div id="autocomplete"></div>

<script>
  const addressAutocomplete = new autocomplete.GeocoderAutocomplete(
    document.getElementById('autocomplete'),
    'YOUR_API_KEY',
    {
      placeholder: 'Enter address...',
      lang: 'en',
      limit: 5
    }
  );
</script>

这创造了一个交互输入,可以实时获取地址建议. 您可以通过 构造器 和可用 选项。 。 。 .

3. 聆听活动

订阅事件以响应用户选择或 API 更新 :

addressAutocomplete.on('select', (feature) => {
  console.log('Selected location:', feature);
});

addressAutocomplete.on('suggestions', (suggestions) => {
  console.log('Address suggestions:', suggestions);
});

addressAutocomplete.on('open', () => console.log('Dropdown opened'));
addressAutocomplete.on('close', () => console.log('Dropdown closed'));

参见本报告所列现有事件的完整清单 参考文献。 。 。 .

4. 清理

打电话 destroy() 删除主机页面或框架组件之前:

addressAutocomplete.destroy();

这将取消活动请求生命周期,并删除控件拥有的DOM收听器和标记. 如果视图再次挂起, 则创建新实例 .

文档

探索集成、配置和维护自动完成的指南:

试试现在

地址 自动完整游戏场

尝试在游戏场中自动完成地址 。 实验用不同的选择,如地理编码,偏差结果,以及更多,来观察自动完成行为如何适应:

现场演示收藏

本寄存器中可提供一套完整的即时运行演示.
这些例子说明如何将 地理编码自动完成 从简单的地址表到先进的基于地图的应用程序.

预览说明演示来源
One Field一个字段地址表 ——单场自动完成输入打开来源
Multi-field多字段地址表单 ——分步骤结构化地址输入打开来源
Form + Map地址表+地图 ——地址搜索与交互式地图相结合打开来源
Types自动完整类型 ——按位置类型筛选结果打开来源
Filters & Bias过滤( B) - 演示过滤和偏见定制打开来源
Events事件显示大小写 - 展示现有事件和召回打开来源
Places — No Map地点搜索( 无地图) ——带有内置列表的类别搜索打开来源
Leaflet叶片整合 — 交互式地图上的地址搜索和标记打开来源
Leaflet + Custom List传单 + 自定义位置列表 ——按位结果自定义 UI打开来源
Leaflet + Built-in List传单+已建站点列表 —— 以默认 UI 进行分类搜索打开来源
MapLibre GLMapLibre GL 整合 ——矢量地图并点击反向地理编码打开来源

JS小调节奏

探索显示如何使用的实际实例 地理编码自动完成 包含各种地图库和输入方案.

演示说明链接
地址字段 + 传单地图将自动完成字段与叶片映射集成,用于交互式地址搜索.打开 JSFidle
地址字段 + MapLibre GL 地图显示如何用 MapLibre GL 映射连接自动完成 .打开 JSFidle
地址表 1显示地址搜索和自动填充的简单地址表 .打开 JSFidle
地址表 2另一个包含多个字段的地址形式示例 .打开 JSFidle
航运地点审查显示如何审查和确认选定交付地点.打开 JSFidle
自定义地理编码函数使用 Geoapify 地址自动完成 API 的自定义自动完成逻辑示例 .打开 JSFidle

⚠️ 说明: 地址自动完成可以加速用户输入,但没有任何服务保证100%的精度或全局覆盖.
对于装运或交付等关键用途,在地图上显示所选点并请求用户确认. 反向地理编码可以帮助将一个地址与所选坐标进行比较,但并不能独立地证明送出或进入的准确性.

捐款和支助

我们欢迎捐款! 这就是你能帮助:

  1. 未决问题:如果遇到任何错误或有特性请求,请打开一个问题 GitHub 问题。 。 。 .
  2. 提交拉动请求:叉出寄存器,进行修改,并提交拉出请求复核.
  3. 文件最新情况:通过提交更正或改进帮助改进本文件.

如果你需要帮助或有任何问题,请随意联系我们的支援团队 信息库@geoapify.com。 。 。 .

版本与发布记录

@geoapify/geocoder-autocomplete 共发布 36 个版本,首次发布于 2020/04/13;过去 12 个月发布了 1 个版本。

版本发布日期距今
3.1.0latest2026/07/283 个月前
3.0.12025/11/111 年前
3.0.02025/11/071 年前
3.0.0-rc.1next2025/11/031 年前
2.2.12025/08/151.3 年前
2.2.02025/08/121.3 年前

关于 @geoapify/geocoder-autocomplete 的常见问题

@geoapify/geocoder-autocomplete 是什么?

一个JavaScript地址自动完成输入,兼容Leaflet,MapLibre,OpenLayers等地图库,用于高效的位置搜索和地理编码.

如何安装 @geoapify/geocoder-autocomplete?

在项目目录运行 npm install @geoapify/geocoder-autocomplete,或使用 pnpm add / yarn add / bun add。

@geoapify/geocoder-autocomplete 支持 TypeScript 吗?

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

@geoapify/geocoder-autocomplete 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@geoapify/geocoder-autocomplete 可以商用吗?

@geoapify/geocoder-autocomplete 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geoapify/geocoder-autocomplete 的下载量有多少?

根据 npm 官方下载统计,@geoapify/geocoder-autocomplete 在 2026/10/16 – 2026/11/14 这 30 天内被下载 48,449 次,日均约 1,615 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geoapify/geocoder-autocomplete 还在维护吗?

最新版本 3.1.0 发布于 2026/07/28(3 个月前);至今共发布 36 个版本,其中过去 12 个月发布了 1 个;首次发布于 2020/04/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。