کیت UI Places را برای کاربران API مکان‌های موجود بپذیرید

هدف : اجرای Places API یا Place Class خود را با Places UI Kit جایگزین کنید.

این راهنما برای چه کسی است

توسعه دهندگانی که عبارتند از:

  • درخواست HTTP به نقاط پایانی Places API (جدید یا قدیمی).
  • استفاده از کلاس مکان در Maps JavaScript API.
  • مدیریت پاسخ API برای ارائه اطلاعات مکان در UI برنامه وب آنها.

پیش نیازها

Places UI Kit را در پروژه Google Cloud خود فعال کنید. می‌توانید به استفاده از کلید API موجود خود ادامه دهید یا یک کلید جدید برای Places UI Kit ایجاد کنید. برای اطلاعات بیشتر، از جمله محدود کردن کلید ، به استفاده از کلیدهای API مراجعه کنید.

به روز رسانی Maps JavaScript API در حال بارگیری

کیت UI Places به روش Dynamic Library Import برای بارگیری Maps JavaScript API نیاز دارد. اگر از برچسب بارگیری مستقیم اسکریپت استفاده می کنید، این باید به روز شود.

پس از به‌روزرسانی اسکریپت بارگیری برای Maps JavaScript API، کتابخانه‌های مورد نیاز را برای استفاده از Places UI Kit وارد کنید .

عنصر Place Details را پیاده سازی کنید

عنصر Place Details و Place Details Compact Element عناصر HTML هستند که جزئیات یک مکان را ارائه می کنند.

اجرای فعلی

  • شما با استفاده از درخواست HTTP یک تماس با جزئیات مکان انجام می دهید یا از کلاس مکان API جاوا اسکریپت استفاده می کنید.
  • شما پاسخ API را تجزیه می کنید و جزئیات مکان را با استفاده از HTML و CSS نمایش می دهید.

مهاجرت به عنصر جزئیات مکان

تغییر ساختار HTML

محفظه HTML را که در آن جزئیات مکان ارائه می شود، شناسایی کنید. عناصر HTML سفارشی خود را (divs، دهانه نام، آدرس، عکس‌ها و غیره) با html عنصر جزئیات مکان جایگزین کنید.

دو عنصر برای انتخاب وجود دارد:

  • جزئیات مکان عنصر فشرده
  • عنصر جزئیات مکان

برای اطلاعات بیشتر در مورد اینکه کدام یک از آنها استفاده کنید، به عنصر جزئیات مکان مراجعه کنید.

HTML موجود شما ممکن است به این شکل باشد.

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

نمونه HTML جدید، به صراحت بیان می کند که کدام محتوا نمایش داده شود:

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <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-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

منطق جاوا اسکریپت را تطبیق دهید

منطق موجود

منطق موجود شما احتمالاً شامل موارد زیر است:

  • بازیابی شناسه مکان
  • استفاده از PlacesService().getDetails() یا برقراری تماس با سرویس وب.
  • تعیین آرایه فیلدها (برای JS API) یا FieldMask (برای وب سرویس) برای درخواست داده های خاص.
  • در وضوح تماس، عناصر HTML خود را به صورت دستی انتخاب کنید و آنها را با داده های دریافتی پر کنید.

در زیر نمونه‌ای از نحوه پیاده‌سازی جزئیات مکان آمده است:

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}
منطق جدید

منطق جدید شما شامل موارد زیر است:

  • شناسه مکان یا شی مکان خود را بازیابی کنید.
  • یک مرجع به عنصر <gmp-place-details-place-request> دریافت کنید.
  • شناسه مکان یا شی مکان را به ویژگی مکان در عنصر <gmp-place-details-place-request> منتقل کنید.

در زیر نمونه ای از نحوه پیاده سازی کیت Place Details UI در منطق جاوا اسکریپت آورده شده است. مرجعی به عنصر جزئیات مکان دریافت کنید. اگر این وجود دارد، به عنصر Place Details Place Request ارجاع دهید و ویژگی مکان را با استفاده از شناسه مکان تنظیم کنید. در مثال کد HTML بالا، سبک Place Details Element تنظیم شده است که display: none . این برای display: block .

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

عنصر جستجوی مکان یک عنصر HTML است که نتایج جستجوی مکان را در یک لیست نمایش می دهد.

  • شما با استفاده از یک درخواست HTTP یک جستجوی متن یا جستجوی نزدیک انجام می دهید یا از کلاس مکان API جاوا اسکریپت استفاده می کنید.
  • شما با استفاده از FieldMask پارامترهای پرس و جو، محدودیت ها یا بایاس های مکان، انواع و فیلدهای درخواستی را مشخص می کنید.
  • شما پاسخ API را تجزیه می کنید، در میان آرایه مکان ها تکرار می کنید و به صورت دستی آیتم های لیست HTML را ایجاد می کنید.

