地图模块：显示位置而不隐藏地址

地图模块帮助访客理解实际场所的位置，并从阅读过渡到导航。其核心内容是 HTML 中经过验证的地址；视觉地图是可选的方向辅助工具。默认实现会预留地图区域，显示轻量级的静态备选方案，并仅在访客主动要求后才加载已获批的互动提供商。

国家美术馆
特拉法加广场，伦敦 WC2N 5DN，英国
地图未加载。在地图应用中打开该位置，或激活加载互动地图以查看周围街道。

这个渲染外观层在发起任何第三方请求之前就很有用。它标识地点名称，以可选择的文本形式展示地址，解释未加载状态，并提供两条清晰的路径：打开外部地图或有目的地加载嵌入地图。

为什么这个元素很重要

位置问题是实际问题。访客可能正在判断某个分支机构是否足够近，查看它位于铁路线的哪一侧，寻找正确的入口，或比较公共交通与停车情况。地图减少了将不熟悉地址转化为空间背景所需的脑力劳动。它比一段文字更快地展示附近地标和街道关系。

这种便利性并不意味着地图就是信息源。访客可能会复制地址、发送给他人，或使用辅助技术阅读。地图图块无法可靠地支持这些操作，而数据薄弱、隐私设置或提供商故障也可能阻止这些操作。地址必须在不依赖地图的情况下仍然可用。

嵌入地图可能引入 iframe、JavaScript、字体、图片和第三方请求。这些资源会与页面的主体内容竞争，并可能暴露 IP 地址或启动需要用户同意的存储。从不使用地图的访客不应承担这些成本。

机器可提取性意味着软件无需解读地图像素或执行提供商代码即可识别地点。搜索爬虫、AI 系统、屏幕阅读器、翻译工具和本地数据管道需要地点名称、完整邮政地址、受管辖的坐标，以及 HTML 或结构化字段中的稳定目标链接。iframe URL 并非可靠的地址。提供商的标签可能发生变化，图钉可能略有偏移。同一经过验证的位置记录应为可见地址、地图标记、导航链接和任何符合条件的结构化数据提供信息。

元素编写规则 具有优先权：根据目的而非外观选择类型化元素。如果目的是围绕一个经过验证的地点提供空间方位信息，请使用地图模块。如果目的是发布联系信息，请使用营业时间与联系模块 或 NAP 模块 ，让地图使用相同的地址记录。如果目的是预约时间，请使用预订模块 。

何时使用

当看到地点所处的周边环境有助于读者完成位置相关任务时，使用地图模块。典型用途包括商店、办公室、诊所、场馆、取货点、展厅、酒店、景点、分支机构、活动入口或服务区域边界。当入口与邮政地址不同、附近道路容易混淆、无障碍路线需要说明，或公共交通和停车影响访问时，地图模块尤其有用。

对照实际入口或服务点确认标记位置，而不是直接接受提供商的首次地理编码结果。对于位于较大建筑内的地点，在文本中注明楼层、单元或入口。

容易混淆的情况往往会创建美观但无帮助的地图：

• **服务城市列表：**这是服务区域声明，而非实体地点的证明。不要在城市中心放置图钉来暗示设有办公室。
• **无法接待访客的邮寄地址：**发布邮政信息并说明无法接待访客。地图会暗示不存在的到访行为。
• **远程或在线的公司：**注册办公室可能在法律上有意义，但不会因为嵌入地图能找到它而成为客户的目的地。
• **逐向导航指示：**链接到导航提供商并提供路线相关说明。静态嵌入地图无法考虑交通、封路或访客的出发位置。
• **多个地点：**使用带有文字结果列表的位置查找器。图钉云无法替代各个分支机构页面。
• **本地存在证明：**地图不能证明团队在那里运营。需要用一致的身份、地址、联系方式、营业时间和分支机构特定内容来支持这一声明。
• **装饰性的地理背景：**如果位置不影响任务，则省略地图。城市天际线或区域轮廓属于不同的视觉用途。

放置位置

