A próxima geração do SDK do Places para iOS já está disponível com o lançamento do SDK do Places para iOS (novo).

Esta página foi traduzida pela API Cloud Translation.

Place Autocomplete

Selecione a plataforma: Android iOS JavaScript Serviço da Web

Avisos de descontinuação

O serviço de preenchimento automático no SDK do Places para iOS retorna previsões de lugares em resposta às consultas de pesquisa dos usuários. À medida que o usuário digita, o serviço de preenchimento automático retorna sugestões de lugares como empresas, endereços, Plus Codes e pontos de interesse.

É possível adicionar o preenchimento automático no aplicativo das seguintes formas:

Adicionar um controle de interface de preenchimento automático para economizar tempo de desenvolvimento e garantir uma experiência consistente do usuário.
Receba previsões de lugares de forma programática para criar uma experiência do usuário personalizada.

Adicionar um controle de interface de preenchimento automático

O controle de interface de preenchimento automático é uma caixa de diálogo de pesquisa com a funcionalidade de preenchimento automático integrada. Quando o usuário digita termos de pesquisa, o controle apresenta uma lista de lugares previstos para escolher. Quando o usuário faz uma seleção, uma instância GMSPlace é retornada, que seu app pode usar para ver detalhes sobre o lugar selecionado.

É possível adicionar o widget de preenchimento automático do seu aplicativo das seguintes formas:

Adicionar um controle de tela cheia
Adicionar um controlador de resultados
Usar uma fonte de dados de tabela

Como adicionar um controle de tela cheia

Use o controle de tela cheia quando quiser um contexto modal, em que a interface de preenchimento automático substitui temporariamente a interface do app até que o usuário faça a seleção. Essa funcionalidade é fornecida pela classe GMSAutocompleteViewController. Quando o usuário seleciona um local, o aplicativo recebe um retorno de chamada.

Para adicionar um widget de tela cheia ao aplicativo:

Crie um elemento de interface no app principal para iniciar o controle de interface de preenchimento automático, por exemplo, um gerenciador de toque em uma UIButton.
Implemente o protocolo GMSAutocompleteViewControllerDelegate no controlador de visualizações pai.
Crie uma instância de GMSAutocompleteViewController e atribua o controlador de visualização pai como a propriedade "delegada".
Crie um GMSPlaceField para definir os tipos de dados de lugar que serão retornados.
Adicione um GMSAutocompleteFilter para restringir a consulta a um determinado tipo de lugar.
Apresente a GMSAutocompleteViewController usando [self presentViewController...].
Processe a seleção do usuário no método delegado didAutocompleteWithPlace.
Dispense o controlador nos métodos delegados didAutocompleteWithPlace, didFailAutocompleteWithError e wasCancelled.

O exemplo abaixo demonstra uma maneira possível de iniciar GMSAutocompleteViewController em resposta ao toque do usuário em um botão.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

  override func viewDidLoad() {
    makeButton()
  }

  // Present the Autocomplete view controller when the button is pressed.
  @objc func autocompleteClicked(_ sender: UIButton) {
    let autocompleteController = GMSAutocompleteViewController()
    autocompleteController.delegate = self

    // Specify the place data types to return.
    let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
      UInt(GMSPlaceField.placeID.rawValue))!
    autocompleteController.placeFields = fields

    // Specify a filter.
    let filter = GMSAutocompleteFilter()
    filter.types = [.address]
    autocompleteController.autocompleteFilter = filter

    // Display the autocomplete view controller.
    present(autocompleteController, animated: true, completion: nil)
  }

  // Add a button to the view.
  func makeButton() {
    let btnLaunchAc = UIButton(frame: CGRect(x: 5, y: 150, width: 300, height: 35))
    btnLaunchAc.backgroundColor = .blue
    btnLaunchAc.setTitle("Launch autocomplete", for: .normal)
    btnLaunchAc.addTarget(self, action: #selector(autocompleteClicked), for: .touchUpInside)
    self.view.addSubview(btnLaunchAc)
  }

}

extension ViewController: GMSAutocompleteViewControllerDelegate {

  // Handle the user's selection.
  func viewController(_ viewController: GMSAutocompleteViewController, didAutocompleteWith place: GMSPlace) {
    print("Place name: \(place.name)")
    print("Place ID: \(place.placeID)")
    print("Place attributions: \(place.attributions)")
    dismiss(animated: true, completion: nil)
  }

  func viewController(_ viewController: GMSAutocompleteViewController, didFailAutocompleteWithError error: Error) {
    // TODO: handle the error.
    print("Error: ", error.localizedDescription)
  }

  // User canceled the operation.
  func wasCancelled(_ viewController: GMSAutocompleteViewController) {
    dismiss(animated: true, completion: nil)
  }

  // Turn the network activity indicator on and off again.
  func didRequestAutocompletePredictions(_ viewController: GMSAutocompleteViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
  }

  func didUpdateAutocompletePredictions(_ viewController: GMSAutocompleteViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
  }

}

Objective-C

#import "ViewController.h"
@import GooglePlaces;

@interface ViewController () <GMSAutocompleteViewControllerDelegate>

@end

@implementation ViewController {
  GMSAutocompleteFilter *_filter;
}

- (void)viewDidLoad {
  [super viewDidLoad];
  [self makeButton];
}

  // Present the autocomplete view controller when the button is pressed.
- (void)autocompleteClicked {
  GMSAutocompleteViewController *acController = [[GMSAutocompleteViewController alloc] init];
  acController.delegate = self;

  // Specify the place data types to return.
  GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);
  acController.placeFields = fields;

  // Specify a filter.
  _filter = [[GMSAutocompleteFilter alloc] init];
  _filter.types = @[ kGMSPlaceTypeBank ];
  acController.autocompleteFilter = _filter;

  // Display the autocomplete view controller.
  [self presentViewController:acController animated:YES completion:nil];
}

  // Add a button to the view.
- (void)makeButton{
  UIButton *btnLaunchAc = [UIButton buttonWithType:UIButtonTypeCustom];
  [btnLaunchAc addTarget:self
             action:NSSelectorFromString(@"autocompleteClicked") forControlEvents:UIControlEventTouchUpInside];
  [btnLaunchAc setTitle:@"Launch autocomplete" forState:UIControlStateNormal];
  btnLaunchAc.frame = CGRectMake(5.0, 150.0, 300.0, 35.0);
  btnLaunchAc.backgroundColor = [UIColor blueColor];
  [self.view addSubview:btnLaunchAc];
}

  // Handle the user's selection.
- (void)viewController:(GMSAutocompleteViewController *)viewController
didAutocompleteWithPlace:(GMSPlace *)place {
  [self dismissViewControllerAnimated:YES completion:nil];
  // Do something with the selected place.
  NSLog(@"Place name %@", place.name);
  NSLog(@"Place ID %@", place.placeID);
  NSLog(@"Place attributions %@", place.attributions.string);
}

- (void)viewController:(GMSAutocompleteViewController *)viewController
didFailAutocompleteWithError:(NSError *)error {
  [self dismissViewControllerAnimated:YES completion:nil];
  // TODO: handle the error.
  NSLog(@"Error: %@", [error description]);
}

  // User canceled the operation.
- (void)wasCancelled:(GMSAutocompleteViewController *)viewController {
  [self dismissViewControllerAnimated:YES completion:nil];
}

  // Turn the network activity indicator on and off again.
- (void)didRequestAutocompletePredictions:(GMSAutocompleteViewController *)viewController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
}

- (void)didUpdateAutocompletePredictions:(GMSAutocompleteViewController *)viewController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = NO;
}

@end

Como adicionar um controlador de resultados

