迁移到 Places Swift SDK for iOS

从 Places SDK for iOS 迁移到 Places Swift SDK for iOS 应该非常简单，并且可以逐步完成。由于适用于 iOS 的 Places Swift SDK 中的结构体与其基于 Objective-C 的对应项不兼容，因此我们建议根据 GMSPlacesClient 中 API 的使用情况迁移离散的功能块。

将 Places Swift SDK for iOS 添加到您的项目

如需使用 Places Swift SDK for iOS，请按以下步骤操作：

  1. 启用 Places API（新）。

  2. 将 Places Swift SDK 添加到您的依赖项中。您可以选择安装 GooglePlaces、GooglePlacesSwift 或同时安装这两者。

  3. 使用 PlacesClient 初始化 Places 客户端。

分步迁移示例

例如，假设某个应用使用 Places SDK for iOS 接收基于文本输入的自动补全建议，然后提取第一个地点建议的详细信息。使用 Places SDK for iOS 时，现有代码可能如下所示：

// Initialize Places Client.
GMSPlacesClient.provideAPIKey(apiKey)
let client = GMSPlacesClient.shared()

// Fetch Autocomplete Request.
let center = CLLocation(latitude: 37.3913916, longitude: -122.0879074)
let northEast = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWest = CLLocationCoordinate2DMake(37.395804, -122.077023)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.origin = center
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest)

let request = GMSAutocompleteRequest(query: "Sicilian piz")
request.filter = filter

client.fetchAutocompleteSuggestions(from: request) { (results, error) in
  guard let results, error == nil else {
    print("Autocomplete error: \(String(describing: error))")
    return
  }

  // Fetch Place Request.
  guard let placeID = results.first?.placeSuggestion?.placeID else { return }
  let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

  let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

  client.fetchPlace(with: fetchPlaceRequest) { (place: GMSPlace?, error: Error?) in
    guard let place, error == nil else { return }
    print("Place found: \(String(describing: place.name)); \(String(describing: place.website))")
  }
}

更新 Places Client 初始化程序

为了使代码现代化并利用新 SDK 的功能，您需要将 GMSPlacesClient 替换为 PlacesClient。此外，新方法中的形参名称已更改，因此您需要将形参更新为 from，而不是 with。最后，Places Swift SDK 使用升级后的 AutocompleteRequest。

更新后的代码

// Initialize Places Swift Client.
let _ = PlacesClient.provideAPIKey(apiKey)
let placesSwiftClient = PlacesClient.shared

原始代码

// Initialize Places Client.
GMSPlacesClient.provideAPIKey(apiKey)
let client = GMSPlacesClient.shared()

更新自动填充请求

您可以先更新自动补全请求流程。旧代码使用回调来请求自动补全建议，而新代码采用 switch/await 模式。回调可能会增加代码结构和错误处理的复杂性。新的 Places Swift SDK 支持并发，可简化异步操作。

// Initialize Places Swift Client.
let _ = PlacesClient.provideAPIKey(apiKey)
let placesSwiftClient = PlacesClient.shared

// Fetch Autocomplete Request.
let center = CLLocation(latitude: 37.3913916, longitude: -122.0879074)
let northEast = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWest = CLLocationCoordinate2DMake(37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
let placeID: String
switch await placesSwiftClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let results):
  switch results.first {
  case .place(let placeSuggestion):
    placeID = placeSuggestion.placeID
  case .none:
    fallthrough
  @unknown default:
    return
  }
case .failure(let placesError):
  print("Autocomplete error: \(placesError)")
  return
}

// Initialize Places Client.
GMSPlacesClient.provideAPIKey(apiKey)
let placesClient = GMSPlacesClient.shared()

// Fetch Place Request.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

placesClient.fetchPlace(with: fetchPlaceRequest) { (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name)); \(String(describing: place.website))")
}

替换已弃用的类、方法和 typedef

自 v10.4 起，Places SDK for iOS 中的以下类、方法和 typedef 已弃用。在 2026 年第 3 季度发布的 v11.0 版本中，这些功能将不再提供。

下表显示了已弃用的方法及其替代方法：

已弃用 替换
currentPlaceWithCallback 或 findPlaceLikelihoodsFromCurrentLocationWithPlaceFields searchNearbyWithRequest
lookUpPlaceID 或 fetchPlaceFromPlaceID fetchPlaceWithRequest
lookUpPhotosForPlaceID 或 loadPlacePhoto fetchPhotoWithRequest
GMSAutocompletePrediction AutocompleteSuggestion
findAutocompletePredictionsFromQuery 或 GMSAutocompleteFetcher fetchAutocompleteSuggestionsFromRequest
isOpenWithPlaceID 或 isOpenWithPlace isOpenWithRequest
GMSAutocompleteResultsViewController、GMSAutocompleteTableDataSource 或 GMSAutocompleteViewController placeAutocomplete

更新方法和类名称

最后，通过重构 fetchPlace 代码并移除 GMSPlacesClient 初始化和 GMSPlaceProperty 声明来完成迁移。在 Places Swift SDK 中，方法和类名称已更新，移除了“GMS”前缀，因此必须相应地进行更新；例如，GMSFetchPlaceRequest 变为 FetchPlaceRequest。

类型处理

新的 fetchPlace 方法改进了类型处理。旧代码需要传递属性的原始值，而新代码不需要开发者在此处显式提取原始值，从而提高了简洁性和可读性。

并发

此外，新方法还支持并发，从而允许在 placesSwiftClient.fetchPlace 中使用 switch/await 模式替换 placesClient.fetchPlace 中的回调。

// Initialize Places Swift Client.
let _ = PlacesClient.provideAPIKey(apiKey)
let placesSwiftClient = PlacesClient.shared

// Fetch Autocomplete Request.
let center = CLLocation(latitude: 37.3913916, longitude: -122.0879074)
let northEast = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWest = CLLocationCoordinate2DMake(37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
let placeID: String
switch await placesSwiftClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let results):
  switch results.first {
  case .place(let placeSuggestion):
    placeID = placeSuggestion.placeID
  case .none:
    fallthrough
  @unknown default:
    return
  }
case .failure(let placesError):
  print("Autocomplete error: \(placesError)")
  return
}

// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(placeID: placeID, placeProperties: [.displayName, .websiteURL])
switch await placesSwiftClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  print("Place found: \(place.displayName): \(String(describing: place.description))")

case .failure(let placesError):
  print("Place not found: \(placeID); \(placesError)")
}

随时掌握最新动态

访问 Places Swift SDK for iOS 的版本说明页面，了解新功能和变更。