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

بیاموزید که چگونه Places API یا پیاده‌سازی Place Class موجود خود را به کامپوننت‌های Places UI Kit منتقل کنید.

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

این راهنما برای توسعه‌دهندگانی است که پیاده‌سازی موجود با استفاده از Places API را دارند و علاقه‌مند به به‌روزرسانی کد خود برای استفاده از Places UI Kit هستند. اگر از قبل موارد زیر را دارید، این راهنما بسیار مفید خواهد بود:

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

پیش‌نیازها

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

به‌روزرسانی نقشه‌ها، API جاوا اسکریپت، در حال بارگذاری

کیت رابط کاربری Places برای بارگذاری API جاوا اسکریپت Maps به روش Dynamic Library Import نیاز دارد. اگر از تگ بارگذاری مستقیم اسکریپت استفاده می‌کنید، این تگ باید به‌روزرسانی شود.

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

عنصر جزئیات مکان را پیاده‌سازی کنید

عنصر جزئیات مکان و عنصر فشرده جزئیات مکان، عناصر HTML هستند که جزئیات یک مکان را رندر می‌کنند.

پیاده‌سازی فعلی

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

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

اصلاح ساختار HTML

کانتینر HTML که جزئیات مکان در آن رندر می‌شوند را شناسایی کنید. عناصر HTML سفارشی خود (divها، spanها برای نام، آدرس، عکس‌ها و غیره) را با عنصر جزئیات مکان 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 خود را به صورت دستی انتخاب کرده و آنها را با داده‌های دریافتی پر کنید.

مثال زیر نحوه‌ی پیاده‌سازی Place Details را نشان می‌دهد:

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 در منطق جاوا اسکریپت شما ارائه شده است. یک ارجاع به عنصر Place Details دریافت کنید. در صورت وجود، یک ارجاع به عنصر Place Details Request دریافت کنید و ویژگی place را با استفاده از یک شناسه مکان تنظیم کنید. در مثال کد 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 یا استفاده از کلاس Place در API جاوا اسکریپت، یک جستجوی متنی یا جستجوی نزدیک انجام دهید.
  • شما پارامترهای پرس‌وجو، محدودیت‌های مکانی یا بایاس‌ها، انواع و فیلدهای درخواستی را با استفاده از FieldMask مشخص می‌کنید.
  • شما پاسخ API را تجزیه می‌کنید، روی آرایه مکان‌ها پیمایش می‌کنید و به صورت دستی آیتم‌های لیست HTML را ایجاد می‌کنید.

اصلاح ساختار HTML

کانتینر HTML که لیست مکان‌های خود را در آن رندر می‌کنید، شناسایی کنید. عناصر HTML سفارشی خود (divها، spanها برای نام، آدرس و غیره) را با عنصر 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 را فراخوانی می‌کند و نتایج را نمایش می‌دهد.
  • استفاده از شناسه مکان (Place ID) مکان انتخاب شده توسط کاربر برای دریافت جزئیات بیشتر، برای مثال با استفاده از API جزئیات مکان (Place Details API).
  • نمایش جزئیات مکان انتخاب شده

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

اصلاح ساختار HTML

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

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

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

<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">

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

از عناصر محتوا برای مشخص کردن محتوایی که باید درون عنصر جزئیات مکان (Place Details Element) رندر شود، استفاده کنید. برای مثال، حذف عنصر محتوای <gmp-place-type> باعث می‌شود عنصر جزئیات مکان (Place Details Element) دیگر نوع مکان انتخاب شده را رندر نکند. برای فهرست کامل عناصر محتوا، به مستندات مرجع 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، اجزای تعاملی هستند که به شما امکان می‌دهند به رویدادها گوش دهید و داده‌ها را به صورت برنامه‌نویسی‌شده بازیابی کنید.

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

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

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

  • 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 را فعال کنید تا مطمئن شوید برنامه شما آن را به درستی مدیریت می‌کند. پیام‌های خطا و گزارش‌گیری کاربرپسند را پیاده‌سازی کنید تا از رابط کاربری خراب یا گیج‌کننده جلوگیری شود.