Tự động hoàn thành địa điểm

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

Dịch vụ tự động hoàn thành trong Places SDK dành cho iOS sẽ trả về gợi ý về địa điểm để phản hồi các cụm từ tìm kiếm của người dùng. Khi người dùng nhập dữ liệu, dịch vụ tự động hoàn thành sẽ trả về các đề xuất cho các địa điểm như doanh nghiệp, địa chỉ, mã cộng và địa điểm yêu thích.

Bạn có thể thêm tính năng tự động hoàn thành vào ứng dụng của mình theo các cách sau:

Thêm thành phần điều khiển giao diện người dùng tự động hoàn thành

Thành phần điều khiển giao diện người dùng tự động hoàn thành là một hộp thoại tìm kiếm có tích hợp sẵn chức năng tự động hoàn thành. Khi người dùng nhập cụm từ tìm kiếm, chế độ kiểm soát này sẽ hiển thị danh sách các địa điểm được dự đoán để lựa chọn. Khi người dùng lựa chọn, hệ thống sẽ trả về một thực thể GMSPlace. Sau đó, ứng dụng của bạn có thể dùng thực thể này để xem thông tin chi tiết về địa điểm đã chọn.

Bạn có thể thêm chế độ điều khiển giao diện người dùng tự động hoàn thành vào ứng dụng của mình theo các cách sau:

Thêm chế độ điều khiển toàn màn hình

Sử dụng thành phần điều khiển toàn màn hình khi bạn muốn ngữ cảnh phương thức, trong đó giao diện người dùng tự động hoàn thành sẽ tạm thời thay thế giao diện người dùng của ứng dụng cho đến khi người dùng lựa chọn. Chức năng này do lớp GMSAutocompleteViewController cung cấp. Khi người dùng chọn một địa điểm, ứng dụng sẽ nhận được một lệnh gọi lại.

Cách thêm chế độ điều khiển toàn màn hình vào ứng dụng:

  1. Tạo một thành phần trên giao diện người dùng trong ứng dụng chính để chạy chế độ điều khiển giao diện người dùng tự động hoàn thành, chẳng hạn như trình xử lý thao tác chạm trên UIButton.
  2. Triển khai giao thức GMSAutocompleteViewControllerDelegate trong bộ điều khiển chế độ xem gốc.
  3. Tạo một thực thể của GMSAutocompleteViewController và chỉ định bộ điều khiển chế độ xem gốc làm thuộc tính uỷ quyền.
  4. Tạo GMSPlaceField để xác định các loại dữ liệu địa điểm cần trả về.
  5. Thêm GMSAutocompleteFilter để ràng buộc truy vấn đến một loại địa điểm cụ thể.
  6. Trình bày GMSAutocompleteViewController bằng [self presentViewController...].
  7. Xử lý lựa chọn của người dùng trong phương thức uỷ quyền didAutocompleteWithPlace.
  8. Loại bỏ bộ điều khiển trong phương thức uỷ quyền didAutocompleteWithPlace, didFailAutocompleteWithErrorwasCancelled.

Ví dụ sau đây minh hoạ một cách khả thi để chạy GMSAutocompleteViewController để phản hồi khi người dùng nhấn vào một nút.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

  override func viewDidLoad() {
    makeButton()
  }

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

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

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

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

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

}

extension ViewController: GMSAutocompleteViewControllerDelegate {

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

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

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

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

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

}

Objective-C

#import "ViewController.h"
@import GooglePlaces;

@interface ViewController () <GMSAutocompleteViewControllerDelegate>

@end

@implementation ViewController {
  GMSAutocompleteFilter *_filter;
}

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

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

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

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

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

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

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

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

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

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

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

@end

Thêm bộ kiểm soát kết quả

Sử dụng trình kiểm soát kết quả khi bạn muốn có nhiều quyền kiểm soát hơn đối với giao diện người dùng nhập văn bản. Trình kiểm soát kết quả tự động bật/tắt chế độ hiển thị của danh sách kết quả dựa trên tiêu điểm đầu vào trên giao diện người dùng.

Cách thêm trình kiểm soát kết quả vào ứng dụng:

  1. Tạo một GMSAutocompleteResultsViewController.
  2. Triển khai giao thức GMSAutocompleteResultsViewControllerDelegate trong bộ điều khiển chế độ xem gốc và chỉ định bộ điều khiển chế độ xem gốc làm thuộc tính uỷ quyền.
  3. Tạo một đối tượng UISearchController, truyền vào GMSAutocompleteResultsViewController làm đối số của trình kiểm soát kết quả.
  4. Đặt GMSAutocompleteResultsViewController làm thuộc tính searchResultsUpdater của UISearchController.
  5. Thêm searchBar cho UISearchController vào giao diện người dùng của ứng dụng.
  6. Xử lý lựa chọn của người dùng trong phương thức uỷ quyền didAutocompleteWithPlace.