Use um controlador de resultados quando quiser ter mais controle sobre a IU de inserção de texto. O controlador de resultados alterna dinamicamente a visibilidade da lista de resultados com base no foco da interface de entrada.

Para adicionar um controlador de resultados ao aplicativo:

Crie um GMSAutocompleteResultsViewController.
Implemente o protocolo GMSAutocompleteResultsViewControllerDelegate no controlador de visualizações pai e atribua esse controlador como a propriedade delegada.
Crie um objeto UISearchController, transmitindo o GMSAutocompleteResultsViewController como o argumento do controlador de resultados.
Defina GMSAutocompleteResultsViewController como a propriedade searchResultsUpdater do UISearchController.
Adicione o searchBar do UISearchController à interface do app.
Processe a seleção do usuário no método delegado didAutocompleteWithPlace.

Há várias maneiras de colocar a barra de pesquisa de um UISearchController na interface do seu app:

Adicionar uma barra de pesquisa à barra de navegação
Adicionar uma barra de pesquisa à parte de cima de uma visualização
Adicionar uma barra de pesquisa usando os resultados de pop-over

Adicionar uma barra de pesquisa à barra de navegação

O exemplo de código abaixo demonstra como adicionar um controlador de resultados, adicionar o searchBar à barra de navegação e processar a seleção do usuário:

Swift

class ViewController: UIViewController {

  var resultsViewController: GMSAutocompleteResultsViewController?
  var searchController: UISearchController?
  var resultView: UITextView?

  override func viewDidLoad() {
    super.viewDidLoad()

    resultsViewController = GMSAutocompleteResultsViewController()
    resultsViewController?.delegate = self

    searchController = UISearchController(searchResultsController: resultsViewController)
    searchController?.searchResultsUpdater = resultsViewController

    // Put the search bar in the navigation bar.
    searchController?.searchBar.sizeToFit()
    navigationItem.titleView = searchController?.searchBar

    // When UISearchController presents the results view, present it in
    // this view controller, not one further up the chain.
    definesPresentationContext = true

    // Prevent the navigation bar from being hidden when searching.
    searchController?.hidesNavigationBarDuringPresentation = false
  }
}

// Handle the user's selection.
extension ViewController: GMSAutocompleteResultsViewControllerDelegate {
  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didAutocompleteWith place: GMSPlace) {
    searchController?.isActive = false
    // Do something with the selected place.
    print("Place name: \(place.name)")
    print("Place address: \(place.formattedAddress)")
    print("Place attributions: \(place.attributions)")
  }

  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didFailAutocompleteWithError error: Error){
    // TODO: handle the error.
    print("Error: ", error.localizedDescription)
  }

  // Turn the network activity indicator on and off again.
  func didRequestAutocompletePredictions(_ viewController: GMSAutocompleteViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
  }

  func didUpdateAutocompletePredictions(_ viewController: GMSAutocompleteViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
  }
}

Objective-C

- (void)viewDidLoad {
  _resultsViewController = [[GMSAutocompleteResultsViewController alloc] init];
  _resultsViewController.delegate = self;

  _searchController = [[UISearchController alloc]
                       initWithSearchResultsController:_resultsViewController];
  _searchController.searchResultsUpdater = _resultsViewController;

  // Put the search bar in the navigation bar.
  [_searchController.searchBar sizeToFit];
  self.navigationItem.titleView = _searchController.searchBar;

  // When UISearchController presents the results view, present it in
  // this view controller, not one further up the chain.
  self.definesPresentationContext = YES;

  // Prevent the navigation bar from being hidden when searching.
  _searchController.hidesNavigationBarDuringPresentation = NO;
}

// Handle the user's selection.
- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
  didAutocompleteWithPlace:(GMSPlace *)place {
    _searchController.active = NO;
    // Do something with the selected place.
    NSLog(@"Place name %@", place.name);
    NSLog(@"Place address %@", place.formattedAddress);
    NSLog(@"Place attributions %@", place.attributions.string);
}

- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didFailAutocompleteWithError:(NSError *)error {
  [self dismissViewControllerAnimated:YES completion:nil];
  // TODO: handle the error.
  NSLog(@"Error: %@", [error description]);
}

// Turn the network activity indicator on and off again.
- (void)didRequestAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
}

- (void)didUpdateAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = NO;
}

Adicionar uma barra de pesquisa à parte de cima de uma visualização

O exemplo de código abaixo mostra como adicionar o searchBar à parte de cima de uma visualização.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

  var resultsViewController: GMSAutocompleteResultsViewController?
  var searchController: UISearchController?
  var resultView: UITextView?

  override func viewDidLoad() {
    super.viewDidLoad()

    resultsViewController = GMSAutocompleteResultsViewController()
    resultsViewController?.delegate = self

    searchController = UISearchController(searchResultsController: resultsViewController)
    searchController?.searchResultsUpdater = resultsViewController

    let subView = UIView(frame: CGRect(x: 0, y: 65.0, width: 350.0, height: 45.0))

    subView.addSubview((searchController?.searchBar)!)
    view.addSubview(subView)
    searchController?.searchBar.sizeToFit()
    searchController?.hidesNavigationBarDuringPresentation = false

    // When UISearchController presents the results view, present it in
    // this view controller, not one further up the chain.
    definesPresentationContext = true
  }
}

// Handle the user's selection.
extension ViewController: GMSAutocompleteResultsViewControllerDelegate {
  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didAutocompleteWith place: GMSPlace) {
    searchController?.isActive = false
    // Do something with the selected place.
    print("Place name: \(place.name)")
    print("Place address: \(place.formattedAddress)")
    print("Place attributions: \(place.attributions)")
  }

  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didFailAutocompleteWithError error: Error){
    // TODO: handle the error.
    print("Error: ", error.localizedDescription)
  }

  // Turn the network activity indicator on and off again.
  func didRequestAutocompletePredictions(forResultsController resultsController: GMSAutocompleteResultsViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
  }

  func didUpdateAutocompletePredictions(forResultsController resultsController: GMSAutocompleteResultsViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
  }
}

Objective-C

- (void)viewDidLoad {
    [super viewDidLoad];

    _resultsViewController = [[GMSAutocompleteResultsViewController alloc] init];
    _resultsViewController.delegate = self;

    _searchController = [[UISearchController alloc]
                             initWithSearchResultsController:_resultsViewController];
    _searchController.searchResultsUpdater = _resultsViewController;

    UIView *subView = [[UIView alloc] initWithFrame:CGRectMake(0, 65.0, 250, 50)];

    [subView addSubview:_searchController.searchBar];
    [_searchController.searchBar sizeToFit];
    [self.view addSubview:subView];

    // When UISearchController presents the results view, present it in
    // this view controller, not one further up the chain.
    self.definesPresentationContext = YES;
}

// Handle the user's selection.
- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didAutocompleteWithPlace:(GMSPlace *)place {
  [self dismissViewControllerAnimated:YES completion:nil];
  // Do something with the selected place.
  NSLog(@"Place name %@", place.name);
  NSLog(@"Place address %@", place.formattedAddress);
  NSLog(@"Place attributions %@", place.attributions.string);
}

- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didFailAutocompleteWithError:(NSError *)error {
  [self dismissViewControllerAnimated:YES completion:nil];
  // TODO: handle the error.
  NSLog(@"Error: %@", [error description]);
}

// Turn the network activity indicator on and off again.
- (void)didRequestAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
}

- (void)didUpdateAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = NO;
}

Por padrão, o UISearchController oculta a barra de navegação durante a apresentação. Essa opção pode ser desativada. Nos casos em que a barra de navegação está visível e opaca, o UISearchController não define o posicionamento corretamente.

