Place Details 元素和 Place Details 密集元素是 HTML 元素,可轉譯地點詳細資料:
-
PlaceDetailsElement支援所有可視覺化的地點資料,且可能包含多張相片。 -
PlaceDetailsCompactElement旨在盡可能減少空間,並顯示地點的簡明資訊,包括名稱、地址、評分等。此外,也可能包含一張相片。
使用自訂工具,以視覺化方式呈現不同屬性組合對 Place Details 元素外觀的影響,並存取 HTML/CSS、Kotlin/XML 和 Swift 程式碼。
代理應用程式的權杖
有了代理資料視覺化權杖,代理應用程式就能在地圖體驗代理工具 (舊稱 Maps Grounding Lite) 回應中,顯示地點的 Places UI Kit 元素,不需額外付費。詳情請參閱「代理式資料視覺化權杖」。
Place Details 元素
按一下地圖上的標記,即可在 Place Details 元素中查看地點詳細資料。
PlaceDetailsElement 支援多種內容元素,包括完整營業時間、熱門時段、網站、電話號碼、AI 摘要 (可備用編輯摘要)、特定類型重點、評論、AI 評論摘要、Plus Code 和功能清單。
如要在地圖上顯示地點詳細資料,請在 HTML 網頁的 gmp-map 元素中加入 gmp-place-details 元素。加入子元素 gmp-place-details-place-request 來選取地點。可以是地點物件、地點 ID 或地點的資源名稱:
<gmp-map center="47.759737, -122.250632" zoom="16" map-id="DEMO_MAP_ID">
<div class="widget-container" slot="control-inline-start-block-start">
<gmp-place-details>
<gmp-place-details-place-request place="ChIJC8HakaIRkFQRiOgkgdHmqkk"></gmp-place-details-place-request>
<gmp-place-all-content></gmp-place-all-content>
</gmp-place-details>
</div>
<gmp-advanced-marker></gmp-advanced-marker>
</gmp-map>設定內容
您可以透過巢狀子元素選取及設定 Place Details,藉此控制 gmp-place-details 元素顯示的特定地點內容,如以下範例所示:
<gmp-place-details>
<gmp-place-details-place-request
place="ChIJC8HakaIRkFQRiOgkgdHmqkk"></gmp-place-details-place-request>
<gmp-place-name></gmp-place-name>
<gmp-place-address></gmp-place-address>
<gmp-place-rating></gmp-place-rating>
<gmp-place-type></gmp-place-type>
<gmp-place-price></gmp-place-price>
<gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
<gmp-place-opening-hours></gmp-place-opening-hours>
<gmp-place-popular-times></gmp-place-popular-times>
<gmp-place-website></gmp-place-website>
<gmp-place-phone-number></gmp-place-phone-number>
<gmp-place-summary></gmp-place-summary>
<gmp-place-type-specific-highlights></gmp-place-type-specific-highlights>
<gmp-place-review-summary></gmp-place-review-summary>
<gmp-place-reviews></gmp-place-reviews>
<gmp-place-feature-list></gmp-place-feature-list>
</gmp-place-details>
每個子項內容元素都會選取要顯示的對應 Place Details:gmp-place-address 會選取地點的地址,gmp-place-price 則會選取地點的價格等級等。gmp-place-summary 和 gmp-place-review-summary 元素則分別提供 AI 輔助的地點摘要和評論。子項元素的順序並不重要,因為所選詳細資料一律會按照預先定義的固定順序顯示。系統只會顯示您加入的內容元素,因此請加入 gmp-place-name 來顯示地點名稱。
其中部分元素可使用內容專屬屬性進一步設定:
-
gmp-place-media元素用於顯示單張相片,並包含lightbox-preferred屬性,點選後會在燈箱中開啟相片。Lightbox 預設為停用。 -
gmp-place-attribution元素用於顯示相片來源。light-scheme-color和dark-scheme-color屬性用於設定淺色和深色模式下的作者資訊文字顏色。
如要進一步瞭解所有支援的內容元素,請參閱Place Widgets 內容自訂參考文件。
為求簡化,您也可以使用 gmp-place-all-content 顯示 Place Details 元素中所有可用的詳細資料,或使用 gmp-place-standard-content 顯示標準設定。這兩個元素都包含地點名稱。
熱門時段
gmp-place-popular-times 元素會在「總覽」分頁的營業時間下方,顯示熱門時段和人潮資訊:
- 一週中每天每小時的繁忙度互動式直方圖,預設為地點目前的當地日期。
- 目前人潮狀態 (如有即時人潮資訊,則顯示「即時:人潮比平常多」等資訊,或顯示一般歷來人潮資訊),以及目前時段的一般等待時間。
- 所選日期的最長等待時間 (如有)。
在 gmp-place-details 元素上使用 gmp-place-all-content 或 gmp-place-standard-content 時,系統會自動加入熱門時段,您也可以將 gmp-place-popular-times 做為 gmp-place-details 的直接子項。gmp-place-popular-times 元素僅支援完整的 PlaceDetailsElement 和 AdvancedPlaceDetailsElement (不支援 PlaceDetailsCompactElement、AdvancedPlaceDetailsCompactElement 或已淘汰的 gmp-place-content-config 元素)。
並非所有地點都有熱門時段資料。如果地點沒有熱門時段資料,系統會略過該部分,不會顯示錯誤。如要檢查是否已顯示熱門時段資料,請在父項元素觸發 gmp-load 事件後,使用 PlacePopularTimesElement 的唯讀 rendered 屬性:
const detailsElement = document.querySelector('gmp-place-details'); const popularTimesElement = detailsElement.querySelector('gmp-place-popular-times'); detailsElement.addEventListener('gmp-load', () => { console.log('Popular times rendered:', popularTimesElement.rendered); });
您可以使用 --gmp-popular-times-bar-color、--gmp-popular-times-bar-current-hour-color 和 --gmp-popular-times-bar-current-hour-live-color CSS 屬性,自訂熱門時段直方圖長條和即時繁忙度指標的顏色。詳情請參閱「Places UI Kit 自訂樣式」。
設定外觀
gmp-place-details 元素的建議寬度範圍為 250px 至 400px。如果寬度小於 250 像素,可能無法正確顯示。請根據應用程式設定高度。Place Details 元素會視需要,在分配的空間內捲動。
gmp-place-details 元素也支援多種自訂 CSS 屬性,可用來設定元素的顏色和字型。詳情請參閱「Places UI Kit 自訂樣式」。
查看完整程式碼範例
JavaScript
// Use querySelector to select elements for interaction. const map = document.querySelector('gmp-map'); const placeDetails = document.querySelector('gmp-place-details'); const placeDetailsRequest = document.querySelector( 'gmp-place-details-place-request' ); const marker = document.querySelector('gmp-advanced-marker'); async function init() { // Request needed libraries. await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('marker'), google.maps.importLibrary('places'), ]); // Hide the map type control. map.innerMap.setOptions({ mapTypeControl: false }); // Function to update map and marker based on place details const updateMapAndMarker = () => { if (placeDetails.place?.location) { map.innerMap.panTo(placeDetails.place.location); map.innerMap.setZoom(16); // Set zoom after panning if needed marker.position = placeDetails.place.location; marker.collisionBehavior = 'REQUIRED_AND_HIDES_OPTIONAL'; marker.style.display = 'block'; } }; // Set up map once widget is loaded. placeDetails.addEventListener('gmp-load', () => { updateMapAndMarker(); }); // Add an event listener to handle clicks. map.innerMap.addListener('click', (event) => { marker.position = null; event.stop(); if ('placeId' in event && event.placeId) { // Fire when the user clicks a POI. placeDetailsRequest.place = event.placeId; updateMapAndMarker(); } else { // Fire when the user clicks the map (not on a POI). console.log('No place was selected.'); marker.style.display = 'none'; } }); } void init();
CSS
/* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; } .container { display: flex; height: 100vh; width: 100%; } gmp-map { flex-grow: 1; } .ui-panel { width: 400px; margin-left: 20px; margin-top: 10px; } gmp-place-details { width: 100%; margin: 0; border: none; }
HTML
<!doctype html>
<html>
<head>
<title>Place Details with Google Maps</title>
<meta charset="utf-8" />
<link rel="stylesheet" type="text/css" href="style.css" />
<script type="module" src="./index.js"></script>
<script>
// prettier-ignore
(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
key: "GOOGLE_MAPS_API_KEY"
});
</script>
</head>
<body>
<div class="container">
<!-- map-id is required to use advanced markers. See https://developers.google.com/maps/documentation/javascript/map-ids/mapid-over. -->
<gmp-map zoom="17" map-id="DEMO_MAP_ID">
<gmp-advanced-marker></gmp-advanced-marker>
</gmp-map>
<div class="ui-panel">
<gmp-place-details>
<gmp-place-details-place-request
place="ChIJC8HakaIRkFQRiOgkgdHmqkk"></gmp-place-details-place-request>
<gmp-place-content-config>
<gmp-place-address></gmp-place-address>
<gmp-place-rating></gmp-place-rating>
<gmp-place-type></gmp-place-type>
<gmp-place-price></gmp-place-price>
<gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
<gmp-place-opening-hours></gmp-place-opening-hours>
<gmp-place-website></gmp-place-website>
<gmp-place-phone-number></gmp-place-phone-number>
<gmp-place-summary></gmp-place-summary>
<gmp-place-type-specific-highlights></gmp-place-type-specific-highlights>
<gmp-place-review-summary></gmp-place-review-summary>
<gmp-place-reviews></gmp-place-reviews>
<gmp-place-feature-list></gmp-place-feature-list>
</gmp-place-content-config>
</gmp-place-details>
</div>
</div>
</body>
</html>試用範例
Place Details Compact 元素
按一下地圖上的標記,即可在 Place Details Compact Element 中查看地點詳細資料。
PlaceDetailsCompactElement 會使用最少的空間,顯示所選地點的詳細資料。這項功能可用於在地圖上醒目顯示地點的資訊視窗、在即時通訊中分享位置等社群媒體體驗、建議選取目前位置,或在媒體文章中參照 Google 地圖上的地點。PlaceDetailsCompactElement 可顯示名稱、地址、評分、類型、價格、無障礙圖示、營業狀態和單張相片。可根據 orientation 屬性選取的值,水平或垂直顯示。
在下列程式碼片段中,gmp-place-details-compact 已設定為 orientation 設為 horizontal。另一個屬性 truncation-preferred 會截斷特定內容,使其顯示在單行中,而不是換行。gmp-place-details-compact 元素包含子元素 gmp-place-details-place-request,用於選取地點。可以是地點物件、地點 ID 或地點的資源名稱。
<gmp-place-details-compact orientation="horizontal" truncation-preferred>
<gmp-place-details-place-request place="ChIJC8HakaIRkFQRiOgkgdHmqkk"></gmp-place-details-place-request>
<gmp-place-all-content></gmp-place-all-content>
</gmp-place-details-compact>設定內容
您可以透過巢狀子元素,選取及設定地點詳細資料,藉此控制 gmp-place-details-compact 元素顯示的特定地點內容,如以下程式碼片段所示:
<gmp-place-details-compact orientation="horizontal" truncation-preferred> <gmp-place-details-place-request place="ChIJC8HakaIRkFQRiOgkgdHmqkk"></gmp-place-details-place-request> <gmp-place-media lightbox-preferred></gmp-place-media> <gmp-place-name></gmp-place-name> <gmp-place-rating></gmp-place-rating> <gmp-place-type></gmp-place-type> <gmp-place-price></gmp-place-price> <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon> <gmp-place-open-now-status></gmp-place-open-now-status> <gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution> </gmp-place-details-compact>
每個子項內容元素都會選取要顯示的對應地點詳細資料。子項元素的順序無關緊要,因為所選詳細資料一律會按照預先定義的固定順序顯示。系統只會顯示您加入的內容元素,因此請加入 gmp-place-name 來顯示地點名稱。其中部分元素可使用內容專屬屬性進一步設定。
如要進一步瞭解所有支援的內容元素,請參閱Place Widgets 內容自訂參考文件。
為求簡化,您也可以使用 gmp-place-all-content 顯示 Place Details Compact 元素中所有可用的詳細資料,或使用 gmp-place-standard-content 顯示標準設定。這兩個元素都包含地點名稱。
設定外觀
直向 gmp-place-details-compact 元素的建議寬度範圍為 180px 至 300px。寬度小於 160 像素可能無法正確顯示。請勿設定固定高度。
水平方向的 gmp-place-details-compact 元素建議寬度範圍為 180px 至 500px。寬度小於 160 像素可能無法正確顯示。如果寬度小於 350 像素,系統就不會顯示縮圖。請勿設定固定高度。
gmp-place-details-compact 元素也支援多種自訂 CSS 屬性,可用於設定元素的顏色和字型。詳情請參閱「Places UI Kit 自訂樣式」。
請注意,如果將 Place Details 密集元素加入資訊視窗,則必須直接對 gmp-place-details-compact 元素套用自訂樣式。這是因為資訊視窗是地圖 Shadow DOM 的一部分,因此不會套用外部 CSS 樣式。
<gmp-place-details-compact
orientation="horizontal"
truncation-preferred
style="
width: 400px;
padding: 0;
margin: 0;
border: none;
background-color: transparent;
color-scheme: light;
">
<gmp-place-details-place-request
place="ChIJC8HakaIRkFQRiOgkgdHmqkk"></gmp-place-details-place-request>查看完整程式碼範例
本範例示範如何使用 InfoWindow 和 AdvancedMarkerElement,以程式輔助方式在地圖中加入 PlaceDetailsCompactElement。
JavaScript
// Use querySelector to select elements for interaction. const map = document.querySelector('gmp-map'); const placeDetails = document.querySelector('gmp-place-details-compact'); const placeDetailsRequest = document.querySelector( 'gmp-place-details-place-request' ); const marker = document.querySelector('gmp-advanced-marker'); async function init() { // Request needed libraries. void Promise.all([ google.maps.importLibrary('marker'), google.maps.importLibrary('places'), ]); const { InfoWindow } = await google.maps.importLibrary('maps'); await window.customElements.whenDefined('gmp-map'); // Set the inner map options. map.innerMap.setOptions({ mapTypeControl: false, streetViewControl: false, }); await window.customElements.whenDefined('gmp-advanced-marker'); marker.collisionBehavior = 'REQUIRED_AND_HIDES_OPTIONAL'; const infoWindow = new InfoWindow(); infoWindow.addListener('close', () => { marker.position = null; }); const showInfoWindow = () => { if (infoWindow.isOpen) return; infoWindow.setContent(placeDetails); infoWindow.open({ anchor: marker }); }; placeDetails.addEventListener('gmp-load', () => { // For the initial load case, with no user click, we fall back to the place's location, and ensure the map has a center set and the InfoWindow is show. // (The clicked POI LatLng will be a more natural marker position, when available.) if (!map.center && placeDetails.place?.location) { map.center = marker.position = placeDetails.place.location; showInfoWindow(); } }); // Add an event listener to handle clicks. map.innerMap.addListener('click', (event) => { event.stop(); if ('placeId' in event) { // When the user clicks a POI. marker.position = event.latLng; placeDetailsRequest.place = event.placeId; showInfoWindow(); } else { // When the user clicks the map (not on a POI). marker.position = null; placeDetailsRequest.place = null; console.log('No place was selected.'); } }); } void init();
CSS
/* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; } .container { display: flex; height: 100vh; width: 100%; } gmp-map { flex-grow: 1; }
HTML
<!doctype html>
<html>
<head>
<title>Place Details Compact with Google Maps</title>
<meta charset="utf-8" />
<link rel="stylesheet" type="text/css" href="style.css" />
<script type="module" src="./index.js"></script>
<script>
// prettier-ignore
(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
key: "GOOGLE_MAPS_API_KEY"
});
</script>
</head>
<body>
<div class="container">
<!-- map-id is required to use Advanced Markers. See https://developers.google.com/maps/documentation/javascript/map-ids/mapid-over. -->
<gmp-map zoom="17" map-id="DEMO_MAP_ID">
<gmp-advanced-marker></gmp-advanced-marker>
</gmp-map>
</div>
<!--
The gmp-place-details-compact element is styled inline because it is
conditionally rendered and moved into the info window, which is
part of the map's shadow DOM.
-->
<gmp-place-details-compact
orientation="horizontal"
truncation-preferred
style="
width: 400px;
padding: 0;
margin: 0;
border: none;
background-color: transparent;
color-scheme: light;
">
<gmp-place-details-place-request
place="ChIJC8HakaIRkFQRiOgkgdHmqkk"></gmp-place-details-place-request>
<gmp-place-content-config>
<gmp-place-media lightbox-preferred></gmp-place-media>
<gmp-place-rating></gmp-place-rating>
<gmp-place-type></gmp-place-type>
<gmp-place-price></gmp-place-price>
<gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
<gmp-place-open-now-status></gmp-place-open-now-status>
<gmp-place-attribution
light-scheme-color="gray"
dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-content-config>
</gmp-place-details-compact>
</body>
</html>