Place Autocomplete

選取平台： Android iOS JavaScript 網頁服務

淘汰通知

通知： initWithBounds:filter 方法已於 ，且不適用於 v4.0.0 以上版本。 而是改用 initWithFilter:敬上 GMSAutocompleteFetcher.h中。 相關詳情請見這篇文章。

通知： setAutocompleteBoundsUsingNorthEastCorner:SouthWestCorner 輔助工具 GMSAutocompleteViewController 中的方法， GMSAutocompleteResultsViewController, 和 GMSAutocompleteTableDataSource， 自 3.10.0 版起淘汰， v4.0.0 以上版本。 請改用 locationBias， 或 locationRestriction。 相關詳情請見這篇文章。

通知： GMSAutocompleteViewController.autocompleteBounds 屬性 和GMSAutocompleteViewController.autocompleteBoundsMode 自 3.9.0 版起淘汰， v4.0.0 以上版本。 如需對等屬性，請使用 GMSAutocompleteViewController.filter、 包含 GMSAutocompleteFilter.locationBias 或 GMSAutocompleteFilter.locationRestriction。

通知： bounds 和 boundsMode 的參數 findAutocompletePredictionsFromQuery:bounds:boundsMode:filter:SessionToken:callback, autocompleteQuery:bounds:boundsMode:filter:callback和 autocompleteQuery:bounds:boundsMode:filter:callback是 自 3.9.0 版起淘汰，不適用於 v4.0.0 以上版本。適用對象 同等功能，請使用 findAutocompletePredictionsFromQuery:filter:sessionToken:callback 搭配 GMSAutocompleteFilter.locationBias 或 GMSAutocompleteFilter.locationRestriction。

Places SDK for iOS 中的自動完成服務會傳回地點 來回應使用者的搜尋查詢使用者輸入時， 自動完成服務會傳回地點的建議，例如商家、 地址、plus code 和 搜尋點。

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

• 如要儲存，請新增自動完成 UI 控制項 並確保使用者體驗保持一致
• 透過程式輔助方式取得地點預測結果，建立自訂使用者 無須專人管理

新增自動完成 UI 控制項

自動完成 UI 控制項是內建自動完成功能的搜尋對話方塊 功能。使用者輸入搜尋字詞時，控制項會顯示 列出可供選擇的預測地點清單使用者做出選擇後 GMSPlace 例項，應用程式可以使用該例項取得 選取的地點

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

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

新增全螢幕控制項

如要採用強制回應情境，請使用全螢幕控制項 自動完成 UI 會暫時取代應用程式的使用者介面，直到 使用者選取的項目這項功能是由 GMSAutocompleteViewController敬上 類別使用者選取地點時，應用程式會收到回呼。

如何為應用程式新增全螢幕控制項：

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