تغییر ساختار HTML

محفظه HTML را که در آن لیست مکان خود را ارائه می کنید، شناسایی کنید. عناصر HTML سفارشی خود (divs، دهانه نام، آدرس و غیره) را با عنصر html عنصر جستجوی مکان جایگزین کنید.

HTML موجود شما ممکن است چیزی شبیه به این باشد:

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

عنصر جستجوی مکان با استفاده از مولفه <gmp-place-search> پیاده سازی می شود. برای پیکربندی نوع جستجو، یکی از اجزای پیکربندی شکافدار زیر را در داخل قرار دهید:

  • <gmp-place-text-search-request> برای جستجوی متن.
  • <gmp-place-nearby-search-request> برای جستجوی نزدیک.

برای تعریف نحوه نمایش نتایج، می‌توانید از میانبر <gmp-place-all-content> استفاده کنید، یا مجموعه‌ای از مؤلفه‌های ارائه جداگانه را ارائه دهید. ویژگی های کلیدی مانند selectable (برای اجازه دادن به کلیک بر روی موارد لیست) و orientation (برای یک طرح افقی یا عمودی) را می توان مستقیماً روی مؤلفه والد تنظیم کرد.

مثال جستجوی نزدیک 
<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>
نمونه جستجوی متن 
<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>

منطق جاوا اسکریپت را تطبیق دهید

در جاوا اسکریپت خود، با استفاده از document.querySelector() یک مرجع به جزء کنترلر جستجو دریافت کنید. بسته به تنظیمات شما، این عنصر <gmp-place-text-search-request> یا <gmp-place-nearby-search-request> خواهد بود.

در مرحله بعد، ویژگی های این کنترلر را برای تعریف جستجوی شما تنظیم کنید. ویژگی های مورد نیاز به نوع جستجویی که انجام می دهید بستگی دارد.

برای جستجوی متن ( <gmp-place-text-search-request> )، ویژگی اصلی textQuery است:

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

برای جستجوی نزدیک ( <gmp-place-nearby-search-request> )، باید ناحیه جستجو را با استفاده از یک locationRestriction تعریف کنید. سپس می‌توانید از includedTypes برای فیلتر کردن انواع خاصی از مکان‌ها در آن منطقه استفاده کنید:

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

مؤلفه والد <gmp-place-search> به محض تنظیم ویژگی های مورد نیاز کنترلر، به طور خودکار جستجوی جدیدی را آغاز می کند.

  • برای جستجوی متن، جستجو در لحظه ای که مقداری را به textQuery اختصاص می دهید، اجرا می شود.
  • برای جستجوی نزدیک، جستجو پس از ارائه یک locationRestriction معتبر انجام می شود.

عنصر تکمیل خودکار مکان پایه را پیاده سازی کنید

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

این عنصر برای ایجاد یک فیلد ورودی جستجو و در عین حال کنترل کامل بر نحوه نمایش نتایج در رابط کاربری سفارشی شما ایده آل است. مسئولیت انحصاری عنصر تکمیل خودکار ارائه پیش‌بینی مکان هنگام تایپ کاربر و نمایش برنامه‌ای یک شناسه مکان برای مکان انتخابی است.

خود هیچ جزئیاتی را نمایش نمی‌دهد، یا اطلاعات قابل دسترسی برنامه‌نویسی دیگری را ارائه نمی‌دهد.

اجرای فعلی

منطق موجود شما احتمالاً شامل موارد زیر است:

  • ارائه یک فیلد ورودی متنی در صفحه شما که با تایپ کاربر، Place Autocomplete را فراخوانی می کند و نتایج را نمایش می دهد.
  • استفاده از شناسه مکان مکان انتخابی کاربر برای واکشی جزئیات بیشتر، به عنوان مثال با استفاده از API جزئیات مکان.
  • نمایش جزئیات مکان انتخاب شده

مهاجرت به محل عنصر تکمیل خودکار

تغییر ساختار HTML

عنصر HTML را که ویجت تکمیل خودکار را به آن متصل می کنید، شناسایی و حذف کنید. احتمالاً از یک فیلد ورودی استاندارد HTML استفاده می کند. 

<input id="pac-input" type="text" placeholder="Search for a location" />

نمونه HTML جدید، با استفاده از رویکرد مؤلفه وب برای مقداردهی اولیه عنصر تکمیل خودکار مکان اصلی در صفحه شما. 

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

منطق جاوا اسکریپت را تطبیق دهید

منطق جاوا اسکریپت شما احتمالاً شامل ایجاد ویجت تکمیل خودکار متصل به عنصر HTML input است. سپس این ویجت به رویداد place_changed گوش می دهد و با داده های برگشتی اقدامی را آغاز می کند.

