Place Autocomplete

Places SDK for iOS 中的自動完成服務會根據使用者搜尋查詢傳回地點預測結果。使用者輸入時，自動完成服務會傳回地點 (例如商家、地址、區碼和搜尋點) 的建議。

你可以透過以下方式在應用程式中加入自動完成功能：

• 新增 Autocomplete 使用者介面控制項，以節省開發時間，並確保使用者體驗一致。
• 透過程式輔助方式取得地點預測結果，藉此建立自訂使用者體驗。

新增 Autocomplete UI 控制項

Autocomplete UI 控制項是包含內建自動完成功能的搜尋對話方塊。使用者輸入搜尋字詞時，控制項會列出可預測的地點清單。使用者做出選擇後，系統會傳回 GMSPlace 執行個體，以供應用程式用於取得有關所選地點的詳細資料。

您可以透過下列方式，在應用程式中加入自動完成 UI 控制項：

• 新增全螢幕控制項
• 新增結果控制器
• 使用資料表資料來源

新增全螢幕控制項

當您需要模組化內容時，請用全螢幕控制項，在其當使用者選取之前，自動完成 UI 會暫時取代應用程式的 UI。這項功能是由 GMSAutocompleteViewController 類別提供。使用者選取地點時，應用程式會收到回呼。

如何在應用程式中加入全螢幕控制項：

1. 在主要應用程式中建立 UI 元素，即可啟動自動完成 UI 控制項，例如 UIButton 上的觸控處理常式。
2. 在父項檢視控制器中實作 GMSAutocompleteViewControllerDelegate 通訊協定。
3. 建立 GMSAutocompleteViewController 的執行個體，並將上層檢視控制器指派為委派屬性。
4. 建立 GMSPlaceField 以定義要傳回的地點資料類型。
5. 新增 GMSAutocompleteFilter，將查詢範圍限制在特定的地點類型。
6. 使用 [self presentViewController...] 呈現 GMSAutocompleteViewController。
7. 在 didAutocompleteWithPlace 委派方法中處理使用者的選項。
8. 關閉 didAutocompleteWithPlace、didFailAutocompleteWithError 和 wasCancelled 委派方法中的控制器。

以下範例將展示如何啟動 GMSAutocompleteViewController，以回應使用者的按鈕。

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
  }

}

#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

新增結果控制器

如要進一步控管文字輸入 UI，請使用結果控制器。結果控制器會根據輸入 UI 焦點動態切換結果清單的顯示設定。

如何在應用程式中新增結果控制器：

1. 建立 GMSAutocompleteResultsViewController。
2. 在上層檢視區塊控制器中實作 GMSAutocompleteResultsViewControllerDelegate 通訊協定，並將父項檢視控制器指派為委派屬性。
3. 建立 UISearchController 物件，並傳入 GMSAutocompleteResultsViewController 做為結果控制器引數。
4. 將 GMSAutocompleteResultsViewController 設為 UISearchController 的 searchResultsUpdater 屬性。
5. 將 UISearchController 的 searchBar 加入應用程式的使用者介面。
6. 在 didAutocompleteWithPlace 委派方法中處理使用者的選項。

您可以透過多種方式將 UISearchController 的搜尋列放入應用程式使用者介面：

• 在搜尋列中新增搜尋列
• 在搜尋列頂端新增搜尋列
• 使用彈出的搜尋結果新增搜尋列

在導覽列中新增搜尋列

以下程式碼範例示範如何新增結果控制器、將 searchBar 新增至導覽列，以及處理使用者的選項：

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
  }
}

- (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;
}

在檢視畫面頂端新增搜尋列

以下程式碼範例說明如何將 searchBar 新增至檢視畫面頂端。

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
  }
}

- (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;
}

根據預設，UISearchController 會在進行簡報時隱藏導覽列 (可停用此功能)。如果導覽列可見且不透明，UISearchController 就無法正確設定位置。

請改用以下程式碼做為替代方案：

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

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;

