عنصر "البحث المتقدّم عن الأماكن" (معاينة)

‫AdvancedPlaceSearchElement هو عنصر HTML يعرض نتائج البحث عن مكان في قائمة. هناك طريقتان لإعداد العنصر gmp-advanced-place-search:

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

طلب البحث في الأماكن القريبة

اختَر نوع مكان من القائمة للاطّلاع على نتائج البحث القريبة لهذا النوع من الأماكن.

تم إعداد البحث القريب بشكل أساسي للبحث حسب نوع المكان والموقع الجغرافي، ويمكن ترتيب النتائج حسب المسافة أو حسب مدى الرواج باستخدام السمة rankPreference. لمزيد من التفاصيل، يُرجى الاطّلاع على PlaceNearbySearchRequestElement مستندات مرجع الفئة.

يعرض هذا المثال عنصر "بحث متقدّم عن الأماكن" استجابةً لعملية بحث بالقرب من المستخدم مع تحديد نوع المكان من قِبل المستخدم. تعرض هذه السمة أيضًا AdvancedPlaceDetailsCompactElement للمكان المحدّد.

لإضافة عنصر "البحث المتقدّم عن الأماكن" إلى الخريطة، أضِف عنصر gmp-advanced-place-search مع عنصر gmp-place-nearby-search-request متداخل إلى صفحة HTML. 

<gmp-advanced-place-search selectable>
    <!-- Nearby search requests require a location restriction to return results. Often set programmatically. -->
    <gmp-place-nearby-search-request max-result-count="5"></gmp-place-nearby-search-request>
    <template slot="place-list-item">
        <gmp-place-all-content></gmp-place-all-content>
    </template>
</gmp-advanced-place-search>

يتيح العنصر select للمستخدم اختيار نوع مكان من القائمة. لتبسيط الأمر، يتم إدراج ثلاثة أنواع من الأماكن فقط: مطعم ومقهى ومحطة شحن للسيارات الكهربائية. 

<div class="controls">
    <label for="type-select">
        Select a place type:
        <select id="type-select" class="type-select">
            <option value="restaurant">Restaurant</option>
            <option value="cafe" selected>Cafe</option>
            <option value="electric_vehicle_charging_station">
                EV charging station
            </option>
        </select>
    </label>
</div>

عندما يختار المستخدم نوع مكان من القائمة، يتم تعديل العنصر gmp-place-nearby-search-request، ويعرض العنصر &quot;البحث المتقدم عن الأماكن&quot; النتائج.

طلب البحث حسب النص

أدخِل عبارة بحث في حقل الإدخال وانقر على زر بحث للحصول على قائمة بالأماكن التي تتطابق مع عبارة البحث.

تم إعداد البحث النصي بشكل أساسي للبحث باستخدام طلب بحث نصي وموقع جغرافي، ويمكن تحسين النتائج حسب مستوى السعر والتقييم وما إذا كان المكان مفتوحًا حاليًا. يمكن أيضًا ترتيب النتائج حسب المسافة أو حسب مدى الرواج باستخدام السمة rankPreference. لمزيد من التفاصيل، يُرجى الاطّلاع على PlaceTextSearchRequestElement مستندات مرجع الفئة.

يعرض هذا المثال عنصر &quot;البحث المتقدّم عن الأماكن&quot; استجابةً لإدخال نصي من المستخدم. يعرض أيضًا AdvancedPlaceDetailsCompactElement للمكان المحدّد.

لإضافة عنصر &quot;البحث المتقدّم عن الأماكن&quot; إلى الخريطة، أضِف عنصر gmp-advanced-place-search مع عنصر gmp-place-text-search-request متداخل إلى صفحة HTML. 

<gmp-advanced-place-search selectable>
    <gmp-place-text-search-request max-result-count="5"></gmp-place-text-search-request>
    <template slot="place-list-item">
        <gmp-place-all-content></gmp-place-all-content>
    </template>
</gmp-advanced-place-search>

يسمح العنصر input للمستخدم بإدخال نص البحث. 

<div class="controls">
    <input
        type="text"
        id="query-input"
        class="query-input"
        placeholder="Search for a place"
        value="cafe" />
    <button id="search-button" class="search-button">
        Search
    </button>
</div>

عندما ينقر المستخدم على زر بحث، يتم تنفيذ وظيفة البحث، ويتم تعديل العنصر gmp-place-text-search-request، ويعرض العنصر &quot;بحث متقدّم عن الأماكن&quot; النتائج.

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

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

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

<gmp-advanced-place-search selectable>
  <gmp-place-text-search-request text-query="pizza" max-result-count="5"></gmp-place-text-search-request>
  <template slot="place-list-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-search>

فلترة المراجعات والوسائط

لا تعرض عيّنة الرمز هذه سوى الوسائط والمراجعات التي تتضمّن كلمة "قهوة".

<gmp-advanced-place-search selectable>
  <gmp-place-text-search-request text-query="pizza" max-result-count="5"></gmp-place-text-search-request>
  <template slot="place-list-item">
    <gmp-place-name></gmp-place-name>
    <gmp-place-media query="coffee"></gmp-place-media>
    <gmp-place-reviews query="coffee" rank-preference="newest"></gmp-place-reviews>
  </template>
</gmp-advanced-place-search>

إعداد الإحالة إلى المكان

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

<gmp-advanced-place-search selectable>
  <gmp-place-text-search-request text-query="pizza" max-result-count="5"></gmp-place-text-search-request>
  <template slot="place-list-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-search>

التعامل مع اختيار الأماكن والأخطاء

عند توفّر السمة selectable، يمكنك الاستماع إلى الحدث gmp-select لاسترداد المكان الذي اختاره المستخدم. يمكنك أيضًا الاستماع إلى الحدث gmp-error للتعامل بشكل سليم مع الحالات التي يتعذّر فيها جلب بيانات المكان. 

const searchElement = document.querySelector('gmp-advanced-place-search');

searchElement.addEventListener('gmp-select', (e) => {
  console.log('User selected place: ', e.place);
});

searchElement.addEventListener('gmp-error', (e) => {
  // e.detail contains the structured error payload
  console.error('Failed to load places: ', e.detail.error);
});