نمونه جاوا اسکریپت موجود برای حذف: 

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

منطق جاوا اسکریپت جدید شما مرجعی به عنصر تکمیل خودکار مکان پایه دریافت می کند و به رویدادهای gmp-select گوش می دهد: 

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

با انتخاب یک مکان در منوی کشویی تکمیل خودکار، رویداد gmp-select فعال می‌شود. شناسه مکان مکان انتخاب شده را می توان از شی event بازیابی کرد. سپس از شناسه مکان می توان برای مقداردهی اولیه یک نمونه از عنصر جزئیات مکان برای نمایش جزئیات مکان انتخاب شده استفاده کرد.

سفارشی سازی دسته

جزئیات مکان سفارشی سازی عنصر

جهت گیری

عنصر جزئیات مکان را می توان در هر دو جهت افقی و عمودی ارائه کرد. برای انتخاب بین عمودی و افقی از ویژگی orientation در gmp-place-details-compact استفاده کنید. به عنوان مثال:

<gmp-place-details-compact orientation="vertical">

فیلدهایی را برای ارائه انتخاب کنید

از عناصر محتوا برای تعیین محتوایی که باید در عنصر جزئیات مکان ارائه شود، استفاده کنید. برای مثال، کنار گذاشتن عنصر محتوا <gmp-place-type> باعث می‌شود که عنصر جزئیات مکان، نوع مکان مکان انتخابی را نمایش دهد. برای فهرست کامل عناصر محتوا، به مستندات مرجع PlaceContentConfigElement مراجعه کنید.

افزودن یا حذف فیلدها از عنصر جزئیات مکان، هزینه رندر عنصر در صفحه را تغییر نمی دهد.

سبک های CSS را تنظیم کنید

ویژگی‌های CSS سفارشی برای پیکربندی رنگ‌ها و فونت‌های عنصر موجود است. به عنوان مثال، برای تنظیم پس زمینه عنصر به رنگ سبز، ویژگی CSS زیر را تنظیم کنید: 

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

برای جزئیات بیشتر به مستندات مرجع برای PlaceDetailsCompactElement مراجعه کنید.

سفارشی سازی عنصر جستجوی مکان

جهت گیری

عنصر جستجوی مکان را می توان در هر دو جهت افقی و عمودی ارائه کرد. برای انتخاب بین عمودی و افقی از ویژگی orientation در <gmp-place-search> استفاده کنید. به عنوان مثال: 

<gmp-place-search orientation="horizontal" selectable>

فیلدهایی را برای ارائه انتخاب کنید

از عناصر محتوا برای تعیین محتوایی که باید در عنصر جستجوی مکان ارائه شود، استفاده کنید. عنصر <gmp-place-all-content> را می توان برای نمایش تمام محتوا یا مجموعه ای از تگ های html برای پیکربندی محتوای رندر شده استفاده کرد.

گنجاندن <gmp-place-address> در <gmp-place-content-config> فقط آدرس هر مکان را نشان می دهد، به عنوان مثال: 

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

سفارشی‌سازی عنصر تکمیل خودکار مکان اصلی

سبک های CSS را تنظیم کنید

ویژگی های CSS سفارشی برای سفارشی کردن ظاهر و احساس عنصر تکمیل خودکار در دسترس هستند. به عنوان مثال، برای تنظیم رنگ پس‌زمینه روی بنفش روشن، باید ویژگی background-color روی عنصر تنظیم کنید. 

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

برای جزئیات بیشتر به مستندات مرجع BasicPlaceAutocompleteElement مراجعه کنید.

رویدادها و داده ها را مدیریت کنید

Places UI Kit Elements اجزای تعاملی هستند که به شما امکان می دهند به رویدادها گوش دهید و داده ها را به صورت برنامه ای بازیابی کنید.

به رویدادها گوش دهید

می‌توانید شنونده‌های رویداد را به عناصر اضافه کنید تا اقداماتی را بر اساس تعامل کاربر یا وضعیت عنصر ایجاد کنید.

رویداد انتخاب

  • gmp-select : این رویداد زمانی فعال می شود که کاربر انتخابی را انجام دهد.
    • در عنصر جستجوی مکان، زمانی فعال می شود که کاربر روی مکانی در لیست نتایج کلیک کند.
    • در عنصر تکمیل خودکار مکان اصلی، زمانی فعال می‌شود که کاربر روی یک پیش‌بینی در لیست کشویی کلیک کند.

رویدادهای رایج