以下範例示範了一種啟動程序 GMSAutocompleteViewController敬上 來回應使用者輕觸按鈕的動作

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:@selector(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 新增至應用程式的 UI。
6. 在 didAutocompleteWithPlace 中處理使用者的選項 委派方法。

將 UISearchController 的搜尋列置入的方法有以下幾種： 應用程式的使用者介面：

• 在導覽列中加入搜尋列
• 在檢視畫面頂端加入搜尋列
• 使用彈出式搜尋結果新增搜尋列

在導覽列中加入搜尋列

以下程式碼範例示範如何新增結果控制器，將 將 searchBar 傳送至導覽列，並處理使用者選擇的內容：

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

注意： 如要正確顯示搜尋列，應用程式的檢視控制器必須 包含在 UINavigationController 中。

在檢視畫面頂端加入搜尋列

以下程式碼範例說明如何在檢視區塊頂端新增 searchBar。

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

根據預設，UISearchController 在進行簡報時隱藏導覽列 (可以停用此功能)。如果 導覽列仍然顯示且不透明，未設定 UISearchController 正確設定刊登位置

請改用以下程式碼：

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;

運用彈出式搜尋結果新增搜尋列

以下程式碼範例顯示如何將搜尋列放在 導覽列，並在彈出式視窗中顯示結果。

注意： 彈出式視窗只會顯示在 iPad 上，以及處於橫向模式的 iPhone 6 以上版本。啟用 所有其他裝置都會改回全螢幕檢視控制器

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

注意： 如要正確顯示搜尋列，應用程式的檢視控制器必須 包含在 UINavigationController 中。

使用資料表資料來源

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

使用 GMSAutocompleteTableDataSource 做為資料來源和 UITableView 的委派代表 ，就能：

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

以下程式碼範例示範如何使用 GMSAutocompleteTableDataSource敬上 類別，在單獨新增 UISearchBar 時驅動 UIViewController 的資料表檢視。

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

      

自訂文字和背景顏色

您可以在自動完成使用者介面中設定所有文字和背景的顏色 控制項，讓小工具更貼近應用程式的外觀 。您可以透過兩種方式設定 UI 控制項顏色：

• 盡可能使用原生 iOS UIAppearance 通訊協定，為 UI 控制項設定全域樣式。這些設定會套用到許多 UI 控制項，但並非全部都適用 元素。
• 在小工具類別上使用 SDK 方法設定屬性， UIAppearance 通訊協定不支援。

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

下表列出所有 UI 元素，並指出每個元素 且應設定樣式 (UIAppearance 通訊協定或 SDK 方法)。

UI 元素	方法	造型教學
導覽列色調 (背景)	UIAppearance 通訊協定	透過 UINavigationBar Proxy 呼叫 setBarTintColor。
導覽列色調顏色 (搜尋列文字插入點和取消按鈕)	UIAppearance 通訊協定	透過 UINavigationBar Proxy 呼叫 setTintColor。
搜尋列文字顏色	UIAppearance 通訊協定	已在「searchBarTextAttributes」中設定「NSForegroundColorAttributeName」。
搜尋列色調顏色	不適用	搜尋列為半透明，以陰影版本的形式顯示 。
搜尋列預留位置文字顏色 (預設搜尋文字)	UIAppearance 通訊協定	已在「placeholderAttributes」中設定「NSForegroundColorAttributeName」。
主要文字 (也同時套用至錯誤和訊息文字)	SDK 方法	歡迎致電primaryTextColor。
主要文字醒目顯示	SDK 方法	歡迎致電primaryTextHighlightColor。
次要文字	SDK 方法	歡迎致電secondaryTextColor。
錯誤和訊息文字	SDK 方法	歡迎致電primaryTextColor。
表格儲存格背景	SDK 方法	歡迎致電tableCellBackgroundColor。
表格儲存格分隔符顏色	SDK 方法	歡迎致電tableCellSeparatorColor。
「再試一次」按鈕	SDK 方法	歡迎致電tintColor。
活動指標 (進度旋轉圖示)	UIAppearance 通訊協定	透過 UIActivityIndicatorView Proxy 呼叫 setColor。
「Google 技術提供」標誌、Sad 雲端圖片	不適用	系統會根據背景對比度自動選取白色或灰色版本。
搜尋列文字欄位中的放大鏡和清晰文字圖示	不適用	如要設定樣式，請將預設圖片換成所需顏色的圖片。

注意： 這些屬性只會影響 UI 元素的色彩設定。變更中 系統不支援 UI 元素大小或表格儲存格中使用的字型。

使用 UIAppearance 通訊協定

您可以使用 UIAppearance 通訊協定 取得特定 UI 元素的外觀 Proxy，隨後就能使用 設定 UI 元素的顏色。修改時， 指定的 UI 元素會受到影響舉例來說 會在 UITextField 類別出現時，將文字顏色變更為綠色 包含在 UISearchBar 中：

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

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

下列程式碼片段顯示了您需要使用的所有 Proxy 指令 設定全螢幕自動完成 UI 控制項中的所有樣式。加入這段程式碼 附加至 AppDelegate.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 通訊協定，因此必須直接設定。以下程式碼範例 顯示定義前景和背景色彩，並套用至 UI 控制執行個體，名為 acController。將此程式碼新增至 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;

敬上

注意： 就 GMSAutocompleteViewController 和 GMSAutocompleteResultsViewController 而言， 可以使用 Interface Builder 設定這些值。

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

您可以建立自訂搜尋使用者介面，做為 自動完成小工具。也就是說，應用程式必須取得地點預測結果 編寫程式應用程式可取得預測的地點名稱和/或 匯入超過 90 個 IP 位址：

• 呼叫 GMSPlacesClient findAutocompletePredictionsFromQuery:
• 使用擷取程式

正在打給GMSPlacesClient findAutocompletePredictionsFromQuery:

如要取得預測的地點名稱和/或地址清單，請先 instantiate GMSPlacesClient， 接著呼叫 GMSPlacesClient findAutocompletePredictionsFromQuery:敬上 方法，包含以下參數：

• autocompleteQuery 字串，包含使用者輸入的文字。
• GMSAutocompleteSessionToken、 可用來識別各個工作階段您的應用程式應 然後傳遞相同的符記。 在後續呼叫 fetchPlacefromPlaceID: 時，以及地點 ID 來擷取使用者所選地點的 Place Details。
• GMSAutocompleteFilter 執行以下動作：
  • 針對特定區域調整或限制結果。
  • 將結果限制為特定地點類型。
  • GMSPlaceLocationBias/Restriction 物件會將結果自訂調整至經緯度範圍指定的特定區域。
• 處理傳回的預測結果的回呼方法。

以下程式碼範例顯示對 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);
    }
  }
}];