将地图紧跟在地点名称、完整地址以及任何对访问至关重要的限定说明之后。在位置页面上，通常的顺序是：介绍、地址和联系信息、地图、到达说明、营业时间，然后是访问或预订操作。如果路线指引是主要内容，请在地图之前进行总结。

将地址、地图外观层、加载控制、备选链接、说明文字和路线说明保持在一个标记区域内。访客不应需要经过推荐语或营销版块才能找到属于图钉的地址。“获取路线"链接必须使用与显示标记相同的坐标或地点标识符。

该模块可以靠近同一分支机构的营业时间放置，但不能与冲突的地址、另一张地图、自动播放视频或伪装成控件的广告相邻。不得将其放置在轮播、折叠面板、必填弹窗、隐藏标签或狭窄的表格单元格内。

不得将地图放在警告信息和其限定的说明之间，或放在预订操作与其先决条件之间。切勿将重要的地址文本、同意措辞或唯一的路线链接叠加在地图图块上。在移动设备上，保持此阅读顺序：地点名称、地址、访问限定说明、备选方案、加载控制、地图区域，然后是路线指引。

构成要素

1. **地点名称：**标识标记所代表的分支机构、场馆或目的地。
2. **完整文字地址：**包含区分该地点所需的每一行地址、地区、邮政编码和国家。
3. **访问限定说明：**说明改变到达方式的入口、单元、楼层、预约要求、访客限制或无障碍信息。
4. **预留视口：**在互动资源加载之前固定宽度和宽高比，防止布局移动。
5. **静态备选方案：**无需脚本即可提供有用的空间背景；必须在引用之前作为真实生成的资源存在。
6. **标记：**表示经过验证的到达点，而不仅仅是邮政编码或行政中心。
7. **加载控制：**是一个真正的按钮，带有具体的无障碍名称，例如"为国家美术馆加载互动地图”。
8. **提供商声明：**命名第三方，并说明激活可能会连接到该提供商。
9. **路线链接：**打开稳定的 HTTPS 目的地进行导航，无需依赖嵌入播放器。
10. **说明文字或地标注释：**解释地图的有用结论，例如入口朝向某条命名街道。
11. **位置记录：**向渲染器提供受管辖的坐标、地点标识符和验证日期。
12. **故障状态：**在提供商无法加载时，保留地址、路线链接和重试选项。

设计示例

每个变体都将地址保留在 HTML 中，预留地图尺寸，并提供直接的路线链接。只有加载行为发生变化。

静态地图 + 外部路线 — 最低成本

当方向感有帮助但平移和缩放功能不必要时，使用优化的地图图片。替代文本说明其空间结论；说明文字承载地标信息。仅在资源存在后才发布路径。

点击加载互动地图 — 默认方式

首先显示静态备选方案或中性预留面板。一个按钮在用户明确激活后加载已获批的 iframe。这可以保护页面速度，使第三方连接变为有意的操作，同时按需提供平移、缩放和街道查看功能。

需同意才能加载的地图

当网站的隐私政策要求在使用前获得同意才能联系提供商时使用此方式。用通俗的语言说明后果，并提供无需同意即可使用的路线链接。拒绝时不得隐藏地址或影响页面其余部分的正常功能。

始终加载的互动地图 — 有条件的例外

仅在互动是核心功能、允许联系提供商且现场测量接受成本时使用。延迟加载仍可在访客接近时初始化。保留服务端渲染的备选方案，因为 loading="lazy" 无法防止提供商故障。

位置查找器中的单地点模块

对于多地点页面，将选中的地图与文字结果列表配对。加载一个选定的分支机构使交互保持可理解性；更改选择会同时更新地点名称、地址、标记和路线链接。列表无需地图即可使用。

参数

“来源"指渲染器获取创作值的途径。权威的位置系统仍然负责验证实际地址和坐标。

渲染器必须从已批准列表中的标识符和数字坐标构建提供商 URL。作者不得将任意 iframe HTML、API 密钥、访问令牌或 JavaScript 粘贴到正文中。六位小数的精度远超访客通常需要的精度；若发布精确的私密入口会带来安全或隐私风险，应保留更少的位数。

语法和代码示例

