重要提示：此文档不适用于您当前选择的格式 ads！

amp-geo

描述

提供近似的国家/地区级地理位置接口。

必需的脚本

<script async custom-element="amp-geo" src="https://cdn.ampproject.org/v0/amp-geo-0.1.js"></script>

支持的布局

nodisplay

用法

amp-geo 组件提供国家/地区级地理位置。amp-geo 组件还提供了一种简单的机制来分组国家/地区，从而更容易一次将属性应用于多个国家/地区。

amp-geo 组件使用请求来源的国家/地区，格式为 ISO 3166-1 alpha-2 国家/地区代码。amp-geo 组件从客户端的 IP 地址确定此代码。ISO 国家/地区代码可能与顶级域名不同。例如，英国的代码是 gb 而不是 uk。

在 WHOIS 数据库中具有国家/地区信息的 IP 地址可能在 amp-geo 中没有国家/地区信息。如果无法确定国家/地区，则该值设置为 unknown。如果使用了分组功能，则至少一个组必须包含 unknown。

amp-geo 组件提供 CSS、amp-bind 和变量替换接口。

生成的 CSS 类

如果将 amp-iso-country-XX 类应用于 body 元素，其中 XX 替换为 ISO 国家/地区代码或值 unknown，则可以使用 CSS 修改 body 元素。

在以下示例中，我们添加 <amp-geo> 来确定用户的位置，以便我们可以显示相应的旗帜。

<amp-geo layout="nodisplay"></amp-geo>

如果用户在加拿大，则 amp-geo 组件会将 amp-iso-country-ca CSS 类应用于 body 标签。然后，我们可以使用 CSS 应用加拿大的正确背景图像

/* defaults */
.flag {
  background-image: './starsandstripes.png';
}
/* override */
.amp-iso-country-ca .flag {
  background-image: './mapleleaf.png';
}

用于分组位置的可选配置

或者，您可以在 amp-geo 标签中包含 JSON 配置脚本。ISOCountryGroups 键允许按国家/地区代码组进行选择。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "soccer": ["au", "ca", "ie", "nz", "us", "za"],
        "football": ["unknown"]
      }
    }
  </script>
</amp-geo>

如果指定了国家/地区组，amp-geo 将遍历这些组。对于包含当前国家/地区的任何组，将名称为 amp-geo-group- 后跟组名称的类添加到 <body>。组名称只能包含 a-z、A-Z 和 0-9，并且不能以数字开头。如果没有匹配的国家/地区组，则将类 amp-geo-no-group 添加到 body。

示例：生成的 CSS 类

<body class="amp-geo-group-football amp-iso-country-gb …"></body>

示例：使用 CSS 类和国家/地区组将“soccer”更改为“football”

在以下示例中，我们确定用户是否在“soccer”国家/地区，并为这些用户显示“football”消息。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "soccer": ["au", "ca", "ie", "nz", "us", "za"],
        "football": ["unknown"]
      }
    }
  </script>
</amp-geo>

如果用户在“soccer”国家/地区之一，则 amp-geo-group-soccer CSS 类将应用于 body 标签。

/* defaults */
.football:after {
  content: 'football';
}
/* override */
.amp-geo-group-soccer .football:after {
  content: 'soccer';
}

然后，使用 CSS 选择正确的单词（即 football）非常简单。

<div>The game is called <span class="football"></span>!</div>

预设国家/地区组

除了用户指定的国家/地区组之外，amp-geo 还支持预设国家/地区列表。有关可用的预设列表，请参阅 amp-geo-presets.js。

GOOGLE 和 AMP 提供此信息是出于礼貌，但不保证此处包含的任何信息的准确性或完整性。此信息“按原样”提供，不作任何明示或暗示的保证，包括但不限于对适销性和特定用途适用性的暗示保证。

美国加利福尼亚州检测

当 amp-geo 组件确定请求来自加利福尼亚州时，它会提供 ISO 3166-2 信息。预设列表中的 preset-us-ca 值支持此功能。

可以像下面的 myList 示例一样，将其他国家/地区包含在预设列表中。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "eea": ["preset-eea"],
        "usca": ["preset-us-ca"],
        "myList": ["preset-eea", "preset-us-ca", "ca", "au", "nz"]
      }
    }
  </script>
</amp-geo>

美国分区检测

当 amp-geo 组件确定请求来自美国州或哥伦比亚特区（华盛顿特区）时，它会提供 ISO 3166-2 信息。这些值采用 ${country}-${subdivision} 格式，并支持以下代码。

us-al - 阿拉巴马州
us-ak - 阿拉斯加州
us-az - 亚利桑那州
us-ar - 阿肯色州
us-ca - 加利福尼亚州
us-co - 科罗拉多州
us-ct - 康涅狄格州
us-de - 特拉华州
us-dc - 哥伦比亚特区
us-fl - 佛罗里达州
us-ga - 佐治亚州
us-hi - 夏威夷州
us-id - 爱达荷州
us-il - 伊利诺伊州
us-in - 印第安纳州
us-ia - 爱荷华州
us-ks - 堪萨斯州
us-ky - 肯塔基州
us-la - 路易斯安那州
us-me - 缅因州
us-md - 马里兰州
us-ma - 马萨诸塞州
us-mi - 密歇根州
us-mn - 明尼苏达州
us-ms - 密西西比州
us-mo - 密苏里州
us-mt - 蒙大拿州
us-ne - 内布拉斯加州
us-nv - 内华达州
us-nh - 新罕布什尔州
us-nj - 新泽西州
us-nm - 新墨西哥州
us-ny - 纽约州
us-nc - 北卡罗来纳州
us-nd - 北达科他州
us-oh - 俄亥俄州
us-ok - 俄克拉荷马州
us-or - 俄勒冈州
us-pa - 宾夕法尼亚州
us-ri - 罗得岛州
us-sc - 南卡罗来纳州
us-sd - 南达科他州
us-tn - 田纳西州
us-tx - 德克萨斯州
us-ut - 犹他州
us-vt - 佛蒙特州
us-va - 弗吉尼亚州
us-wa - 华盛顿州
us-wv - 西弗吉尼亚州
us-wi - 威斯康星州
us-wy - 怀俄明州

