نقل البيانات إلى ميزة "الإكمال التلقائي للأماكن" الجديدة

المطوّرون في المنطقة الاقتصادية الأوروبية

"الإكمال التلقائي للأماكن" هي ميزة في "مكتبة الأماكن" ضمن Maps JavaScript API. يمكنك استخدام ميزة "الإكمال التلقائي" لتزويد تطبيقاتك بسلوك البحث أثناء الكتابة في حقل البحث في "خرائط Google".

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

واجهة الإكمال التلقائي الآلية

يسرد الجدول التالي بعض الاختلافات الرئيسية في استخدام ميزة "الإكمال التلقائي للأماكن" آليًا بين خدمة الإكمال التلقائي للأماكن (القديمة) وواجهة برمجة التطبيقات الخاصة ببيانات الإكمال التلقائي (الجديدة):

PlacesService (قديم) Place (جديد)
مرجع خدمة الإكمال التلقائي للأماكن مرجع بيانات الإكمال التلقائي (جديد)
AutocompletionRequest AutocompleteRequest
AutocompleteService.getPlacePredictions AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction PlacePrediction
تتطلّب الطرق استخدام دالة ردّ اتصال لمعالجة عنصر النتائج واستجابة PlacesServiceStatus. تستخدم هذه الواجهة Promises وتعمل بشكل غير متزامن.
تتطلّب الطرق إجراء فحص PlacesServiceStatus. لا حاجة إلى التحقّق من الحالة، ويمكن استخدام المعالجة العادية للأخطاء. مزيد من المعلومات
يتم ضبط حقول بيانات الأماكن كخيارات عند إنشاء مثيل Autocomplete. يتم ضبط حقول بيانات الأماكن لاحقًا عند استدعاء fetchFields().
تتوفّر عبارات البحث المقترَحة (SearchBox فقط). لا تتوفّر عبارات البحث المقترَحة في الصف Autocomplete.
تقتصر على مجموعة ثابتة من أنواع الأماكن وحقول بيانات الأماكن. الوصول إلى مجموعة موسّعة من أنواع الأماكن وحقول بيانات الأماكن

يتم استخدام ما يلي في كل من واجهات برمجة التطبيقات القديمة والجديدة لميزة "الإكمال التلقائي":

مقارنة الرموز البرمجية (آليًا)

يقارن هذا القسم بين الرموز البرمجية لميزة "الإكمال التلقائي" لتوضيح الاختلافات بين خدمة "الأماكن" وفئة "المكان"، وذلك لواجهات الاستخدام الآلي.

استرداد عبارات البحث المقترحة (القديمة)

تتيح لك خدمة "الأماكن" القديمة استرداد عبارات البحث المقترحة برمجيًا، ما يمنحك مزيدًا من التحكّم في واجهة المستخدم مقارنةً بما تقدّمه فئة Autocomplete. في المثال التالي، يتم تقديم طلب واحد لـ "par"، مع AutocompletionRequest يتكون من قيمة الإدخال ومجموعة من الحدود لانحياز التنبؤ. يعرض المثال قائمة بمثيلات AutocompletePrediction ويعرض الوصف لكل منها. تنشئ الدالة في المثال أيضًا رمزًا مميزًا للجلسة وتطبّقه على الطلب.

function init() {
  const placeInfo = document.getElementById("prediction");
  const service = new google.maps.places.AutocompleteService();
  const placesService = new google.maps.places.PlacesService(placeInfo);
  var sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    bounds: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  }

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const displaySuggestions = function (predictions, status) {
    // Check the status of the Places Service.
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");
      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });

    const placeRequest = {
      placeId: predictions[0].place_id,
      fields: ["name", "formatted_address"],
    };

    placesService.getDetails(placeRequest, (place, status) => {
      if (status == google.maps.places.PlacesServiceStatus.OK && place) {
        placeInfo.textContent = `
          First predicted place: ${place.name} at ${place.formatted_address}`
      }
    });

  };

  // Show the results of the query.
  service.getPlacePredictions(request, displaySuggestions);
}

استرداد عبارات البحث المقترحة (جديد)

تتيح لك فئة Place الجديدة أيضًا استرداد عبارات البحث المقترحة برمجيًا لمزيد من التحكّم في واجهة المستخدم مقارنةً بما تقدّمه فئة PlaceAutocompleteElement. في المثال التالي، يتم إرسال طلب واحد لـ "par"، مع AutocompleteRequest يتألف من قيمة الإدخال ومجموعة من الحدود لتوجيه التوقّع. يعرض المثال قائمة بمثيلات placePrediction ويعرض الوصف لكل منها. تنشئ الدالة في المثال أيضًا رمزًا مميزًا للجلسة وتطبّقه على الطلب.