Use o código a seguir como solução alternativa:

Swift

navigationController?.navigationBar.translucent = false
searchController?.hidesNavigationBarDuringPresentation = false

// This makes the view area include the nav bar even though it is opaque.
// Adjust the view placement down.
self.extendedLayoutIncludesOpaqueBars = true
self.edgesForExtendedLayout = .top

Objective-C

self.navigationController.navigationBar.translucent = NO;
_searchController.hidesNavigationBarDuringPresentation = NO;

// This makes the view area include the nav bar even though it is opaque.
// Adjust the view placement down.
self.extendedLayoutIncludesOpaqueBars = YES;
self.edgesForExtendedLayout = UIRectEdgeTop;

O exemplo de código a seguir mostra como colocar uma barra de pesquisa no lado direito da barra de navegação e mostrar os resultados em um pop-over.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

  var resultsViewController: GMSAutocompleteResultsViewController?
  var searchController: UISearchController?
  var resultView: UITextView?

  override func viewDidLoad() {
    super.viewDidLoad()

    resultsViewController = GMSAutocompleteResultsViewController()
    resultsViewController?.delegate = self

    searchController = UISearchController(searchResultsController: resultsViewController)
    searchController?.searchResultsUpdater = resultsViewController

    // Add the search bar to the right of the nav bar,
    // use a popover to display the results.
    // Set an explicit size as we don't want to use the entire nav bar.
    searchController?.searchBar.frame = (CGRect(x: 0, y: 0, width: 250.0, height: 44.0))
    navigationItem.rightBarButtonItem = UIBarButtonItem(customView: (searchController?.searchBar)!)

    // When UISearchController presents the results view, present it in
    // this view controller, not one further up the chain.
    definesPresentationContext = true

    // Keep the navigation bar visible.
    searchController?.hidesNavigationBarDuringPresentation = false
    searchController?.modalPresentationStyle = .popover
  }
}
// Handle the user's selection.
extension ViewController: GMSAutocompleteResultsViewControllerDelegate {
  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didAutocompleteWith place: GMSPlace) {
    searchController?.isActive = false
    // Do something with the selected place.
    print("Place name: \(place.name)")
    print("Place address: \(place.formattedAddress)")
    print("Place attributions: \(place.attributions)")
  }

  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didFailAutocompleteWithError error: Error){
    // TODO: handle the error.
    print("Error: ", error.localizedDescription)
  }

  // Turn the network activity indicator on and off again.
  func didRequestAutocompletePredictions(forResultsController resultsController: GMSAutocompleteResultsViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
  }

  func didUpdateAutocompletePredictions(forResultsController resultsController: GMSAutocompleteResultsViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
  }
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  _resultsViewController = [[GMSAutocompleteResultsViewController alloc] init];
  _resultsViewController.delegate = self;

  _searchController = [[UISearchController alloc]
                           initWithSearchResultsController:_resultsViewController];
  _searchController.searchResultsUpdater = _resultsViewController;

  // Add the search bar to the right of the nav bar,
  // use a popover to display the results.
  // Set an explicit size as we don't want to use the entire nav bar.
  _searchController.searchBar.frame = CGRectMake(0, 0, 250.0f, 44.0f);
  self.navigationItem.rightBarButtonItem =
  [[UIBarButtonItem alloc] initWithCustomView:_searchController.searchBar];

  // When UISearchController presents the results view, present it in
  // this view controller, not one further up the chain.
  self.definesPresentationContext = YES;

  // Keep the navigation bar visible.
  _searchController.hidesNavigationBarDuringPresentation = NO;

  _searchController.modalPresentationStyle = UIModalPresentationPopover;
}

// Handle the user's selection.
- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didAutocompleteWithPlace:(GMSPlace *)place {
  [self dismissViewControllerAnimated:YES completion:nil];
  NSLog(@"Place name %@", place.name);
  NSLog(@"Place address %@", place.formattedAddress);
  NSLog(@"Place attributions %@", place.attributions.string);
}

- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didFailAutocompleteWithError:(NSError *)error {
  [self dismissViewControllerAnimated:YES completion:nil];
  // TODO: handle the error.
  NSLog(@"Error: %@", [error description]);
}

// Turn the network activity indicator on and off again.
- (void)didRequestAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
}

- (void)didUpdateAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = NO;
}

Como usar uma fonte de dados de tabela

Se o app tiver uma interface de texto de pesquisa personalizada, use a classe GMSAutocompleteTableDataSource para fazer com que a visualização em tabela mostre os resultados no controlador.

Para usar GMSAutocompleteTableDataSource como a fonte de dados e delegado da UITableView em um controlador de visualização:

Implemente os protocolos GMSAutocompleteTableDataSourceDelegate e UISearchBarDelegate no controlador de visualizações.
Crie uma instância GMSAutocompleteTableDataSource e atribua o controlador de visualização como a propriedade delegada.
Defina GMSAutocompleteTableDataSource como a fonte de dados e as propriedades de delegação da instância UITableView no controlador de visualização.
No gerenciador da entrada de texto da pesquisa, chame sourceTextHasChanged no GMSAutocompleteTableDataSource.
Processe a seleção do usuário no método delegado didAutocompleteWithPlace.
Dispense o controlador nos métodos delegados didAutocompleteWithPlace, didFailAutocompleteWithError e wasCancelled.

O exemplo de código a seguir demonstra o uso da classe GMSAutocompleteTableDataSource para direcionar a visualização de tabela de um UIViewController quando o UISearchBar é adicionado separadamente.

Swift

// Copyright 2020 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
//
//      http://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.

import GooglePlaces
import UIKit

class PlaceAutocompleteViewController: UIViewController {

  private var tableView: UITableView!
  private var tableDataSource: GMSAutocompleteTableDataSource!

  override func viewDidLoad() {
    super.viewDidLoad()

    let searchBar = UISearchBar(frame: CGRect(x: 0, y: 20, width: self.view.frame.size.width, height: 44.0))
    searchBar.delegate = self
    view.addSubview(searchBar)

    tableDataSource = GMSAutocompleteTableDataSource()
    tableDataSource.delegate = self

    tableView = UITableView(frame: CGRect(x: 0, y: 64, width: self.view.frame.size.width, height: self.view.frame.size.height - 44))
    tableView.delegate = tableDataSource
    tableView.dataSource = tableDataSource

    view.addSubview(tableView)
  }
}

extension PlaceAutocompleteViewController: UISearchBarDelegate {
  func searchBar(_ searchBar: UISearchBar, textDidChange searchText: String) {
    // Update the GMSAutocompleteTableDataSource with the search text.
    tableDataSource.sourceTextHasChanged(searchText)
  }
}

extension PlaceAutocompleteViewController: GMSAutocompleteTableDataSourceDelegate {
  func didUpdateAutocompletePredictions(for tableDataSource: GMSAutocompleteTableDataSource) {
    // Turn the network activity indicator off.
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
    // Reload table data.
    tableView.reloadData()
  }

  func didRequestAutocompletePredictions(for tableDataSource: GMSAutocompleteTableDataSource) {
    // Turn the network activity indicator on.
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
    // Reload table data.
    tableView.reloadData()
  }

  func tableDataSource(_ tableDataSource: GMSAutocompleteTableDataSource, didAutocompleteWith place: GMSPlace) {
    // Do something with the selected place.
    print("Place name: \(place.name)")
    print("Place address: \(place.formattedAddress)")
    print("Place attributions: \(place.attributions)")
  }

  func tableDataSource(_ tableDataSource: GMSAutocompleteTableDataSource, didFailAutocompleteWithError error: Error) {
    // Handle the error.
    print("Error: \(error.localizedDescription)")
  }