API 會叫用指定的回呼方法，並傳入 GMSAutocompletePrediction敬上 如需儲存大量結構化物件 建議使用 Cloud Bigtable

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

• attributedFullText - 預測結果的全文，格式為 NSAttributedString。例如，「Sydney Opera House, Sydney, New South」 澳洲威爾斯凡是與使用者輸入內容相符的文字範圍，都有 屬性，kGMSAutocompleteMatchAttribute。這項屬性可以 醒目顯示使用者查詢中的相符文字，如下所示。
• placeID：預測地點的地點 ID。地點 ID 是 可識別特定地點的文字 ID；如要進一步瞭解 地點 ID 請參閱 Place ID 總覽。
• distanceMeters：與指定距離的直線距離 origin 到目的地。如果未設定 origin 屬性，則沒有距離 的值。

以下程式碼範例說明如何以粗體文字醒目顯示各個部分 使用 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;
    

使用擷取程式

如果想從頭開始自行建立自動完成控制項 GMSAutocompleteFetcher、 這會納入 GMSPlacesClient 上的 autocompleteQuery 方法。 擷取程式會調節要求，只傳回最近的結果 輸入的搜尋文字。它沒有提供 UI 元素。

如要實作 GMSAutocompleteFetcher， 步驟如下：

1. 導入 GMSAutocompleteFetcherDelegate 因此效能相當卓越
2. 建立 GMSAutocompleteFetcher 物件。
3. 在使用者輸入內容時，呼叫擷取器上的 sourceTextHasChanged。
4. 使用 didAutcompleteWithPredictions 處理預測和錯誤 和 didFailAutocompleteWithError 通訊協定方法

以下程式碼範例示範如何使用擷取程式取得使用者輸入內容 並在文字檢視區塊中顯示地點相符結果選取地點的功能 已經省略。FetcherSampleViewController衍生自 UIViewController 在 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>

@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 辨別每個工作階段您的應用程式應在 並將每個新工作階段開始，然後傳送相同的符記以及地點 ID。 對 fetchPlacefromPlaceID: 的後續呼叫 來擷取使用者所選地點的 Place Details。

提示： 如果您的應用程式使用自動完成 小工具，你 不需要實作工作階段，因為小工具會自動處理工作階段 在背景執行。

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

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

let token: GMSAutocompleteSessionToken = GMSAutocompleteSessionToken.init()

用量限制

• 使用 GMSPlacesClient findAutocompletePredictionsFromQuery 方法必須遵守分層查詢的限制。詳情請參閱 用量限制。

在應用程式中顯示作者資訊

• 如果應用程式以程式輔助方式使用自動完成服務，您的使用者介面必須 分別顯示「Google 技術提供」或顯示在 Google 品牌地圖。
• 如果您的應用程式使用自動完成 UI 控制項，則無須採取其他動作 (系統預設會顯示必要的出處)。
• 如果您在刪除及顯示其他地點資訊後， 使用 ID 取得地點 必須同時顯示第三方出處資訊

詳情請參閱 作者資訊。

控制網路活動指標

要控制應用程式狀態列中的網路活動指標 請務必為自動完成功能實作適當的選用委派方法 ，並且自行開啟及關閉網路指標。

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

實作這些方法並設定 [UIApplication sharedApplication].networkActivityIndicatorVisible 分別定義為 YES 和 NO，狀態列將正確符合 自動完成 UI。

限制自動完成結果

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

• 如要在定義區域內「偏好」 (偏誤) 結果，請將 locationBias 設為 GMSAutocompleteFilter (對定義區域以外的結果可能會 )。如果一併設定 locationRestriction，系統會忽略 locationBias。

• 如要只顯示 (限制) 指定區域內的結果，請設定 GMSAutocompleteFilter上的 locationRestriction (僅限 就會傳回該值)。

  • 注意：這項限制僅適用於整條路線，合成 矩形邊界外的結果可能會根據路線傳回 與地區限制重疊的廣告

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

• 如果只要傳回最多 5 個指定國家/地區的結果，請設定 GMSAutocompleteFiltercountries。

針對特定區域調整結果

如要在定義區域內「偏好」 (偏誤) 結果，請將 locationBias 設為 GMSAutocompleteFilter，如下所示：

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

