ما هي حزمة أدوات Places UI Kit وكيف يمكن استخدامها لإنشاء حلول جذابة؟

مقدمة

بالنسبة إلى ملايين المستخدمين حول العالم، تشكّل "خرائط Google" المصدر الأساسي للحصول على معلومات دقيقة وحديثة عن الأماكن. توفّر قاعدة بيانات Google الغنية التي تضم أكثر من 250 مليون مكان حول العالم، بما في ذلك مراجعات المستخدمين وصورهم وتقييماتهم، مستوى لا مثيل له من التفاصيل والموثوقية. لتقديم بيانات جديدة ودقيقة، نجري 100 مليون تعديل على الخريطة كل يوم.

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

المكونات

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

  • تفاصيل المكان: يعرض هذا المكوّن معلومات تفصيلية حول مكان معيّن، مثل اسمه وعنوانه ورقم هاتفه وموقعه الإلكتروني وساعات عمله ومراجعات المستخدمين.

  • البحث عن أماكن: يعرض هذا المكوّن قائمة بالأماكن القريبة حسب الفئة أو من خلال البحث بنص حر.

  • الإكمال التلقائي الأساسي للأماكن: ينشئ هذا المكوّن حقل إدخال نصي، ويعرض قائمة منسدلة بالأماكن المتوقّعة التي تتطابق مع الإدخال.

مكوّنات حزمة أدوات Places UI Kit

المزايا الرئيسية لحزمة أدوات Places UI Kit

  • سهولة الاستخدام: يمكنك دمج تجربة المستخدم الموثوقة من Google في Places في تطبيقاتك باستخدام الحد الأدنى من الرموز البرمجية.

  • الاستخدام على أي خريطة: للمرة الأولى، يمكنك استخدام محتوى "الأماكن" على خريطة غير تابعة لـ Google.

  • واجهة مستخدم مألوفة: توفّر المكوّنات واجهة مستخدم تتوافق مع تجربة "خرائط Google"، ما يجعلها سهلة الاستخدام.

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

  • فعّالية التكلفة: يمكن أن تكون Places UI Kit حلاً أكثر فعالية من حيث التكلفة مقارنةً باستخدام Places API مباشرةً.

حالات الاستخدام الواقعية

يمكن استخدام Places UI Kit في مجموعة متنوعة من التطبيقات لتحسين تجربة المستخدم.

  • تطبيقات استكشاف الأماكن المحلية: يمكن لتطبيق "أماكن مقترَحة" استخدام مكوّن "البحث عن الأماكن" لعرض قائمة بالمطاعم أو المقاهي أو مناطق الجذب القريبة. عندما يختار المستخدم مكانًا من القائمة، يمكن استخدام مكوّن "تفاصيل المكان" لعرض المزيد من المعلومات حول هذا الموقع الجغرافي.

  • تطبيقات التخطيط للسفر: يمكن لتطبيق سفر استخدام خدمة "البحث عن الأماكن" للسماح للمستخدمين بالبحث عن فنادق أو نقاط اهتمام في مدينة معيّنة. يمكن لمكوّن "تفاصيل المكان" بعد ذلك عرض الصور والتقييمات والمراجعات لكل موقع جغرافي للمساعدة في التخطيط.

  • بوابات البحث عن العقارات: يمكن لتطبيق عقارات استخدام مكوّن "البحث عن الأماكن" لعرض فئات مختلفة من الأماكن القريبة لمساعدة مشتري المنازل أو المستأجرين المحتملين على فهم مدى ملاءمة أسلوب الحياة في الحي قبل تحديد موعد للمعاينة.

  • تطبيقات المراسلة ووسائل التواصل الاجتماعي: يمكن لتطبيق مراسلة أو تطبيق على وسائل التواصل الاجتماعي استخدام خدمة "البحث عن الأماكن" للبحث عن أماكن قريبة واقتراحها على المستخدمين لمساعدتهم في العثور على مكان مناسب للقاء. يمكن استخدام مكوّن "تفاصيل المكان" لعرض معلومات الأماكن الغنية بصريًا عندما يشارك المستخدمون الأماكن. باستخدام زر "خرائط Google" المضمّن، يمكن للمستخدمين استكشاف المزيد من المواقع الجغرافية ومعلومات السفر بسهولة ودقة على "خرائط Google".

التخصيص

تخصيص حزمة أدوات Places UI Kit

يمكن تخصيص محتوى مجموعة أدوات واجهة مستخدم "أماكن Google" وأنماطها لتناسب احتياجاتك.

يتيح لك استخدام خصائص CSS المخصّصة، مثل خصائص CSS لمكوّن "تفاصيل المكان"، تخصيص شكل المكوّنات ومظهرها بما يتناسب مع تصميم تطبيقك. يمكنك تخصيص الألوان والخطوط والجوانب المرئية الأخرى. من المهم الالتزام بمتطلبات تحديد المصدر عند إجراء تعديلات مرئية. على سبيل المثال، يمكنك تغيير اللون الأساسي المستخدَم للروابط وعدد المراجعات باستخدام السمة --gmp-mat-color-primary CSS.

يمكنك التحكّم في المحتوى المعروض في مكان محدّد باستخدام عنصر gmp-place-content-config متداخل لاختيار المحتوى وتكوينه، أو ببساطة باستخدام gmp-place-all-content لعرض كل المحتوى المتاح.

تتوفّر أداة تخصيص في المستندات لمساعدتك في عرض إعدادات الأنماط المختلفة.

إرشادات التنفيذ

تتوفّر Places UI Kit من خلال JavaScript للخرائط وPlaces SDK لنظامَي التشغيل Android وiOS.

البدء