这些可移植示例描述了一个标准内容模型。在作者将语法用于生产环境之前，项目必须实现并测试相应的渲染器。

可移植 Markdown 指令

:::map{variant=facade place-id="north-street-clinic" latitude=51.454514 longitude=-2.587910 zoom=16 aspect-ratio="4/3" provider=osm directions-url="https://www.openstreetmap.org/directions?to=51.454514,-2.587910" verified=2026-08-27}
## North Street Clinic

18 North Street, Bristol BS1 3PR, United Kingdom

Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.
:::

第一个标题提供 title；下一行提供结构化地址；剩余正文提供说明文字或到达说明。

Hugo 短代码映射

仅使用命名参数。此标记法用于说明预期的适配器；并不表示此仓库中已存在地图短代码。

{{< map variant="facade" placeId="north-street-clinic" latitude="51.454514" longitude="-2.587910" zoom="16" aspectRatio="4/3" provider="osm" directionsUrl="https://www.openstreetmap.org/directions?to=51.454514,-2.587910" verified="2026-08-27" >}}
## North Street Clinic

18 North Street, Bristol BS1 3PR, United Kingdom

Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.
{{< /map >}}

适配器必须预留宽高比，在服务端渲染地址和备选方案，并仅在声明触发条件后创建 iframe。绝不能在创作内容中暴露提供商 API 密钥。

WordPress 区块

<!-- wp:amicited/map {"variant":"facade","placeId":"north-street-clinic","latitude":51.454514,"longitude":-2.587910,"zoom":16,"aspectRatio":"4/3","provider":"osm","directionsUrl":"https://www.openstreetmap.org/directions?to=51.454514,-2.587910","verified":"2026-08-27"} -->
<h2>North Street Clinic</h2>
<address>18 North Street, Bristol BS1 3PR, United Kingdom</address>
<p>Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.</p>
<!-- /wp:amicited/map -->

原生区块应将坐标存储为数字，保持地址字段结构化，验证提供商，并渲染安全的服务端外观层。编辑器预览可显示静态表示，而非初始化完整的提供商。

好与坏的示例

好示例

North Street Clinic
18 North Street, Bristol BS1 3PR, United Kingdom
请使用药房旁边的庭院入口。North Street 提供无台阶通道。
加载互动地图 · 在地图应用中打开路线

这样做之所以有效，是因为访客无需嵌入即可识别、复制和导航到该地点。入口说明解决了实际到达时的模糊性问题。加载第三方是一种选择，两个操作都清楚地说明了会发生什么。

坏示例

在这里找到我们！
[全宽互动地图，带有无标签图钉]

这样做之所以失败，是因为"这里"并未标识地点，地址只存在于提供商的像素中，且图钉可能代表邮政编码而非实际入口。急于加载的地图为不使用它的访客也增加了成本。没有备选方案、验证日期、到达说明或可访问的导航链接。在 iframe 的 title 中添加地址可以改进框架标签，但不会创建可选择的页面文本。

架构标记和无障碍性

地图模块没有专用的 Schema.org 类型。当页面代表相应实体时，经过验证的字段可以为适当的 Organization、LocalBusiness 子类型、Place、PostalAddress 或 GeoCoordinates 提供信息。使用一个共享的位置记录；可见地址、标记、规范分支 URL 和 JSON-LD 必须一致。

不要仅为让页面看起来更完整而添加 hasMap。使用时，应指向同一位置的稳定地图 URL，而非过期会话 URL 或暴露密钥的 iframe 端点。没有公开客户地点的服务区域企业应如实描述其服务范围，不得编造场地或发布过于精确的私人坐标。

无障碍性从独立于地图开始。将地点名称和完整地址放在 HTML 中，仅在涉及联系信息时使用 <address>。提供正常的路线链接。用文字描述入口、地标、公共交通、停车和无台阶通道。静态地图的替代文本应传达有用的结论，而非列出每条街道。

加载控制必须是一个可通过键盘操作的 <button>，带有可见焦点和与地点相关的无障碍名称。加载不得意外移动焦点。激活后，宣布简短状态，如"互动地图已加载”，然后将焦点保留在发起控制上或仅在界面有已记录的键盘入口点时移动焦点。为每个 iframe 提供唯一的标题，例如"North Street Clinic 互动街道地图"。

