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，在 Safari 中进行 DevChannel 调试可能无法正常工作。

验证

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

需要更多帮助？

你已经阅读此文档十几次了，但它仍然没有涵盖你的所有问题？也许其他人也有同样的感受：请在 Stack Overflow 上联系他们。

前往 Stack Overflow

发现错误或缺少功能？

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

前往 GitHub