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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تقدّم خدمة Places Service نوعَين من التطبيقات المصغّرة لميزة "الإكمال التلقائي"، ويمكنكم إضافتهما باستخدام فئتَي 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);
  });
}

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

تقدّم فئة 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,
  });
}