Componente Place Details
Il componente Place Details di Places UI Kit ti consente di aggiungere un singolo componente UI che mostra i dettagli del luogo nella tua app. Questo componente è personalizzabile.
Il componente Dettagli luogo può essere utilizzato in modo indipendente o in combinazione con altri servizi e API di Google Maps Platform. Il componente accetta un ID luogo, un nome della risorsa o coordinate di latitudine/longitudine e restituisce le informazioni di Place Details visualizzate.
Il componente Dettagli luogo è completamente personalizzabile, il che ti consente di modificare caratteri, colori e raggi angolari in base al tuo caso d'uso e alle linee guida per il brand visivo. Puoi personalizzare l'aspetto dei dettagli del luogo creando un tema che estenda PlacesMaterialTheme e fornisca override per gli attributi del tema. Puoi anche personalizzare i campi dei dettagli dei luoghi inclusi specificando un elenco di voci di contenuti, ognuna delle quali corrisponde a un'informazione mostrata sul luogo.
Varianti di layout
Il componente Place Details supporta due varianti di layout principali:
- Compatto:un layout per visualizzare in anteprima le informazioni chiave.
- Completo:un layout completo che mostra tutti i dettagli disponibili del luogo.
Il layout compatto può essere visualizzato in orientamento verticale o orizzontale. In questo modo puoi integrare il componente in vari layout di design e dimensioni dello schermo. Il layout completo può essere visualizzato solo verticalmente.
Il componente Dettagli del luogo ti offre un controllo granulare sui contenuti visualizzati nel componente. Ogni elemento (come foto, recensioni e dati di contatto) può essere mostrato o nascosto singolarmente, consentendo una personalizzazione precisa dell'aspetto dei componenti e della densità delle informazioni.
Visualizzazione compatta dei dettagli del luogo
Il frammento compatto Place Details (PlaceDetailsCompactFragment) esegue il rendering dei dettagli di un luogo selezionato utilizzando uno spazio minimo. Questo può essere utile in una finestra informativa che mette in evidenza un luogo su una mappa, in un'esperienza sui social media come la condivisione di una posizione in una chat, come suggerimento per selezionare la tua posizione attuale o all'interno di un articolo multimediale per fare riferimento al luogo su Google Maps.
Visualizzazione completa dei dettagli del luogo
La visualizzazione completa dei dettagli del luogo (PlaceDetailsFragment) offre una superficie più ampia per visualizzare le informazioni dettagliate sul luogo e consente di mostrare più tipi di informazioni.
Opzioni di visualizzazione dei contenuti
Puoi specificare i contenuti da visualizzare utilizzando le enumerazioni in PlaceDetailsCompactFragment.Content o PlaceDetailsFragment.Content.
| Visualizzazione compatta | Visualizzazione completa |
|---|---|
|
|
Fatturazione
Quando utilizzi Place Details UI Kit, ti viene addebitato un costo ogni volta che viene chiamato il metodo .loadWithPlaceId(), .loadWithResourceName() o loadWithCoordinates(). Se carichi lo stesso luogo più volte, ti viene addebitato un importo per ogni richiesta.
Per evitare addebiti multipli, non aggiungere direttamente .loadWithPlaceId() o .loadWithResourceName() nei metodi del ciclo di vita di Android. Ad esempio, non chiamare direttamente .loadWithPlaceId() o .loadWithResourceName() nel metodo onResume().
Aggiungere i dettagli dei luoghi all'app
Puoi aggiungere i dettagli del luogo alla tua app aggiungendo un frammento a un layout. Quando crei un'istanza del fragment, puoi personalizzare l'aspetto delle informazioni sui dettagli del luogo in base alle tue esigenze e all'aspetto della tua app. Scopri di più sulla personalizzazione.
Sono disponibili tre metodi sia in Kotlin che in Java: uno per caricare il fragment con un ID luogo (loadWithPlaceId()), uno per caricare il fragment con un nome risorsa (loadWithResourceName()) e uno per caricare il fragment con le coordinate di latitudine/longitudine (loadWithCoordinates()). Puoi scegliere uno o più metodi.
La posizione predefinita per la visualizzazione compatta è verticale. Se vuoi un layout orizzontale, specifica Orientation.HORIZONTAL. Se vuoi, puoi anche specificare Orientation.VERTICAL per maggiore chiarezza. La visualizzazione completa può essere visualizzata solo in verticale.
Vedi gli esempi nella sezione Esempi di componenti Dettagli luogo.
Personalizzare l'aspetto visivo
Il kit UI Places offre un approccio di sistema di progettazione alla personalizzazione visiva basato approssimativamente su Material Design (con alcune modifiche specifiche di Google Maps). Consulta il riferimento di Material Design per Colori e Tipografia. Per impostazione predefinita, lo stile rispetta il linguaggio di progettazione visiva di Google Maps.
Quando istanzi un frammento, puoi specificare un tema che esegue l'override di uno qualsiasi degli attributi di stile predefiniti. Gli attributi del tema non sostituiti utilizzano gli stili predefiniti. Se vuoi supportare un tema scuro, puoi aggiungere una voce per il colore in values-night/colors.xml.
<style name="CustomizedPlaceDetailsTheme" parent="PlacesMaterialTheme"> <item name="placesColorPrimary">@color/app_primary_color</item> <item name="placesColorOnSurface">@color/app_color_on_surface</item> <item name="placesColorOnSurfaceVariant">@color/app_color_on_surface</item> <item name="placesTextAppearanceBodySmall">@style/app_text_appearence_small</item> <item name="placesCornerRadius">20dp</item> </style>
Puoi personalizzare i seguenti stili:
| Attributo tema | Utilizzo |
|---|---|
| Colore | |
placesColorSurface |
Sfondo del contenitore e della finestra di dialogo |
placesColorOutlineDecorative |
Bordo del contenitore |
placesColorPrimary |
Link, indicatore di caricamento, icone di panoramica |
placesColorOnSurface |
Intestazioni, contenuti della finestra di dialogo |
placesColorOnSurfaceVariant |
Informazioni sul luogo |
placesColorSecondaryContainer |
Sfondo pulsante |
placesColorOnSecondaryContainer |
Testo e icona del pulsante |
placesColorNeutralContainer |
Esamina il badge della data e le forme segnaposto di caricamento |
placesColorOnNeutralContainer |
Data della revisione, errore di caricamento |
placesColorPositiveContainer |
Badge Stazione di ricarica EV disponibile |
placesColorOnPositiveContainer |
Contenuti del badge per caricabatterie EV disponibili |
placesColorPositive |
Etichetta "Aperto" del luogo |
placesColorNegative |
Etichetta "Chiuso" ora |
placesColorInfo |
Icona Ingresso accessibile |
placesColorButtonBorder |
Pulsanti Apri in Maps e OK |
| Tipografia | |
placesTextAppearanceBodySmall |
Informazioni sul luogo |
placesTextAppearanceBodyMedium |
Informazioni sul luogo, contenuti della finestra di dialogo |
placesTextAppearanceLabelMedium |
Contenuti del badge |
placesTextAppearanceLabelLarge |
Contenuto del pulsante |
placesTextAppearanceHeadlineMedium |
Intestazioni delle finestre di dialogo |
placesTextAppearanceDisplaySmall |
Nome del luogo |
placesTextAppearanceTitleSmall |
Nome del luogo |
| Spaziatura | |
placesSpacingExtraSmall |
|
placesSpacingSmall |
|
placesSpacingMedium |
|
placesSpacingLarge |
|
placesSpacingExtraLarge |
|
placesSpacingTwoExtraLarge |
|
| Misurazione | |
placesBorderWidth |
Container |
placesBorderWidthButton |
|
| Forma | |
placesCornerRadius |
Container |
placesCornerRadiusButton |
Pulsanti Apri in Maps e OK (escluso il pulsante icona rotondo) |
placesCornerRadiusThumbnail |
Immagine in miniatura del luogo |
placesCornerRadiusCollageOuter |
Collage multimediale |
placesCornerRadiusCard |
Scheda luogo, scheda recensione utente |
placesCornerRadiusDialog |
Finestra di dialogo di divulgazione di Google Maps |
| Attribuzione del brand Google Maps | |
placesColorAttributionLightTheme |
Pulsante di attribuzione e informativa di Google Maps con tema chiaro (enumerazioni per bianco, grigio e nero) |
placesColorAttributionDarkTheme |
Pulsante di attribuzione e informativa del tema scuro di Google Maps (enumerazioni per bianco, grigio e nero) |
Vedi gli esempi nella sezione Esempi di componenti Dettagli luogo.
Personalizzazione di larghezza e altezza
Visualizzazioni compatte
Larghezze consigliate:
- Orientamento verticale: tra 180 dp e 300 dp.
- Orientamento orizzontale: tra 180 dp e 500 dp.
Le larghezze inferiori a 160 dp potrebbero non essere visualizzate correttamente.
La best practice prevede di non impostare un'altezza per le visualizzazioni compatte. In questo modo, l'altezza della finestra verrà impostata in base ai contenuti, consentendo la visualizzazione di tutte le informazioni.
Visualizzazioni complete
Per le visualizzazioni complete, la larghezza consigliata è compresa tra 250 dp e 450 dp. Una larghezza inferiore a 250 dp potrebbe non essere visualizzata correttamente.
Puoi impostare l'altezza del componente: la visualizzazione verticale Dettagli del luogo scorrerà verticalmente nello spazio assegnato.
La best practice prevede di impostare un'altezza per le visualizzazioni complete. In questo modo, i contenuti nella finestra scorreranno correttamente.
Colori di attribuzione
I Termini di servizio di Google Maps richiedono di utilizzare uno dei tre colori del brand per l'attribuzione di Google Maps. Questa attribuzione deve essere visibile e accessibile quando sono state apportate modifiche alla personalizzazione.
Offriamo tre colori del brand tra cui scegliere, che possono essere impostati in modo indipendente per i temi chiaro e scuro:
- Tema chiaro:
placesColorAttributionLightcon valori enum per bianco, grigio e nero. - Tema scuro:
placesColorAttributionDarkcon valori enum per bianco, grigio e nero.
Esempi di componenti Place Details
Creare una visualizzazione compatta o completa
Kotlin
// Create a new instance of the fragment from the Places SDK. val fragment = PlaceDetailsCompactFragment.newInstance( PlaceDetailsCompactFragment.ALL_CONTENT, orientation, R.style.CustomizedPlaceDetailsTheme, ).apply { // Set a listener to be notified when the place data has been loaded. setPlaceLoadListener(object : PlaceLoadListener { override fun onSuccess(place: Place) { Log.d(TAG, "Place loaded: ${place.id}") // Hide loader, show the fragment container and the dismiss button binding.loadingIndicator.visibility = View.GONE binding.placeDetailsContainer.visibility = View.VISIBLE binding.dismissButton.visibility = View.VISIBLE } override fun onFailure(e: Exception) { Log.e(TAG, "Place failed to load", e) // Hide everything on failure dismissPlaceDetails() Toast.makeText(this@MainActivity, "Failed to load place details.", Toast.LENGTH_SHORT).show() } }) } // Add the fragment to the container in the layout. supportFragmentManager .beginTransaction() .replace(binding.placeDetailsContainer.id, fragment) .commitNow() // Use commitNow to ensure the fragment is immediately available. // **This is the key step**: Tell the fragment to load data for the given Place ID. binding.root.post { fragment.loadWithPlaceId(placeId) } }
Java
PlaceDetailsCompactFragment fragment = PlaceDetailsCompactFragment.newInstance( Orientation.HORIZONTAL, Arrays.asList(Content.ADDRESS, Content.TYPE, Content.RATING, Content.ACCESSIBLE_ENTRANCE_ICON), R.style.CustomizedPlaceDetailsTheme); fragment.setPlaceLoadListener( new PlaceLoadListener() { @Override public void onSuccess(Place place) { ... } @Override public void onFailure(Exception e) { ... } }); getSupportFragmentManager() .beginTransaction() .add(R.id.fragment_container, fragment) .commitNow(); // Load the fragment with a Place ID. fragment.loadWithPlaceId(placeId); // Load the fragment with a resource name. fragment.loadWithResourceName(resourceName);
Questo esempio di codice completo determina l'orientamento della visualizzazione compatta in modo programmatico in base alla configurazione del dispositivo dell'utente.
Kotlin
package com.example.placedetailsuikit import android.Manifest import android.annotation.SuppressLint import android.content.pm.PackageManager import android.content.res.Configuration import android.location.Location import android.os.Bundle import android.util.Log import android.view.View import android.widget.Toast import androidx.activity.enableEdgeToEdge import androidx.activity.result.ActivityResultLauncher import androidx.activity.result.contract.ActivityResultContracts import androidx.activity.viewModels import androidx.appcompat.app.AppCompatActivity import androidx.core.app.ActivityCompat import androidx.lifecycle.ViewModel import com.example.placedetailsuikit.databinding.ActivityMainBinding 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.OnMapReadyCallback import com.google.android.gms.maps.SupportMapFragment import com.google.android.gms.maps.model.LatLng import com.google.android.gms.maps.model.PointOfInterest import com.google.android.libraries.places.api.Places import com.google.android.libraries.places.api.model.Place import com.google.android.libraries.places.widget.PlaceDetailsCompactFragment import com.google.android.libraries.places.widget.PlaceLoadListener import com.google.android.libraries.places.widget.model.Orientation private const val TAG = "PlacesUiKit" /** * A simple ViewModel to store UI state that needs to survive configuration changes. * In this case, it holds the ID of the selected place. */ class MainViewModel : ViewModel() { var selectedPlaceId: String? = null } /** * Main Activity for the application. This class is responsible for: * 1. Displaying a Google Map. * 2. Handling location permissions to center the map on the user's location. * 3. Handling clicks on Points of Interest (POIs) on the map. * 4. Displaying a [PlaceDetailsCompactFragment] to show details of a selected POI. */ class MainActivity : AppCompatActivity(), OnMapReadyCallback, GoogleMap.OnPoiClickListener { // ViewBinding for safe and easy access to views. private lateinit var binding: ActivityMainBinding private var googleMap: GoogleMap? = null // Client for retrieving the device's last known location. private lateinit var fusedLocationClient: FusedLocationProviderClient // Modern approach for handling permission requests and their results. private lateinit var requestPermissionLauncher: ActivityResultLauncher<Array<String>> // ViewModel to store state across configuration changes (like screen rotation). private val viewModel: MainViewModel by viewModels() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Initialize the permissions launcher. This defines what to do after the user // responds to the permission request dialog. requestPermissionLauncher = registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { permissions -> if (permissions[Manifest.permission.ACCESS_FINE_LOCATION] == true || permissions[Manifest.permission.ACCESS_COARSE_LOCATION] == true) { // Permission was granted. Fetch the user's location. Log.d(TAG, "Location permission granted by user.") fetchLastLocation() } else { // Permission was denied. Show a message and default to a fallback location. Log.d(TAG, "Location permission denied by user.") Toast.makeText( this, "Location permission denied. Showing default location.", Toast.LENGTH_LONG ).show() moveToSydney() } } // Standard setup for ViewBinding and enabling edge-to-edge display. enableEdgeToEdge() binding = ActivityMainBinding.inflate(layoutInflater) setContentView(binding.root) // Set up the dismiss button listener binding.dismissButton.setOnClickListener { dismissPlaceDetails() } // --- Crucial: Initialize Places SDK --- val apiKey = BuildConfig.PLACES_API_KEY if (apiKey.isEmpty() || apiKey == "YOUR_API_KEY") { Log.e(TAG, "No api key") Toast.makeText( this, "Add your own API_KEY in local.properties", Toast.LENGTH_LONG ).show() finish() return } // Initialize the SDK with the application context and API key. Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey) // Initialize the location client. fusedLocationClient = LocationServices.getFusedLocationProviderClient(this) // ------------------------------------ // Obtain the SupportMapFragment and request the map asynchronously. val mapFragment = supportFragmentManager.findFragmentById(R.id.map_fragment) as SupportMapFragment? mapFragment?.getMapAsync(this) // After rotation, check if a place was selected. If so, restore the fragment. if (viewModel.selectedPlaceId != null) { viewModel.selectedPlaceId?.let { placeId -> Log.d(TAG, "Restoring PlaceDetailsFragment for place ID: $placeId") showPlaceDetailsFragment(placeId) } } } /** * Callback triggered when the map is ready to be used. */ override fun onMapReady(map: GoogleMap) { Log.d(TAG, "Map is ready") googleMap = map // Set a listener for clicks on Points of Interest. googleMap?.setOnPoiClickListener(this) // Check for location permissions to determine the initial map position. if (isLocationPermissionGranted()) { fetchLastLocation() } else { requestLocationPermissions() } } /** * Checks if either fine or coarse location permission has been granted. */ private fun isLocationPermissionGranted(): Boolean { return ActivityCompat.checkSelfPermission( this, Manifest.permission.ACCESS_FINE_LOCATION ) == PackageManager.PERMISSION_GRANTED || ActivityCompat.checkSelfPermission( this, Manifest.permission.ACCESS_COARSE_LOCATION ) == PackageManager.PERMISSION_GRANTED } /** * Launches the permission request flow. The result is handled by the * ActivityResultLauncher defined in onCreate. */ private fun requestLocationPermissions() { Log.d(TAG, "Requesting location permissions.") requestPermissionLauncher.launch( arrayOf( Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION ) ) } /** * Fetches the device's last known location and moves the map camera to it. * This function should only be called after verifying permissions. */ @SuppressLint("MissingPermission") private fun fetchLastLocation() { if (isLocationPermissionGranted()) { fusedLocationClient.lastLocation .addOnSuccessListener { location: Location? -> if (location != null) { // Move camera to user's location if available. val userLocation = LatLng(location.latitude, location.longitude) googleMap?.moveCamera(CameraUpdateFactory.newLatLngZoom(userLocation, 13f)) Log.d(TAG, "Moved to user's last known location.") } else { // Fallback to a default location if the last location is null. Log.d(TAG, "Last known location is null. Falling back to Sydney.") moveToSydney() } } .addOnFailureListener { // Handle errors in fetching location. Log.e(TAG, "Failed to get location.", it) moveToSydney() } } } /** * A default fallback location for the map camera. */ private fun moveToSydney() { val sydney = LatLng(-33.8688, 151.2093) googleMap?.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 13f)) Log.d(TAG, "Moved to Sydney") } /** * Callback for when a Point of Interest on the map is clicked. */ override fun onPoiClick(poi: PointOfInterest) { val placeId = poi.placeId Log.d(TAG, "Place ID: $placeId") // Save the selected place ID to the ViewModel to survive rotation. viewModel.selectedPlaceId = placeId showPlaceDetailsFragment(placeId) } /** * Instantiates and displays the [PlaceDetailsCompactFragment]. * @param placeId The unique identifier for the place to be displayed. */ private fun showPlaceDetailsFragment(placeId: String) { Log.d(TAG, "Showing PlaceDetailsFragment for place ID: $placeId") // Show the wrapper, hide the dismiss button, and show the loading indicator. binding.placeDetailsWrapper.visibility = View.VISIBLE binding.dismissButton.visibility = View.GONE binding.placeDetailsContainer.visibility = View.GONE binding.loadingIndicator.visibility = View.VISIBLE // Determine the orientation based on the device's current configuration. val orientation = if (resources.configuration.orientation == Configuration.ORIENTATION_LANDSCAPE) { Orientation.HORIZONTAL } else { Orientation.VERTICAL } // Create a new instance of the fragment from the Places SDK. val fragment = PlaceDetailsCompactFragment.newInstance( PlaceDetailsCompactFragment.ALL_CONTENT, orientation, R.style.CustomizedPlaceDetailsTheme, ).apply { // Set a listener to be notified when the place data has been loaded. setPlaceLoadListener(object : PlaceLoadListener { override fun onSuccess(place: Place) { Log.d(TAG, "Place loaded: ${place.id}") // Hide loader, show the fragment container and the dismiss button binding.loadingIndicator.visibility = View.GONE binding.placeDetailsContainer.visibility = View.VISIBLE binding.dismissButton.visibility = View.VISIBLE } override fun onFailure(e: Exception) { Log.e(TAG, "Place failed to load", e) // Hide everything on failure dismissPlaceDetails() Toast.makeText(this@MainActivity, "Failed to load place details.", Toast.LENGTH_SHORT).show() } }) } // Add the fragment to the container in the layout. supportFragmentManager .beginTransaction() .replace(binding.placeDetailsContainer.id, fragment) .commitNow() // Use commitNow to ensure the fragment is immediately available. // **This is the key step**: Tell the fragment to load data for the given Place ID. binding.root.post { fragment.loadWithPlaceId(placeId) } } private fun dismissPlaceDetails() { binding.placeDetailsWrapper.visibility = View.GONE viewModel.selectedPlaceId = null } override fun onDestroy() { super.onDestroy() // Clear references to avoid memory leaks. googleMap = null } }
Creare un tema
Quando istanzi un frammento, puoi specificare un tema che esegue l'override di uno qualsiasi degli attributi di stile predefiniti. Gli attributi del tema non sostituiti utilizzano gli stili predefiniti. Se vuoi supportare un tema scuro, puoi aggiungere una voce per il colore in values-night/colors.xml.
<style name="CustomizedPlaceDetailsTheme" parent="PlacesMaterialTheme"> <item name="placesColorPrimary">@color/app_primary_color</item> <item name="placesColorOnSurface">@color/app_color_on_surface</item> <item name="placesColorOnSurfaceVariant">@color/app_color_on_surface</item> <item name="placesTextAppearanceBodySmall">@style/app_text_appearence_small</item> <item name="placesCornerRadius">20dp</item> </style>
Utilizzare contenuti standard
Questo esempio utilizza i contenuti standard.
val fragmentStandardContent = PlaceDetailsCompactFragment.newInstance(
PlaceDetailsCompactFragment.STANDARD_CONTENT,
orientation,
R.style.CustomizedPlaceDetailsTheme
)Personalizzare contenuti specifici
Questo campione seleziona solo le opzioni indirizzo, ingresso accessibile e media Content per una visualizzazione compatta e le visualizza con CustomizedPlaceDetailsTheme.
val placeDetailsFragment = PlaceDetailsCompactFragment.newInstance(
orientation,
listOf(
Content.ADDRESS,
Content.ACCESSIBLE_ENTRANCE,
Content.MEDIA
),
R.style.CustomizedPlaceDetailsTheme
)Utilizzare tutti i contenuti
Questo esempio utilizza tutte le opzioni Content di una visualizzazione compatta.
val fragmentAllContent = PlaceDetailsCompactFragment.newInstance(
orientation,
PlaceDetailsCompactFragment.ALL_CONTENT,
R.style.CustomizedPlaceDetailsTheme
)