# 如何在自己的网站中集成一张移动地图？

> 在您的网站中集成ROOTE地图：响应式iframe，自行车、厕所、公交和有轨电车过滤器，城市搜索及参数传递。

Source: https://www.roote.ai/zh/guides/ru-he-zhong-de-yidong-huaban-yinru-zhi-fang-fa/
Language: zh
Author: ROOTE

想在您的网站中集成一张移动地图，而无需构建完整界面，可使用ROOTE的iframe。该嵌入支持城市搜索和页面对应的过滤器：自行车用于骑行指南，厕所用于洗手间指南，公交和有轨电车用于交通出行。

本指南中的示例使用 embed.roote.ai，这一域名已在ROOTE指南中集成。通用文档也描述了 map.roote.ai 的集成方法，并区分了摄像机参数与完整搜索参数。

## 添加响应式iframe

此代码块开启了波尔多的自行车搜索，缩放级别为15。URL在代码中构建；iframe的标题为屏幕阅读器用户描述其内容。请根据页面语言调整该标题。

```
<iframe
  title="Carte ROOTE — vélos à Bordeaux"
  src="https://embed.roote.ai/?q=Bordeaux&amp;modes=bicycle&amp;zoom=15"
  width="100%"
  height="480"
  loading="lazy"
  allow="geolocation"
  style="display:block; width:100%; min-height:360px; border:0; border-radius:16px;"
></iframe>
```

在HTML属性中，分隔符&应写为&amp;。宽度100%跟随容器宽度。保持适合移动端的高度，避免将必需控件置于不可见区域。

## 选择与页面相符的出行模式

| 需求 | 嵌入参数 |
| --- | --- |
| 自行车 | modes=bicycle |
| 厕所 | modes=toilets |
| 公交 | modes=bus |
| 有轨电车 | modes=tram |
| 公交和有轨电车 | modes=bus,tram |
| 自行车和厕所 | modes=bicycle,toilets |

这些值对应ROOTE的嵌入路径，涵盖出行、服务和通勤三大类。它们不能替代REST参数：服务类用types，通勤类用modes。一张以城市为中心的地图不保证每个分类都有数据。

## 区分摄像机位置与搜索起点

lat和lon定位摄像机视角。但在地图的文档协议中，这不足以创建临近搜索。还需使用search_lat、search_lon和search_label参数，配合出行模式和缩放级别，以还原已知搜索。

```
https://embed.roote.ai/?search_lat=44.8416106&search_lon=-0.5810938&search_label=Bordeaux&zoom=15&modes=bus,tram
```

以上坐标是波尔多的参考点，不是用户位置。如果也加入摄像机参数，可以在保持距离计算点的同时显示其他区域。仅在需要区分时使用此方法。

[ROOTE地图参数文档](https://doc.roote.ai/map)

## 构建URL时避免特殊字符丢失

建议使用URL和URLSearchParams对象，而非手动拼接字符串。它们会正确编码空格、重音符号和分隔符。以下代码适用于浏览器，从输入的地点生成iframe地址。

```
const embedUrl = new URL('https://embed.roote.ai/');
embedUrl.searchParams.set('q', 'Place des Quinconces, Bordeaux');
embedUrl.searchParams.set('modes', 'bicycle,toilets');
embedUrl.searchParams.set('zoom', '15');
document.querySelector('iframe').src = embedUrl.toString();
```

## 保持状态传递至完整地图

指向 map.roote.ai 的链接应包含当前搜索状态。重建没有参数的URL会丢失城市、出行模式或缩放信息。维护一个统一的URL对象，页面更新时同步其参数。

```
const fullMapUrl = new URL('https://map.roote.ai/');
fullMapUrl.search = embedUrl.search;
const link = document.querySelector('[data-open-map]');
link.href = fullMapUrl.toString();
link.target = '_blank';
link.rel = 'noopener noreferrer';
```

此代码保持父页面已知参数。若用户在iframe内修改搜索，父页面无法直接读取跨域的iframe URL。需要明确实现且有文档支持的机制，例如通过postMessage并校验来源来传递状态。不要凭空发明iframe未支持的事件名称。

## 管理定位和移动端交互

allow="geolocation"允许iframe请求定位权限，但需用户同意并符合网站权限策略。拒绝定位请求时应允许城市搜索功能正常使用。不要在用户未经选择时页面加载即请求位置。

文章中主动激活地图能避免地图滚动和缩放阻拦阅读手势。控件必须键盘可达且明确标识。检测设备转向和窄屏，兼顾移动端与桌面视角。

## 检查结果显示及异常状态

测试每个过滤条件、一个已知城市、数据稀少区域、无效搜索及无可用分类。地图无标记时无法单独区分搜索结果为空还是接口故障。保留嵌入消息及可用的完整地图访问。

[区分无结果与API错误](https://www.roote.ai/zh/guides/api-no-result-vs-error-chinese/)

[选择使用embed、API还是MCP](https://www.roote.ai/zh/guides/api-ou-mcp-lequel-choisir-pour-integrer-des-donnees-de-mobilite/)

[寻找厕所功能演示指南示例](https://www.roote.ai/zh/guides/zairuzhao-cha-mi-gong-gong-ce-suo/)

## 常见问题

### iframe需要API密钥吗？

此处展示的公开URL均不包含密钥。不要将秘密放在嵌入URL或客户端代码中。

### zoom=15是否扩大搜索半径？

缩放控制视图范围，不能等同于API请求半径。请确认您使用的接口中搜索参数的具体含义。

### 父页面是否知晓iframe中的变动？

父页面仅知道传入的参数。iframe内部变更需双方跨域通信机制并有文档支持。