اختيار النظام الأساسي: Android iOS JavaScript

المكوّن الأساسي لميزة "الإكمال التلقائي للأماكن"

يتيح لك مكوّن "الإكمال التلقائي البسيط للأماكن" في Places UI Kit إضافة مكوّن فردي لواجهة المستخدم يعرض رقم تعريف مكان عندما يختار المستخدم مكانًا. المكوّن هو غطاء بملء الشاشة يوفّر شريط بحث للمستخدمين لإدخال طلب بحث. أثناء كتابة المستخدم، ستظهر قائمة بنتائج الإكمال التلقائي أسفل شريط البحث. عندما ينقر المستخدم على مكان، يتم عرض عنصر مكان يتضمّن معرّف المكان فقط للمطوّر. هذا المكوِّن قابل للتخصيص.

تتلقّى الأداة حدودًا جغرافية ومَعلمات بحث أخرى من خلال البنية AutocompleteFilter.

يوفّر الرد بنية Place مع ملء الحقل placeID فقط.

يتضمّن مكوّن "الإكمال التلقائي للأماكن" الأساسي خيارات التخصيص التالية: كثافة القائمة، وما إذا كان سيتم تضمين رموز المواقع الجغرافية. استخدِم بنية AutocompleteUICustomization لتخصيص المكوّن.

يمكنك استخدام مكوّن "الإكمال التلقائي للأماكن" الأساسي بشكل مستقل أو بالاشتراك مع واجهات برمجة التطبيقات والخدمات الأخرى في Google Maps Platform.

الفوترة

يتم تحصيل رسوم منك في كل مرة يتم فيها فتح المكوّن وإجراء طلب بحث. ولن يتم تحصيل رسوم منك مرة أخرى مقابل هذه الجلسة ما لم تنتهِ صلاحية الجلسة أو يتم اختيار مكان من القائمة.

إضافة مكوّن "الإكمال التلقائي الأساسي" إلى تطبيقك

اضبط مَعلمات فلتر الإكمال التلقائي (على سبيل المثال، الأنواع المطلوب عرضها، والبلد الذي يجب حصر النتائج فيه، وإحداثيات المنطقة للنتائج، ومعلومات المسافة في حال ضبط مصدر المستخدم) كما تفعل لاستخدام Place Autocomplete (New) بدون Places UI Kit. راجِع مستندات Place Autocomplete (جديد) للحصول على التعليمات الكاملة ومثال على الرمز البرمجي لإنشاء فلتر إكمال تلقائي.

بعد إنشاء فلتر الإكمال التلقائي، يمكنك إنشاء بنية تتضمّن تخصيصات واجهة المستخدم. الاطّلاع على خيارات التخصيص والتعليمات

بعد ذلك، أنشئ زرًا سيشغّل مكوّن "الإكمال التلقائي الأساسي" المخصّص.

Swift

  Button("Search for a place") {
    showWidget.toggle()
  }
  .basicPlaceAutocomplete(
    show: $showWidget
     // ...
  )

الاطّلاع على المثال الكامل

تخصيص مكوّن "الإكمال التلقائي الأساسي"

تخصيص المحتوى

كثافة القائمة

يمكنك اختيار عرض قائمة من سطرَين أو قائمة متعدّدة الأسطر. استخدِم الخيارات في AutocompleteListDensity (.twoLine أو .multiLine) في الفئة AutocompleteUICustomization. إذا لم تحدّد كثافة القائمة، سيعرض المكوّن قائمة من سطرَين.

رمز الموقع الجغرافي

يمكنك اختيار ما إذا كنت تريد عرض رمز مكان تلقائي في قائمة النتائج. استخدِم الخيارات في AutocompleteUIIcon (.defaultIcon أو .noIcon) في الفئة AutocompleteUICustomization.

تخصيص المظهر

يمكنك تحديد مظهر يلغي أيًا من سمات النمط التلقائي. يمكنك تخصيص ألوان ومظهر الخطوط والمسافات والحدود والزوايا لمكوّن "تفاصيل المكان". القيمة التلقائية هي PlacesMaterialTheme.

تستخدم أي سمات للمظهر لم يتم إلغاؤها الأنماط التلقائية.

توفّر حزمة Places UI Kit مظهرًا داكنًا تلقائيًا، لذا قد تحتاج إلى تخصيص المظهرين الداكن والفاتح. لتخصيص المظهر الداكن، أضِف قيمًا إلى .dark وattribution.darkModeColor في المظهر المخصّص.

راجِع قسم التصميم المخصّص لمزيد من المعلومات حول التصميم.

إضافة تخصيصات المحتوى والمظهر إلى مكوّن "الإكمال التلقائي الأساسي"

استخدِم الفئة AutocompleteUICustomization لتخصيص مكوّن "الإكمال التلقائي الأساسي".

Swift

let uiCustomization = AutocompleteUICustomization(
    listDensity: .multiLine,
    listItemIcon: .noIcon,
    theme: PlacesMaterialTheme()
)