Có một số cách để đặt thanh tìm kiếm của UISearchController vào giao diện người dùng của ứng dụng:

Thêm thanh tìm kiếm vào thanh điều hướng

Mã ví dụ sau đây minh hoạ cách thêm trình kiểm soát kết quả, thêm searchBar vào thanh điều hướng và xử lý lựa chọn của người dùng:

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

Thêm thanh tìm kiếm vào đầu chế độ xem

Ví dụ về mã sau đây cho thấy cách thêm searchBar vào đầu một thành phần hiển thị.

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

Theo mặc định, UISearchController ẩn thanh điều hướng khi trình bày (bạn có thể tắt tuỳ chọn này). Trong trường hợp thanh điều hướng hiển thị và mờ, UISearchController sẽ không đặt vị trí đúng cách.

Hãy sử dụng mã sau đây để khắc phục:

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;

Thêm thanh tìm kiếm bằng kết quả cửa sổ bật lên

Mã ví dụ sau đây cho thấy việc đặt một thanh tìm kiếm ở bên phải thanh điều hướng và hiển thị kết quả trong một cửa sổ bật lên.

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

Sử dụng nguồn dữ liệu bảng

Nếu ứng dụng của bạn có giao diện người dùng văn bản tìm kiếm tuỳ chỉnh, bạn có thể sử dụng lớp GMSAutocompleteTableDataSource để điều khiển chế độ xem theo bảng hiển thị kết quả trên bộ điều khiển chế độ xem.

Cách sử dụng GMSAutocompleteTableDataSource làm nguồn dữ liệu và uỷ quyền của UITableView trong trình kiểm soát chế độ xem:

  1. Triển khai giao thức GMSAutocompleteTableDataSourceDelegateUISearchBarDelegate trong bộ điều khiển chế độ xem.
  2. Tạo một thực thể GMSAutocompleteTableDataSource rồi chỉ định bộ kiểm soát chế độ xem làm thuộc tính uỷ quyền.
  3. Đặt GMSAutocompleteTableDataSource làm thuộc tính nguồn dữ liệu và thuộc tính uỷ quyền của thực thể UITableView trên bộ điều khiển chế độ xem.
  4. Trong trình xử lý để nhập văn bản tìm kiếm, hãy gọi sourceTextHasChanged trên GMSAutocompleteTableDataSource.
  5. Xử lý lựa chọn của người dùng trong phương thức uỷ quyền didAutocompleteWithPlace.
  6. Loại bỏ bộ điều khiển trong phương thức uỷ quyền didAutocompleteWithPlace, didFailAutocompleteWithError, wasCancelled.

Mã ví dụ sau đây minh hoạ cách sử dụng lớp GMSAutocompleteTableDataSource để thúc đẩy chế độ xem theo bảng của UIViewController khi UISearchBar được thêm riêng.

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

      

Tuỳ chỉnh màu văn bản và màu nền

Bạn có thể đặt màu của tất cả văn bản và nền trong tuỳ chọn điều khiển giao diện người dùng tự động hoàn thành để tiện ích này phù hợp hơn với giao diện hình ảnh của ứng dụng. Có hai cách để thiết lập màu điều khiển giao diện người dùng:

  • Sử dụng giao thức UIAppearance của iOS để điều khiển giao diện người dùng theo kiểu toàn cục nếu có thể. Các chế độ cài đặt này áp dụng cho nhiều, nhưng không phải tất cả, thành phần điều khiển giao diện người dùng.
  • Bằng cách sử dụng các phương thức SDK trên các lớp tiện ích để đặt các thuộc tính không được giao thức UIAppearance hỗ trợ.

Thông thường, ứng dụng sẽ sử dụng một số kết hợp giữa giao thức UIAppearance và các phương thức SDK. Sơ đồ sau đây cho thấy các phần tử có thể được tạo kiểu:

Màu điều khiển giao diện người dùng tự động hoàn thành

Bảng sau đây liệt kê tất cả các thành phần trên giao diện người dùng và cho biết cách tạo kiểu cho từng thành phần (giao thức UIAppearance hoặc phương thức SDK).