  func tableDataSource(_ tableDataSource: GMSAutocompleteTableDataSource, didSelect prediction: GMSAutocompletePrediction) -> Bool {
    return true
  }
}

Objective-C

// Copyright 2020 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
//
//      http://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.

#import "PlaceAutocompleteViewController.h"
@import GooglePlaces;
@import UIKit;

@interface PlaceAutocompleteViewController () <GMSAutocompleteTableDataSourceDelegate, UISearchBarDelegate>

@end

@implementation PlaceAutocompleteViewController {
  UITableView *tableView;
  GMSAutocompleteTableDataSource *tableDataSource;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  UISearchBar *searchBar = [[UISearchBar alloc] initWithFrame:CGRectMake(0, 20, self.view.frame.size.width, 44)];
  searchBar.delegate = self;

  [self.view addSubview:searchBar];

  tableDataSource = [[GMSAutocompleteTableDataSource alloc] init];
  tableDataSource.delegate = self;

  tableView = [[UITableView alloc] initWithFrame:CGRectMake(0, 64, self.view.frame.size.width, self.view.frame.size.height - 44)];
  tableView.delegate = tableDataSource;
  tableView.dataSource = tableDataSource;

  [self.view addSubview:tableView];
}

#pragma mark - GMSAutocompleteTableDataSourceDelegate

- (void)didUpdateAutocompletePredictionsForTableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource {
  // Turn the network activity indicator off.
  UIApplication.sharedApplication.networkActivityIndicatorVisible = NO;

  // Reload table data.
  [tableView reloadData];
}

- (void)didRequestAutocompletePredictionsForTableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource {
  // Turn the network activity indicator on.
  UIApplication.sharedApplication.networkActivityIndicatorVisible = YES;

  // Reload table data.
  [tableView reloadData];
}

- (void)tableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource didAutocompleteWithPlace:(GMSPlace *)place {
  // Do something with the selected place.
  NSLog(@"Place name: %@", place.name);
  NSLog(@"Place address: %@", place.formattedAddress);
  NSLog(@"Place attributions: %@", place.attributions);
}

- (void)tableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource didFailAutocompleteWithError:(NSError *)error {
  // Handle the error
  NSLog(@"Error %@", error.description);
}

- (BOOL)tableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource didSelectPrediction:(GMSAutocompletePrediction *)prediction {
  return YES;
}

#pragma mark - UISearchBarDelegate

- (void)searchBar:(UISearchBar *)searchBar textDidChange:(NSString *)searchText {
  // Update the GMSAutocompleteTableDataSource with the search text.
  [tableDataSource sourceTextHasChanged:searchText];
}

@end

Personalizar as cores do texto e do plano de fundo

Você pode definir as cores de todos os textos e planos de fundo no widget de preenchimento automático para que o widget corresponda à aparência do app de maneira mais precisa. Há duas formas de definir as cores do widget:

Usando o protocolo UIAppearance nativo do iOS para estilizar controles de IU globalmente sempre que possível. Essas configurações se aplicam a muitos, mas não a todos os elementos do controle de interface.
Usando os métodos do SDK nas classes do widget para definir propriedades que não têm suporte do protocolo UIAppearance.

Normalmente, o app usa uma combinação do protocolo UIAppearance com os métodos do SDK. O diagrama a seguir mostra que elementos podem ser estilizados:

Cores do controle de interface de preenchimento automático

A tabela abaixo lista todos os elementos da interface e indica como cada um precisa ser estilizado (protocolo UIAppearance ou método do SDK).

Elemento de IU	Método	Guias de estilo
Tonalidade da barra de navegação (plano de fundo)	Protocolo UIAppearance	Chame `setBarTintColor` no proxy `UINavigationBar`.
Tonalidade da barra de navegação (circunflexo no texto da barra de pesquisa e botão Cancelar)	Protocolo UIAppearance	Chame `setTintColor` no proxy `UINavigationBar`.
Cor do texto da barra de pesquisa	Protocolo UIAppearance	Defina `NSForegroundColorAttributeName` em `searchBarTextAttributes`.
Cor da tonalidade da barra de pesquisa	N/A	A barra de pesquisa é translúcida e será exibida como uma versão sombreada da barra de navegação.
Cor do texto do marcador da barra de pesquisa (texto de pesquisa padrão)	Protocolo UIAppearance	Defina `NSForegroundColorAttributeName` em `placeholderAttributes`.
Texto principal (também aplicado ao texto da mensagem e do erro)	Método do SDK	Chame `primaryTextColor`.
Destaque do texto principal	Método do SDK	Chame `primaryTextHighlightColor`.
Texto secundário	Método do SDK	Chame `secondaryTextColor`.
Erro e texto da mensagem	Método do SDK	Chame `primaryTextColor`.
Plano de fundo da célula da tabela	Método do SDK	Chame `tableCellBackgroundColor`.
Cor do separador de células da tabela	Método do SDK	Chame `tableCellSeparatorColor`.
Botão "Tentar novamente"	Método do SDK	Chame `tintColor`.
Indicador de atividade (ícone de carregamento de progresso)	Protocolo UIAppearance	Chame `setColor` no proxy `UIActivityIndicatorView`.
Logotipo "Tecnologia do Google", imagem de nuvem triste	N/A	A versão branca ou cinza é selecionada automaticamente com base no contraste do plano de fundo.
Ícones de lupa e limpar texto no campo de texto da barra de pesquisa	N/A	Para definir o estilo, substitua as imagens padrão por outras na cor desejada.

Como usar o protocolo UIAppearance

Você pode usar o protocolo UIAppearance para conseguir o proxy de aparência de um elemento da interface, que pode ser usado para definir a cor desse elemento. Quando uma modificação é feita, todas as instâncias de um determinado elemento da interface são afetadas. Por exemplo, o exemplo a seguir muda globalmente a cor do texto das classes UITextField para verde quando elas estão contidas em um UISearchBar:

[[UITextField appearanceWhenContainedIn:[UISearchBar class], nil]
    setDefaultTextAttributes:@{NSForegroundColorAttributeName:[UIColor greenColor]}];

Para saber mais sobre como definir valores de cor, consulte a Referência da classe UIColor.

Os snippets de código a seguir mostram todos os comandos de proxy que você precisa usar para estilizar tudo no controle de interface de preenchimento automático em tela cheia. Adicione este código ao método didFinishLaunchingWithOptions em Appdelegate.m:

// Define some colors.
UIColor *darkGray = [UIColor darkGrayColor];
UIColor *lightGray = [UIColor lightGrayColor];

// Navigation bar background.
[[UINavigationBar appearance] setBarTintColor:darkGray];
[[UINavigationBar appearance] setTintColor:lightGray];

// Color of typed text in the search bar.
NSDictionary *searchBarTextAttributes = @{
                                          NSForegroundColorAttributeName: lightGray,
                                          NSFontAttributeName : [UIFont systemFontOfSize:[UIFont systemFontSize]]
                                          };
[UITextField appearanceWhenContainedInInstancesOfClasses:@[[UISearchBar class]]]
    .defaultTextAttributes = searchBarTextAttributes;

// Color of the placeholder text in the search bar prior to text entry.
NSDictionary *placeholderAttributes = @{
                                        NSForegroundColorAttributeName: lightGray,
                                        NSFontAttributeName : [UIFont systemFontOfSize:[UIFont systemFontSize]]
                                        };

// Color of the default search text.
// NOTE: In a production scenario, "Search" would be a localized string.
NSAttributedString *attributedPlaceholder =
[[NSAttributedString alloc] initWithString:@"Search"
                                attributes:placeholderAttributes];