可以像下面的 usWithSubdivisions 示例一样，将其他国家/地区/分区包含在预设列表中。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "usca": ["preset-us-ca"],
        "usco":["us-co"],
        "usct":["us-ct"],
        "usva":["us-va"],
        "usWithSubdivisions": ["us-ca", "us-co", "us-ct", "us-va"]
      }
    }
  </script>
</amp-geo>

渲染阻塞

默认情况下，amp-geo 组件不会阻塞渲染。也就是说，即使 amp-geo 尚未加载和执行，页面也会加载并呈现元素。如果某些元素在特定地理位置永远不会呈现很重要，请使用 amp-geo-pending 类来提供选择性渲染阻塞。这是通过发布商将 amp-geo-pending 添加到 <body> 元素来实现的。当 amp-geo 脚本加载时，它会在添加 amp-iso-country... 和 amp-geo-group-... 类时同时删除 amp-geo-pending 类。

示例：要始终禁止在美国具有 foo 类的元素，请设置 <body class="amp-geo-pending">，并在 CSS 中包含以下内容

.amp-geo-pending .foo,
.amp-iso-country-us .foo {
  display: none;
}

此 CSS 隐藏具有 foo 类的元素，直到 amp-geo 加载，如果国家/地区是 us，则继续隐藏它。

设置为 display: none 时，诸如 amp-ad 和 amp-iframe 之类的元素不会发出外部网络请求。

变量替换

也可以通过 AMP 变量替换获得国家/地区代码

AMP_GEO 或 ${ampGeo} 返回匹配组的列表（逗号分隔）。AMP_GEO(ISOCountry) 或 ${ampGeo(ISOCountry)} 返回国家/地区代码（或 unknown）。

也可以通过 AMP 变量替换获得分区代码

AMP_GEO 或 ${ampGeo} 返回匹配组的列表（逗号分隔）。AMP_GEO(ISOSubdivision) 或 ${ampGeo(ISOSubdivision)} 返回国家/地区分区（或 unknown）。

缓存

amp-geo JavaScript 文件以 30 分钟的缓存生命周期 (Cache-control: private, max-age=1800) 提供，以防止使用过时的地理位置数据，并确保用户移动位置时地理位置准确。

预渲染

amp-geo 组件支持预渲染。如果文档从发布商来源提供，并且它已经包含匹配 amp-iso-country-* 的类，则 amp-geo 将遵循该值。amp-geo 将使用提供的国家/地区和配置来向合作的 AMP 扩展（例如 amp-consent）提供数据。如果检测到预渲染的国家/地区代码，则 amp-geo 将不会修改文档以添加国家/地区组或 amp-state 的类。

但是，如果文档是通过 AMP 缓存之一提供的，则 amp-geo 会删除并替换任何提供的地理位置类，并且如果 amp-bind 配置键为 true，则会相应地更新 <amp-state id="ampGeo">。这允许发布商在文档直接从其来源提供时使用他们自己的地理位置代码，同时在从缓存提供时保留动态配置。

希望预渲染 amp-geo 的缓存应该打开一个 issue，请求从预渲染覆盖中移除。

自托管

重新托管 AMP JavaScript 文件的发布者和缓存必须实现对 amp-geo-0.1.js 文件的服务器端修补或预渲染（见上文）。

从 cdn.ampproject.org 提供的文件不应被用作修补的基础，因为它在下载时已经被修补过了。相反，应该使用基础 ./dist/v0/amp-geo-0.1.js 文件。

字符串 {{AMP_ISO_COUNTRY_HOTPATCH}} 必须在提供服务时替换为与请求 IP 地址对应的小写 2 字母 ISO 3166-1 alpha-2 国家代码。该值应填充到与原始长度匹配，以避免破坏 amp-geo-0.1.max.js.map 文件。如果无法确定国家/地区，则可以通过不修补文件或使用等长的空格字符串进行修补来指示 “未知” 国家/地区。

调试

在文档 URL 中添加 #amp-geo=XX 会强制将国家/地区显示为国家/地区 XX。这使您无需 VPN 连接到某个国家/地区即可进行测试。出于安全原因，为了防止共享地理位置欺骗 URL，此功能仅适用于已启用实验性频道或在本地进行测试的用户（即，amp-geo.js 通过 amp serve 在开发模式下提供）。

由于 ITP，在 DevChannel 中进行调试可能在 Safari 中不起作用。

验证

请参阅 AMP 验证器规范中的 amp-geo 规则。

需要更多帮助？

您已经阅读过本文档十几次，但它实际上并没有涵盖您的所有问题？也许其他人也有同感：在 Stack Overflow 上联系他们。

转到 Stack Overflow

发现错误或缺少功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您能成为我们开源社区的持续参与者，但我们也欢迎您对您特别感兴趣的问题做出一次性贡献。

转到 GitHub