async function init() {
  let sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    locationBias: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  };

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const { suggestions } =
    await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

  const resultsElement = document.getElementById("results");

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    const listItem = document.createElement("li");

    listItem.appendChild(
      document.createTextNode(placePrediction.text.text),
    );

    resultsElement.appendChild(listItem);
  }

  // Show the first predicted place.
  let place = suggestions[0].placePrediction.toPlace();

  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  const placeInfo = document.getElementById("prediction");

  placeInfo.textContent = `
    First predicted place: ${place.displayName} at ${place.formattedAddress}`
}

تطبيق مصغّر للإكمال التلقائي للأماكن

يسرد الجدول التالي بعض الاختلافات الرئيسية في استخدام تطبيقات مصغّرة للإكمال التلقائي بين خدمة Places (الإصدار القديم) وفئة Place (الإصدار الجديد):

خدمة الأماكن (الإصدار القديم) المكان (جديد)
Autocomplete للتوقّعات المتعلقة بالأماكن PlaceAutocompleteElement لتوقّعات الأماكن
SearchBox class
للتوقّعات المتعلقة بطلبات البحث 		لا تتوفّر عبارات البحث المقترَحة في الصف Autocomplete.
يتم فقط ترجمة النص المؤقت التلقائي للإدخال. يتيح كلّ من العنصر النائب لإدخال النص وشعار قائمة التوقعات وتوقعات الأماكن إمكانية الأقلمة الإقليمية.
تستخدم الأداة setBounds() أو autocomplete.bindTo() لحصر (توجيه) البحث ضمن الحدود المحدّدة، و strictBounds لحصر النتائج ضمن الحدود المحدّدة. تستخدم الأداة السمة locationBias لتوجيه النتائج إلى الحدود المحدّدة، والسمة locationRestriction لحصر البحث في الحدود المحدّدة.
لا يمكن دمج التطبيقات المصغّرة إلا باستخدام عنصر إدخال HTML عادي. يمكن دمج التطبيق المصغّر باستخدام عنصر إدخال HTML عادي أو عنصر gmp-place-autocomplete.
عند استخدام التطبيق المصغّر، يمكن للمستخدمين طلب أشياء قد لا تكون صالحة (على سبيل المثال "bisneyland")، ويجب التعامل مع هذه الحالة بشكل صريح. ستعرض الأداة فقط نتائج الاقتراحات المقدَّمة، ولا يمكنها إصدار طلبات لقيم عشوائية، وبالتالي ليست هناك حاجة إلى التعامل مع الطلبات التي يُحتمل أن تكون غير صالحة.
تعرض مثيل PlaceResult القديم. تعرض مثيل Place.
يتم ضبط حقول بيانات الأماكن كخيارات لعنصر Autocomplete. يتم ضبط حقول بيانات الأماكن عندما يختار المستخدم مكانًا ويتم استدعاء fetchFields().
تقتصر على مجموعة ثابتة من أنواع الأماكن وحقول بيانات الأماكن. الوصول إلى مجموعة موسّعة من أنواع الأماكن وحقول بيانات الأماكن

مقارنة الرموز (التطبيقات المصغّرة)

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

أداة "الإكمال التلقائي للأماكن" (الإصدار القديم)

