حزمة أدوات Places UI Kit: هي مكتبة جاهزة للاستخدام تتيح للمطوّرين إمكانية التخصيص والتحكّم. ننصحك بتجربتها ومشاركة ملاحظاتك حول تجربتك مع حزمة واجهة المستخدم.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

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

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

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

يتيح 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 التي تفتح الصورة في عرض مبسط عند النقر عليها. تكون ميزة Lightbox غير مفعَّلة تلقائيًا.
يُستخدم العنصر 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();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"></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>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 نفسه على عدد من عناصر المحتوى الثانوية، ويختار كل عنصر تفاصيل مكان ذات صلة لعرضها. لا يهم ترتيب العناصر الفرعية، لأنّ التفاصيل المحدّدة يتم عرضها دائمًا بترتيب ثابت ومحدّد مسبقًا. يمكن ضبط بعض هذه العناصر بشكل أكبر باستخدام سمات خاصة بالمحتوى.

لتبسيط الأمر، يمكن استبدال العنصر 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. ويرجع ذلك إلى أنّ نافذة المعلومات هي جزء من 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 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();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"></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>index.html

عناصر تفاصيل المكان تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

ضبط المحتوى

ضبط المظهر

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

JavaScript

CSS

HTML

العنصر المضغوط لتفاصيل المكان

ضبط المحتوى

ضبط المظهر

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

JavaScript

CSS

HTML

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