[UITextField appearanceWhenContainedInInstancesOfClasses:@[[UISearchBar class]]]
    .attributedPlaceholder = attributedPlaceholder;

// Color of the in-progress spinner.
[[UIActivityIndicatorView appearance] setColor:lightGray];

// To style the two image icons in the search bar (the magnifying glass
// icon and the 'clear text' icon), replace them with different images.
[[UISearchBar appearance] setImage:[UIImage imageNamed:@"custom_clear_x_high"]
                  forSearchBarIcon:UISearchBarIconClear
                            state:UIControlStateHighlighted];
[[UISearchBar appearance] setImage:[UIImage imageNamed:@"custom_clear_x"]
                  forSearchBarIcon:UISearchBarIconClear
                            state:UIControlStateNormal];
[[UISearchBar appearance] setImage:[UIImage imageNamed:@"custom_search"]
                    forSearchBarIcon:UISearchBarIconSearch
                            state:UIControlStateNormal];

// Color of selected table cells.
UIView *selectedBackgroundView = [[UIView alloc] init];
selectedBackgroundView.backgroundColor = [UIColor lightGrayColor];
[UITableViewCell appearanceWhenContainedIn:[GMSAutocompleteViewController class], nil]
    .selectedBackgroundView = selectedBackgroundView;

Como definir propriedades de estilo do controle de interface

Um subconjunto de elementos de controle de interface tem propriedades que não são afetadas pelo protocolo UIAppearance, portanto, precisa ser definido diretamente. O exemplo de código abaixo mostra como definir cores de primeiro e segundo plano e aplicá-las a uma instância de controle de interface chamada acController. Adicione este código ao método onLaunchClicked em ViewController.m:

UIColor *darkGray = [UIColor darkGrayColor];
UIColor *lightGray = [UIColor lightGrayColor];

acController.secondaryTextColor = [UIColor colorWithWhite:1.0f alpha:0.5f];
acController.primaryTextColor = lightGray;
acController.primaryTextHighlightColor = [UIColor grayColor];
acController.tableCellBackgroundColor = darkGray;
acController.tableCellSeparatorColor = lightGray;
acController.tintColor = lightGray;

Como receber previsões de lugares de forma programática

É possível criar uma interface de pesquisa personalizada como alternativa à interface fornecida pelo widget de preenchimento automático. Para fazer isso, seu app precisa receber previsões de locais de forma programática. Seu app pode conseguir uma lista de nomes e/ou endereços de lugares previstos de uma das seguintes maneiras:

Ligar para GMSPlacesClient findAutocompletePredictionsFromQuery:
Usar o coletor

Ligando para `GMSPlacesClient findAutocompletePredictionsFromQuery:`

Para ver uma lista de nomes e/ou endereços de lugares previstos, primeiro instanciar GMSPlacesClient (em inglês) e, em seguida, chamar o método GMSPlacesClient findAutocompletePredictionsFromQuery: com os seguintes parâmetros:

Uma string autocompleteQuery contendo o texto digitado pelo usuário.
Um GMSAutocompleteSessionToken, que é usado para identificar cada sessão individual. Seu app precisa transmitir o mesmo token para cada chamada de solicitação de preenchimento automático e, em seguida, transmitir esse token e um ID de lugar na chamada seguinte para fetchPlacefromPlaceID: para recuperar o Place Details do lugar selecionado pelo usuário.
Um GMSAutocompleteFilter para:
- Direcionar ou restringir os resultados a uma região específica.
- Restrinja os resultados a um tipo de lugar específico.
- Um objeto GMSPlaceLocationBias/Restriction que direciona os resultados para uma área específica especificada por limites de latitude e longitude.
Um método de retorno de chamada para tratar das previsões retornadas.

Os exemplos de código abaixo mostram uma chamada para findAutocompletePredictionsFromQuery:.

Swift

/**
 * Create a new session token. Be sure to use the same token for calling
 * findAutocompletePredictions, as well as the subsequent place details request.
 * This ensures that the user's query and selection are billed as a single session.
 */
let token = GMSAutocompleteSessionToken.init()

// Create a type filter.
let filter = GMSAutocompleteFilter()
filter.types = [.bank] 
filter.locationBias = GMSPlaceRectangularLocationOption( northEastBounds,
                                   southWestBounds);

placesClient?.findAutocompletePredictions(fromQuery: "cheesebu",

                                          filter: filter,
                                          sessionToken: token,
                                          callback: { (results, error) in
    if let error = error {
      print("Autocomplete error: \(error)")
      return
    }
    if let results = results {
      for result in results {
        print("Result \(result.attributedFullText) with placeID \(result.placeID)")
      }
    }
})

Objective-C

/**
 * Create a new session token. Be sure to use the same token for calling
 * findAutocompletePredictionsFromQuery:, as well as the subsequent place details request.
 * This ensures that the user's query and selection are billed as a single session.
 */
GMSAutocompleteSessionToken *token = [[GMSAutocompleteSessionToken alloc] init];

// Create a type filter.
GMSAutocompleteFilter *_filter = [[GMSAutocompleteFilter alloc] init];
_filter.types = @[ kGMSPlaceTypeBank ];

[_placesClient findAutocompletePredictionsFromQuery:@"cheesebu"
filter:_filter sessionToken:token callback:^(NSArray<GMSAutocompletePrediction *> * _Nullable results, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (results != nil) {
    for (GMSAutocompletePrediction *result in results) {
      NSLog(@"Result %@ with PlaceID %@", result.attributedFullText, result.placeID);
    }
  }
}];

A API invoca o método de callback especificado, transmitindo uma matriz de objetos GMSAutocompletePrediction.

Cada objeto GMSAutocompletePrediction contém as seguintes informações:

attributedFullText: o texto completo da previsão, na forma de um NSAttributedString. Por exemplo, "Sydney Opera House, Sydney, Nova Gales do Sul, Austrália". Cada intervalo de texto que corresponde à entrada do usuário tem um atributo, kGMSAutocompleteMatchAttribute. É possível usar esse atributo para destacar o texto correspondente na consulta do usuário, por exemplo, conforme mostrado abaixo.
placeID: o ID do local previsto. O ID de lugar é um identificador textual que determina um local de forma exclusiva. Para mais informações sobre IDs de lugar, consulte a visão geral de IDs de lugar.
distanceMeters: a distância em linha reta do origin especificado até o destino. Se a propriedade origin não for definida, nenhum valor de distância será retornado.

O exemplo de código a seguir ilustra como destacar em negrito as partes do resultado que correspondem ao texto na consulta do usuário usando enumerateAttribute:

Swift

let regularFont = UIFont.systemFont(ofSize: UIFont.labelFontSize)
let boldFont = UIFont.boldSystemFont(ofSize: UIFont.labelFontSize)

let bolded = prediction.attributedFullText.mutableCopy() as! NSMutableAttributedString
bolded.enumerateAttribute(kGMSAutocompleteMatchAttribute, in: NSMakeRange(0, bolded.length), options: []) {
  (value, range: NSRange, stop: UnsafeMutablePointer<ObjCBool>) -> Void in
    let font = (value == nil) ? regularFont : boldFont
    bolded.addAttribute(NSFontAttributeName, value: font, range: range)
}

label.attributedText = bolded

Objective-C

UIFont *regularFont = [UIFont systemFontOfSize:[UIFont labelFontSize]];
UIFont *boldFont = [UIFont boldSystemFontOfSize:[UIFont labelFontSize]];