توفّر خدمة الأماكن نوعَين من تطبيقات الإكمال التلقائي المصغّرة التي يمكنك إضافتها باستخدام الفئتَين Autocomplete وSearchBox. يمكن إضافة كل نوع من التطبيقات المصغّرة إلى خريطة كعنصر تحكّم في الخريطة، أو تضمينه مباشرةً في صفحة ويب. يوضّح مثال الرمز التالي كيفية تضمين تطبيق مصغّر من Autocomplete كعنصر تحكّم في الخريطة.

  • تتطلّب دالة الإنشاء الخاصة بأداة Autocomplete وسيطتَين:
    • عنصر HTML input من النوع text هذا هو حقل الإدخال الذي ستراقبه خدمة الإكمال التلقائي وترفق نتائجها به.
    • وسيطة AutocompleteOptions اختيارية، حيث يمكنك تحديد المزيد من الخيارات لتقييد طلب البحث.
  • لضبط الحدود، يمكن ربط مثيل Autocomplete بشكل صريح بالخريطة من خلال استدعاء autocomplete.bindTo().
  • حدِّد حقول بيانات الأماكن في خيارات الإكمال التلقائي.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapTypeControl: false,
  });
  const card = document.getElementById("pac-card");
  const input = document.getElementById("pac-input");
  const options = {
    fields: ["formatted_address", "geometry", "name"],
    strictBounds: false,
  };

  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

  const autocomplete = new google.maps.places.Autocomplete(input, options);

  // Bind the map's bounds (viewport) property to the autocomplete object,
  // so that the autocomplete requests use the current map bounds for the
  // bounds option in the request.
  autocomplete.bindTo("bounds", map);

  const infowindow = new google.maps.InfoWindow();
  const infowindowContent = document.getElementById("infowindow-content");

  infowindow.setContent(infowindowContent);

  const marker = new google.maps.Marker({
    map,
    anchorPoint: new google.maps.Point(0, -29),
  });

  autocomplete.addListener("place_changed", () => {
    infowindow.close();
    marker.setVisible(false);

    const place = autocomplete.getPlace();

    if (!place.geometry || !place.geometry.location) {
      // User entered the name of a Place that was not suggested and
      // pressed the Enter key, or the Place Details request failed.
      window.alert("No details available for input: '" + place.name + "'");
      return;
    }

    // If the place has a geometry, then present it on a map.
    if (place.geometry.viewport) {
      map.fitBounds(place.geometry.viewport);
    } else {
      map.setCenter(place.geometry.location);
      map.setZoom(17);
    }

    marker.setPosition(place.geometry.location);
    marker.setVisible(true);
    infowindowContent.children["place-name"].textContent = place.name;
    infowindowContent.children["place-address"].textContent =
      place.formatted_address;
    infowindow.open(map, marker);
  });
}

أداة الإكمال التلقائي للأماكن (جديدة)

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

تم تحسين "التطبيق المصغّر للإكمال التلقائي للأماكن" بالطرق التالية:

  • تتيح واجهة مستخدم التطبيق المصغّر لميزة "الإكمال التلقائي" الترجمة الإقليمية (بما في ذلك اللغات التي تُكتب من اليمين إلى اليسار) للنص النائب في حقل الإدخال وشعار قائمة عبارات البحث المقترَحة وعبارات البحث المقترَحة للأماكن.
  • تحسين ميزات تسهيل الاستخدام، بما في ذلك التوافق مع قارئات الشاشة والتفاعل مع لوحة المفاتيح
  • تعرض أداة "الإكمال التلقائي" فئة Place الجديدة لتبسيط معالجة العنصر الذي تم عرضه.
  • دعم أفضل للأجهزة الجوّالة والشاشات الصغيرة
  • أداء أفضل ومظهر رسومي محسّن

تشمل الاختلافات الرئيسية في التنفيذ ما يلي:

  • يوفّر PlaceAutocompleteElement حقل إدخال خاصًا به، ويتم إدراجه مباشرةً في الصفحة باستخدام HTML أو JavaScript (بدلاً من توفير عنصر إدخال حالي).
  • لا تتوفّر عبارات البحث المقترَحة في الفئة Autocomplete.
  • يتم إنشاء PlaceAutocompleteElement باستخدام PlaceAutocompleteElementOptions.
    • يتم تحديد حقول بيانات الأماكن في وقت الاختيار (عند استدعاء fetchFields()).
  • اضبط الحدود باستخدام الخيار locationBounds أو locationRestriction.
let map;
let marker;
let infoWindow;

async function initMap() {
  // Request needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("marker"),
    google.maps.importLibrary("places"),
  ]);

  // Initialize the map.
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapId: "4504f8b37365c3d0",
    mapTypeControl: false,
  });

  const placeAutocomplete =
    new google.maps.places.PlaceAutocompleteElement({
      locationRestriction: map.getBounds(),
    });

  placeAutocomplete.id = "place-autocomplete-input";
  const card = document.getElementById("place-autocomplete-card");

  card.appendChild(placeAutocomplete);
  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

  // Create the marker and infowindow.
  marker = new google.maps.marker.AdvancedMarkerElement({
    map,
  });
  infoWindow = new google.maps.InfoWindow({});

  // Add the gmp-select listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-select", async ( event ) => {
    const place = event.placePrediction.toPlace();
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location", "viewport"],
    });
    // If the place has a geometry, then present it on a map.
    if (place.viewport) {
      map.fitBounds(place.viewport);
    } else {
      map.setCenter(place.location);
      map.setZoom(17);
    }

    let content =
      '<div id="infowindow-content">' +
      '<span id="place-displayname" class="title">' +
      place.displayName +
      '</span><br />' +
      '<span id="place-address">' +
      place.formattedAddress +
      '</span>' +
      '</div>';

    updateInfoWindow(content, place.location);
    marker.position = place.location;
  });
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
  infoWindow.setContent(content);
  infoWindow.setPosition(center);
  infoWindow.open({
    map,
    anchor: marker,
    shouldFocus: false,
  });
}