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

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

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

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

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

تتيح 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 لعرض جميع التفاصيل المتاحة في العنصر Place Details، أو بالعنصر gmp-place-standard-content لعرض إعدادات عادية.

ضبط المظهر

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

يتوافق العنصر 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 initMap() {
    // 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 && 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 =
                google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;
            marker.style.display = 'block';
        }
    };
    // Set up map once widget is loaded.
    placeDetails.addEventListener('gmp-load', (event) => {
        updateMapAndMarker();
    });
    // Add an event listener to handle clicks.
    map.innerMap.addListener('click', async (event) => {
        marker.position = null;
        event.stop();
        if (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';
        }
    });
}
initMap();
index.js

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;
}
style.css

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" defer></script>
        <!-- prettier-ignore -->
        <script>
      (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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});
    </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>
index.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>
index.html

يحتوي العنصر 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 المخصّصة لضبط ألوان العنصر وخطوطه. راجِع مقالة التصميم المخصّص لحزمة أدوات Places UI Kit لمزيد من التفاصيل.

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

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

يوضّح هذا المثال كيفية إضافة 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 initMap() {
    // Request needed libraries.
    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 =
        google.maps.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', (event) => {
        // 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) {
            map.center = marker.position = placeDetails.place.location;
            showInfoWindow();
        }
    });
    // Add an event listener to handle clicks.
    map.innerMap.addListener('click', async (event) => {
        event.stop();
        if (event.placeId) {
            // 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.');
        }
    });
}
initMap();
index.js

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;
}
style.css

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" defer></script>
        <!-- prettier-ignore -->
        <script>
      (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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});
    </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>
index.html

تجربة عيّنة