重要事項：本文件不適用於您目前選取的格式廣告！

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 元件判斷要求來自美國州或哥倫比亞特區 (華盛頓 DC) 時，會提供 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 設定鍵為 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 位址的小寫 2 字母 ISO 3166-1 alpha-2 國家/地區代碼。這個值應填補到符合原始長度，以避免破壞 amp-geo-0.1.max.js.map 檔案。如果無法判斷國家/地區，「unknown」國家/地區可以透過讓檔案保持未修補，或使用長度相等的空格字串進行修補來表示。

偵錯

將 #amp-geo=XX 新增至文件網址會強制國家/地區顯示為國家/地區 XX。這可讓您進行測試，而無需 VPN 連線到國家/地區。基於安全考量，為了防止共用地理位置詐騙網址，此功能僅適用於已啟用實驗性管道或在本地端測試的使用者 (亦即，amp-geo.js 是在開發模式中透過 amp serve 提供)。

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

驗證

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

需要更多協助嗎？

您已閱讀本文件十幾次，但它仍然沒有真正涵蓋您的所有問題？也許其他人也有相同感受：請在 Stack Overflow 上與他們聯繫。

前往 Stack Overflow

發現錯誤或缺少功能？

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

前往 GitHub