Phần tử trên giao diện người dùng Phương thức Hướng dẫn định phong cách
Phủ màu của Thanh điều hướng (nền) Giao thức UIAppearance Gọi setBarTintColor trên proxy UINavigationBar.
Màu phủ của Thanh điều hướng (dấu nháy văn bản của thanh tìm kiếm và nút Huỷ) Giao thức UIAppearance Gọi setTintColor trên proxy UINavigationBar.
Màu văn bản trên Thanh tìm kiếm Giao thức UIAppearance Đặt NSForegroundColorAttributeName trong searchBarTextAttributes.
Màu phủ cho thanh tìm kiếm Không áp dụng Thanh tìm kiếm trong suốt và sẽ hiển thị dưới dạng phiên bản được tô bóng của Thanh điều hướng.
Màu văn bản phần giữ chỗ của thanh tìm kiếm (văn bản tìm kiếm mặc định) Giao thức UIAppearance Đặt NSForegroundColorAttributeName trong placeholderAttributes.
Văn bản chính (cũng được áp dụng cho nội dung lỗi và nội dung thông báo) Phương thức SDK Gọi cho primaryTextColor.
Làm nổi bật văn bản chính Phương thức SDK Gọi cho primaryTextHighlightColor.
Văn bản phụ Phương thức SDK Gọi cho secondaryTextColor.
Lỗi và nội dung thông báo Phương thức SDK Gọi cho primaryTextColor.
Nền ô trong bảng Phương thức SDK Gọi cho tableCellBackgroundColor.
Màu dòng phân cách ô trong bảng Phương thức SDK Gọi cho tableCellSeparatorColor.
Nút "Thử lại" Phương thức SDK Gọi cho tintColor.
Chỉ báo hoạt động (vòng quay tiến trình) Giao thức UIAppearance Gọi setColor trên proxy UIActivityIndicatorView.
Biểu trưng "Do Google cung cấp", Hình ảnh đám mây buồn Không áp dụng Phiên bản màu trắng hoặc xám được chọn tự động dựa trên độ tương phản của nền.
Kính lúp và các biểu tượng văn bản rõ ràng trong trường văn bản của Thanh tìm kiếm Không áp dụng Để tạo kiểu, hãy thay thế hình ảnh mặc định bằng hình ảnh có màu mong muốn.

Sử dụng giao thức UIAppearance

Bạn có thể sử dụng giao thức UIAppearance để lấy proxy giao diện cho một thành phần trên giao diện người dùng nhất định. Sau đó, bạn có thể sử dụng proxy này để đặt màu cho thành phần trên giao diện người dùng. Khi sửa đổi, mọi bản sao của một thành phần trên giao diện người dùng nhất định đều sẽ bị ảnh hưởng. Ví dụ: trong ví dụ sau đây, trên toàn cục sẽ thay đổi màu văn bản của các lớp UITextField thành màu xanh lục khi các lớp đó nằm trong UISearchBar:

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

Để biết thêm thông tin về cách xác định giá trị màu, hãy tham khảo Tài liệu tham khảo về lớp UIColor.

Các đoạn mã sau đây cho thấy tất cả lệnh proxy bạn cần sử dụng để định kiểu cho mọi thứ trong thành phần điều khiển giao diện người dùng tự động hoàn thành toàn màn hình. Thêm mã này vào phương thức didFinishLaunchingWithOptions trong AppDelegate.m:

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

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

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

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

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

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

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

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

Đặt thuộc tính kiểu điều khiển giao diện người dùng

Một tập hợp con các thành phần điều khiển trên giao diện người dùng có các thuộc tính không chịu ảnh hưởng của giao thức UIAppearance, do đó phải được thiết lập trực tiếp. Mã ví dụ sau đây cho thấy cách xác định màu nền trước và màu nền sau, đồng thời áp dụng các màu đó cho thực thể kiểm soát giao diện người dùng có tên là acController. Thêm mã này vào phương thức onLaunchClicked trong ViewController.m:

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

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

Nhận các gợi ý địa điểm bằng cách lập trình

Bạn có thể tạo giao diện người dùng tìm kiếm tuỳ chỉnh để thay thế cho giao diện người dùng do tiện ích tự động hoàn tất cung cấp. Để làm việc này, ứng dụng của bạn phải nhận thông tin dự đoán địa điểm theo phương thức lập trình. Ứng dụng của bạn có thể nhận được danh sách tên và/hoặc địa chỉ địa điểm được dự đoán theo một trong những cách sau:

Đang gọi cho GMSPlacesClient findAutocompletePredictionsFromQuery:

Để nhận danh sách tên địa điểm và/hoặc địa chỉ dự đoán, trước tiên, hãy tạo thực thể GMSPlaceClient, sau đó gọi phương thức GMSPlacesClient findAutocompletePredictionsFromQuery: với các tham số sau:

  • Một chuỗi autocompleteQuery chứa văn bản do người dùng nhập.
  • GMSAutocompleteSessionToken, dùng để xác định từng phiên riêng lẻ. Ứng dụng của bạn nên truyền cùng một mã thông báo cho mỗi lệnh gọi yêu cầu tự động hoàn thành, sau đó truyền mã thông báo đó (cùng với Mã địa điểm) trong lệnh gọi tiếp theo đến fetchPlacefromPlaceID: để truy xuất Thông tin chi tiết về địa điểm cho địa điểm mà người dùng đã chọn.
  • GMSAutocompleteFilter để:
    • Thiên vị hoặc giới hạn kết quả ở một khu vực cụ thể.
    • Giới hạn kết quả cho một loại địa điểm cụ thể.
    • Đối tượng GMSPlaceLocationBias/Restriction tạo xu hướng kết quả đến một khu vực cụ thể được chỉ định bởi các giới hạn vĩ độ và kinh độ.
  • Phương pháp gọi lại để xử lý các dự đoán được trả về.

