重要事項：本文件不適用於您目前選取的格式 **電子郵件**！

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。

IP 位址在 WHOIS 資料庫中可能含有國家/地區資訊，但在 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 的快取應提出問題，要求從預先渲染覆寫中移除。

自行託管

重新託管 AMP JavaScript 檔案的發布商和快取必須實作 amp-geo-0.1.js 檔案的伺服器端修補或預先渲染 (請參閱上方)。

從 cdn.ampproject.org 提供的檔案不應做為修補的基礎，因為檔案下載時就已修補過。而應使用基礎 ./dist/v0/amp-geo-0.1.js 檔案。

字串 {{AMP_ISO_COUNTRY_HOTPATCH}} 必須在提供時替換為對應於要求 IP 位址的小寫雙字母 ISO 3166-1 alpha-2 國家/地區代碼。這個值應填補至符合原始長度，以免破壞 amp-geo-0.1.max.js.map 檔案。如果無法判斷國家/地區，則可以讓檔案保持未修補狀態，或使用長度相等的空格字串進行修補，以表示「unknown」國家/地區。

偵錯

在文件網址中加入 #amp-geo=XX 會強制國家/地區顯示為國家/地區 XX。這樣一來，您就可以進行測試，而不必 VPN 連線到其他國家/地區。基於安全性考量，為了防止共用地理位置詐騙網址，這項功能僅適用於已啟用實驗性管道的使用者，或是在本機進行測試的使用者 (也就是透過 amp serve 在開發模式下提供 amp-geo.js)。

由於 ITP，在 Safari 中，DevChannel 的偵錯功能可能無法運作。

驗證

請參閱 AMP 驗證器規格中的 amp-geo 規則。

需要更多協助嗎？

您是否已閱讀本文件十幾次，但內容還是沒有涵蓋您的所有問題？或許其他人也有相同的感受：請在 Stack Overflow 上與他們交流。

前往 Stack Overflow

發現錯誤或缺少功能？

AMP 專案非常鼓勵您參與及貢獻！我們希望您能成為我們開放原始碼社群的長期參與者，但我們也歡迎針對您特別關心的問題提供一次性貢獻。

前往 GitHub