使用彈出式視窗搜尋結果新增搜尋列

以下程式碼範例說明如何將搜尋列置於導覽列的右側，並在彈出式視窗中顯示結果。

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
  }
}

- (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;
}

使用資料表資料來源

如果您的應用程式有自訂搜尋文字 UI，則可以使用 GMSAutocompleteTableDataSource 類別推動資料表檢視，以便在檢視控制器上顯示結果。

如要在檢視控制器中使用 GMSAutocompleteTableDataSource 做為資料來源，以及 UITableView 的委派，請按照下列步驟操作：

1. 在檢視控制器中實作 GMSAutocompleteTableDataSourceDelegate 和 UISearchBarDelegate 通訊協定。
2. 建立 GMSAutocompleteTableDataSource 執行個體，並將檢視控制器指派為委派屬性。
3. 將 GMSAutocompleteTableDataSource 設為資料檢視控制器上的 UITableView 執行個體資料來源，並委派屬性。
4. 在搜尋文字輸入的處理常式中，呼叫 GMSAutocompleteTableDataSource 上的 sourceTextHasChanged。
5. 處理使用者在 didAutocompleteWithPlace 委派方法中的所選項目。
6. 關閉 didAutocompleteWithPlace、didFailAutocompleteWithError、wasCancelled 委派方法中的控制器。

以下程式碼範例展示使用 GMSAutocompleteTableDataSource 類別，在新增 UISearchBar 時對 UIViewController 的資料表檢視畫面。

// 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
  }
}

      

// 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

      

自訂文字和背景顏色

您可以在 Autocomplete UI 控制項中設定所有文字和背景的顏色，讓小工具看起來更接近應用程式的外觀。設定使用者介面控制項顏色的方式有兩種：

• 盡可能使用原生 iOS UIAppearance 通訊協定來全面設定使用者介面樣式。這些設定適用於許多 UI 控制元素，但不是全部。
• 使用小工具類別的 SDK 方法來設定 UIAppearance 通訊協定不支援的屬性。

一般而言，應用程式會使用 UIAppearance 通訊協定和 SDK 方法的某些組合。下圖顯示可設定元素的樣式：

下表列出所有 UI 元素，並指出各元素的格式 (UIAppearance 通訊協定或 SDK 方法)。

使用 UIAppearance 通訊協定

您可以使用 UIAppearance 通訊協定來取得特定 UI 元素的外觀 Proxy，然後用來設定 UI 元素的顏色。修改時，特定 UI 元素的所有執行個體都會受到影響。例如，當 UISearchBar 包含 UITextField 類別的文字顏色時，全域範例便會將其變更為綠色：

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

如要進一步瞭解如何定義顏色值，請參閱 UIColor 類別參考資料。

下列程式碼片段顯示在全螢幕自動完成 UI 控制項中，您需要設定所有樣式的 Proxy 指令。將這段程式碼新增至 App 委派.m 中的 didFinishLaunchingWithOptions 方法：

// 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;

設定 UI 控制項樣式屬性

部分 UI 控制元素的屬性不受 UIAppearance 通訊協定影響，因此必須直接設定。以下程式碼範例顯示如何定義前景和背景顏色，並套用至名為 acController 的 UI 控制執行個體。將下列程式碼新增至 ViewController.m 中的 onLaunchClicked 方法：

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;

透過程式輔助方式取得地點預測結果

除了自訂小工具提供的 UI，您也可以建立自訂搜尋 UI。為此，您的應用程式必須透過程式輔助方式取得地點預測結果。應用程式可透過下列其中一種方式取得預測地點名稱和/或地址清單：

• 撥打 GMSPlacesClient findAutocompletePredictionsFromQuery:
• 使用擷取工具

正在打給GMSPlacesClient findAutocompletePredictionsFromQuery:

如要取得預測地點名稱和/或地址清單，請先執行個體化 GMSPlacesClient，並使用下列參數呼叫 GMSPlacesClient findAutocompletePredictionsFromQuery: 方法：