لبدء استخدام Places UI Kit، عليك اتّباع الخطوات التالية:

  1. إعداد مشروعك على Google Cloud: يجب أن يكون لديك مشروع على Cloud مع حساب فوترة لاستخدام Places UI Kit.

  2. تفعيل حزمة أدوات Places UI Kit: يجب تفعيل حزمة أدوات Places UI Kit لمشروعك.

  3. الحصول على مفتاح واجهة برمجة تطبيقات: يجب الحصول على مفتاح واجهة برمجة تطبيقات للمصادقة على طلباتك.

للحصول على مزيد من التفاصيل الخاصة بكل منصة، يمكنك الاطّلاع على إرشادات البدء في Places UI Kit لكل من JavaScript وAndroid وiOS.

مثال على التنفيذ

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

في ما يلي مقتطفات الرموز. يمكنك العثور على العرض التوضيحي والرمز البرمجي الكامل في مستودع GitHub هذا.

قبل البدء، تأكَّد من إكمال خطوات "البدء" المذكورة أعلاه ذات الصلة بلغة JavaScript.

حمِّل المكتبات المطلوبة في HTML.

<script>
  (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: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

في HTML، أضِف حاوية خريطة وحقل إدخال نص وزر بحث. سيحتوي حاوية الخريطة هذه على الخرائط الديناميكية التي سيتم إنشاؤها في JavaScript. يتيح مربّع الإدخال للمستخدمين كتابة طلبات البحث.

<div id="map-container"></div>
<div class="controls">
    <input type="text" class="query-input" />
    <button class="search-button">Search</button>
</div>

أضِف مكوّن "البحث عن الأماكن". يوفّر مكوّن "بحث الأماكن" تخطيطات أفقية وعمودية. في هذا المثال، نستخدم التصميم الأفقي. تتيح السمة "قابلة للاختيار" إمكانية النقر على عنصر قائمة نتائج البحث (سيتم تفعيل الحدث gmp-select عند النقر).

داخل العنصر gmp-place-search، نضيف عنصرَين فرعيَين:

  • يُستخدم gmp-place-all-content لعرض كل المحتوى المتاح
  • يتم استخدام gmp-place-text-search-request لضبط عنصر "البحث عن الأماكن".

سنضبط الإعدادات في JavaScript في هذا المثال

<div class="list-container">
    <gmp-place-search orientation="horizontal" selectable>
         <gmp-place-all-content></gmp-place-all-content>  
         <gmp-place-text-search-request></gmp-place-text-search-request>
    </gmp-place-search>
</div>

بعد ذلك، أضِف مكوّن "تفاصيل المكان" المتوفّر في التنسيقات المضغوطة والكاملة، وكلّ منها يتيح استخدام الاتجاهين العمودي والأفقي. يستخدم هذا المثال التنسيق الأفقي المضغوط. كما هو الحال مع مكوّن "البحث عن الأماكن"، نضيف عنصرَين ثانويَين:

  • يشير gmp-place-all-content إلى عرض كل المحتوى المتاح
  • تُستخدَم gmp-place-details-place-request لاختيار مكان.

سنضبط المكان في JavaScript في هذا المثال

<div id="details-container">
     <gmp-place-details-compact orientation="horizontal">
        <gmp-place-details-place-request></gmp-place-details-place-request> 
        <gmp-place-all-content></gmp-place-all-content>
    </gmp-place-details-compact> 
</div>

في JavaScript، استورِد المكتبات التي نحتاج إليها في هذا المثال. تستورد مكتبة Places مكتبة Places UI Kit الخاصة بلغة JavaScript.

const {Map} = await google.maps.importLibrary("maps");
await google.maps.importLibrary("places");
({AdvancedMarkerElement} = await google.maps.importLibrary("marker"));
({LatLngBounds, LatLng} = await google.maps.importLibrary("core"));

إنشاء خرائط ديناميكية

const mapContainer = document.getElementById("map-container");
const mapOptions = {
    center: {lat: 37.422, lng: -122.085},
    zoom: 12 
};
const gMap = new Map(mapContainer, mapOptions);

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

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

const queryInput = document.querySelector(".query-input");
const searchButton = document.querySelector(".search-button");
const placeSearch = document.querySelector("gmp-place-search");
const placeSearchQuery = document.querySelector("gmp-place-text-search-request");
const placeDetails = document.querySelector("gmp-place-details-compact");
const placeRequest = document.querySelector("gmp-place-details-place-request");

placeDetailsPopup = new AdvancedMarkerElement({
    map: null,
    content: placeDetails,
    zIndex: 1
});

searchButton.addEventListener("click", searchPlaces);

function searchPlaces(){    
    if (queryInput.value.trim()) {
        placeSearchQuery.textQuery = queryInput.value.trim();
        placeSearchQuery.locationBias = gMap.getBounds();
        placeSearch.addEventListener('gmp-load', addMarkers, { once: true });
    }
}

async function addMarkers(){
    const bounds = new LatLngBounds();
    placeSearch.places.forEach((place) => {
        let marker = new AdvancedMarkerElement({
            map: gMap,
            position: place.location
        });
        bounds.extend(place.location);
        marker.addListener('click',(event) => {
            placeRequest.place = place;
            placeDetails.style.display = 'block';
            placeDetailsPopup.position = place.location;
            placeDetailsPopup.map = gMap;
            gMap.fitBounds(place.viewport, {top: 200, left: 100});
        });
        gMap.setCenter(bounds.getCenter());
        gMap.fitBounds(bounds);
    });
}

احرص على الاطّلاع على العرض التوضيحي والرمز البرمجي الكامل في مستودع GitHub هذا.

مراجع لمساعدتك في إنشاء المحتوى

المساهمون

المؤلفون الرئيسيون:

تيريزا تشين | مهندسة حلول في "منصة خرائط Google"