NSMutableAttributedString *bolded = [prediction.attributedFullText mutableCopy];
[bolded enumerateAttribute:kGMSAutocompleteMatchAttribute
                   inRange:NSMakeRange(0, bolded.length)
                   options:0
                usingBlock:^(id value, NSRange range, BOOL *stop) {
                  UIFont *font = (value == nil) ? regularFont : boldFont;
                  [bolded addAttribute:NSFontAttributeName value:font range:range];
                }];

label.attributedText = bolded;

Como usar o coletor

Se você quiser criar seu próprio controle de preenchimento automático do zero, use GMSAutocompleteFetcher, que une o método autocompleteQuery em GMSPlacesClient. O coletor limita as solicitações, retornando resultados apenas para o texto de pesquisa inserido mais recentemente. Ele não fornece elementos de IU.

Para implementar o GMSAutocompleteFetcher, siga estas etapas:

Implemente o protocolo GMSAutocompleteFetcherDelegate.
Crie um objeto GMSAutocompleteFetcher.
Chame sourceTextHasChanged no coletor enquanto o usuário digita.
Gerencie previsões e erros usando os métodos de protocolo didAutcompleteWithPredictions e didFailAutocompleteWithError.

O exemplo de código a seguir demonstra o uso do coletor para receber a entrada do usuário e exibir correspondências de local em uma visualização de texto. A funcionalidade de selecionar um lugar foi omitida. FetcherSampleViewController deriva de UIViewController em FetcherSampleViewController.h.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

  var textField: UITextField?
  var resultText: UITextView?
  var fetcher: GMSAutocompleteFetcher?

  override func viewDidLoad() {
    super.viewDidLoad()

    view.backgroundColor = .white
    edgesForExtendedLayout = []

    // Set bounds to inner-west Sydney Australia.
    let neBoundsCorner = CLLocationCoordinate2D(latitude: -33.843366,
                                                longitude: 151.134002)
    let swBoundsCorner = CLLocationCoordinate2D(latitude: -33.875725,
                                                longitude: 151.200349)

    // Set up the autocomplete filter.
    let filter = GMSAutocompleteFilter()
    filter.locationRestriction = GMSPlaceRectangularLocationOption(neBoundsCorner, swBoundsCorner)

    // Create a new session token.
    let token: GMSAutocompleteSessionToken = GMSAutocompleteSessionToken.init()

    // Create the fetcher.
    fetcher = GMSAutocompleteFetcher(bounds: nil, filter: filter)
    fetcher?.delegate = self
    fetcher?.provide(token)

    textField = UITextField(frame: CGRect(x: 5.0, y: 10.0,
                                          width: view.bounds.size.width - 5.0,
                                          height: 64.0))
    textField?.autoresizingMask = .flexibleWidth
    textField?.addTarget(self, action: #selector(textFieldDidChange(textField:)),
                         for: .editingChanged)
    let placeholder = NSAttributedString(string: "Type a query...")

    textField?.attributedPlaceholder = placeholder

    resultText = UITextView(frame: CGRect(x: 0, y: 65.0,
                                          width: view.bounds.size.width,
                                          height: view.bounds.size.height - 65.0))
    resultText?.backgroundColor = UIColor(white: 0.95, alpha: 1.0)
    resultText?.text = "No Results"
    resultText?.isEditable = false

    self.view.addSubview(textField!)
    self.view.addSubview(resultText!)
  }

  @objc func textFieldDidChange(textField: UITextField) {
    fetcher?.sourceTextHasChanged(textField.text!)
  }

}

extension ViewController: GMSAutocompleteFetcherDelegate {
  func didAutocomplete(with predictions: [GMSAutocompletePrediction]) {
    let resultsStr = NSMutableString()
    for prediction in predictions {
      resultsStr.appendFormat("\n Primary text: %@\n", prediction.attributedPrimaryText)
      resultsStr.appendFormat("Place ID: %@\n", prediction.placeID)
    }

    resultText?.text = resultsStr as String
  }

  func didFailAutocompleteWithError(_ error: Error) {
    resultText?.text = error.localizedDescription
  }
}

Objective-C

#import "FetcherSampleViewController.h"
#import <GooglePlaces/GooglePlaces.h>
#import <GoogleMapsBase/GoogleMapsBase.h>

@interface FetcherSampleViewController () <GMSAutocompleteFetcherDelegate>

@end

@implementation FetcherSampleViewController {
  UITextField *_textField;
  UITextView *_resultText;
  GMSAutocompleteFetcher* _fetcher;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  self.view.backgroundColor = [UIColor whiteColor];
  self.edgesForExtendedLayout = UIRectEdgeNone;

  // Set bounds to inner-west Sydney Australia.
  CLLocationCoordinate2D neBoundsCorner = CLLocationCoordinate2DMake(-33.843366, 151.134002);
  CLLocationCoordinate2D swBoundsCorner = CLLocationCoordinate2DMake(-33.875725, 151.200349);

  GMSAutocompleteFilter *autocompleteFilter = [[GMSAutocompleteFilter alloc] init];
  autocompleteFilter.locationRestriction =
        GMSPlaceRectangularLocationOption(neBoundsCorner, swBoundsCorner);

  // Create the fetcher.
  _fetcher = [[GMSAutocompleteFetcher alloc] initWithBounds:nil
                                                     filter:filter];
  _fetcher.delegate = self;

  // Set up the UITextField and UITextView.
  _textField = [[UITextField alloc] initWithFrame:CGRectMake(5.0f,
                                                             0,
                                                             self.view.bounds.size.width - 5.0f,
                                                             44.0f)];
  _textField.autoresizingMask = UIViewAutoresizingFlexibleWidth;
  [_textField addTarget:self
                 action:@selector(textFieldDidChange:)
       forControlEvents:UIControlEventEditingChanged];
  _resultText =[[UITextView alloc] initWithFrame:CGRectMake(0,
                                                            45.0f,
                                                            self.view.bounds.size.width,
                                                            self.view.bounds.size.height - 45.0f)];
  _resultText.backgroundColor = [UIColor colorWithWhite:0.95f alpha:1.0f];
  _resultText.text = @"No Results";
  _resultText.editable = NO;
  [self.view addSubview:_textField];
  [self.view addSubview:_resultText];
}

- (void)textFieldDidChange:(UITextField *)textField {
  NSLog(@"%@", textField.text);
  [_fetcher sourceTextHasChanged:textField.text];
}

#pragma mark - GMSAutocompleteFetcherDelegate
- (void)didAutocompleteWithPredictions:(NSArray *)predictions {
  NSMutableString *resultsStr = [NSMutableString string];
  for (GMSAutocompletePrediction *prediction in predictions) {
      [resultsStr appendFormat:@"%@\n", [prediction.attributedPrimaryText string]];
  }
  _resultText.text = resultsStr;
}

- (void)didFailAutocompleteWithError:(NSError *)error {
  _resultText.text = [NSString stringWithFormat:@"%@", error.localizedDescription];
}

@end

Tokens de sessão

Os tokens de sessão agrupam as fases de consulta e seleção de uma pesquisa de preenchimento automático do usuário em uma sessão discreta para fins de faturamento. A sessão começa quando o usuário começa a digitar uma consulta e termina quando seleciona um lugar. Cada sessão pode ter várias consultas, seguidas por uma seleção de lugar. Após a conclusão de uma sessão, o token não é mais válido. Seu app precisa gerar um novo token para cada sessão. Recomendamos o uso de tokens de sessão para todas as sessões de preenchimento automático programático. Quando você usa o controlador de tela cheia ou o de resultados, a API cuida disso automaticamente.

O SDK do Places para iOS usa um GMSAutocompleteSessionToken para identificar cada sessão. Seu app precisa transmitir um novo token de sessão ao iniciar cada nova sessão e, em seguida, transmitir esse mesmo token com um ID de lugar na chamada seguinte para fetchPlacefromPlaceID: para recuperar o Place Details do lugar selecionado pelo usuário.