• autocompleteQuery 字串，包含使用者輸入的文字。
• GMSAutocompleteSessionToken，用來識別每個工作階段。應用程式必須在每個自動完成要求呼叫中傳遞相同的權杖，然後在後續的 fetchPlacefromPlaceID: 呼叫中，將該權杖與地點 ID 一併傳遞，以便在使用者選取的地點擷取 Place Details。
• 符合以下條件的 GMSAutocompleteFilter：
  • 將結果限製或限制在特定區域。
  • 將結果限制為特定的地點類型。
  • GMSPlaceLocationBias/Restriction 物件，將結果自訂在緯度和經度邊界的指定區域。
• 處理傳回預測結果的回呼方法。

以下程式碼範例顯示對 findAutocompletePredictionsFromQuery: 的呼叫。

/**
 * 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)")
      }
    }
})

/**
 * 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);
    }
  }
}];

API 會叫用指定的回呼方法，並傳入 GMSAutocompletePrediction 物件的陣列。

每個 GMSAutocompletePrediction 物件都包含下列資訊：

• attributedFullText：預測結果的完整文字，格式為 NSAttributedString。例如：「Sydney Opera House, Sydney, New South WaWless, Australia」。符合使用者輸入內容的每個文字範圍都有 kGMSAutocompleteMatchAttribute 屬性。您可以利用這項屬性，在使用者查詢中醒目顯示相符的文字，如下所示。
• placeID：預測地點的地點 ID。地點 ID 是用來識別特定地點的文字 ID，如要進一步瞭解地點 ID，請參閱地點 ID 總覽。
• distanceMeters：從指定 origin 到目的地的直線距離。如未設定 origin 屬性，則不會傳回距離值。

以下程式碼範例說明如何使用 enumerateAttribute，以粗體醒目顯示與使用者查詢內容相符的部分部分：

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
    

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;
    

使用擷取工具

如要從頭開始建構自動完成控制項，可以使用 GMSAutocompleteFetcher，在 GMSPlacesClient 中納入 autocompleteQuery 方法。擷取器會限制要求，只傳回最近輸入的搜尋文字結果。不提供 UI 元素。

如要實作 GMSAutocompleteFetcher，請按照下列步驟操作：

1. 實作 GMSAutocompleteFetcherDelegate 通訊協定。
2. 建立 GMSAutocompleteFetcher 物件。
3. 在使用者輸入內容時呼叫擷取工具上的 sourceTextHasChanged。
4. 使用 didAutcompleteWithPredictions 和 didFailAutocompleteWithError 通訊協定方法處理預測和錯誤。

以下程式碼範例示範如何使用擷取器，在文字檢視畫面中呈現使用者輸入內容和顯示地點相符項目。系統已略過選取地點的功能。FetcherSampleViewController 衍生自 FetcherSampleViewController.h 中的 UIViewController。

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
  }
}

#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

工作階段符記

工作階段符記會將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。工作階段是從使用者輸入查詢時開始，到使用者選取地點時結束。在每個工作階段中，使用者可以輸入多筆查詢，最終選擇一個地點。工作階段結束後，符記就會失效；您的應用程式必須為每個工作階段產生獨立的權杖。我們建議在所有程式輔助自動完成工作階段使用工作階段符記 (如果您使用全螢幕控制器或結果控制器，API 會自動處理這個問題)。

Places SDK for iOS 使用 GMSAutocompleteSessionToken 來識別各個工作階段。應用程式必須在每個新的工作階段開始時傳遞新的工作階段符記，然後在後續呼叫 fetchPlacefromPlaceID: 中傳遞相同的權杖與地點 ID，以針對使用者選取的地點擷取 Place Details。

進一步瞭解工作階段符記。

請使用以下程式碼產生新的工作階段符記：

let token: GMSAutocompleteSessionToken = GMSAutocompleteSessionToken.init()

用量限制

• 使用 GMSPlacesClient findAutocompletePredictionsFromQuery 方法時，必須遵守分級查詢限制。請參閱用量限制說明文件。

在應用程式中顯示出處

• 如果應用程式透過程式輔助方式使用自動完成服務，則 UI 必須顯示「由 Google 技術提供」屬性，或是在 Google 品牌地圖中顯示。
• 如果您的應用程式使用自動完成 UI 控制項，則無須採取其他行動 (系統預設會顯示必要屬性)。
• 如果您在依 ID 取得地點後擷取及顯示其他地點資訊，您也必須顯示第三方出處資訊。

詳情請參閱歸因說明文件。

控管網路活動指標

如要在應用程式狀態列中控制網路活動指標，您必須針對您使用的自動完成類別實作適當的選用委派方法，並自行開啟或關閉網路指標。

• 針對 GMSAutocompleteViewController，您必須實作委派方法 didRequestAutocompletePredictions: 和 didUpdateAutocompletePredictions:。
• 針對 GMSAutocompleteResultsViewController，您必須實作委派方法 didRequestAutocompletePredictionsForResultsController: 和 didUpdateAutocompletePredictionsForResultsController:。
• 針對 GMSAutocompleteTableDataSource，您必須實作委派方法 didRequestAutocompletePredictionsForTableDataSource: 和 didUpdateAutocompletePredictionsForTableDataSource:。

導入這些方法並將 [UIApplication sharedApplication].networkActivityIndicatorVisible 設為 YES 和 NO，狀態列會正確與自動完成 UI 相符。

限制自動完成結果

您可以設定自動完成 UI 控制項，將結果限制在特定的地理區域內，並/或篩選結果的一或多個地點類型或特定國家/地區。如要限制結果範圍，您可以執行下列操作：

• 如要在已定義的區域中偏好 (偏誤) 結果，請在 GMSAutocompleteFilter 上設定 locationBias (系統仍可能會傳回定義區域以外的部分結果)。如果同時設定了 locationRestriction，系統將忽略 locationBias。

• 如果只想顯示已定義區域內的結果，請在 GMSAutocompleteFilter 上設定 locationRestriction (系統只會傳回已定義區域內的結果)。

  • 注意：這項限制僅適用於整個路徑，系統可能會根據與地點限制重疊的路徑，傳回位於矩形邊界外的綜合結果。

• 如果只要傳回符合特定地點類型的結果，請在 GMSAutocompleteFilter 上設定 types (例如指定 TypeFilter.ADDRESS 會導緻小工具只傳回包含精確地址的結果)。

• 如果只要傳回最多五個指定國家/地區的結果，請在 GMSAutocompleteFilter 上設定 countries。

針對特定區域調整結果

如要在定義的區域中偏好 (偏誤) 結果，請在 GMSAutocompleteFilter 上設定 locationBias，如下所示：

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

將結果限制在特定地區

如果「只要顯示」 (限制) 在已定義的區域中的結果，請在 GMSAutocompleteFilter 上設定 locationRestriction，如下所示：

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

依國家/地區篩選結果

如要篩選指定最多五個國家/地區的結果，請在 GMSAutocompleteFilter 上設定 countries，如下所示：

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

依地點類型或類型集合篩選結果

透過設定 GMSAutoCompleteFilter 的 types 屬性，將結果限制在特定類型或類型集合。使用這個屬性指定地點類型 表 1、2 和 3 中列出的篩選器。如未指定，則會傳回所有類型。

如何指定類型或類型集合篩選器：

• 使用 types 屬性指定最多表 1 的類型值 (表 1 和表類型)。類型值是由 GMSPlaceType 中的常數定義。

• 使用 types 屬性，指定「地點類型」一文中表 3 的類型集合。類型集合值是由 GMSPlaceType 中的常數定義。

  在要求中只能使用表 3 中的一種類型。如果您指定表 3 的值，就無法指定表 1 或資料表 2 的值。否則系統會發生錯誤。

舉例來說，如要只傳回符合特定地點類型的結果，請在 GMSAutocompleteFilter 上設定 types。以下範例說明如何將篩選器設為只傳回包含精確地址的結果：

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

Place Autocomplete 最佳化

本節將說明最佳做法，協助您充分運用 Place Autocomplete 服務。

以下列出幾項一般準則：

• 如要開發有效的使用者介面，最快的方法就是使用 Maps JavaScript API Autocomplete 小工具、Places SDK for Android Autocomplete 小工具，或 Places SDK for iOS Autocomplete UI 控制項
• 從一開始就嘗試瞭解 Place Autocomplete 的必要資料欄位。
• 「位置自訂調整」和「位置限制」為自選欄位，但可能會對自動完成效能產生重大影響。
• 使用錯誤處理機制，可以減輕 API 傳回錯誤時對應用程式效能造成的影響。
• 確保應用程式能處理未選取任何項目的情況，以便使用者繼續操作。

費用最佳化最佳做法

基本費用最佳化

為了讓 Place Autocomplete 服務費用發揮最大效益，請使用 Place Details 和 Place Autocomplete 小工具中的欄位遮罩，只傳回所需的地點資料欄位。

進階費用最佳化

建議您透過程式輔助方式導入 Place Autocomplete，採用按請求計價，並要求已選地點 (而非 Place Details) 的相關 Geocoding API 結果。如果同時符合以下兩項條件，搭配 Geocoding API 使用「按要求」計價會比使用「按工作階段」(以工作階段為準) 計價更具成本效益：

• 如果您只需要針對使用者選取的地點取得經緯度或地址，透過 Geocoding API 擷取這項資訊，支付的費用會比使用 Place Details 呼叫更低。
• 如果使用者在平均四次以內的自動預測結果要求選取了自動預測結果，則「按要求」計價可能會比「按工作階段」計價更符合成本效益。

除了所選預測結果的地址和經緯度，應用程式是否需要任何其他資訊？

效能最佳做法

以下準則說明如何將 Place Autocomplete 效能最佳化：

• 針對導入的 Place Autocomplete 加入國家/地區限制、位置自訂調整和 (適用於程式輔助導入) 語言偏好設定。小工具會從使用者的瀏覽器或行動裝置選擇語言偏好設定，因此不需要設定語言偏好。
• 如果 Place Autocomplete 附帶地圖，您就可以根據地圖可視區域進行位置自訂調整。
• 如果使用者沒有選擇任何自動預測結果 (通常是因為這些預測結果並非他們想要的地址)，您可以重複使用原始使用者輸入內容，嘗試取得更相關的結果：
  • 如果您預期使用者只會輸入地址資訊，請在 Geocoding API 呼叫中重複使用原始使用者輸入內容。
  • 如果您預期使用者會依名稱或地址查詢某個地點，請使用「Find Place」要求。如果希望將結果範圍限制在特定區域，請使用位置自訂調整。
  適合改回使用 Geocoding API 的其他情況如下：
  • 使用者輸入的次要場所地址，位於 Place Autocomplete 未能完整提供次要場所地址支援的國家/地區 (例如捷克、愛沙尼亞和立陶宛)。例如，捷克地址「Stroupežnického 3191/17, Praha」在 Place Autocomplete 中會產生不完整的預測結果。
  • 使用者輸入的地址含有路段前置字元，例如紐約的「23-30 29th St, Queens」或夏威夷考艾島的「47-380 Kamehameha Hwy, Kaneohe」。

疑難排解

雖然可以發生各式各樣的錯誤，但應用程式最有可能發生的錯誤多半是設定錯誤 (例如 API 金鑰錯誤或 API 金鑰設定錯誤)，或是配額錯誤 (應用程式已超出配額)。如要進一步瞭解配額，請參閱用量限制。

使用自動完成控制項時發生的錯誤，會在各種委派通訊協定的 didFailAutocompleteWithError() 方法中傳回。所提供 NSError 物件的 code 屬性會設為 GMSPlacesErrorCode 列舉的其中一個值。