عنصر قائمة الأماكن المتقدّم

‫AdvancedPlaceListElement هو عنصر HTML يعرض مجموعة من الأماكن في قائمة استنادًا إلى أسماء موارد الأماكن.

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

الاستخدام الأساسي

لاستخدام المكوّن، أضِف عنصر <gmp-advanced-place-list> إلى صفحتك وأدخِل قائمة بأسماء موارد الأماكن مفصولة بمسافات من خلال السمة places.

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

TypeScript

async function init() {
    await google.maps.importLibrary('places');
    await customElements.whenDefined('gmp-advanced-place-list');
    const listElement = document.querySelector('gmp-advanced-place-list');

    if (listElement) {
        listElement.addEventListener('gmp-error', (e: Event) => {
            const customEvent = e as CustomEvent<{ errors?: unknown }>;
            console.error(
                'Failed to load places: ',
                customEvent.detail.errors ?? customEvent
            );
        });
    }
}

void init();

JavaScript

async function init() {
    await google.maps.importLibrary('places');
    await customElements.whenDefined('gmp-advanced-place-list');
    const listElement = document.querySelector('gmp-advanced-place-list');

    if (listElement) {
        listElement.addEventListener('gmp-error', (e) => {
            const customEvent = e;
            console.error(
                'Failed to load places: ',
                customEvent.detail.errors ?? customEvent
            );
        });
    }
}

void init();

CSS

html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
    font-family: Roboto, Arial, sans-serif;
}

HTML

<!doctype html>
<html>
    <head>
        <title>Advanced Place List</title>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <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",
                v: "beta"
            });
        </script>
    </head>
    <body>
        <gmp-advanced-place-list
            places="places/ChIJLU7jZClu5kcR4PcOOO6p3I0 places/ChIJrRMgU7ZhLxMRxAOFkC7I8Sg places/ChIJbf8C1yFxdDkR3n12P4DkKt0 places/ChIJPTacEpBQwokRKwIlDXelxkA places/ChIJVVVViV-abZERJxqgpA43EDo">
            <template slot="details-item">
                <gmp-place-name></gmp-place-name>
                <gmp-place-address></gmp-place-address>
                <gmp-place-media query="coffee"></gmp-place-media>
            </template>
        </gmp-advanced-place-list>
    </body>
</html>

الميزات المتقدمة

تخصيص أزرار الإجراءات

أضِف أزرار الإجراءات كعناصر فرعية داخل عنصر <template slot="details-item"> في مكوّن "قائمة الأماكن المتقدّمة". استخدِم <gmp-place-link> للاتصالات التنقّلية العادية، وحدِّد السمة action بشكل صريح. يمكنك تحديد السمة slot اختياريًا. الإجراءات المحدّدة مسبقًا الصالحة هي open-website وopen-directions وopen-map وcall. في حال حذف السمة slot، يتم ضبطها تلقائيًا على action-main.

<gmp-advanced-place-list places="places/ChIJT7FdmYiAhYAROFOvrIxRJDU">
  <template slot="details-item">
    <gmp-place-name></gmp-place-name>
    <gmp-place-link action="open-website" target="_blank"></gmp-place-link>
    <gmp-place-link action="open-directions" slot="action-corner"></gmp-place-link>
  </template>
</gmp-advanced-place-list>

ضبط إعدادات تحديد مصدر المكان

لضبط الإحالة المرئية، أضِف عنصر <gmp-place-attribution> لعرض إعدادات إحالة بيانات Maps API الشاملة، مثل مصدر صورة أو مراجعة. ويجب إضافته كعنصر شقيق مباشر لـ <template>. سيتم تجاهل معلومات تحديد المصدر الموضوعة داخل العنصر <template>.

<gmp-advanced-place-list places="places/ChIJT7FdmYiAhYAROFOvrIxRJDU">
  <template slot="details-item">
    <gmp-place-name></gmp-place-name>
  </template>
  <gmp-place-attribution light-scheme-color="black" dark-scheme-color="gray"></gmp-place-attribution>
</gmp-advanced-place-list>

معالجة الأخطاء

يمكنك الاستماع إلى الحدث gmp-error للتعامل بسلاسة مع السيناريوهات التي يتعذّر فيها تحميل مكان واحد أو أكثر من الأماكن المطلوبة.

const listElement = document.querySelector('gmp-advanced-place-list');
listElement.addEventListener('gmp-error', (e) => {
  // e.detail.errors contains an array of failure objects with specific failed Resource Names
  console.error('Failed to load places: ', e.detail.errors);
});