مثال

إضافة مكوّن "إكمال تلقائي أساسي"

ملاحظة مهمة: اضبط القيمة الأولية لـ showWidget على "خطأ" لكي يظهر المكوّن المخصّص عند نقر المستخدم على الزر.

ينشئ هذا المثال مكوّن "الإكمال التلقائي الأساسي" مخصّصًا يتضمّن زرًا. تم ضبط الرمز التلقائي وكثافة عرض القائمة المكوّنة من سطرَين والمظهر المخصّص. تم ضبط فلتر الإكمال التلقائي للعثور على أماكن ذات صلة بالمحاسبة في لاس فيغاس والمناطق القريبة منها.

Swift

  // Note: You must provide an API key in your app entry point first.
  // A demo view of the basic place autocomplete widget.
  public struct BasicPlaceAutocompleteView: View {
    @State private var fetchedPlace: Place?
    @State private var placesError: PlacesError?
    @State private var showWidget = false
    public var body: some View {
      let types: Set<PlaceType> = [.accounting]
      let countries: Set<String> = ["US"]
      let origin = CLLocation(latitude: 36.19030535579595, longitude: -115.25397680618019)
      let coordinateRegion = RectangularCoordinateRegion(
        northEast: CLLocationCoordinate2D(
          latitude: 36.25290087640495, longitude: -115.08025549571225),
        southWest: CLLocationCoordinate2D(latitude: 36.06607422287787, longitude: -115.33431432920293)
      )
      let regionCode = "US"
      let inputOffset = 10
      let filter = AutocompleteFilter(
        types: types,
        countries: countries,
        origin: origin,
        coordinateRegionBias: coordinateRegion,
        regionCode: regionCode)
      let uiCustomization = AutocompleteUICustomization(
        listDensity: .multiLine,
        listItemIcon: .noIcon,
        theme: PlacesMaterialTheme()
      )
      VStack {
        Button("Search for a place") {
          showWidget.toggle()
        }
        .basicPlaceAutocomplete(
          filter: filter,
          uiCustomization: uiCustomization ?? AutocompleteUICustomization(),
          show: $showWidget,
          onSelection: { place in
            guard let placeID = place.placeID else {
              self.placesError = .internal(
                "Could not fetch place details because place ID from selected suggestion not found."
              )
              return
            }
            Task {
              let placesClient = await PlacesClient.shared
              let fetchPlaceRequest = FetchPlaceRequest(
                placeID: placeID,
                placeProperties: [.displayName, .formattedAddress]
              )
              switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
              case .success(let place):
                print("Fetched place: \(place)")
                self.fetchedPlace = place
              case .failure(let placesError):
                print("Failed to fetch place: \(placesError)")
                self.placesError = placesError
              }
            }
          },
          onError: { placesError in
            self.placesError = placesError
          }
        )
        if let placesError = $placesError.wrappedValue {
          Text(placesError.localizedDescription)
            .frame(maxWidth: .infinity, alignment: .leading)
        } else if let fetchedPlace = $fetchedPlace.wrappedValue {
          Text("\(fetchedPlace)")
            .frame(maxWidth: .infinity, alignment: .leading)
        }
      }
    }
  }

تخصيص المظهر

Swift

@Environment(\.colorScheme) var colorScheme
var theme: PlacesMaterialTheme {
    if customTheme {
      var theme = PlacesMaterialTheme()
      var color = PlacesMaterialColor()
      color.surface = (colorScheme == .dark ? .blue : .gray)
      color.outlineDecorative = (colorScheme == .dark ? .white : .black)
      color.onSurface = (colorScheme == .dark ? .yellow : .red)
      color.onSurfaceVariant = (colorScheme == .dark ? .white : .blue)
      color.onSecondaryContainer = (colorScheme == .dark ? .white : .red)
      color.secondaryContainer = (colorScheme == .dark ? .green : .purple)
      color.positive = (colorScheme == .dark ? .yellow : .red)
      color.primary = (colorScheme == .dark ? .yellow : .purple)
      color.info = (colorScheme == .dark ? .yellow : .purple)
      var shape = PlacesMaterialShape()
      shape.cornerRadius = 10
      var font = PlacesMaterialFont()
      font.labelLarge = .system(size: UIFontMetrics.default.scaledValue(for: 18))
      font.headlineMedium = .system(size: UIFontMetrics.default.scaledValue(for: 15))
      font.bodyLarge = .system(size: UIFontMetrics.default.scaledValue(for: 15))
      font.bodyMedium = .system(size: UIFontMetrics.default.scaledValue(for: 12))
      font.bodySmall = .system(size: UIFontMetrics.default.scaledValue(for: 11))
      var attribution = PlacesMaterialAttribution()
      attribution.lightModeColor = .black
      attribution.darkModeColor = .white
      theme.color = color
      theme.shape = shape
      theme.font = font
      theme.attribution = attribution
    } else {
      return PlacesMaterialTheme()
    }
}