提供商的控制在狭窄宽度和 200% 缩放时必须保持可操作。不要将键盘焦点困在 iframe 内部。不要依赖图钉颜色、拖拽手势、悬停或视觉街道标签来提供重要信息。如果地图加载失败或用户拒绝同意，请保持预留区域稳定，并展示地址、到达说明、外部路线链接和重试操作。

编写规则

以 2 到 10 个词的形式呈现官方公共地点名称。紧接着提供受管辖位置记录中存储的完整邮政地址。不要缩写到达正确入口所需的单元、建筑、地区或邮政编码。当页面可能接收国际流量或城市名称存在歧义时，包含国家信息。

仅当到达说明改变访客应采取的操作时，添加一条 8 到 35 个词的到达说明。命名持久的地标或入口关系：“请使用药房旁边的庭院入口"有用，而"你不会找不到的"则不然。有时效性的道路封闭、施工路线和临时入口需要在内容系统的其他地方有负责人和审核日期。

一个地图模块对应一个选定的目的地。位置查找器可以切换该目的地，但每次选定状态必须原子性地更新标题、地址、标记、说明文字和链接。默认显示一个主要标记。次要地标仅在其有助于说明到达方式且在视觉上可区分（文字和控制层面）时才能出现。

保持控制标签直白明确：“加载互动地图”、“打开路线"和"查看无障碍入口”。避免使用模糊标签，如"探索”、“查看更多"或"点击此处”。当连接涉及隐私问题时，在激活前说明提供商名称。

切勿将电话号码、营业时间、促销声明、评论、价格、预订表格或长篇停车政策放在互动画布内部。这些信息属于 HTML 和各自的类型化元素。切勿发布 API 密钥、用户的实时位置、私人住宅入口、虚构的办公室图钉、未经验证的服务区域，或从未经检查的地理编码器复制的坐标。地图不得暗示不存在访客访问权限的地方。

在发布时、地点变更后以及定期审核期间验证地址和标记。提供商的道路和标签可能独立变化；组织机构仍对其位置记录和到达说明的准确性负责。

使用此模块的文章类型

postTypes 前置元数据字段是该实现矩阵的来源。

QA 检查清单

• 地点名称和完整地址作为可选择的服务端渲染文本出现在地图外部。
• 标记指向已验证的公共到达点，而非邮政编码或建筑中心点。
• 地址、坐标、地点标识符、路线链接和结构化数据来自同一受管辖的记录。
• 模块说明了到达所需的任何单元、楼层、入口、预约规则或无障碍路线。
• 默认实现避免在用户明确激活或有效同意之前发起第三方请求。
• 始终加载的例外情况有记录的目的、隐私依据和经过测量的性能预算。
• 在图像、iframe 或提供商代码加载之前预留宽度和宽高比。
• 任何静态图像路径指向真实已获批的资源并具有有用的替代文本。
• 加载控制是一个按钮，带有特定地点且可无障碍访问的名称和可见焦点。
• iframe（创建时）具有唯一的描述性标题，并且不会将键盘焦点困在其中。
• 当地址、路线链接、到达说明和重试路径因脚本、同意或提供商故障而失效时，这些信息仍可使用。
• 重要信息不依赖于图钉颜色、悬停、拖拽、缩放或地图标签。
• 布局在狭窄宽度和 200% 缩放时仍能正常工作，且不会遮挡提供商控制。
• 页面未声明组织机构无法验证的公共办公室、入口或服务区域。
• 创作内容中不出现 API 密钥、访问令牌、用户位置、私人坐标或任意 iframe URL。
• 多地点实现保留键盘可访问的文字列表，并原子性地同步选定分支机构。
• Schema（如有）描述与向访客展示的相同的真实实体和地址。
• 验证日期和审核负责人符合站点的本地数据维护政策。

地图模块的成功在于：失去地图改变的只是便利性，而非信息本身。读者仍然知道地点、如何到达以及到达后可以期待什么；提供商始终是可选的。