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

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

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

واجهة برمجة التطبيقات للإكمال التلقائي

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

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

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

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

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

استرداد عبارات البحث المقترَحة من خلال ميزة "الإكمال التلقائي" (قديم)

تتيح لك خدمة Places القديمة استرجاع التوقّعات المبرمَجة للإكمال التلقائي، ما يمنحك مزيدًا من التحكّم في واجهة المستخدِم أكثر مما تقدّمه فئة 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);
}

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

تتيح لك أيضًا فئة "المكان" الجديدة استرجاع اقتراحات الإكمال التلقائي آليًا من أجل التحكّم بشكل أكبر في واجهة المستخدِم مقارنةً بما تقدّمه فئة 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}`
}

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

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

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

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

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

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

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

  • تأخذ دالة إنشاء التطبيق المصغّر Autocomplete وسيطتين:
    • عنصر input HTML من النوع 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);
  });
}

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

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

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

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

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

  • لا تتوفّر اقتراحات طلبات البحث في فئة Autocomplete.
  • يتم إنشاء PlaceAutocompleteElement باستخدام PlaceAutocompleteElementOptions.
  • يتم تحديد حقول بيانات المكان في وقت الاختيار (عند استدعاء fetchFields()).
  • اضبط الحدود باستخدام الخيار locationBounds أو locationRestriction.
  • اربط PlaceAutocompleteElement بعنصر إدخال نص HTML باستخدام السمة id (المكتسَبة من HTMLElement).
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-placeselect listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location"],
    });
    // 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,
  });
}