Các mã ví dụ bên dưới minh hoạ lệnh gọi đến 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 gọi phương thức gọi lại đã chỉ định, truyền vào một mảng các đối tượng GMSAutocompletePrediction.

Mỗi đối tượng GMSAutocompletePrediction chứa các thông tin sau:

  • attributedFullText – Văn bản đầy đủ của dự đoán, dưới dạng NSAttributedString. Ví dụ: "Nhà hát Opera Sydney, Sydney, New South Wales, Úc". Mọi dải ô văn bản khớp với thông tin mà người dùng nhập đều có một thuộc tính kGMSAutocompleteMatchAttribute. Bạn có thể dùng thuộc tính này để làm nổi bật văn bản trùng khớp trong cụm từ tìm kiếm của người dùng, chẳng hạn như dưới đây.
  • placeID – Mã địa điểm của địa điểm được dự đoán. Mã địa điểm là giá trị nhận dạng văn bản xác định duy nhất một địa điểm. Để biết thêm thông tin về mã địa điểm, hãy xem bài viết Tổng quan về mã địa điểm.
  • distanceMeters – Khoảng cách theo đường thẳng từ origin được chỉ định đến đích đến. Nếu bạn không đặt thuộc tính origin thì sẽ không có giá trị khoảng cách nào được trả về.

Ví dụ về mã sau đây minh hoạ cách làm nổi bật văn bản in đậm những phần của kết quả khớp với văn bản trong truy vấn của người dùng, bằng cách sử dụng 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;
    

Sử dụng trình tìm nạp

Nếu muốn tạo chế độ kiểm soát tính năng tự động hoàn thành của riêng mình từ đầu, bạn có thể sử dụng GMSAutocompleteFetcher để gói phương thức autocompleteQuery trên GMSPlacesClient. Trình tìm nạp điều tiết các yêu cầu, chỉ trả về kết quả cho văn bản tìm kiếm được nhập gần đây nhất. Lớp này không cung cấp thành phần trên giao diện người dùng.

Để triển khai GMSAutocompleteFetcher, hãy thực hiện các bước sau:

  1. Triển khai giao thức GMSAutocompleteFetcherDelegate.
  2. Tạo một đối tượng GMSAutocompleteFetcher.
  3. Gọi sourceTextHasChanged trên trình tìm nạp khi người dùng nhập.
  4. Xử lý thông tin dự đoán và lỗi bằng phương thức giao thức didAutcompleteWithPredictionsdidFailAutocompleteWithError.

Ví dụ về mã sau đây minh hoạ cách sử dụng trình tìm nạp để lấy thông tin do người dùng nhập và hiển thị các địa điểm trùng khớp trong thành phần hiển thị văn bản. Chức năng chọn một địa điểm đã bị bỏ qua. FetcherSampleViewController bắt nguồn từ UIViewController trong FinderSampleViewController.h.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

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

  override func viewDidLoad() {
    super.viewDidLoad()

    view.backgroundColor = .white
    edgesForExtendedLayout = []

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

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

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

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

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

    textField?.attributedPlaceholder = placeholder

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

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

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

}

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

    resultText?.text = resultsStr as String
  }

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

Objective-C

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

@interface FetcherSampleViewController () <GMSAutocompleteFetcherDelegate>

@end

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

