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

عنصر "تفاصيل المكان" وعنصر "تفاصيل المكان المدمج" هما عنصرا HTML يعرضان تفاصيل مكان معيّن:

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

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

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

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

لعرض تفاصيل المكان على خريطة، أضِف عنصر 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-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-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>

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

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

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

لمزيد من المعلومات عن جميع عناصر المحتوى المتوافقة، يُرجى الاطّلاع على المستندات المرجعية حول تخصيص محتوى &quot;أدوات تحديد الأماكن&quot;.

لتبسيط الأمر، يمكنك أيضًا استخدام 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-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 لعرض اسم المكان. ويمكن ضبط بعض هذه العناصر بشكل أكبر باستخدام سمات خاصة بالمحتوى.

لمزيد من المعلومات عن جميع عناصر المحتوى المتوافقة، يُرجى الاطّلاع على المستندات المرجعية حول تخصيص محتوى &quot;أدوات تحديد الأماكن&quot;.

لتبسيط الأمر، يمكنك أيضًا استخدام 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>