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 组件还提供一种简单的机制来对国家进行分组，从而更容易一次性对多个国家应用属性。

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 类和国家/地区组将“足球”更改为“英式足球”

在以下示例中，我们确定用户是否在“足球”国家，并为这些用户显示“足球”消息。

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

如果用户在“足球”国家之一，则amp-geo-group-soccer CSS 类将应用于body 标记。

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

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

<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-geo-pending 类，同时添加 amp-iso-country... 和 amp-geo-group-... 类。

示例：要在美国始终禁止具有 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 配置键为真，则会相应地更新 <amp-state id="ampGeo">。这允许发布者在文档直接从其源提供时使用自己的地理位置代码，同时在从缓存提供时保留动态配置。

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

自托管

重新托管 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

发现了一个 bug 或缺少某个功能？

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

转到 GitHub