„Place Markers“-Komponente

Mit der Komponente „Ortsmarkierungen“ können Sie benutzerdefinierte Kartenanmerkungen erstellen, in denen wichtige Ortsinformationen direkt auf der Karte angezeigt werden. Sie können Inhalte wie die Bewertung eines Orts, den Ortstyp, den Status „Geöffnet“ oder „Geschlossen“, die Preisspanne oder benutzerdefinierten Text (z. B. ein KI-generiertes Label oder eine Routennummer) anzeigen. So können Nutzer die Karte besser erkunden, ohne auf eine detaillierte Ortskarte tippen zu müssen.

Verfügbare Symbole und Texte für Ortsmarkierungen

Pro PlaceMarker können Sie ein Markierungssymbol und optionalen Markierungstext anzeigen lassen.

Folgende Symbole sind verfügbar:

  • Type: Der Ortstyp.
  • None: Kein Symbol.
Folgende Textmarkierungen sind verfügbar:
  • Rating: Bewertungs-Score.
  • PriceRange: Preisspanne (z. B. 10–20 €)
  • OpenStatus: Gibt an, ob ein Unternehmen geöffnet oder geschlossen ist.
  • Custom: Benutzerdefinierter Text, z. B. „BELIEBT“.

Verweisen Sie auf den Ort mit einer Orts-ID (PlaceId), einem Ressourcennamen (ResourceName) oder geografischen Koordinaten (Coordinates).

Anzeige- und Quellenangabeanforderungen

Wenn Kartenmarkierungen des Places UI Kit angezeigt werden, dürfen sie nicht isoliert dargestellt werden. Sie müssen interaktiv sein und beim Klicken oder Tippen eine zugehörige Place Details-Komponente oder eine Lightbox öffnen, um das erforderliche Google-Branding, die Quellenangabe für Mitwirkende und die Abläufe zum Melden von Problemen bereitzustellen.

Hier finden Sie Informationen zu den Anforderungen an die Quellenangabe für Fotos und Rezensionen für Szenarien, in denen der Platz begrenzt ist.

Beispiele für „Markierung platzieren“

Wir stellen Jetpack Compose-Funktionen @Composable zur Verfügung, um den Overhead von View-to-Compose-Wrappern zu vermeiden und Probleme mit Theme-Inkompatibilitäten zu umgehen.

Einfache Anpassung von Markierungen

Das folgende Codebeispiel zeigt grundlegende Anpassungen von Ortsmarkierungen, einschließlich des Ausblendens der dreieckigen Sprechblase für die Standardmarkierung.

Kotlin

import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.PlaceMarker
import com.google.android.libraries.places.compose.marker.MarkerIcon
import com.google.android.libraries.places.compose.marker.MarkerText
import com.google.android.libraries.places.compose.PlaceReference

@Composable
fun DefaultMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.None,
        beakPresence = false, // remove beak
    )
}

@Composable
fun RatingMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.None,
        text = MarkerText.Rating
    )
}

@Composable
fun TypeAndRatingMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.Type,
        text = MarkerText.Rating

    )
}

@Composable
fun PriceRangeMarker() {
    PlaceMarker(
        reference = PlaceReference.ResourceName("places/PLACE_RESOURCE_NAME"),
        icon = MarkerIcon.None,
        text = MarkerText.PriceRange
    )
}

@Composable
fun OpenStatusMarker() {
   PlaceMarker(
       reference = PlaceReference.Coordinates(latitude = 37.7749, longitude = -122.4194),
        icon = MarkerIcon.None,
        text = MarkerText.OpenStatus
   )
}

@Composable
fun CustomTextMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.None,
        // Custom text accepts a String to display a number (e.g. "3") or text (e.g. "NEW")
        text = MarkerText.Custom("NEW")
    )
}

Click Listener erstellen

Sie können einen onClick-Callback angeben, um benutzerdefinierte Aktionen auszulösen, wenn auf eine eigenständige Markierung getippt wird. Wenn die Markierung jedoch auf einer Karte gerendert wird (z. B. innerhalb von MarkerComposable), werden Tippereignisse von der Karte abgefangen. In diesem Fall müssen Sie den onClick-Handler des MarkerComposable anstelle des Markers verwenden.

Das folgende Codebeispiel zeigt, wie der onClick-Handler von MarkerComposable verwendet wird.

Kotlin

import android.util.Log
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.PlaceMarker
import com.google.android.libraries.places.compose.marker.MarkerIcon
import com.google.android.libraries.places.compose.PlaceReference


/**
 * PlaceMarker used outside of a map (e.g. in a list, bottom sheet, or custom overlay).
 *
 * There is no host component that provides a default click behavior here, so PlaceMarker's own
 * `onClick` is the only way for a developer to react to a tap. This is why `onClick` must stay
 * on the PlaceMarker API.
 */
@Composable
fun ClickableMarkerWithCustomConfig() {
   PlaceMarker(
       reference = PlaceReference.PlaceId("PLACE_ID"),
       icon = MarkerIcon.Type,
       
       onClick = { place ->
           openPlaceCard(place.id) // developer might want to open the place card
           Log.i("PlacesMarker", "Marker was tapped by user!")
       }
   )
}