依國家/地區篩選結果

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

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

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

設定 types 項資源 GMSAutoCompleteFilter。 請使用這項資源指定表 1、2 和 3 中列出的篩選器 地點類型。如未指定，系統會傳回所有類型。

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

• 使用 types 屬性指定表 1 中最多五個「類型」值 和「地點類型」上的表 2。類型值為 由 GMSPlaceType 中的常數定義。

• 使用 types 屬性指定表 3 所示的類型集合 前往地點類型。類型集合值是由 GMSPlaceType 中的常數。

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

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

  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 Details 使用以工作階段為準的 Place Autocomplete。
您的應用程式會要求 Place Details (例如地點名稱、商家狀態或營業時間)，因此在導入 Place Autocomplete 時，建議使用工作階段符記 (透過程式輔助方式，或是內建於 JavaScript、Android 或 iOS 小工具)，總費用為每個工作階段 $0.017 美元，再加上適用的地點資料 SKU (視您要求的地點資料欄位而定)¹。

透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Place Autocomplete 要求和 Place Details 要求。請務必指定 fields 參數，確保您只要求所需的地點資料欄位。

透過程式輔助方式導入
搭配 Place Autocomplete 要求使用工作階段符記。要求所選預測結果的相關 Place Details 時，請加入下列參數：

1. Place Autocomplete 回應中的地點 ID
2. Place Autocomplete 要求中使用的工作階段符記
3. 指定所需地點資料欄位的 fields 參數

否，只需要地址和位置資訊

對您的應用程式而言，Geocoding API 可能比 Place Details 更符合成本效益，視 Place Autocomplete 使用效能而定。每個應用程式的自動完成效率各不相同，可能取決於使用者輸入的內容、使用應用程式的位置，以及是否採用效能最佳化最佳做法。

為了找出以下問題的解答，請分析使用者在應用程式中選取 Place Autocomplete 預測結果前，平均輸入的字元數量。

使用者是否會在平均四次以內的要求中選取 Place Autocomplete 預測結果？

是

透過程式輔助方式導入 Place Autocomplete，但不使用工作階段符記，並針對已選取的地點預測結果呼叫 Geocoding API。
Geocoding API 提供地址和經緯度座標，收費為每次要求 $0.005 美元。提出四次 Place Autocomplete - Per Request 要求的費用為 $0.01132 美元，因此如果將四次要求加上所選地點預測結果的相關 Geocoding API 呼叫，總費用就會是 $0.01632 美元，低於自動完成功能「按工作階段」計價的每個工作階段 $0.017 美元¹。

建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。

否

搭配 Place Details 使用以工作階段為準的 Place Autocomplete。
您預期使用者在選取 Place Autocomplete 預測結果前提出的平均要求數量，會超過「按工作階段」計價的費用，因此在導入 Place Autocomplete 時，建議針對 Place Autocomplete 要求和相關聯的 Place Details 要求都使用工作階段符記，總費用為每個工作階段 $0.017 美元¹。

透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Place Autocomplete 要求和 Place Details 要求。請務必指定 fields 參數，確保只要求需要的 Basic Data 欄位。

透過程式輔助方式導入
搭配 Place Autocomplete 要求使用工作階段符記。要求所選預測結果的相關 Place Details 時，請加入下列參數：

1. Place Autocomplete 回應中的地點 ID
2. Place Autocomplete 要求中使用的工作階段符記
3. 指定地址和幾何圖形等 Basic Data 欄位的 fields 參數

考慮延後 Place Autocomplete 要求
您可以運用一些策略，例如將 Place Autocomplete 要求延後到使用者輸入三或四個字元時再開始，藉此減少應用程式提出要求數量。舉例來說，如果您是在使用者輸入第三個字元「之後」才針對每個字元提出 Place Autocomplete 要求，那麼當使用者在輸入七個字元後，選取您透過單次 Geocoding API 要求帶出的一筆預測結果，總費用就是 $0.01632 美元 (4 * $0.00283 Autocomplete Per Request + $0.005 美元 Geocoding)¹。

如果延後要求可以讓平均程式輔助要求少於四次，您可以按照使用 Geocoding API 提高 Place Autocomplete 效能的指南操作。請注意，如果使用者希望每輸入一個字就能看到預測結果，可能就會將延後要求視為時間上的延遲。

建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。

---

1. 這裡列出的費用是以美元計算。如需完整計價資訊，請參閱「Google 地圖平台計費方式」頁面。

效能最佳做法

以下準則說明如何將 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 列舉。