عناصر تفاصيل المكان

اختيار النظام الأساسي: Android iOS JavaScript

إنّ عنصري "تفاصيل المكان" و"تفاصيل المكان المصغّرة" هما عنصرا HTML يعرضان تفاصيل مكان معيّن:

استخدِم أداة التخصيص لتصوُّر كيفية تأثير مجموعات الخصائص المختلفة في مظهر عنصر "تفاصيل المكان" والوصول إلى الرمز البرمجي بتنسيقات HTML/CSS وKotlin/XML وSwift.

عنصر "تفاصيل المكان"

انقر على علامة على الخريطة للاطّلاع على تفاصيل المكان في عنصر "تفاصيل المكان" .

يتوافق PlaceDetailsElement مع مجموعة واسعة من عناصر المحتوى، بما في ذلك ساعات العمل الكاملة، والموقع الإلكتروني ورقم الهاتف، والملخّص المستنِد إلى الذكاء الاصطناعي مع الرجوع إلى الملخّص التحريري والميزات البارزة الخاصة بالنوع والمراجعات، وملخّص المراجعات المستنِد إلى الذكاء الاصطناعي، بالإضافة إلى الرمز البرمجي وقوائم الميزات.

لعرض تفاصيل المكان على خريطة، أضِف عنصر gmp-place-details إلى عنصر gmp-map في صفحة HTML. أدرِج عنصرًا ثانويًا، gmp-place-details-place-request، لاختيار المكان. يمكن أن يكون هذا العنصر كائن مكان أو معرّف مكان أو اسم مورد مكان: 

<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>

إعداد المحتوى

يمكنك التحكّم في محتوى المكان المحدّد الذي يعرضه gmp-place-details باستخدام عنصر gmp-place-content-config متداخل لاختيار تفاصيل المكان وإعدادها، كما هو موضّح في هذا المثال: 

        <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>

يحتوي العنصر gmp-place-content-config نفسه على عدد من عناصر المحتوى الثانوية، ويختار كل منها تفاصيل مكان مقابلة لعرضها: gmp-place-address يختار عنوان المكان، وgmp-place-price يختار مستوى سعر المكان، وما إلى ذلك. يقدّم العنصران gmp-place-summary وgmp-place-review-summary ملخّصًا مستنِدًا إلى الذكاء الاصطناعي للمكان ومراجعاته، على التوالي. لا يهم ترتيب العناصر الثانوية ، لأنّ التفاصيل المحدّدة يتم عرضها دائمًا بترتيب ثابت ومحدّد مسبقًا.

يمكن إعداد بعض هذه العناصر بشكلٍ إضافي باستخدام سمات خاصة بالمحتوى:

  • يُستخدَم عنصر gmp-place-media لعرض صورة واحدة، ويتضمّن سمة lightbox-preferred تفتح الصورة في عرض مبسط عند النقر عليها. العرض المبسط غير مفعّل تلقائيًا.
  • يُستخدَم عنصر gmp-place-attribution لعرض مصدر الصورة. تُستخدَم السمتان light-scheme-color و dark-scheme-color لضبط لون نص الإسناد في الوضعَين الفاتح والداكن.

راجِع PlaceContentConfigElement مستندات المرجع لمزيد من المعلومات عن جميع عناصر المحتوى المتوافقة.

لتبسيط الأمر، يمكن استبدال عنصر gmp-place-content-config بعنصر gmp-place-all-content لعرض جميع التفاصيل المتاحة في عنصر "تفاصيل المكان"، أو بعنصر gmp-place-standard-content لعرض إعدادات عادية.

إعداد المظهر

يتراوح عرض عنصر gmp-place-details المقترَح بين 250 بكسل و400 بكسل. قد لا يتم عرض العروض الأقل من 250 بكسل بشكلٍ صحيح. اضبط الـ ارتفاع ليناسب تطبيقك. تم تصميم عنصر "تفاصيل المكان" بحيث يتم التمرير فيه ضمن المساحة المخصّصة حسب الحاجة.

يتوافق عنصر gmp-place-details أيضًا مع مجموعة متنوعة من خصائص CSS المخصّصة لإعداد ألوان العنصر وخطوطه. راجِع مقالة تخصيص مظهر حزمة أدوات "خرائط Google" الجاهزة للأماكن لمزيد من التفاصيل.