Saiba mais sobre tokens de sessão.

Use o código a seguir para gerar um novo token de sessão:

let token: GMSAutocompleteSessionToken = GMSAutocompleteSessionToken.init()

Limites de uso

O uso do método GMSPlacesClient findAutocompletePredictionsFromQuery está sujeito a limites de consulta em níveis. Consulte a documentação sobre limites de uso.

Mostrar atribuições no app

Se o app usa o serviço de preenchimento automático de forma programática, a interface precisa exibir uma atribuição "Tecnologia do Google" ou aparecer em um mapa com a marca do Google.
Se o app usa o controle de interface de preenchimento automático, nenhuma outra ação é necessária (a atribuição necessária é exibida por padrão).
Se você recuperar e mostrar outras informações do local depois de acessar um lugar pelo ID, também precisará exibir atribuições de terceiros.

Para mais detalhes, consulte a documentação sobre atribuições.

Como controlar o indicador de atividade de rede

Para controlar o indicador de atividade de rede na barra de status do app, implemente os métodos delegados opcionais adequados para a classe de preenchimento automático que você está usando e ative e desative o indicador de rede por conta própria.

Para o GMSAutocompleteViewController, implemente os métodos delegados didRequestAutocompletePredictions: e didUpdateAutocompletePredictions:.
Para o GMSAutocompleteResultsViewController, implemente os métodos delegados didRequestAutocompletePredictionsForResultsController: e didUpdateAutocompletePredictionsForResultsController:.
Para o GMSAutocompleteTableDataSource, implemente os métodos delegados didRequestAutocompletePredictionsForTableDataSource: e didUpdateAutocompletePredictionsForTableDataSource:.

Ao implementar esses métodos e definir [UIApplication sharedApplication].networkActivityIndicatorVisible como YES e NO, respectivamente, a barra de status vai corresponder corretamente à interface de preenchimento automático.

Restringir resultados do preenchimento automático

É possível definir o controle de interface de preenchimento automático para restringir os resultados a uma região geográfica específica e/ou filtrar os resultados a um ou mais tipos de lugares ou a países ou países específicos. Para restringir os resultados, faça o seguinte:

Para preferir (viés) resultados dentro da região definida, defina locationBias no GMSAutocompleteFilter. Alguns resultados de fora da região definida ainda podem ser retornados. Se locationRestriction também for definido, locationBias será ignorado.
Para mostrar (restringir) apenas os resultados dentro da região definida, defina locationRestriction no GMSAutocompleteFilter (apenas resultados dentro da região definida serão retornados).
- Observação:essa restrição é aplicada somente a rotas inteiras. Os resultados sintéticos localizados fora dos limites retangulares podem ser retornados com base em uma rota que se sobreponha à restrição de local.
Para retornar apenas resultados que estejam em conformidade com um tipo de lugar específico, defina types no GMSAutocompleteFilter. Por exemplo, especificar TypeFilter.ADDRESS fará com que o widget retorne apenas resultados com um endereço preciso.
Para retornar apenas resultados em até cinco países especificados, defina countries no GMSAutocompleteFilter.

Direcionamento dos resultados para uma região específica

Para preferir (viés) resultados dentro da região definida, defina locationBias no GMSAutocompleteFilter, como mostrado aqui:

  northEast = CLLocationCoordinate2DMake(39.0, -95.0);
  southWest = CLLocationCoordinate2DMake(37.5, -100.0);
  GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
  filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);

Restringir os resultados a uma região específica

Para mostrar (restringir) apenas os resultados dentro da região definida, defina locationRestriction no GMSAutocompleteFilter, conforme mostrado aqui:

  northEast = CLLocationCoordinate2DMake(39.0, -95.0);
  southWest = CLLocationCoordinate2DMake(37.5, -100.0);
  GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
  filter.locationRestriction = GMSPlaceRectangularLocationOption(northEast, southWest);

Filtrar resultados por país

Para filtrar resultados em até cinco países especificados, defina countries no GMSAutocompleteFilter, conforme mostrado aqui:

  GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
  filter.countries = @[ @"au", @"nz" ];

Filtrar resultados por tipo de lugar ou conjunto de tipos

Para restringir os resultados a um determinado tipo ou coleção de tipos, defina a propriedade types de GMSAutoCompleteFilter. Use essa propriedade para especificar os filtros listados nas tabelas 1, 2 e 3 em Tipos de lugares. Se nada for especificado, todos os tipos serão retornados.

Para especificar um tipo ou um filtro de coleções:

Use a propriedade types para especificar até cinco valores de type das Tabelas 1 e 2 mostradas em Tipos de lugares. Os valores de tipo são definidos pelas constantes em GMSPlaceType.
Use a propriedade types para especificar uma coleção de tipos da Tabela 3 mostrada em Tipos de lugares. Os valores da coleção de tipos são definidos pelas constantes em GMSPlaceType.

Somente um tipo da Tabela 3 é permitido na solicitação. Se você especificar um valor na Tabela 3, não será possível fazer isso na Tabela 1 ou na 2. Se você fizer isso, ocorrerá um erro.

Por exemplo, para retornar apenas resultados que estejam em conformidade com um tipo de lugar específico, defina types em GMSAutocompleteFilter. O exemplo a seguir mostra a configuração do filtro para retornar apenas resultados com um endereço preciso:

  GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
  filter.types = @[ kGMSPlaceTypeAirport, kGMSPlaceTypeAmusementPark ];

Otimização do Place Autocomplete

Esta seção descreve as práticas recomendadas para você aproveitar ao máximo o serviço Place Autocomplete.

Aqui estão algumas diretrizes gerais:

A maneira mais rápida de desenvolver uma interface do usuário funcional é usar o widget do Autocomplete da API Maps JavaScript, o widget do Autocomplete do SDK do Places para Android ou Controle de IU do Autocomplete do SDK do Places para iOS.
Entender os campos de dados essenciais do Place Autocomplete desde o início.
Os campos de direcionamento de local e restrição de local são opcionais, mas podem afetar bastante a performance do preenchimento automático.
Use o tratamento de erros para garantir que o aplicativo faça uma degradação simples se a API retornar um erro.
Verifique se o app continua funcionando quando não há seleção e que oferece às pessoas uma maneira de continuar.

Práticas recomendadas de otimização de custos

Otimização básica de custos

Para otimizar o custo do uso do serviço Place Autocomplete, use máscaras de campo nos widgets Place Details e Place Autocomplete para retornar apenas os campos de dados de lugar necessários.

Otimização avançada de custos

Faça a implementação programática do Place Autocomplete para acessar preços por solicitação e pedir resultados da API Geocoding sobre o lugar selecionado em vez do Place Details. O preço por solicitação combinado com a API Geocoding vai ser mais econômico que o preço por sessão se as duas condições a seguir forem atendidas:

Se você só precisa da latitude/longitude ou do endereço do local selecionado pela pessoa, a API Geocoding fornece essas informações por menos do que uma chamada do Place Details.
Se os usuários selecionarem uma previsão de preenchimento automático em média com quatro solicitações desse tipo, o preço por solicitação poderá ser mais econômico que o custo por sessão.

Se quiser ajuda para escolher a implementação do Place Autocomplete de acordo com o que você precisa, selecione a guia correspondente à resposta à pergunta abaixo.

Seu aplicativo requer outras informações além do endereço e da latitude/longitude da previsão selecionada?

Sim, mais detalhes são necessários

