Cuando se completa una dirección de entrega, información de facturación o de eventos, habilitar formularios con Place Autocomplete ayuda a los usuarios a reducir las pulsaciones de teclas y los errores cuando ingresan información de direcciones. En este instructivo, se explican los pasos necesarios para habilitar un campo de entrada con Place Autocomplete y completar los campos del formulario de dirección con los componentes de la dirección que seleccionó el usuario, y presentar la dirección seleccionada en un mapa para facilitar la confirmación visual.
Videos: Mejora los formularios de dirección con Place Autocomplete
Formularios de dirección
Android
iOS
Web
Google Maps Platform proporciona un widget de Place Autocomplete para plataformas móviles y la Web. El widget, que se muestra en las imágenes anteriores, proporciona un diálogo de búsqueda con una funcionalidad de autocompletado integrada que incluso puedes optimizar para la búsqueda con alcance de ubicación.
Obtén el código
En GitHub, clona o descarga el repositorio de demostraciones del SDK de Google Places para Android.
Consulta la versión de Java de la actividad:
/* * Copyright 2022 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * https://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.example.placesdemo; import android.annotation.SuppressLint; import android.app.Activity; import android.content.Intent; import android.content.pm.PackageManager; import android.content.res.Resources; import android.os.Bundle; import android.util.Log; import android.view.View; import android.view.ViewStub; import android.widget.Button; import android.widget.CheckBox; import android.widget.Toast; import androidx.activity.result.ActivityResultLauncher; import androidx.activity.result.contract.ActivityResultContracts; import androidx.annotation.NonNull; import androidx.annotation.Nullable; import androidx.appcompat.app.AppCompatActivity; import androidx.core.content.ContextCompat; import com.example.placesdemo.databinding.AutocompleteAddressActivityBinding; import com.google.android.gms.location.FusedLocationProviderClient; import com.google.android.gms.location.LocationServices; import com.google.android.gms.maps.CameraUpdateFactory; import com.google.android.gms.maps.GoogleMap; import com.google.android.gms.maps.GoogleMapOptions; import com.google.android.gms.maps.OnMapReadyCallback; import com.google.android.gms.maps.SupportMapFragment; import com.google.android.gms.maps.model.LatLng; import com.google.android.gms.maps.model.MapStyleOptions; import com.google.android.gms.maps.model.Marker; import com.google.android.gms.maps.model.MarkerOptions; import com.google.android.libraries.places.api.Places; import com.google.android.libraries.places.api.model.AddressComponent; import com.google.android.libraries.places.api.model.AddressComponents; import com.google.android.libraries.places.api.model.Place; import com.google.android.libraries.places.api.model.TypeFilter; import com.google.android.libraries.places.api.net.PlacesClient; import com.google.android.libraries.places.widget.Autocomplete; import com.google.android.libraries.places.widget.model.AutocompleteActivityMode; import java.util.ArrayList; import java.util.Arrays; import java.util.List; import static android.Manifest.permission.ACCESS_FINE_LOCATION; import static com.google.maps.android.SphericalUtil.computeDistanceBetween; /** * Activity for using Place Autocomplete to assist filling out an address form. */ @SuppressWarnings("FieldCanBeLocal") public class AutocompleteAddressActivity extends AppCompatActivity implements OnMapReadyCallback { private static final String TAG = "ADDRESS_AUTOCOMPLETE"; private static final String MAP_FRAGMENT_TAG = "MAP"; private LatLng coordinates; private boolean checkProximity = false; private SupportMapFragment mapFragment; private GoogleMap map; private Marker marker; private PlacesClient placesClient; private View mapPanel; private LatLng deviceLocation; private static final double acceptedProximity = 150; private AutocompleteAddressActivityBinding binding; View.OnClickListener startAutocompleteIntentListener = view -> { view.setOnClickListener(null); startAutocompleteIntent(); }; private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Activity.RESULT_OK) { Intent intent = result.getData(); if (intent != null) { Place place = Autocomplete.getPlaceFromIntent(intent); // Write a method to read the address components from the Place // and populate the form with the address components Log.d(TAG, "Place: " + place.getAddressComponents()); fillInAddress(place); } } else if (result.getResultCode() == Activity.RESULT_CANCELED) { // The user canceled the operation. Log.i(TAG, "User canceled autocomplete"); } }); @Override protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent intent) { super.onActivityResult(requestCode, resultCode, intent); binding.autocompleteAddress1.setOnClickListener(startAutocompleteIntentListener); } @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); binding = AutocompleteAddressActivityBinding.inflate(getLayoutInflater()); setContentView(binding.getRoot()); // Retrieve a PlacesClient (previously initialized - see MainActivity) placesClient = Places.createClient(this); // Attach an Autocomplete intent to the Address 1 EditText field binding.autocompleteAddress1.setOnClickListener(startAutocompleteIntentListener); // Update checkProximity when user checks the checkbox CheckBox checkProximityBox = findViewById(R.id.checkbox_proximity); checkProximityBox.setOnCheckedChangeListener((view, isChecked) -> { // Set the boolean to match user preference for when the Submit button is clicked checkProximity = isChecked; }); // Submit and optionally check proximity Button saveButton = findViewById(R.id.autocomplete_save_button); saveButton.setOnClickListener(v -> saveForm()); // Reset the form Button resetButton = findViewById(R.id.autocomplete_reset_button); resetButton.setOnClickListener(v -> clearForm()); } private void startAutocompleteIntent() { // Set the fields to specify which types of place data to // return after the user has made a selection. List<Place.Field> fields = Arrays.asList(Place.Field.ADDRESS_COMPONENTS, Place.Field.LAT_LNG, Place.Field.VIEWPORT); // Build the autocomplete intent with field, country, and type filters applied Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.OVERLAY, fields) .setCountries(Arrays.asList("US")) .setTypesFilter(new ArrayList<String>() {{ add(TypeFilter.ADDRESS.toString().toLowerCase()); }}) .build(this); startAutocomplete.launch(intent); } @Override public void onMapReady(@NonNull GoogleMap googleMap) { map = googleMap; try { // Customise the styling of the base map using a JSON object defined // in a string resource. boolean success = map.setMapStyle( MapStyleOptions.loadRawResourceStyle(this, R.raw.style_json)); if (!success) { Log.e(TAG, "Style parsing failed."); } } catch (Resources.NotFoundException e) { Log.e(TAG, "Can't find style. Error: ", e); } map.moveCamera(CameraUpdateFactory.newLatLngZoom(coordinates, 15f)); marker = map.addMarker(new MarkerOptions().position(coordinates)); } private void fillInAddress(Place place) { AddressComponents components = place.getAddressComponents(); StringBuilder address1 = new StringBuilder(); StringBuilder postcode = new StringBuilder(); // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // Possible AddressComponent types are documented at https://goo.gle/32SJPM1 if (components != null) { for (AddressComponent component : components.asList()) { String type = component.getTypes().get(0); switch (type) { case "street_number": { address1.insert(0, component.getName()); break; } case "route": { address1.append(" "); address1.append(component.getShortName()); break; } case "postal_code": { postcode.insert(0, component.getName()); break; } case "postal_code_suffix": { postcode.append("-").append(component.getName()); break; } case "locality": binding.autocompleteCity.setText(component.getName()); break; case "administrative_area_level_1": { binding.autocompleteState.setText(component.getShortName()); break; } case "country": binding.autocompleteCountry.setText(component.getName()); break; } } } binding.autocompleteAddress1.setText(address1.toString()); binding.autocompletePostal.setText(postcode.toString()); // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of sub-premise information such as apartment, unit, or floor number. binding.autocompleteAddress2.requestFocus(); // Add a map for visual confirmation of the address showMap(place); } private void showMap(Place place) { coordinates = place.getLatLng(); // It isn't possible to set a fragment's id programmatically so we set a tag instead and // search for it using that. mapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentByTag(MAP_FRAGMENT_TAG); // We only create a fragment if it doesn't already exist. if (mapFragment == null) { mapPanel = ((ViewStub) findViewById(R.id.stub_map)).inflate(); GoogleMapOptions mapOptions = new GoogleMapOptions(); mapOptions.mapToolbarEnabled(false); // To programmatically add the map, we first create a SupportMapFragment. mapFragment = SupportMapFragment.newInstance(mapOptions); // Then we add it using a FragmentTransaction. getSupportFragmentManager() .beginTransaction() .add(R.id.confirmation_map, mapFragment, MAP_FRAGMENT_TAG) .commit(); mapFragment.getMapAsync(this); } else { updateMap(coordinates); } } private void updateMap(LatLng latLng) { marker.setPosition(latLng); map.moveCamera(CameraUpdateFactory.newLatLngZoom(latLng, 15f)); if (mapPanel.getVisibility() == View.GONE) { mapPanel.setVisibility(View.VISIBLE); } } private void saveForm() { Log.d(TAG, "checkProximity = " + checkProximity); if (checkProximity) { checkLocationPermissions(); } else { Toast.makeText( this, R.string.autocomplete_skipped_message, Toast.LENGTH_SHORT) .show(); } } private void clearForm() { binding.autocompleteAddress1.setText(""); binding.autocompleteAddress2.getText().clear(); binding.autocompleteCity.getText().clear(); binding.autocompleteState.getText().clear(); binding.autocompletePostal.getText().clear(); binding.autocompleteCountry.getText().clear(); if (mapPanel != null) { mapPanel.setVisibility(View.GONE); } binding.autocompleteAddress1.requestFocus(); } // Register the permissions callback, which handles the user's response to the // system permissions dialog. Save the return value, an instance of // ActivityResultLauncher, as an instance variable. private final ActivityResultLauncher<String> requestPermissionLauncher = registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> { if (isGranted) { // Since ACCESS_FINE_LOCATION is the only permission in this sample, // run the location comparison task once permission is granted. // Otherwise, check which permission is granted. getAndCompareLocations(); } else { // Fallback behavior if user denies permission Log.d(TAG, "User denied permission"); } }); private void checkLocationPermissions() { if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) { getAndCompareLocations(); } else { requestPermissionLauncher.launch( ACCESS_FINE_LOCATION); } } @SuppressLint("MissingPermission") private void getAndCompareLocations() { // TODO: Detect and handle if user has entered or modified the address manually and update // the coordinates variable to the Lat/Lng of the manually entered address. May use // Geocoding API to convert the manually entered address to a Lat/Lng. LatLng enteredLocation = coordinates; map.setMyLocationEnabled(true); FusedLocationProviderClient fusedLocationClient = LocationServices.getFusedLocationProviderClient(this); fusedLocationClient.getLastLocation() .addOnSuccessListener(this, location -> { // Got last known location. In some rare situations this can be null. if (location == null) { return; } deviceLocation = new LatLng(location.getLatitude(), location.getLongitude()); Log.d(TAG, "device location = " + deviceLocation); Log.d(TAG, "entered location = " + enteredLocation.toString()); // Use the computeDistanceBetween function in the Maps SDK for Android Utility Library // to use spherical geometry to compute the distance between two Lat/Lng points. double distanceInMeters = computeDistanceBetween(deviceLocation, enteredLocation); if (distanceInMeters <= acceptedProximity) { Log.d(TAG, "location matched"); // TODO: Display UI based on the locations matching } else { Log.d(TAG, "location not matched"); // TODO: Display UI based on the locations not matching } }); } }
Habilita las APIs
Para implementar estas recomendaciones, debes habilitar las siguientes APIs en la consola de Google Cloud:
- SDK de Maps para Android (o la API de tu plataforma preferida)
- API de Places
Para obtener más información sobre la configuración, consulta Configura tu proyecto de Google Cloud.
Agrega Autocomplete a los campos de entrada
En esta sección, se describe cómo agregar Place Autocomplete a un formulario de direcciones.
Cómo agregar el widget de Place Autocomplete
En Android, puedes agregar el widget de autocompletado con un intent de Autocomplete que inicie Place Autocomplete desde el campo de entrada Línea de dirección 1, donde el usuario comenzará a ingresar su dirección. Cuando comience a escribir, podrá seleccionar su dirección de la lista de predicciones de Autocomplete.
Primero, prepara un selector de actividad con ActivityResultLauncher, que escuchará un resultado proveniente de la actividad iniciada. La devolución de llamada que se obtenga contendrá un objeto Place correspondiente a la dirección que el usuario seleccione en las predicciones de Autocomplete.
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Activity.RESULT_OK) { Intent intent = result.getData(); if (intent != null) { Place place = Autocomplete.getPlaceFromIntent(intent); // Write a method to read the address components from the Place // and populate the form with the address components Log.d(TAG, "Place: " + place.getAddressComponents()); fillInAddress(place); } } else if (result.getResultCode() == Activity.RESULT_CANCELED) { // The user canceled the operation. Log.i(TAG, "User canceled autocomplete"); } });
Luego, define los campos, la ubicación y las propiedades de tipo del intent de Place Autocomplete y compílalo con Autocomplete.IntentBuilder.
Por último, inicia el intent con el ActivityResultLauncher definido en la muestra de código anterior.
private void startAutocompleteIntent() { // Set the fields to specify which types of place data to // return after the user has made a selection. List<Place.Field> fields = Arrays.asList(Place.Field.ADDRESS_COMPONENTS, Place.Field.LAT_LNG, Place.Field.VIEWPORT); // Build the autocomplete intent with field, country, and type filters applied Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.OVERLAY, fields) .setCountries(Arrays.asList("US")) .setTypesFilter(new ArrayList<String>() {{ add(TypeFilter.ADDRESS.toString().toLowerCase()); }}) .build(this); startAutocomplete.launch(intent); }
Control de la dirección mostrada por Place Autocomplete
En la definición del elemento ActivityResultLauncher anterior también se indica lo que se debe hacer con el resultado de la actividad que se muestra en la devolución de llamada. Si el usuario seleccionó una predicción, se entregará en el intent contenido en el objeto del resultado. Debido a que el intent se creó con Autocomplete.IntentBuilder, el método Autocomplete.getPlaceFromIntent() puede extraer el objeto Place.
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Activity.RESULT_OK) { Intent intent = result.getData(); if (intent != null) { Place place = Autocomplete.getPlaceFromIntent(intent); // Write a method to read the address components from the Place // and populate the form with the address components Log.d(TAG, "Place: " + place.getAddressComponents()); fillInAddress(place); } } else if (result.getResultCode() == Activity.RESULT_CANCELED) { // The user canceled the operation. Log.i(TAG, "User canceled autocomplete"); } });
Desde allí, llama a Place.getAddressComponents() y haz coincidir el componente de cada dirección con el campo de entrada correspondiente en el formulario de dirección. Para ello, propaga el campo con el valor de Place seleccionado por el usuario.
En el método fillInAddress del código de muestra que se proporciona en la sección Obtén el código de esta página, se comparte una implementación de ejemplo para propagar los campos del formulario de dirección.
Tomar los datos de la dirección de la predicción en lugar de una dirección ingresada manualmente ayuda a garantizar la exactitud de la dirección, garantiza que es conocida y apta para recibir entregas y permite que el usuario escriba menos.
Consideraciones que debes tener en cuenta al implementar Place Autocomplete
Place Autocomplete ofrece una serie de opciones que flexibilizan su implementación en caso de que desees utilizar otras funciones más allá del widget. Puedes combinar varios servicios para crear exactamente la solución que necesitas para establecer la coincidencia de una ubicación de manera adecuada.
En el caso de un formulario de dirección, configura el parámetro
addressde modo tal que se restrinjan las coincidencias a direcciones completas. Obtén más información sobre los tipos admitidos en las solicitudes de Place Autocomplete.Establece las restricciones y personalizaciones adecuadas si no necesitas realizar búsquedas a nivel mundial. Hay una serie de parámetros que pueden utilizarse para personalizar o restringir cualquier coincidencia solo a regiones específicas.
Utiliza
RectangularBoundspara establecer los límites rectangulares y definir un área, ysetLocationRestriction()para garantizar que solo se muestren direcciones dentro de esa zona.Utiliza
setCountries()para restringir las respuestas a un conjunto determinado de países.
Asegúrate de que los campos sean editables en caso de que alguno no se complete con la coincidencia. De esta manera, los clientes podrán actualizar la dirección si es necesario. Dado que la mayoría de las direcciones que muestra Place Autocomplete no incluyen números de departamento, habitación o unidad, puedes trasladar el enfoque hacia la Línea de dirección 2 para que el usuario complete esa información si es necesario.
Proporciona una confirmación visual de la dirección
Como parte del proceso de ingreso de la dirección, bríndales a los usuarios una confirmación visual de la dirección en un mapa. Esto les ofrece una garantía adicional de que la dirección es correcta.
En la siguiente imagen, se muestra un mapa debajo de la dirección con un pin en la dirección ingresada.
En el siguiente ejemplo, se siguen los pasos básicos para agregar un mapa en Android. Consulta la documentación para obtener más detalles.
- Cómo agregar
SupportMapFragment(en este caso, cómo incorporar un fragmento de forma dinámica) - Cómo obtener un handle para el fragmento y registrar la devolución de llamada
- Cómo aplicar estilos y agregar un marcador al mapa
- Cómo inhabilitar los controles del mapa
Cómo agregar SupportMapFragment
Primero, incorpora un fragmento de SupportMapFragment al archivo XML de diseño.
<fragment
android:name="com.google.android.gms.maps.SupportMapFragment"
android:id="@+id/confirmation_map"
android:layout_width="match_parent"
android:layout_height="match_parent"/>Luego, agrega el fragmento de manera programática si aún no existe.
private void showMap(Place place) {
coordinates = place.getLatLng();
// It isn't possible to set a fragment's id programmatically so we set a tag instead and
// search for it using that.
mapFragment = (SupportMapFragment)
getSupportFragmentManager().findFragmentByTag(MAP_FRAGMENT_TAG);
// We only create a fragment if it doesn't already exist.
if (mapFragment == null) {
mapPanel = ((ViewStub) findViewById(R.id.stub_map)).inflate();
GoogleMapOptions mapOptions = new GoogleMapOptions();
mapOptions.mapToolbarEnabled(false);
// To programmatically add the map, we first create a SupportMapFragment.
mapFragment = SupportMapFragment.newInstance(mapOptions);
// Then we add it using a FragmentTransaction.
getSupportFragmentManager()
.beginTransaction()
.add(R.id.confirmation_map, mapFragment, MAP_FRAGMENT_TAG)
.commit();
mapFragment.getMapAsync(this);
} else {
updateMap(coordinates);
}
}Cómo obtener un handle para el fragmento y registrar la devolución de llamada
Para obtener un handle para el fragmento, llama al método
FragmentManager.findFragmentByIdy pásale el ID de recurso del fragmento en tu archivo de diseño. Si agregaste el fragmento de forma dinámica, omite este paso porque ya recuperaste el handle.Llama al método
getMapAsyncpara configurar la devolución de llamada en el fragmento.
Por ejemplo, si agregaste el fragmento de forma estática, el código se verá así:
Kotlin
val mapFragment = supportFragmentManager .findFragmentById(R.id.map) as SupportMapFragment mapFragment.getMapAsync(this)
Java
SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager() .findFragmentById(R.id.map); mapFragment.getMapAsync(this);
Cómo aplicar estilos y agregar un marcador al mapa
Cuando el mapa esté listo, configura el estilo, centra la cámara y agrega un marcador en las coordenadas de la dirección ingresada. El siguiente código usa el estilo definido en un objeto JSON o, como alternativa, puedes cargar un ID de mapa definido con el diseño de mapas basado en Cloud.
@Override public void onMapReady(@NonNull GoogleMap googleMap) { map = googleMap; try { // Customise the styling of the base map using a JSON object defined // in a string resource. boolean success = map.setMapStyle( MapStyleOptions.loadRawResourceStyle(this, R.raw.style_json)); if (!success) { Log.e(TAG, "Style parsing failed."); } } catch (Resources.NotFoundException e) { Log.e(TAG, "Can't find style. Error: ", e); } map.moveCamera(CameraUpdateFactory.newLatLngZoom(coordinates, 15f)); marker = map.addMarker(new MarkerOptions().position(coordinates)); }
(Consulta la muestra de código completa).
Cómo inhabilitar los controles del mapa
Para simplificar el mapa y que se muestre la ubicación sin controles adicionales (como la brújula, la barra de herramientas y otras funciones integradas), inhabilita los controles que no consideres necesarios. En Android, otra opción es habilitar el modo lite para proporcionar interactividad limitada.