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

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

إذا كان عنوان إرسال الفواتير الخاص بك يقع في المنطقة الاقتصادية الأوروبية، ستسري بنود خدمة "منصة خرائط Google" في المنطقة الاقتصادية الأوروبية على استخدامك للخدمات اعتبارًا من 8 تموز (يوليو) 2025. تختلف الوظائف حسب المنطقة. مزيد من المعلومات

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

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

• الواجهة الآلية: للمطوّرين الذين يبحثون عن تخصيص أكبر وتحكّم أفضل في تجربة الإكمال التلقائي.
• أداة Place Autocomplete: شريط بحث يمكن تضمينه في خريطة أو صفحة ويب.

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

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

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

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

• locationBias
• locationRestriction
• AutocompleteSessionToken
• ComponentRestrictions

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

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

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

تتيح لك خدمة "أماكن" القديمة استرداد توقّعات الإكمال التلقائي آليًا، ما يمنحك المزيد من التحكّم في واجهة المستخدم مقارنةً بما يوفّره الصف 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 Autocomplete آليًا
• مثال على ميزة "الإكمال التلقائي للأماكن"
• رموز الجلسات المميزة
• AutocompletionRequest مرجع
• AutocompletePrediction مرجع

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

تتيح فئة 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}`
}

• Place Autocomplete Data API
• مثال على عبارات البحث المقترَحة في Place Autocomplete
• مثال على جلسات بيانات خدمة "الإكمال التلقائي" في Places
• رموز الجلسات المميزة
• AutocompleteRequest مرجع الواجهة
• AutocompleteSuggestion مرجع الفئة
• PlacePrediction مرجع الفئة

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

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

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

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

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

الأداة Place Autocomplete Widget (الإصدار القديم)

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

• مستندات خدمة "الإكمال التلقائي للأماكن"
• مثال على أداة "الإكمال التلقائي للأماكن"
• مثال على مربّع البحث عن الأماكن
• Autocomplete مرجع الفئة

تطبيق Place Autocomplete المصغّر (جديد)

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

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

• تتيح واجهة مستخدم التطبيق المصغّر "الإكمال التلقائي" إمكانية الترجمة إلى اللغات المحلية (بما في ذلك اللغات التي تُكتب من اليمين إلى اليسار) لكل من العنصر النائب لإدخال النص وشعار قائمة العبارات المقترَحة والعبارات المقترَحة الخاصة بالأماكن.
• تحسين إمكانية الوصول، بما في ذلك إتاحة استخدام قارئات الشاشة والتفاعل باستخدام لوحة المفاتيح
• تعرض أداة Autocomplete الفئة الجديدة 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 ( place ) => {
    const place = event.placePrediction.toPlace();
    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,
  });
}

• مستندات "الأداة Place Autocomplete" (معاينة)
• مثال على أداة "الإكمال التلقائي للأماكن"
• مثال على عنصر "الإكمال التلقائي للأماكن"
• PlaceAutocompleteElement مرجع الفئة