عنصر فهرست مکان پیشرفته

‫ AdvancedPlaceListElement یک عنصر HTML است که مجموعه‌ای از مکان‌ها را در فهرستی براساس «نام‌های منبع مکان» آن‌ها ارائه می‌دهد.

«عنصر فهرست مکان پیشرفته» ویژگی‌های پیشرفته ارائه می‌دهد، ازجمله سفارشی‌سازی دکمه‌های کنش، پیکربندی ارجاع «مکان»، و رسیدگی به خطاها.

کدها برای برنامه‌های عامل‌گرا

بااستفاده از کد دیداری‌سازی داده‌های عامل، برنامه عامل شما می‌تواند عناصر «کیت میانای کاربر جاها» را برای مکان‌های موجود در پاسخ ابزارهای عامل Maps Experience (‏Maps Grounding Lite سابق) بدون هزینه اضافی نمایش دهد. برای اطلاعات بیشتر، به نشان داده‌نمایی عاملی مراجعه کنید.

استفاده پایه

برای استفاده از مؤلفه، عنصر <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>

مدیریت کردن خطاها

You can listen for the gmp-error event to gracefully handle scenarios when one or more requested places fail to load.

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);
});