- (void)viewDidLoad {
  [super viewDidLoad];

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

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

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

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

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

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

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

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

@end

Mã thông báo phiên

Mã thông báo phiên sẽ nhóm các giai đoạn truy vấn và lựa chọn của hoạt động tìm kiếm tự động hoàn thành của người dùng thành một phiên riêng biệt cho mục đích thanh toán. Phiên hoạt động bắt đầu khi người dùng bắt đầu nhập cụm từ tìm kiếm và kết thúc khi họ chọn một địa điểm. Mỗi phiên có thể có nhiều truy vấn, theo sau là một lựa chọn vị trí. Sau khi một phiên kết thúc, mã thông báo này không còn hợp lệ nữa. Ứng dụng của bạn phải tạo một mã thông báo mới cho mỗi phiên. Bạn nên sử dụng mã phiên cho tất cả các phiên tự động hoàn thành có lập trình (khi bạn sử dụng trình điều khiển toàn màn hình hoặc trình điều khiển kết quả, API sẽ tự động xử lý việc này).

SDK Địa điểm dành cho iOS sử dụng GMSAutocompleteSessionToken để xác định từng phiên. Ứng dụng của bạn phải truyền mã thông báo phiên mới khi bắt đầu mỗi phiên mới, sau đó truyền mã thông báo đó cùng với Mã địa điểm trong lệnh gọi tiếp theo đến fetchPlacefromPlaceID: để truy xuất Thông tin chi tiết về địa điểm cho địa điểm mà người dùng đã chọn.

Tìm hiểu thêm về mã phiên.

Hãy sử dụng mã sau để tạo mã thông báo phiên mới:

let token: GMSAutocompleteSessionToken = GMSAutocompleteSessionToken.init()

Hạn mức sử dụng

Hiển thị các thuộc tính trong ứng dụng của bạn

  • Nếu ứng dụng của bạn dùng dịch vụ tự động hoàn thành theo phương thức lập trình, thì giao diện người dùng của bạn phải cho thấy thuộc tính "Do Google cung cấp" hoặc xuất hiện trong một bản đồ có thương hiệu Google.
  • Nếu ứng dụng của bạn sử dụng chế độ điều khiển giao diện người dùng tự động hoàn thành, thì bạn không cần làm gì thêm (thuộc tính bắt buộc sẽ hiển thị theo mặc định).
  • Nếu truy xuất và hiển thị thêm thông tin về địa điểm sau khi nhận địa điểm theo mã nhận dạng, bạn cũng phải hiển thị thông tin ghi nhận sự đóng góp của bên thứ ba.

Để biết thêm thông tin chi tiết, vui lòng xem tài liệu về mô hình phân bổ.

Kiểm soát chỉ báo hoạt động mạng

Để kiểm soát chỉ báo hoạt động mạng trên thanh trạng thái của ứng dụng, bạn phải triển khai các phương thức uỷ quyền không bắt buộc thích hợp cho lớp tự động hoàn thành mà bạn đang sử dụng, đồng thời tự bật và tắt chỉ báo mạng.

  • Đối với GMSAutocompleteViewController, bạn phải triển khai các phương thức uỷ quyền didRequestAutocompletePredictions:didUpdateAutocompletePredictions:.
  • Đối với GMSAutocompleteResultsViewController, bạn phải triển khai các phương thức uỷ quyền didRequestAutocompletePredictionsForResultsController:didUpdateAutocompletePredictionsForResultsController:.
  • Đối với GMSAutocompleteTableDataSource, bạn phải triển khai các phương thức uỷ quyền didRequestAutocompletePredictionsForTableDataSource:didUpdateAutocompletePredictionsForTableDataSource:.

Bằng cách triển khai các phương thức này và đặt [UIApplication sharedApplication].networkActivityIndicatorVisible thành YESNO tương ứng, thanh trạng thái sẽ khớp chính xác với giao diện người dùng tự động hoàn thành.

Ràng buộc kết quả tự động hoàn thành

Bạn có thể đặt chế độ điều khiển tính năng tự động hoàn thành trên giao diện người dùng để ràng buộc kết quả ở một khu vực địa lý cụ thể và/hoặc lọc kết quả theo một hoặc nhiều loại địa điểm hoặc theo một hoặc nhiều quốc gia cụ thể. Để ràng buộc kết quả, bạn có thể làm như sau:

  • Để ưu tiên (ưu tiên) kết quả trong khu vực đã xác định, hãy đặt locationBias trên GMSAutocompleteFilter (một số kết quả từ bên ngoài khu vực xác định vẫn có thể được trả về). Nếu bạn cũng đặt locationRestriction, locationBias sẽ bị bỏ qua.
  • Để chỉ hiển thị (hạn chế) kết quả trong vùng xác định, hãy đặt locationRestriction trên GMSAutocompleteFilter (chỉ kết quả trong vùng xác định mới được trả về).

    • Lưu ý: Quy định hạn chế này chỉ áp dụng cho toàn bộ tuyến đường. Kết quả tổng hợp nằm bên ngoài ranh giới hình chữ nhật có thể được trả về dựa trên một tuyến đường trùng lặp với giới hạn về vị trí.
  • Để chỉ trả về các kết quả phù hợp với một loại địa điểm cụ thể, hãy đặt types trên GMSAutocompleteFilter, (ví dụ: chỉ định TypeFilter.ADDRESS sẽ khiến tiện ích chỉ trả về các kết quả có địa chỉ chính xác).

  • Để chỉ trả về kết quả trong tối đa 5 quốc gia đã chỉ định, hãy đặt countries trên GMSAutocompleteFilter.

Chênh lệch kết quả đối với một khu vực cụ thể

Để ưu tiên (độc giả) kết quả trong khu vực xác định, hãy đặt locationBias trên GMSAutocompleteFilter như minh hoạ dưới đây:

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

Hạn chế kết quả ở một khu vực cụ thể

Để chỉ hiển thị (hạn chế) kết quả trong khu vực xác định, hãy đặt locationRestriction trên GMSAutocompleteFilter như minh hoạ dưới đây:

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

Lọc kết quả theo quốc gia

Để lọc kết quả trong tối đa 5 quốc gia được chỉ định, hãy đặt countries trên GMSAutocompleteFilter như minh hoạ dưới đây:

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

Lọc kết quả theo loại địa điểm hoặc bộ sưu tập loại

Hạn chế kết quả để thuộc một loại hoặc bộ sưu tập kiểu nhất định bằng cách đặt thuộc tính types của GMSAutoCompleteFilter. Sử dụng thuộc tính này để chỉ định các bộ lọc được liệt kê trong Bảng 1, 2 và 3 trên Loại địa điểm. Nếu không chỉ định giá trị nào, thì tất cả các loại sẽ được trả về.

Để chỉ định một kiểu hoặc bộ lọc tập hợp kiểu:

  • Sử dụng thuộc tính types để chỉ định tối đa 5 giá trị loại từ Bảng 1 và Bảng 2 như trên Loại địa điểm. Giá trị loại được xác định bằng các hằng số trong GMSPlaceType.

  • Sử dụng thuộc tính types để chỉ định một tập hợp loại từ Bảng 3 được hiển thị trên Loại địa điểm. Giá trị tập hợp kiểu được xác định bằng các hằng số trong GMSPlaceType.

    Chỉ được dùng một loại duy nhất trong Bảng 3 trong yêu cầu. Nếu chỉ định giá trị từ Bảng 3, thì bạn không thể chỉ định giá trị từ Bảng 1 hoặc Bảng 2. Nếu bạn làm như vậy, thì sẽ có lỗi xảy ra.

Ví dụ: để chỉ trả về các kết quả phù hợp với một loại địa điểm cụ thể, hãy đặt types trên GMSAutocompleteFilter. Ví dụ sau đây cho thấy việc thiết lập bộ lọc để chỉ trả về kết quả có địa chỉ chính xác:

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

Tối ưu hoá tính năng Tự động hoàn thành địa điểm

Phần này mô tả các phương pháp hay nhất để giúp bạn khai thác tối đa dịch vụ Tự động hoàn thành của địa điểm.

Dưới đây là một số nguyên tắc chung:

  • Cách nhanh nhất để phát triển một giao diện người dùng hoạt động hiệu quả là sử dụng tiện ích Tự động hoàn thành của API JavaScript Maps, Tiện ích Tự động hoàn thành của SDK Địa điểm dành cho Android hoặc SDK Địa điểm dành cho Kiểm soát giao diện người dùng Tự động hoàn thành dành cho iOS
  • Nâng cao sự hiểu biết về các trường dữ liệu thiết yếu của tính năng Tự động hoàn thành địa điểm ngay từ đầu.
  • Các trường xu hướng vị trí và giới hạn vị trí là không bắt buộc nhưng có thể có tác động đáng kể đến hiệu suất của tính năng tự động hoàn thành.
  • Xử lý lỗi để đảm bảo ứng dụng của bạn sẽ xuống cấp nhẹ nếu API trả về lỗi.
  • Hãy đảm bảo ứng dụng của bạn xử lý khi không có lựa chọn và cung cấp cho người dùng cách tiếp tục.

Các phương pháp hay nhất để tối ưu hoá chi phí

Tối ưu hoá chi phí cơ bản

Để tối ưu hoá chi phí sử dụng dịch vụ Tự động hoàn thành địa điểm, hãy sử dụng mặt nạ trường trong tiện ích Thông tin chi tiết về địa điểm và tiện ích Tự động hoàn thành địa điểm để chỉ trả về các trường dữ liệu địa điểm mà bạn cần.

Tối ưu hoá chi phí nâng cao

Hãy cân nhắc việc triển khai tính năng Tự động hoàn thành địa điểm theo phương thức lập trình để truy cập vào tính năng Mức giá theo yêu cầu và yêu cầu kết quả API mã hóa địa lý về địa điểm đã chọn thay vì Thông tin chi tiết về địa điểm. Đặt giá theo mỗi yêu cầu được kết hợp với API mã hóa địa lý sẽ tiết kiệm chi phí hơn so với đặt giá Theo mỗi phiên (dựa trên phiên) nếu đáp ứng cả hai điều kiện sau:

  • Nếu bạn chỉ cần vĩ độ/kinh độ hoặc địa chỉ của địa điểm người dùng đã chọn, API mã hoá địa lý sẽ cung cấp thông tin này cho ít hơn một cuộc gọi Chi tiết địa điểm.
  • Nếu người dùng chọn một cụm từ gợi ý tự động hoàn thành trong khoảng trung bình 4 yêu cầu cụm từ gợi ý Tự động hoàn thành trở xuống, thì tính năng đặt giá theo Mỗi yêu cầu có thể tiết kiệm chi phí hơn so với đặt giá theo mỗi phiên.
Để được hỗ trợ lựa chọn cách triển khai tính năng Tự động hoàn thành theo địa điểm phù hợp với nhu cầu của bạn, hãy chọn thẻ tương ứng với câu trả lời của bạn cho câu hỏi sau.

Ứng dụng của bạn có yêu cầu thông tin nào khác ngoài địa chỉ và vĩ độ/kinh độ của thông tin dự đoán đã chọn không?

Có, cần thêm thông tin

Sử dụng tính năng Tự động hoàn thành địa điểm dựa trên phiên với Thông tin chi tiết về địa điểm.
Vì ứng dụng của bạn yêu cầu Thông tin chi tiết về địa điểm như tên địa điểm, trạng thái doanh nghiệp hoặc giờ mở cửa, nên việc triển khai tính năng Tự động hoàn thành về địa điểm phải sử dụng mã phiên (theo chương trình hoặc tích hợp trong tiện ích JavaScript, Android hoặc iOS) với tổng chi phí là 0,017 đô la mỗi phiên cộng với SKU dữ liệu địa điểm áp dụng tuỳ thuộc vào trường dữ liệu địa điểm mà bạn yêu cầu

Triển khai tiện ích
Tính năng quản lý phiên được tự động tích hợp vào các tiện ích JavaScript, Android hoặc iOS. Dữ liệu này bao gồm cả yêu cầu Tự động hoàn thành về địa điểm và yêu cầu Chi tiết địa điểm đối với cụm từ gợi ý đã chọn. Nhớ chỉ định tham số fields để đảm bảo rằng bạn chỉ yêu cầu các trường dữ liệu vị trí mà bạn cần.

Triển khai có lập trình
Sử dụng mã thông báo của phiên với các yêu cầu Tự động hoàn thành địa điểm của bạn. Khi yêu cầu Thông tin chi tiết về địa điểm cho cụm từ gợi ý đã chọn, hãy cung cấp các thông số sau:

  1. Mã địa điểm từ phản hồi Tự động hoàn thành địa điểm
  2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành địa điểm
  3. Tham số fields chỉ định các trường dữ liệu địa điểm mà bạn cần

Không, chỉ cần địa chỉ và vị trí

API mã hoá địa lý có thể là một lựa chọn tiết kiệm chi phí hơn so với Thông tin chi tiết về địa điểm cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất sử dụng tính năng Tự động hoàn thành địa điểm của bạn. Hiệu quả của tính năng Tự động hoàn thành của mỗi ứng dụng sẽ khác nhau tuỳ thuộc vào nội dung mà người dùng đang nhập, nơi ứng dụng đang được sử dụng và việc liệu các phương pháp hay nhất về tối ưu hoá hiệu suất đã được triển khai hay chưa.

Để trả lời câu hỏi sau, hãy phân tích số lượng ký tự mà người dùng nhập trung bình trước khi chọn một dự đoán Tự động hoàn thành địa điểm trong ứng dụng của bạn.

Trung bình, người dùng của bạn có chọn một cụm từ gợi ý Tự động hoàn thành địa điểm trong tối đa 4 yêu cầu không?

Triển khai tính năng Tự động hoàn thành địa điểm theo phương thức lập trình mà không cần mã phiên và gọi API Mã hoá địa lý trên thông tin dự đoán địa điểm đã chọn.
API mã hoá địa lý cung cấp địa chỉ và vĩ độ/kinh độ với giá 0,005 USD cho mỗi yêu cầu. Việc thực hiện bốn yêu cầu Tự động hoàn thành địa điểm – Mỗi yêu cầu có chi phí là 0,01132 đô la Mỹ, do đó, tổng chi phí của 4 yêu cầu cộng với lệnh gọi API mã hoá địa lý về thông tin dự đoán địa điểm đã chọn sẽ là 0,01632 đô la, thấp hơn giá của tính năng Tự động hoàn thành cho mỗi phiên là 0,017 đô la Mỹ/phiên.1

Hãy cân nhắc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ muốn chỉ bằng ít ký tự hơn nữa.

Không

Sử dụng tính năng Tự động hoàn thành địa điểm dựa trên phiên với Thông tin chi tiết về địa điểm.
Vì số lượng yêu cầu trung bình mà bạn muốn thực hiện trước khi người dùng chọn dự đoán Tự động hoàn thành địa điểm vượt quá chi phí định giá mỗi phiên, nên việc triển khai tính năng Tự động hoàn thành địa điểm của bạn phải sử dụng mã phiên cho cả yêu cầu Tự động hoàn thành địa điểm và yêu cầu Chi tiết địa điểm được liên kết với tổng chi phí là 0,017 USD mỗi phiên.1

Triển khai tiện ích
Tính năng quản lý phiên được tự động tích hợp vào các tiện ích JavaScript, Android hoặc iOS. Dữ liệu này bao gồm cả yêu cầu Tự động hoàn thành về địa điểm và yêu cầu Chi tiết địa điểm đối với cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu các trường Dữ liệu cơ bản.

Triển khai có lập trình
Sử dụng mã thông báo của phiên với các yêu cầu Tự động hoàn thành địa điểm của bạn. Khi yêu cầu Thông tin chi tiết về địa điểm cho cụm từ gợi ý đã chọn, hãy cung cấp các thông số sau:

  1. Mã địa điểm từ phản hồi Tự động hoàn thành địa điểm
  2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành địa điểm
  3. Tham số fields chỉ định các trường Dữ liệu cơ bản, chẳng hạn như địa chỉ và hình học

Cân nhắc việc trì hoãn các yêu cầu Tự động hoàn thành của địa điểm
Bạn có thể sử dụng các chiến lược như trì hoãn yêu cầu Tự động hoàn thành của địa điểm cho đến khi người dùng nhập ba hoặc bốn ký tự đầu tiên để ứng dụng của bạn đưa ra ít yêu cầu hơn. Ví dụ: việc thực hiện yêu cầu Tự động hoàn thành địa điểm cho từng ký tự sau khi người dùng nhập ký tự thứ ba có nghĩa là nếu người dùng nhập 7 ký tự rồi chọn một dự đoán mà bạn thực hiện một yêu cầu API mã hóa địa lý, thì tổng chi phí sẽ là 0,01632 đô la (4 * 0,00283 đô la Mỹ cho mỗi yêu cầu + 0,005 đô la Mã hóa địa lý).1

Nếu việc trì hoãn các yêu cầu có thể khiến yêu cầu có lập trình trung bình của bạn dưới 4, bạn có thể làm theo hướng dẫn triển khai Tự động hoàn thành địa điểm thực hiện bằng API mã hóa địa lý. Xin lưu ý rằng người dùng có thể xem các yêu cầu trì hoãn là độ trễ, vì người dùng này có thể sẽ thấy các cụm từ gợi ý mỗi khi nhấn phím mới.

Hãy cân nhắc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm trong ít ký tự hơn.


  1. Chi phí liệt kê tại đây được tính theo USD. Vui lòng tham khảo trang Thanh toán trên Nền tảng Google Maps để biết thông tin đầy đủ về giá cả.

Các phương pháp hay nhất về hiệu suất

Các nguyên tắc sau đây mô tả các cách tối ưu hóa hiệu suất của tính năng Tự động hoàn thành theo địa điểm:

  • Thêm các hạn chế theo quốc gia, xu hướng vị trí và lựa chọn ưu tiên về ngôn ngữ (đối với các phương thức triển khai có lập trình) vào phương thức triển khai tính năng Tự động hoàn thành theo địa điểm. Không cần thiết lập lựa chọn ưu tiên về ngôn ngữ cho các tiện ích vì chúng chọn lựa chọn ưu tiên về ngôn ngữ trên trình duyệt hoặc thiết bị di động của người dùng.
  • Nếu tính năng Tự động hoàn thành địa điểm đi kèm với một bản đồ, bạn có thể thiên vị vị trí theo khung nhìn bản đồ.
  • Trong trường hợp người dùng không chọn một trong các cụm từ gợi ý Tự động hoàn thành, thường là do không có cụm từ gợi ý nào trong số đó là địa chỉ kết quả mong muốn, thì bạn có thể sử dụng lại thông tin mà người dùng nhập ban đầu để tìm cách nhận được kết quả phù hợp hơn:
    • Nếu bạn muốn người dùng chỉ nhập thông tin địa chỉ, hãy sử dụng lại thông tin đầu vào ban đầu của người dùng trong lệnh gọi đến API mã hoá địa lý.
    • Nếu bạn muốn người dùng nhập cụm từ tìm kiếm cho một địa điểm cụ thể theo tên hoặc địa chỉ, hãy sử dụng yêu cầu Tìm địa điểm. Nếu kết quả chỉ được mong đợi ở một khu vực cụ thể, hãy sử dụng tính năng thiên về vị trí.
    Có một số trường hợp khác mà bạn nên quay lại sử dụng API Mã hoá địa lý:
    • Người dùng nhập địa chỉ cơ sở phụ ở những quốc gia chưa hỗ trợ tính năng Tự động hoàn thành cho địa điểm, ví dụ: Cộng hoà Séc, Estonia và Lithuania. Ví dụ: địa chỉ bằng tiếng Séc "StroupeAccessnického 3191/17, Praha" sẽ đưa ra thông tin dự đoán một phần trong tính năng Tự động hoàn thành địa điểm.
    • Người dùng nhập địa chỉ có tiền tố phân đoạn đường bộ như "23-30 29th St, Queens" ở Thành phố New York hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawai'i.

Khắc phục sự cố

Mặc dù có nhiều loại lỗi có thể xảy ra, nhưng phần lớn lỗi mà ứng dụng có thể gặp phải thường là do lỗi cấu hình (ví dụ: sử dụng khoá API không chính xác hoặc khoá API được định cấu hình không chính xác) hoặc lỗi hạn mức (ứng dụng của bạn đã vượt quá hạn mức). Bạn có thể xem phần Giới hạn sử dụng để biết thêm thông tin về hạn mức.

Các lỗi xảy ra khi sử dụng các chế độ điều khiển tự động hoàn thành được trả về trong phương thức didFailAutocompleteWithError() của nhiều giao thức uỷ quyền. Thuộc tính code của đối tượng NSError đã cung cấp được đặt thành một trong các giá trị của giá trị liệt kê GMSPlacesErrorCode.