/**
 * PlaceMarker used as the content of a MarkerComposable on a GoogleMap.
 *
 * MarkerComposable does NOT add PlaceMarker to the touch-input hierarchy: it snapshots the
 * composable into a bitmap and hands that bitmap to the Maps renderer as the marker icon. The
 * rendered marker is a map object, not a Compose node, so:
 *
 *   - PlaceMarker's own `onClick` would never be invoked here (no touch events ever reach it).
 *   - The tap is delivered by the Maps SDK to MarkerComposable's `onClick`, which is the only
 *     click entry point on a map.
 *
 * Accordingly, the state-based `PlaceMarker(state = ...)` overload used below deliberately does
 * not expose an `onClick` parameter, so the correct handler is the only one available.
 */
@Composable
fun PlaceMarkerOnMap(markerState: PlaceMarkerState) {
  GoogleMap(
    modifier = Modifier.fillMaxSize(),
    cameraPositionState = rememberCameraPositionState(),
  ) {
    markerState.location?.let { position ->
      MarkerComposable(
        state = rememberUpdatedMarkerState(position = position),
        // this is the click handler for the map use case.
        onClick = {
          markerState.place?.let { place -> openPlaceCard(place.id) }
          true // consume the event
        },
      ) {
        PlaceMarker(state = markerState)
      }
    }
  }
}

Ladestatus und Rückrufe verarbeiten

Das folgende Codebeispiel zeigt, wie Sie Callbacks bereitstellen, um Rendering- oder fehlende Datenfehler zu verarbeiten.

Kotlin

import android.util.Log
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.PlaceMarker
import com.google.android.libraries.places.compose.marker.MarkerIcon
import com.google.android.libraries.places.compose.PlaceReference

@Composable
fun StatusHandlingMarker() {
    PlaceMarker(
        reference = PlaceReference.PlaceId("PLACE_ID"),
        icon = MarkerIcon.Type,
        // Triggered when attribute data is successfully fetched and the marker is rendered.
        // Returns a minimal Place object with ID, location (LatLng), and viewport fields set.
        onMarkerLoaded = { place ->
            Log.i("PlacesMarker", "Marker successfully loaded for place ID: ${place.id}")
        },
        // Triggered when data fetching fails or required attribute data is missing for the place.
        // Returns an optional Place object and an Exception describing the root cause.
        onMarkerLoadFailed = { place, exception ->
            Log.e("PlacesMarker", "Failed to load marker for place ID: ${place?.id}", exception)
        }
    )
}

Mit PlaceMarkerState Markierungen auf der Karte platzieren

Das Place-Objekt wird mit Standort und Viewport zurückgegeben, damit Sie entscheiden können, wo Sie die Markierung platzieren.

Kotlin

// Step 1: Obtain configured handle in a single 1-line call (PlaceMarker mounted internally)
val markerState = rememberPlaceMarkerState(
  reference = PlaceReference.PlaceId(placeId),
  icon = MarkerIcon.Type
)

// Step 2: Pass PlaceMarkerState.location and PlaceMarker(state = PlaceMarkerState) directly to the map marker
GoogleMap(...) {
  markerState.location?.let { position ->
    MarkerComposable(
      state = rememberMarkerState(position = position),
      onClick = {
        markerState.place?.let { place ->
          // Handle marker click
        }
        true
      }
    ) {
      PlaceMarker(state = markerState) // Render marker UI content directly on map canvas
    }
  }
}

Markierung auf eine benutzerdefinierte Größe skalieren

Kotlin

// Off the map: scale with a one-line modifier.
// Modifier.scale is a draw-time transform, so the bubble, beak, icon and text all scale together.
@Composable
fun ScaledMarker() {
  PlaceMarker(
    reference = PlaceReference.PlaceId(placeId),
    icon = MarkerIcon.Type,
    text = MarkerText.Rating,
    modifier = Modifier.scale(2.1f),
  )
}

// On the map: scale by overriding LocalDensity.
// MarkerComposable snapshots its content into a marker bitmap sized to the measured layout bounds.
// Modifier.scale does not change those bounds, so the marker would be clipped and blurry. Scaling
// the density re-measures every dp and sp inside the marker, so the bitmap, the layout bounds and
// the map hit target all grow with it.
@Composable
fun ScaledMarkerOnMap(markerState: PlaceMarkerState) {
  val density = LocalDensity.current
  val scaledDensity = remember(density) {
    Density(density = density.density * 2.1f, fontScale = density.fontScale * 2.1f)
  }
  GoogleMap(...) {
    markerState.location?.let { position ->
      MarkerComposable(
        state = rememberUpdatedMarkerState(position = position),
        anchor = Offset(0.5f, 1.0f),
      ) {
        CompositionLocalProvider(LocalDensity provides scaledDensity) {
          PlaceMarker(state = markerState)
        }
      }
    }
  }
}