الاطّلاع على مثال الرمز البرمجي الكامل

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>

عنصر "تفاصيل المكان المصغّرة"

انقر على علامة على الخريطة للاطّلاع على تفاصيل المكان في عنصر "تفاصيل المكان المصغّرة" .

يعرض PlaceDetailsCompactElement تفاصيل مكان محدّد باستخدام مساحة قليلة. قد يكون ذلك مفيدًا في نافذة معلومات تبرز مكانًا على خريطة، أو في تجربة على وسائل التواصل الاجتماعي مثل مشاركة موقع جغرافي في محادثة، أو كاقتراح لاختيار موقعك الجغرافي الحالي، أو ضِمن مقالة إعلامية للإشارة إلى المكان على "خرائط Google". يمكن أن يعرض PlaceDetailsCompactElement الاسم والعنوان والتقييم والنوع والسعر ورمز إمكانية الوصول وحالة الفتح وصورة واحدة. ويمكن عرضه أفقيًا أو رأسيًا، حسب ما تحدّده سمة orientation.

في المقتطف التالي، تم إعداد gmp-place-details-compact مع ضبط orientation على horizontal. تؤدي سمة إضافية، وهي truncation-preferred، إلى اقتطاع محتوى معيّن ليناسب سطرًا واحدًا بدلاً من التفافه. يحتوي العنصر gmp-place-details-compact على عنصر ثانوي، وهو gmp-place-details-place-request، لاختيار المكان. يمكن أن يكون هذا العنصر كائن مكان أو معرّف مكان أو اسم مورد مكان. 

  <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-content-config متداخل لاختيار تفاصيل المكان وإعدادها، كما هو موضّح في هذا المقتطف: 

<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-content-config نفسه على عدد من عناصر المحتوى الثانوية، ويختار كل منها تفاصيل مكان مقابلة لعرضها. لا يهم ترتيب العناصر الثانوية، لأنّ التفاصيل المحدّدة يتم عرضها دائمًا بترتيب ثابت ومحدّد مسبقًا. يمكن إعداد بعض هذه العناصر بشكلٍ إضافي باستخدام سمات خاصة بالمحتوى.

راجِع PlaceContentConfigElement مستندات المرجع لمزيد من المعلومات عن جميع عناصر المحتوى المتوافقة.

لتبسيط الأمر، يمكن استبدال عنصر gmp-place-content-config بعنصر gmp-place-all-content لعرض جميع التفاصيل المتاحة في عنصر "تفاصيل المكان المصغّرة"، أو بعنصر gmp-place-standard-content لعرض إعدادات عادية.

إعداد المظهر

يتراوح عرض عنصر gmp-place-details-compact المقترَح في الاتجاه الرأسي بين 180 بكسل و300 بكسل. قد لا يتم عرض العروض الأقل من 160 بكسل بشكلٍ صحيح. لا تضبط ارتفاعًا ثابتًا.

يتراوح عرض عنصر gmp-place-details-compact المقترَح في الاتجاه الأفقي بين 180 بكسل و500 بكسل. قد لا يتم عرض العروض الأقل من 160 بكسل بشكلٍ صحيح. لن يتم عرض الصورة المصغّرة عند العروض الأقل من 350 بكسل. لا تضبط ارتفاعًا ثابتًا.

يتوافق عنصر gmp-place-details-compact أيضًا مع مجموعة متنوعة من خصائص CSS المخصّصة لإعداد ألوان العنصر وخطوطه. راجِع مقالة تخصيص مظهر حزمة أدوات "خرائط Google" الجاهزة للأماكن لمزيد من التفاصيل.

يُرجى العِلم أنّه إذا تمت إضافة عنصر "تفاصيل المكان المصغّرة" إلى نافذة معلومات، يجب تطبيق التنسيق المخصّص مباشرةً على gmp-place-details-compact العنصر. ويرجع ذلك إلى أنّ نافذة المعلومات هي جزء من نموذج 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>

الاطّلاع على مثال الرمز البرمجي الكامل

يوضّح هذا المثال كيفية إضافة PlaceDetailsCompactElement إلى خريطة برمجيًا باستخدام InfoWindow و AdvancedMarkerElement.

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>