تعمل خدمة الإكمال التلقائي في حزمة تطوير برامج الأماكن لنظام التشغيل iOS على عرض تنبؤات المكان استجابةً لطلبات بحث المستخدم. أثناء كتابة المستخدم، تعرض خدمة الإكمال التلقائي اقتراحات لأماكن مثل الأنشطة التجارية والعناوين ورموز الجمع ونقاط الاهتمام.
يمكنك إضافة ميزة الإكمال التلقائي إلى تطبيقك بالطرق التالية:
- يمكنك إضافة عنصر تحكم الإكمال التلقائي لواجهة المستخدم لتوفير وقت التطوير وضمان تجربة مستخدم متسقة.
- الحصول على توقعات حول الأماكن آليًا لإنشاء تجربة مستخدم مخصّصة
إضافة عنصر تحكّم في واجهة المستخدم للإكمال التلقائي
عنصر التحكم في واجهة المستخدم للإكمال التلقائي هو مربع حوار بحث مع وظيفة الإكمال التلقائي المضمنة. عندما يُدخل مستخدم عبارات بحث، يعرض عنصر التحكّم
قائمة بالأماكن المتوقّعة للاختيار من بينها. عندما يختار المستخدم الاختيار،
يتم عرض مثيل GMSPlace
الذي يمكن لتطبيقك استخدامه بعد ذلك في الحصول على تفاصيل
عن المكان المحدّد.
يمكنك إضافة عنصر تحكّم في واجهة مستخدم الإكمال التلقائي إلى تطبيقك بالطرق التالية:
إضافة عنصر تحكّم بملء الشاشة
استخدِم عنصر التحكّم في وضع ملء الشاشة عندما تريد الحصول على سياق مشروط، حيث تحلّ واجهة مستخدم الإكمال التلقائي محلّ واجهة المستخدم الخاصة بتطبيقك مؤقتًا إلى أن يختار المستخدم الاختيار. تتوفر هذه الوظيفة من خلال فئة
GMSAutocompleteViewController
. عندما يختار المستخدِم مكانًا، يتلقّى تطبيقك معاودة الاتصال.
لإضافة عنصر تحكّم بملء الشاشة إلى تطبيقك:
- أنشِئ عنصر واجهة مستخدم في تطبيقك الرئيسي لتفعيل عنصر تحكّم ميزة "الإكمال التلقائي" لواجهة المستخدم،
على سبيل المثال، معالج لمس على
UIButton
. - نفِّذ بروتوكول
GMSAutocompleteViewControllerDelegate
في وحدة التحكّم في طريقة العرض الرئيسية - يمكنك إنشاء مثيل
GMSAutocompleteViewController
وتخصيص وحدة التحكّم في الملف الشخصي الرئيسية باعتبارها الموقع المفوَّض. - أنشئ
GMSPlaceField
لتحديد أنواع بيانات الأماكن المطلوب عرضها. - أضِف
GMSAutocompleteFilter
لحصر طلب البحث على نوع مكان معيّن. - قدِّم عرض
GMSAutocompleteViewController
باستخدام[self presentViewController...]
. - يمكنك معالجة اختيار المستخدم من خلال
طريقة التفويض "
didAutocompleteWithPlace
". - إغلاق وحدة التحكّم في طرق التفويض
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: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
إضافة وحدة تحكّم بالنتائج
استخدِم وحدة التحكّم في النتائج عندما تريد المزيد من التحكّم في واجهة مستخدم إدخال النص. تعمل وحدة التحكم في النتائج على تبديل مستوى رؤية قائمة النتائج ديناميكيًا بناءً على تركيز واجهة المستخدم للإدخال.
لإضافة وحدة تحكّم بالنتائج إلى تطبيقك:
- أنشِئ
GMSAutocompleteResultsViewController
. - يمكنك تنفيذ بروتوكول
GMSAutocompleteResultsViewControllerDelegate
في وحدة التحكّم في الملف الشخصي الرئيسية وتخصيص وحدة التحكّم في الملف الشخصي الرئيسي كسمة التفويض. - يمكنك إنشاء كائن
UISearchController
مع إدخالGMSAutocompleteResultsViewController
كوسيطة وحدة التحكم في النتائج. - اضبط
GMSAutocompleteResultsViewController
على أنّها السمةsearchResultsUpdater
فيUISearchController
. - إضافة
searchBar
لواجهة المستخدمUISearchController
إلى واجهة المستخدم الخاصة بتطبيقك. - يمكنك معالجة اختيار المستخدم من خلال
طريقة التفويض "
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; }
إضافة شريط بحث إلى أعلى طريقة عرض
يوضّح مثال الرمز التالي إضافة 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;
إضافة شريط بحث باستخدام النتائج المنبثقة
يوضح مثال الرمز التالي وضع شريط بحث على الجانب الأيمن من شريط التنقّل وعرض النتائج في نافذة منبثقة.
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; }
استخدام مصدر بيانات جدول
إذا كان تطبيقك يحتوي على واجهة مستخدم مخصّصة لنص البحث، يمكنك استخدام الفئة
GMSAutocompleteTableDataSource
لتوجيه العرض في جدول من خلال عرض النتائج في وحدة التحكّم في طرق العرض.
لاستخدام GMSAutocompleteTableDataSource
كمصدر البيانات وتفويض UITableView
في وحدة التحكم في الملفات الشخصية:
- نفِّذ بروتوكولَي
GMSAutocompleteTableDataSourceDelegate
وUISearchBarDelegate
في وحدة التحكّم في طريقة العرض. - يمكنك إنشاء مثيل
GMSAutocompleteTableDataSource
وتخصيص وحدة التحكّم في الملف الشخصي باعتبارها الموقع المفوَّض. - اضبط
GMSAutocompleteTableDataSource
كمصدر البيانات وتفويض الخصائص للمثيلUITableView
في وحدة التحكّم في الملف الشخصي. - في معالج إدخال نص البحث، استدعِ
sourceTextHasChanged
علىGMSAutocompleteTableDataSource
. - يمكنك معالجة اختيار المستخدم من خلال طريقة التفويض في "
didAutocompleteWithPlace
". - إغلاق وحدة التحكّم في طرق التفويض
didAutocompleteWithPlace
وdidFailAutocompleteWithError
وwasCancelled
يوضِّح مثال الرمز التالي استخدام الفئة GMSAutocompleteTableDataSource
لتوفير عرض الجدول UIViewController
عند إضافة UISearchBar
بشكلٍ منفصل.
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
تخصيص ألوان النص والخلفية
يمكنك ضبط ألوان كل النصوص والخلفيات في عنصر تحكّم واجهة مستخدم الإكمال التلقائي، وذلك من أجل تطابُق الأداة مع المظهر المرئي لتطبيقك. هناك طريقتان لضبط ألوان عنصر التحكم في واجهة المستخدم:
- باستخدام بروتوكول واجهة المستخدم الأصلي لنظام التشغيل iOS، كلما أمكن ذلك، نمط عناصر تحكّم في واجهة المستخدم تنطبق هذه الإعدادات على العديد من عناصر التحكّم في واجهة المستخدم، وليس كلّها.
- باستخدام طرق حزمة تطوير البرامج (SDK) في فئات الأدوات لضبط الخصائص غير المتوافقة مع بروتوكول واجهة المستخدم المظهر
سيستخدم تطبيقك عادةً مجموعة من بروتوكول واجهة المستخدم وطرق حزمة تطوير البرامج (SDK). ويوضح المخطّط التالي العناصر التي يمكن تصميمها:
يسرد الجدول التالي جميع عناصر واجهة المستخدم، ويشير إلى كيفية تنسيق كل عنصر (بروتوكول واجهة المستخدم أو طريقة حزمة تطوير البرامج (SDK)).
عنصر في واجهة المستخدم | الطريقة | إرشادات متعلّقة بالموضة |
---|---|---|
درجات لون شريط التنقل (الخلفية) | بروتوكول واجهة المستخدم | يمكنك الاتصال بـ setBarTintColor على الخادم الوكيل UINavigationBar . |
لون تلوين شريط التنقل (علامة إقحام نص شريط البحث وزر الإلغاء) | بروتوكول واجهة المستخدم | يمكنك الاتصال بـ setTintColor على الخادم الوكيل UINavigationBar . |
لون نص شريط البحث | بروتوكول واجهة المستخدم | ضبط NSForegroundColorAttributeName في searchBarTextAttributes |
لون شريط البحث | لا ينطبق | شريط البحث شبه شفاف، وسيتم عرضه كنسخة مظلّلة من شريط التنقل. |
لون نص العنصر النائب لشريط البحث (نص البحث التلقائي) | بروتوكول واجهة المستخدم | ضبط NSForegroundColorAttributeName في placeholderAttributes |
النص الأساسي (يُطبَّق أيضًا على نص الخطأ والرسالة) | طريقة حزمة تطوير البرامج (SDK) | تواصل هاتفيًا مع "primaryTextColor ". |
تمييز النص الأساسي | طريقة حزمة تطوير البرامج (SDK) | تواصل هاتفيًا مع "primaryTextHighlightColor ". |
نص ثانوي | طريقة حزمة تطوير البرامج (SDK) | تواصل هاتفيًا مع "secondaryTextColor ". |
نص الرسالة والخطأ | طريقة حزمة تطوير البرامج (SDK) | تواصل هاتفيًا مع "primaryTextColor ". |
خلفية خلية الجدول | طريقة حزمة تطوير البرامج (SDK) | تواصل هاتفيًا مع "tableCellBackgroundColor ". |
لون فاصل الخلايا في الجدول | طريقة حزمة تطوير البرامج (SDK) | تواصل هاتفيًا مع "tableCellSeparatorColor ". |
زر "إعادة المحاولة" | طريقة حزمة تطوير البرامج (SDK) | تواصل هاتفيًا مع "tintColor ". |
مؤشر النشاط (مؤشر التقدم) | بروتوكول واجهة المستخدم | يمكنك الاتصال بـ setColor على الخادم الوكيل UIActivityIndicatorView . |
شعار "مُشغَّل بواسطة Google"، صورة سحابة إلكترونية حزينة | لا ينطبق | ويتم تحديد النسخة البيضاء أو الرمادية تلقائيًا بناءً على تباين الخلفية. |
رمز العدسة المكبّرة ورموز النص الواضح في حقل النص في "شريط البحث" | لا ينطبق | لاختيار النمط، استبدِل الصور التلقائية بصور باللون الذي تريده. |
استخدام بروتوكول UIالمظهر
يمكنك استخدام بروتوكول واجهة المستخدم للحصول على الخادم الوكيل للمظهر لعنصر واجهة مستخدم معيّن، والذي يمكنك استخدامه بعد ذلك لضبط لون عنصر واجهة المستخدم. عند إجراء تعديل، تتأثر جميع مثيلات
عنصر معين في واجهة المستخدم. على سبيل المثال، يعمل المثال التالي بشكل عام على تغيير لون نص فئات UITextField
إلى اللون الأخضر عندما تكون مضمَّنة في UISearchBar
:
[[UITextField appearanceWhenContainedIn:[UISearchBar class], nil] setDefaultTextAttributes:@{NSForegroundColorAttributeName:[UIColor greenColor]}];
لمزيد من المعلومات حول تحديد قيم الألوان، راجِع مرجع فئة UIColor.
تعرض مقتطفات الرمز التالية جميع أوامر الخادم الوكيل التي تحتاج إلى استخدامها لوضع نمط لكل العناصر في عنصر التحكُّم في واجهة المستخدم ضمن الإكمال التلقائي بملء الشاشة. أضِف هذا الرمز
إلى طريقة didFinishLaunchingWithOptions
في 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;
إعداد خصائص نمط عنصر التحكّم في واجهة المستخدم
هناك مجموعة فرعية من عناصر التحكم في واجهة المستخدم لها خصائص لا تتأثر ببروتوكول واجهة المستخدم، وبالتالي يجب ضبطها مباشرةً. يُظهر مثال الرمز التالي ألوان المقدّمة والخلفية، وتطبيقها على مثيل عنصر تحكّم في واجهة المستخدم يُسمى acController
. أضف هذا الرمز إلى طريقة onLaunchClicked
في 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;
الحصول على توقعات الأماكن آليًا
يمكنك إنشاء واجهة مستخدم مخصّصة للبحث بدلاً من واجهة المستخدم التي توفّرها أداة الإكمال التلقائي. لإجراء ذلك، يجب أن يحصل تطبيقك على توقّعات حول الأماكن آليًا. يمكن لتطبيقك الحصول على قائمة بأسماء الأماكن و/أو عناوينها المتوقّعة بإحدى الطرق التالية:
سيتم الاتصال بالرقم GMSPlacesClient findAutocompletePredictionsFromQuery:
للحصول على قائمة بأسماء و/أو عناوين الأماكن المتوقَّعة، عليك أولاً
إجراء GMSPlacesClient
ثم طلب الإجراء
GMSPlacesClient findAutocompletePredictionsFromQuery:
باستخدام المعلَمات التالية:
- سلسلة
autocompleteQuery
تحتوي على النص الذي كتبه المستخدم - علامة
GMSAutocompleteSessionToken
التي تُستخدم لتحديد كل جلسة على حدة يجب أن يمرر تطبيقك الرمز المميّز نفسه لكل استدعاء من طلبات الإكمال التلقائي، ثم يمرِّر هذا الرمز المميّز مع رقم تعريف المكان في الاستدعاء التالي إلىfetchPlacefromPlaceID:
لاسترداد "تفاصيل المكان" للمكان الذي اختاره المستخدم. GMSAutocompleteFilter
التي يتم إرسالها:- تحيز النتائج أو قصرها على منطقة محددة.
- حصر النتائج على نوع مكان معيّن.
- عنصر التقييد
GMSPlaceLocationBias
/الخاص بتحيز النتائج يؤدي إلى منطقة معينة يتم تحديدها بحدود خط العرض وخط الطول.
- طريقة لرد الاتصال للتعامل مع التوقعات المعروضة.
تعرض أمثلة الرموز أدناه مكالمة للرقم 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); } } }];
تستدعي واجهة برمجة التطبيقات طريقة معاودة الاتصال المحدّدة، ويتم تمرير مصفوفة من كائنات GMSAutocompletePrediction
.
يحتوي كل عنصر GMSAutocompletePrediction
على المعلومات التالية:
attributedFullText
– النص الكامل لعبارة البحث المقترحة، على شكلNSAttributedString
. على سبيل المثال، "دار أوبرا سيدني، سيدني، نيو ساوث ويلز، أستراليا". كل نطاق نصي يطابق إدخال المستخدم له سمةkGMSAutocompleteMatchAttribute
. يمكنك استخدام هذه السمة لإبراز النص المتطابق في استعلام المستخدم، على سبيل المثال، كما هو موضح أدناه.placeID
– معرّف المكان للمكان المتوقّع معرّف المكان هو معرّف نصي يحدّد المكان بشكل فريد. لمزيد من المعلومات عن أرقام تعريف الأماكن، يُرجى الاطّلاع على نظرة عامة على رقم تعريف المكان.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
،
الذي يلّفف طريقة autocompleteQuery
على GMSPlacesClient
.
يتحكّم الجلب في الطلبات، ولا يعرض سوى النتائج المتعلقة بأحدث نص بحث تم إدخاله. لا يوفر أي عناصر في واجهة المستخدم.
لتنفيذ GMSAutocompleteFetcher
،
اتّبِع الخطوات التالية:
- نفِّذ بروتوكول
GMSAutocompleteFetcherDelegate
. - أنشِئ عنصر
GMSAutocompleteFetcher
. - استدعِ "
sourceTextHasChanged
" في الجلب أثناء كتابة المستخدم. - تعامل مع التوقعات والأخطاء باستخدام طريقتي البروتوكول
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> #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
الرموز المميزة للجلسة
تعمل الرموز المميزة للجلسة على تجميع مرحلتي طلب البحث والاختيار في بحث الإكمال التلقائي للمستخدم في جلسة منفصلة لأغراض الفوترة. تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عندما يختار مكانًا. يمكن أن تحتوي كل جلسة على استعلامات متعددة، يتبعها اختيار مكان واحد. وبعد انتهاء الجلسة، لا يبقى الرمز المميّز صالحًا، ويجب أن ينشئ تطبيقك رمزًا مميّزًا جديدًا لكل جلسة. ونقترح استخدام الرموز المميّزة للجلسة في جميع جلسات الإكمال التلقائي الآلية (عند استخدام وحدة التحكّم بملء الشاشة، أو وحدة التحكّم في النتائج، ستتولى واجهة برمجة التطبيقات إجراء ذلك تلقائيًا).
تستخدم حزمة تطوير برامج الأماكن لأجهزة iOS GMSAutocompleteSessionToken
لتحديد كل جلسة. يجب أن يمرر تطبيقك رمزًا مميزًا للجلسة الجديدة عند بدء كل جلسة جديدة، ثم يمرر هذا الرمز المميز نفسه، مع رقم تعريف المكان، في الاستدعاء التالي إلى fetchPlacefromPlaceID:
لاسترداد تفاصيل المكان للمكان الذي حدده المستخدم.
مزيد من المعلومات عن الرموز المميّزة للجلسة
استخدم الرمز التالي لإنشاء رمز مميز جديد للجلسة:
let token: GMSAutocompleteSessionToken = GMSAutocompleteSessionToken.init()
حدود الاستخدام
- يخضع استخدام الطريقة
GMSPlacesClient findAutocompletePredictionsFromQuery
لحدود طلبات البحث المتدرجة. ويمكنك الاطّلاع على مستندات حدود الاستخدام.
عرض الإحالات في تطبيقك
- إذا كان تطبيقك يستخدم خدمة الإكمال التلقائي بشكل آلي، يجب أن تعرض واجهة المستخدم إما الإحالة "مُشغَّل بواسطة Google" أو أن تظهر ضمن خريطة تحمل علامة Google التجارية.
- إذا كان تطبيقك يستخدم عنصر تحكّم الإكمال التلقائي في واجهة المستخدم، ليس عليك اتّخاذ أي إجراء إضافي (يتم عرض معلومات تحديد المصدر المطلوبة تلقائيًا).
- في حال استرداد معلومات إضافية عن المكان وعرضها بعد الحصول على مكان من خلال رقم التعريف، يجب عرض معلومات الجهات الخارجية أيضًا.
للحصول على مزيد من التفاصيل، اطّلع على مستندات الإحالات.
التحكم في مؤشر نشاط الشبكة
للتحكم في مؤشر نشاط الشبكة في شريط حالة التطبيقات، يجب تنفيذ طرق التفويض الاختيارية المناسبة لفئة الإكمال التلقائي التي تستخدمها وتشغيل مؤشر الشبكة أو إيقافه بنفسك.
- بالنسبة إلى
GMSAutocompleteViewController
، عليك تنفيذ طريقتَي التفويضdidRequestAutocompletePredictions:
وdidUpdateAutocompletePredictions:
. - بالنسبة إلى
GMSAutocompleteResultsViewController
، عليك تنفيذ طريقتَي التفويضdidRequestAutocompletePredictionsForResultsController:
وdidUpdateAutocompletePredictionsForResultsController:
. - بالنسبة إلى
GMSAutocompleteTableDataSource
، عليك تنفيذ طريقتَي التفويضdidRequestAutocompletePredictionsForTableDataSource:
وdidUpdateAutocompletePredictionsForTableDataSource:
.
من خلال تنفيذ هاتين الطريقتين وضبط [UIApplication sharedApplication].networkActivityIndicatorVisible
على YES
وNO
على التوالي، سيتطابق شريط الحالة بشكل صحيح مع
واجهة مستخدم الإكمال التلقائي.
تقييد نتائج الإكمال التلقائي
ويمكنك ضبط عنصر تحكم واجهة المستخدم ضمن ميزة الإكمال التلقائي لحصر النتائج بمنطقة جغرافية معيّنة، و/أو فلترة النتائج لعرض نوع واحد أو أكثر من الأماكن، أو إلى بلد معيّن أو بلدان معيّنة. لتقييد النتائج، يمكنك إجراء ما يلي:
- لتفضيل (الانحياز) النتائج ضمن المنطقة المحددة، اضبط
locationBias
علىGMSAutocompleteFilter
(قد يستمر عرض بعض النتائج من خارج المنطقة المحددة). وفي حال ضبطlocationRestriction
أيضًا، سيتم تجاهلlocationBias
. لعرض (تقييد) النتائج ضمن المنطقة المحددة فقط، اضبط
locationRestriction
علىGMSAutocompleteFilter
(سيتم عرض النتائج ضمن المنطقة المحددة فقط).- ملاحظة: ينطبق هذا الشرط على مسارات بأكملها فقط، وقد يتم عرض النتائج الاصطناعية الموجودة خارج الحدود المستطيلة استنادًا إلى مسار يتداخل مع قيود الموقع الجغرافي.
لعرض النتائج التي تتوافق مع نوع مكان معيّن فقط، اضبط
types
علىGMSAutocompleteFilter
(على سبيل المثال، يؤدي تحديد TypeFilter.ADDRESS إلى عرض الأداة نتائج ذات عنوان دقيق فقط).لعرض النتائج التي تصل إلى خمسة بلدان محدّدة فقط، اضبط
countries
علىGMSAutocompleteFilter
.
نتائج التحيز إلى منطقة معينة
لتفضيل النتائج (الانحياز) ضمن المنطقة المحدّدة، اضبط locationBias
على GMSAutocompleteFilter
، كما هو موضّح هنا:
northEast = CLLocationCoordinate2DMake(39.0, -95.0);
southWest = CLLocationCoordinate2DMake(37.5, -100.0);
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);
حصر النتائج بمنطقة معيّنة
إذا أردت عرض النتائج (حصريًا) فقط ضمن المنطقة المحدّدة، اضبط
locationRestriction
على GMSAutocompleteFilter
، كما هو موضّح هنا:
northEast = CLLocationCoordinate2DMake(39.0, -95.0);
southWest = CLLocationCoordinate2DMake(37.5, -100.0);
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationRestriction = GMSPlaceRectangularLocationOption(northEast, southWest);
فلترة النتائج حسب البلد
لفلترة النتائج ضمن ما يصل إلى خمسة بلدان محدّدة، اضبط countries
على GMSAutocompleteFilter
كما هو موضّح هنا:
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"au", @"nz" ];
فلترة النتائج حسب نوع المكان أو مجموعة النوع
يمكنك حصر النتائج لتكون من نوع معيّن أو من نوع محدّد من خلال ضبط السمة
types
في السمة
GMSAutoCompleteFilter
.
استخدِم هذه السمة لتحديد الفلاتر المدرَجة في الجداول 1 و2 و3 في أنواع الأماكن. وإذا لم يتم تحديد أي قيمة، يتم عرض جميع الأنواع.
لتحديد فلتر النوع أو مجموعة الأنواع:
استخدِم السمة
types
لتحديد ما يصل إلى خمس قيم لـ type من الجدول 1 والجدول 2 المعروضة في أنواع الأماكن. يتم تحديد قيم النوع من خلال الثوابت فيGMSPlaceType
.استخدِم السمة
types
لتحديد مجموعة الأنواع من الجدول 3 الموضح في أنواع الأماكن. يتم تحديد قيم جمع الأنواع من خلال الثوابت فيGMSPlaceType
.يُسمح بنوع واحد فقط من الجدول 3 في الطلب. إذا حددت قيمة من الجدول 3، فلا يمكنك تحديد قيمة من الجدول 1 أو الجدول 2. إذا فعلت ذلك، فحدث خطأ.
على سبيل المثال، لعرض النتائج التي تتوافق مع نوع مكان معيّن فقط، اضبط
types
على GMSAutocompleteFilter
. يوضح المثال التالي إعداد الفلتر
لعرض النتائج ذات العنوان الدقيق فقط:
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ kGMSPlaceTypeAirport, kGMSPlaceTypeAmusementPark ];
تحسين الإكمال التلقائي لمكان
يوضّح هذا القسم أفضل الممارسات لمساعدتك في الاستفادة إلى أقصى حدّ من خدمة "الإكمال التلقائي" للأماكن.
وفي ما يلي بعض الإرشادات العامة:
- تتمثل أسرع طريقة لتطوير واجهة مستخدم تعمل في استخدام واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" أداة الإكمال التلقائي أو حزمة تطوير البرامج لتطبيق "الأماكن" على نظام التشغيل Android أداة الإكمال التلقائي أو حزمة تطوير البرامج لتطبيق "الأماكن" لنظام التشغيل iOS عناصر التحكّم في واجهة المستخدم للإكمال التلقائي.
- فهم حقول بيانات "الإكمال التلقائي" الأساسية لميزة "الإكمال التلقائي" من البداية
- حقلا انحياز الموقع الجغرافي وتقييد الموقع الجغرافي اختياريان ولكنهما يمكن أن يكون لهما تأثير كبير في أداء الإكمال التلقائي.
- يجب استخدام طريقة معالجة الأخطاء لضمان تراجع مستوى أداء تطبيقك في حال عرضت واجهة برمجة التطبيقات خطأً.
- يُرجى التأكّد من معالجة تطبيقك في حال عدم تحديد أي خيار وتوفير طريقة للمستخدمين للمتابعة.
أفضل الممارسات لتحسين التكلفة
تحسين التكلفة الأساسية
ولتحسين تكلفة استخدام خدمة "الإكمال التلقائي" لبيانات الأماكن، يمكنك استخدام أقنعة الحقول في أداتَي "تفاصيل المكان" و"الإكمال التلقائي" لعرض حقول بيانات المكان التي تحتاج إليها فقط.
التحسين المتقدم للتكلفة
يمكنك التنفيذ الآلي لميزة "الإكمال التلقائي" عن المكان للوصول إلى السعر لكل طلب وطلب نتائج واجهة برمجة التطبيقات للترميز الجغرافي حول المكان المحدّد بدلاً من تفاصيل المكان. إنّ التسعير حسب الطلب المقترن بواجهة برمجة التطبيقات للترميز الجغرافي يكون أكثر فعالية من حيث التكلفة من التسعير لكل جلسة (استنادًا إلى الجلسة) في حال استيفاء الشرطين التاليين:
- إذا كنت تحتاج فقط إلى خط العرض/خط الطول أو عنوان المكان الذي اختاره المستخدم، سترسل واجهة برمجة التطبيقات للترميز الجغرافي هذه المعلومات مقابل بيانات أقل عن الاتصال بتفاصيل المكان.
- إذا اختار المستخدمون عبارة بحث مقترحة من خلال ميزة "الإكمال التلقائي" في المتوسط أربعة طلبات لعبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي" أو أقل، قد يكون التسعير لكل طلب أكثر فعالية من حيث التكلفة مقارنةً بالتسعير لكل جلسة.
هل يتطلب طلبك أي معلومات أخرى غير العنوان وخط العرض/خط الطول لعبارة البحث المقترحة المحدّدة؟
نعم، بحاجة إلى مزيد من التفاصيل
استخدام ميزة "الإكمال التلقائي" المستنِدة إلى الجلسات في "تفاصيل المكان"
بما أنّ طلبك يتطلب توفّر "تفاصيل عن المكان"، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل، يجب أن تستخدم ميزة "الإكمال التلقائي" للمكان رمزًا مميزًا للجلسة (آليًا أو مضمَّنًا في أدوات JavaScript أو Android أو iOS) بتكلفة إجمالية تبلغ 0.017 دولار أمريكي (أو ما يعادله بالعملة المحلية) لكل جلسة بالإضافة إلى رموز التخزين التعريفية لبيانات الأماكن السارية بناءً علىحقول بيانات المكان التي تطلبها.
تنفيذ الأدوات
يتم دمج ميزة "إدارة الجلسات" تلقائيًا في أدوات JavaScript أو Android أو iOS. ويشمل هذا كلاً من طلبات الإكمال التلقائي الخاصة بالأماكن وطلب تفاصيل المكان في عبارة البحث المقترحة المحدّدة. تأكَّد من تحديد المَعلمة fields
للتأكّد من أنّك لا تطلب سوى حقول بيانات المكان التي تحتاجها فقط.
التنفيذ الآلي
استخدِم الرمز المميّز للجلسة مع طلبات الإكمال التلقائي لميزة "الأماكن". عند طلب تفاصيل المكان عن عبارة البحث المقترحة المحدّدة، أدرِج المَعلمات التالية:
- رقم تعريف المكان من رد الإكمال التلقائي حول المكان
- الرمز المميز للجلسة المستخدم في طلب الإكمال التلقائي لـ "مكان"
- المَعلمة
fields
التي تحدِّد حقول بيانات الأماكن التي تحتاجها
لا، يحتاج فقط إلى العنوان والموقع الجغرافي.
قد تكون واجهة برمجة تطبيقات الترميز الجغرافي خيارًا أكثر فعالية من حيث التكلفة من ميزة "تفاصيل المكان" لتطبيقك، وذلك بناءً على أداء استخدام ميزة "الإكمال التلقائي" لتطبيقك. تختلف كفاءة الإكمال التلقائي لكل تطبيق اعتمادًا على ما يدخله المستخدمون، ومكان استخدام التطبيق، وما إذا كان قد تم تنفيذ أفضل ممارسات تحسين الأداء أم لا.
للإجابة عن السؤال التالي، ننصحك بتحليل عدد الأحرف التي يكتبها المستخدم في المتوسط قبل تحديد أحد توقّعات ميزة "الإكمال التلقائي" في تطبيقك.
هل يختار المستخدمون في مؤسستك عبارة بحث مقترحة لميزة "الإكمال التلقائي" عن "المكان" في أربعة طلبات أو أقل في المتوسط؟
نعم
تنفيذ ميزة "الإكمال التلقائي" لميزة "الإكمال التلقائي" في المكان بشكل آلي بدون الرموز المميزة للجلسة وواجهة برمجة التطبيقات Geocoding API لطلب البحث عن المكان المحدّد
توفّر واجهة برمجة التطبيقات Geocoding API العناوين وإحداثيات خطوط الطول/العرض مقابل 0.005 دولار أمريكي لكل طلب. يكلّف إجراء أربعة طلبات من الإكمال التلقائي - حسب الطلب 0.01132 دولار أمريكي، لذا فإن التكلفة الإجمالية لأربعة طلبات بالإضافة إلى طلب بيانات واجهة برمجة التطبيقات للترميز الجغرافي بشأن توقّع المكان المحدّد سيكون 0.01632 دولار أمريكي، وهو ما يقل عن سعر الإكمال التلقائي لكل جلسة الذي يبلغ 0.017 دولار أمريكي لكل جلسة.1
يمكنك استخدام أفضل ممارسات الأداء لمساعدة المستخدمين في الحصول على التوقعات التي يبحثون عنها باستخدام عدد أقل من الأحرف.
لا
استخدام ميزة "الإكمال التلقائي" المستنِدة إلى الجلسات في "تفاصيل المكان"
بما أنّ متوسط عدد الطلبات التي تتوقّع إجراؤها قبل أن يختار المستخدم عبارة بحث مقترَحة عن ميزة "الإكمال التلقائي" الخاصة بالمكان تتجاوز تكلفة التسعير لكل جلسة، من المفترض أن تستخدم عملية تنفيذ ميزة "الإكمال التلقائي" الخاصة بالجلسة رمزًا مميّزًا للجلسة لكل من طلبات الإكمال التلقائي الخاصة بالأماكن وطلب تفاصيل المكان ذات الصلة، وذلك بتكلفة إجمالية تبلغ 0.017 دولار أمريكي لكل جلسة.1
تنفيذ الأدوات
يتم دمج ميزة "إدارة الجلسات" تلقائيًا في أدوات JavaScript أو Android أو iOS. ويشمل هذا كلاً من طلبات الإكمال التلقائي الخاصة بالأماكن وطلب تفاصيل المكان في عبارة البحث المقترحة المحدّدة. تأكَّد من تحديد المَعلمة fields
لضمان أنّك تطلب حقول البيانات الأساسية فقط.
التنفيذ الآلي
استخدِم الرمز المميّز للجلسة مع طلبات الإكمال التلقائي لميزة "الأماكن". عند طلب تفاصيل المكان عن عبارة البحث المقترحة المحدّدة، أدرِج المَعلمات التالية:
- رقم تعريف المكان من رد الإكمال التلقائي حول المكان
- الرمز المميز للجلسة المستخدم في طلب الإكمال التلقائي لـ "مكان"
- المعلمة
fields
التي تحدد حقول البيانات الأساسية مثل العنوان والهندسة
التفكير في تأخير طلبات الإكمال التلقائي لميزة "الأماكن"
يمكنك استخدام استراتيجيات مثل تأخير طلب "الإكمال التلقائي" الخاص بـ "المكان" إلى أن يكتب المستخدم أول ثلاثة أو أربعة أحرف لكي يتمكن تطبيقك من تقديم عدد أقل من الطلبات. على سبيل المثال، يعني تقديم طلبات "الإكمال التلقائي" لـ "مكان" لكل حرف بعد كتابة المستخدم الحرف الثالث أنه إذا كتب المستخدم سبعة أحرف ثم اختار توقعًا أجريت له طلبًا واحدًا من واجهة برمجة التطبيقات للترميز الجغرافي، ستكون التكلفة الإجمالية 0.01632 دولار أمريكي (4 * 0.00283 إكمال تلقائي لكل طلب + 0.005 دولار أمريكي ترميز جغرافي).1
إذا كان تأخير الطلبات إلى وصول متوسط طلباتك الآلية إلى أقل من أربعة، يمكنك اتّباع الإرشادات الخاصة بتنفيذ الإكمال التلقائي لميزة "الإكمال التلقائي" عن المكان باستخدام واجهة برمجة التطبيقات Geocoding API. تجدر الإشارة إلى أنّ الطلبات المتأخرة قد تنظر إلى وقت استجابة المستخدم الذي قد يتوقّع ظهور توقعات مع كل ضغطة مفتاح جديدة.
يمكنك استخدام أفضل ممارسات الأداء لمساعدة المستخدمين في الحصول على التوقعات التي يبحثون عنها باستخدام عدد أقل من الأحرف.
-
التكاليف الواردة هنا بالدولار الأمريكي. يُرجى الرجوع إلى صفحة الفوترة في "منصة خرائط Google" للحصول على معلومات السعر الكاملة.
أفضل الممارسات المتعلقة بالأداء
توضّح الإرشادات التالية طرق تحسين أداء الإكمال التلقائي للأماكن:
- أضِف القيود المفروضة على البلدان وانحياز الموقع الجغرافي والإعدادات المفضّلة للغة (في عمليات التنفيذ الآلية) إلى تنفيذ ميزة "الإكمال التلقائي" في ميزة "الإكمال التلقائي". ولا حاجة إلى إعداد اللغة المفضّلة في التطبيقات المصغّرة لأنّها تختار الإعدادات المفضّلة للغة من متصفّح المستخدم أو جهازه الجوّال.
- إذا كان الإكمال التلقائي لـ "مكان" مصحوبًا بخريطة، يمكنك انحياز الموقع بواسطة إطار عرض الخريطة.
- في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي"، وبوجه عام
بسبب عدم ظهور أي من هذه عبارات البحث المقترحة بعنوان النتيجة المطلوب، يمكنك إعادة استخدام البيانات التي أدخلها المستخدم
الأصلية لمحاولة الحصول على نتائج أكثر صلة باهتماماتك:
- إذا كنت تتوقّع من المستخدم إدخال معلومات العنوان فقط، أعِد استخدام البيانات الأصلية التي أدخلها المستخدم في طلب واجهة برمجة التطبيقات للترميز الجغرافي.
- إذا كنت تتوقّع من المستخدم إدخال طلبات بحث عن مكان معيّن حسب الاسم أو العنوان، استخدِم طلب البحث عن مكان. إذا كانت النتائج متوقّعة في منطقة معيّنة فقط، استخدِم انحياز الموقع الجغرافي.
- المستخدمون الذين يُدخِلون عناوين المباني الفرعية في البلدان التي لا تتوفّر فيها ميزة "الإكمال التلقائي" لعناوين المباني الفرعية، مثل التشيك وإستونيا وليتوانيا. على سبيل المثال، يؤدي العنوان التشيكي "Stroupezznického 3191/17, Praha" إلى العثور على توقّع جزئي في ميزة "الإكمال التلقائي" في ميزة "الإكمال التلقائي".
- المستخدمون الذين يُدخلون عناوين باستخدام بادئات قطاعات الطرق، مثل " 23-30 29th St, Queens" في مدينة نيويورك أو " 47-380 Kamehameha Hwy, Kaneohe" على جزيرة كاواي في هاواي.
تحديد المشاكل وحلّها
على الرغم من إمكانية حدوث مجموعة كبيرة ومتنوعة من الأخطاء، إلا أنّ معظم الأخطاء التي راجع الحدود القصوى للاستخدام للحصول على مزيد من المعلومات حول الحصص.
يتم عرض الأخطاء التي تحدث عند استخدام عناصر التحكّم في ميزة "الإكمال التلقائي" في طريقة
didFailAutocompleteWithError()
ضمن بروتوكولات التفويض المختلفة. تم ضبط السمة code
لكائن NSError
المقدّم على إحدى قيم التعداد GMSPlacesErrorCode
.