عناصر جستجوی مکان، جزئیات مکان و تکمیل خودکار مکان اصلی همگی از رویدادهای زیر پشتیبانی می‌کنند:

  • gmp-load : زمانی فعال می شود که عنصر و محتوای آن بارگذاری و رندر به پایان برسد.
  • gmp-requesterror : هنگامی که درخواستی به سرور، به عنوان مثال، به دلیل یک کلید API نامعتبر، با شکست مواجه می شود، فعال می شود.

دسترسی برنامه ریزی شده به داده های عنصر

شما می توانید داده های خاصی را پس از تعامل با عناصر یا بارگذاری آنها به صورت برنامه نویسی بازیابی کنید.

  • برای عنصر جستجوی مکان و عنصر جزئیات مکان، می توانید اطلاعات زیر را بازیابی کنید:
    • شناسه مکان
    • موقعیت مکانی (طول و عرض جغرافیایی)
    • درگاه دید
  • برای عنصر اصلی تکمیل خودکار مکان، می توانید اطلاعات زیر را بازیابی کنید:
    • شناسه مکان

تمام داده های دیگر موجود در عناصر از نظر برنامه نویسی قابل دسترسی نیستند.

برای مثال‌های دقیق‌تر، به مستندات جداگانه برای عنصر جستجوی مکان ، عنصر جزئیات مکان و عنصر تکمیل خودکار مکان اصلی مراجعه کنید.

آزمایش و اصلاح

هنگامی که عناصر Places UI Kit را ادغام کردید، آزمایش برای انتقال روان و تجربه کاربری مثبت بسیار مهم است. آزمایش شما باید چندین حوزه کلیدی را پوشش دهد و به تمام عناصری که پیاده‌سازی کرده‌اید رسیدگی کند: جزئیات مکان، جستجوی مکان، و عناصر تکمیل خودکار مکان اصلی.

عنصر جزئیات مکان

برای عنصر جزئیات مکان، با تأیید اینکه جزئیات به درستی برای طیف متنوعی از مکان‌ها نمایش داده می‌شوند، شروع کنید. با ارسال شناسه‌های مکان مختلف به ویژگی .place عنصر <gmp-place-details-place-request> آزمایش کنید. از شناسه‌هایی استفاده کنید که نشان‌دهنده انواع مؤسسات (کسب و کار با داده‌های غنی، نقاط مورد علاقه، آدرس‌های اصلی) و مکان‌ها در مناطق یا زبان‌های مختلف هستند. به قالب بندی، چیدمان و حضور محتوا دقت کنید.

عنصر جستجوی مکان

اگر عنصر جستجوی مکان را پیاده‌سازی کرده‌اید، رندر و رفتار آن را در سناریوهای مختلف جستجو تأیید کنید.

  • برای جستجوی متن، با تنظیم ویژگی textQuery در عنصر <gmp-place-text-search-request> با ورودی های مختلف آزمایش کنید: عبارت های گسترده، آدرس های خاص، و پرس و جوهایی با سوگیری های مکان.
  • برای جستجوی نزدیک، با تنظیم ویژگی‌های locationRestriction و includedTypes در عنصر <gmp-place-nearby-search-request> آزمایش کنید. از اندازه های مختلف مکان استفاده کنید و فیلترها را تایپ کنید.

تأیید کنید که لیست با نتایج مرتبط پر شده است و رویداد gmp-select به درستی پس از انتخاب فعال می شود.

عنصر تکمیل خودکار مکان اصلی

برای عنصر تکمیل خودکار مکان اصلی، آزمایش را روی تعامل کاربر و داده‌های ارسال شده توسط رویداد انتخاب متمرکز کنید. زمانی که کاربر روی یک پیش‌بینی کلیک می‌کند، تأیید کنید که رویداد gmp-select به طور قابل اعتماد فعال می‌شود. بررسی کنید که شی event.place در کنترل کننده رویداد حاوی شناسه مکان معتبر باشد.

مهمتر از همه، آزمایش جریان انتها به انتها: مکانی را از منوی کشویی تکمیل خودکار انتخاب کنید و تأیید کنید که شناسه مکان آن می تواند با موفقیت برای پر کردن یک عنصر دیگر، مانند عنصر جزئیات مکان، استفاده شود.

رسیدگی به خطا

آزمایش دقیق رسیدگی به خطا در همه اجزا ضروری است. انتقال شناسه‌های مکان نامعتبر یا ناموجود به عنصر جزئیات مکان یا استفاده از پارامترهای جستجوی نامعتبر برای عنصر جستجوی مکان را شبیه‌سازی کنید. با شبیه سازی مشکلات شبکه یا استفاده از یک کلید API نامعتبر، رویداد gmp-requesterror را فعال کنید تا مطمئن شوید برنامه شما به خوبی آن را مدیریت می کند. برای جلوگیری از خرابی یا گیج کننده بودن رابط کاربری، پیام های خطای کاربر پسند و ثبت نام را پیاده سازی کنید.