開始使用

請按照下列步驟將當地特色資料庫加進專案,並進行初始化,然後設定當地特色地圖檢視。

啟用必要的 API 和 SDK

如要使用當地特色資料庫,您必須啟用 Maps JavaScript API 和 Places API,方法是按照操作說明啟用一或多個 API 或 SDK。請注意,您必須在 Google Cloud 控制台的同一個專案中啟用這兩個 API。

載入當地特色資料庫

如要載入當地特色資料庫,請照常載入 Maps JavaScript API,並加入下列參數:

  • libraries=localContext:用於載入當地特色資料庫。
  • v=beta:使用這個版本所需的參數。
  • key:包含您的 API 金鑰。
  • callback:用於執行 initMap() 函式。

下例是包含上述所有選項的指令碼標記:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=localContext&v=beta&callback=initMap">
</script>

建立新的當地特色地圖檢視

如要在網頁中加入當地特色資料庫,請先建立 LocalContextMapView 執行個體,然後設定所需屬性:

  • element:應顯示地圖的 div 元素 (在本例中為「map」)。
  • placeTypePreferences:當地特色資料庫應傳回的地點類型 (最多 10 種)。
  • maxPlaceCount:可顯示的地點數量上限 (1 - 24 個)。
  • locationRestriction (選用):將地點搜尋的範圍限制在特定位置。預設為地圖可視區域。

建立 LocalContextMapView 執行個體後,您就可以在內部 Map 執行個體中設定「地圖選項」。LocalContextMapView 內含的地圖支援與標準 Maps JavaScript API 地圖相同的所有地圖選項。下例說明如何建立新的 LocalContextMapView 執行個體,並在內部 Map 中設定一些選項:

TypeScript

let map: google.maps.Map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map!;

  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

let map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map;
  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

window.initMap = initMap;

延遲載入當地特色資料

如要在初始化時延遲載入當地特色資料,請將 LocalContextMapView maxPlaceCount 選項設為 0。如果您想要等到使用者準備好查看資料後再載入,就很適合採用這種做法。準備好載入當地特色資料時,請將 maxPlaceCount 設為 1 以上的值。下例說明如何在不載入當地特色資料的情況下初始化地圖,然後設定 maxPlaceCount 載入資料:

// Initialize without Local Context data.
const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.querySelector('#map'),
    placeTypePreferences: ['restaurant'],
    maxPlaceCount: 0, // Avoids an automatic call to load places during initialization.
  });

//...

// Show places now.
localContextMapView.maxPlaceCount = 12;

顯示當地特色使用者介面的切換鈕

如要切換當地特色使用者介面元素,請將 LocalContextMapView maxPlaceCount 選項設為 0。如要再次顯示當地特色使用者介面,請將 maxPlaceCount 設為 1 以上的值。

設定地圖尺寸下限

當地特色資料庫會根據算繪出的 LocalContextMapView 尺寸調整顯示畫面。支援的 LocalContextMapView 尺寸下限為:

  • 300 像素 x 480 像素 (直向)
  • 480 像素 x 380 像素 (橫向)

如果 LocalContextMapView 包含的元素尺寸小於支援的尺寸下限,就無法顯示當地特色資料庫元素 (包括地點選擇器和搜尋點)。瀏覽器縮放等級會影響支援的尺寸下限。舉例來說,如果瀏覽器視窗放大為 200%,支援的尺寸下限就是 600 x 960 (直向) 和 960 x 760 (橫向)。

CSS 建議

當地特色資料庫 DOM 中的 CSS 類別不包含在公用 API 中,而且不支援在當地特色資料庫 DOM 中設定元素樣式、修改或選取元素。強烈建議您遵循下列準則,以免 DOM 樣式發生衝突,並確保當地特色資料庫地圖檢視能正確顯示:

  • 請勿使用當地特色資料庫 CSS 類別 (這些類別可能會未在事先通知的情況下隨時變更)。
  • 請勿在當地特色資料庫 DOM 內設定元素樣式、修改或選取元素。

如果您使用的 CSS 架構會進行這類修改,或許就能解決樣式衝突問題。

舉例來說,如要將整體頁面的 box-sizing 改為 border-box,請按照下列步驟操作:

  • 使用 box-sizing 覆寫功能,將 <html> 元素設為 border-box
  • 針對包含當地特色資料庫地圖檢視的元素,使用 box-sizing: initial
  • 針對所有其他元素,使用 box-sizing: inherit

這可確保當地特色資料庫 DOM 使用明確性較低的選取器,將 box-sizing 重設為標準預設值。

程式碼如下所示:

html {
  box-sizing: border-box;
}
*, *::before, *::after {
  box-sizing: inherit;
}

.container-for-google-maps {
  box-sizing: initial;
}