Use o Place Autocomplete com base em sessões com o Place Details.
Como seu app exige detalhes do lugar, como nome, status comercial ou horário de funcionamento, a implementação do preenchimento automático precisa usar um token de sessão (de forma programática ou integrada aos widgets do JavaScript, Android ou iOS) a um total de US$ 0,017 por sessão, além de SKU de dados do Places relevantes, dependendo dos campos de dados de lugares que você solicita.¹

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Place Autocomplete e do Place Details na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos de dados de lugares necessários.

Implementação programática
Use um token de sessão com suas solicitações do Place Autocomplete. Ao solicitar Place Details sobre a previsão selecionada, inclua os seguintes parâmetros:

O ID de lugar da resposta do Place Autocomplete
O token de sessão usado na solicitação do Place Autocomplete
O parâmetro fields especificando os campos de dados de lugar necessários.

Não, apenas o endereço e o local são necessários

A API Geocoding pode ser uma opção mais econômica que o Place Details para seu aplicativo, dependendo da performance do Place Autocomplete. A eficiência do preenchimento automático de cada aplicativo varia de acordo com o que as pessoas inserem, onde o aplicativo está sendo usado e se as práticas recomendadas de otimização de performance foram seguidas.

Para responder à pergunta a seguir, analise quantos caracteres a pessoa digita em média antes de selecionar uma previsão do Place Autocomplete no seu aplicativo.

As pessoas selecionam, em média, uma previsão do Place Autocomplete em até quatro solicitações?

Sim

Implementar o Place Autocomplete de forma programática sem tokens de sessão e chamar a API Geocoding na previsão de lugar selecionada.
A API Geocoding oferece endereços e coordenadas de latitude/longitude por US$ 0,005 a cada solicitação. Fazer quatro solicitações de Place Autocomplete: por solicitação custa US$ 0,01132. Portanto, o custo total de quatro solicitações, além de uma chamada da API Geocoding sobre a previsão de lugar selecionada, é de US$ 0,01632, menor que o preço de preenchimento automático por sessão de US$ 0,017.¹

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.

Não

Use o Place Autocomplete com base em sessões com o Place Details.
Como a média de solicitações que você espera fazer antes de alguém selecionar uma previsão do Place Autocomplete é maior que o custo do preço por sessão, a implementação do Place Autocomplete precisa usar um token de sessão para as solicitações do Place Autocomplete e a respectiva solicitação do Place Details por um total de US$ 0,017 a cada sessão.¹

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Place Autocomplete e do Place Details na previsão selecionada. Especifique o parâmetro fields para garantir a solicitação apenas dos campos de dados básicos.

Implementação programática
Use um token de sessão com suas solicitações do Place Autocomplete. Ao solicitar Place Details sobre a previsão selecionada, inclua os seguintes parâmetros:

O ID de lugar da resposta do Place Autocomplete
O token de sessão usado na solicitação do Place Autocomplete
O parâmetro fields que especifica campos de dados básicos como endereço e geometria

Considere atrasar as solicitações do Place Autocomplete
É possível adiar uma solicitação do Place Autocomplete até que a pessoa digite os três ou quatro primeiros caracteres, fazendo com que o aplicativo gere menos solicitações. Por exemplo, fazer solicitações do Place Autocomplete para cada caractere depois que o usuário digita o terceiro caractere significa que, se ele digitar 7 caracteres e selecionar uma previsão em que você fez uma solicitação da API Geocoding, o custo total vai ser de US$ 0,01632 (4 × US$ 0,00283 do Autocomplete por solicitação + US$ 0,005 do Geocoding).¹

Se for possível usar o atraso de solicitações para deixar sua solicitação programática média abaixo de quatro, siga as orientações para ter uma performance eficiente no Place Autocomplete com a API Geocoding. Atrasar solicitações pode ser percebido como latência pelo usuário, que talvez queira ver previsões a cada vez que pressionar uma nova tecla.

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.

Os custos listados aqui estão em USD. Consulte a página Faturamento da Plataforma Google Maps para saber tudo sobre os preços.

Práticas recomendadas de performance

As diretrizes a seguir descrevem como otimizar a performance do Place Autocomplete:

Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Place Autocomplete. A preferência de idioma não é necessária com widgets porque eles usam o que está definido no navegador ou no dispositivo móvel do usuário.
Se o Place Autocomplete estiver acompanhado por um mapa, é possível direcionar o local por janela de visualização do mapa.
Quando a pessoa não escolhe uma das previsões do Autocomplete, geralmente porque nenhuma delas revisões é o endereço que ela quer, você pode reutilizar a entrada original para tentar receber resultados mais relevantes:
- Se quiser que o usuário insira apenas informações de endereço, reutilize a entrada original dele em uma chamada para a API Geocoding.
- Se quiser que o usuário insira consultas para um lugar específico por nome ou endereço, use uma solicitação do Find Place. Se os resultados forem esperados apenas em uma região específica, use o direcionamento de local.
Outros cenários em que é melhor voltar para a API Geocoding são:
- Usuários que inserem endereços de sublocal em países onde a compatibilidade do Place Autocomplete com esse tipo de endereço é parcial (como República Tcheca, Estônia e Lituânia). Por exemplo, o endereço tcheco "Stroupežnického 3191/17, Praha" gera uma previsão parcial no Place Autocomplete.
- Usuários que digitam endereços com prefixos de trechos de via, como "23-30 29th St, Queens", na cidade de Nova York, ou "47-380 Kamehameha Hwy, Kaneohe", na ilha de Kauai, no Havaí.

Solução de problemas

Embora uma grande variedade de erros possa ocorrer, a maioria dos erros que seu app provavelmente vai encontrar geralmente é causada por erros de configuração (por exemplo, a chave de API incorreta foi usada ou a chave de API foi configurada incorretamente) ou por erros de cota (o app excedeu a cota). Consulte Limites de uso para mais informações sobre cotas.

Os erros que ocorrem ao usar os controles de preenchimento automático são retornados no método didFailAutocompleteWithError() dos vários protocolos delegados. A propriedade code do objeto NSError fornecido é definida como um dos valores da enumeração GMSPlacesErrorCode.

Place Autocomplete

Adicionar um controle de interface de preenchimento automático

Como adicionar um controle de tela cheia

Swift

Objective-C

Como adicionar um controlador de resultados

Adicionar uma barra de pesquisa à barra de navegação

Swift

Objective-C

Adicionar uma barra de pesquisa à parte de cima de uma visualização

Swift

Objective-C

Swift

Objective-C

Adicionar uma barra de pesquisa usando os resultados pop-over

Swift

Objective-C

Como usar uma fonte de dados de tabela

Swift

Objective-C

Personalizar as cores do texto e do plano de fundo

Como usar o protocolo UIAppearance

Como definir propriedades de estilo do controle de interface

Como receber previsões de lugares de forma programática

Ligando para GMSPlacesClient findAutocompletePredictionsFromQuery:

Swift

Objective-C

Swift

Objective-C

Como usar o coletor

Swift

Objective-C

Tokens de sessão

Limites de uso

Mostrar atribuições no app

Como controlar o indicador de atividade de rede

Restringir resultados do preenchimento automático

Direcionamento dos resultados para uma região específica

Restringir os resultados a uma região específica

Filtrar resultados por país

Filtrar resultados por tipo de lugar ou conjunto de tipos

Otimização do Place Autocomplete

Práticas recomendadas de otimização de custos

Otimização básica de custos

Otimização avançada de custos

Sim, mais detalhes são necessários

Não, apenas o endereço e o local são necessários

Sim

Não

Práticas recomendadas de performance

Solução de problemas

Ligando para `GMSPlacesClient findAutocompletePredictionsFromQuery:`