SearchTextField
概览
SearchTextField 是UITextField的子类,用Swift编写,简化了显示自动补全建议列表的能力。
您可以选择在字段获得焦点时或用户开始输入时显示列表。
您还可以检测用户何时停止输入,这在您可从远程服务器获取建议列表时非常有用。
新功能!现在您可以使用“内联”建议,将在第一个匹配项显示为占位符(而不是结果列表)并在用户按回车键时选择它。
需求
- iOS 9
安装
SearchTextField可通过CocoaPods获取。要安装它,只需将以下行添加到您的Podfile中。
use_frameworks!
pod "SearchTextField"
手动安装
只需将SearchTextField.swift导入到您的项目中。
用法
您可以用最简单的方式使用它...
import SearchTextField
// Connect your IBOutlet...
@IBOutlet weak var mySearchTextField: SearchTextField!
// ...or create it manually
let mySearchTextField = SearchTextField(frame: CGRectMake(10, 100, 200, 40))
// Set the array of strings you want to suggest
mySearchTextField.filterStrings(["Red", "Blue", "Yellow"])
或者您可以根据需要自定义它
// Show also a subtitle and an image for each suggestion:
let item1 = SearchTextFieldItem(title: "Blue", subtitle: "Color", image: UIImage(named: "icon_blue"))
let item2 = SearchTextFieldItem(title: "Red", subtitle: "Color", image: UIImage(named: "icon_red"))
let item3 = SearchTextFieldItem(title: "Yellow", subtitle: "Color", image: UIImage(named: "icon_yellow"))
mySearchTextField.filterItems([item1, item2, item3])
// Set a visual theme (SearchTextFieldTheme). By default it's the light theme
mySearchTextField.theme = SearchTextFieldTheme.darkTheme()
// Modify current theme properties
mySearchTextField.theme.font = UIFont.systemFontOfSize(12)
mySearchTextField.theme.bgColor = UIColor (red: 0.9, green: 0.9, blue: 0.9, alpha: 0.3)
mySearchTextField.theme.borderColor = UIColor (red: 0.9, green: 0.9, blue: 0.9, alpha: 1)
mySearchTextField.theme.separatorColor = UIColor (red: 0.9, green: 0.9, blue: 0.9, alpha: 0.5)
mySearchTextField.theme.cellHeight = 50
// Set specific comparision options - Default: .caseInsensitive
mySearchTextField.comparisonOptions = [.caseInsensitive]
// Set the max number of results. By default it's not limited
mySearchTextField.maxNumberOfResults = 5
// You can also limit the max height of the results list
mySearchTextField.maxResultsListHeight = 200
// Customize the way it highlights the search string. By default it bolds the string
mySearchTextField.highlightAttributes = [NSBackgroundColorAttributeName: UIColor.yellowColor(), NSFontAttributeName:UIFont.boldSystemFontOfSize(12)]
// Handle what happens when the user picks an item. By default the title is set to the text field
mySearchTextField.itemSelectionHandler = {item, itemPosition in
mySearchTextField.text = item.title
}
// You can force the results list to support RTL languages - Default: false
mySearchTextField.forceRightToLeft = true
// Show the list of results as soon as the user makes focus - Default: false
mySearchTextField.startVisible = true
// ...or show the list of results even without user's interaction as soon as created - Default: false
mySearchTextField.startVisibleWithoutInteraction = true
// Start filtering after an specific number of characters - Default: 0
mySearchTextField.minCharactersNumberToStartFiltering = 3
// Force to show the results list without filtering (but highlighting)
mySearchTextField.forceNoFiltering = true
// Explicitly hide the results list
mySearchTextField.hideResultsList()
/**
* Update data source when the user stops typing.
* It's useful when you want to retrieve results from a remote server while typing
* (but only when the user stops doing it)
**/
mySearchTextField.userStoppedTypingHandler = {
if let criteria = self.mySearchTextField.text {
if criteria.characters.count > 1 {
// Show the loading indicator
self.mySearchTextField.showLoadingIndicator()
self.searchMoreItemsInBackground(criteria) { results in
// Set new items to filter
self.mySearchTextField.filterItems(results)
// Hide loading indicator
self.mySearchTextField.stopLoadingIndicator()
}
}
}
}
// Handle item selection - Default behaviour: item title set to the text field
mySearchTextField.itemSelectionHandler = { filteredResults, itemPosition in
// Just in case you need the item position
let item = filteredResults[itemPosition]
print("Item at position \(itemPosition): \(item.title)")
// Do whatever you want with the picked item
self.mySearchTextField.text = item.title
}
// Define a results list header - Default: nothing
let header = UILabel(frame: CGRect(x: 0, y: 0, width: acronymTextField.frame.width, height: 30))
header.backgroundColor = UIColor.lightGray.withAlphaComponent(0.3)
header.textAlignment = .center
header.font = UIFont.systemFont(ofSize: 14)
header.text = "Pick your option"
mySearchTextField.resultsListHeader = header
新功能:以占位符形式显示第一个匹配结果(行内模式)
// Set the array of strings you want to suggest
mySearchTextField.filterStrings(["Red", "Blue", "Yellow"])
// Then set the inline mode in true
mySearchTextField.inlineMode = true
新功能:从列表中自动完成,例如电子邮件域名列表
emailInlineTextField.inlineMode = true
emailInlineTextField.startFilteringAfter = "@"
emailInlineTextField.startSuggestingInmediately = true
emailInlineTextField.filterStrings(["gmail.com", "yahoo.com", "yahoo.com.ar"])
Swift 版本
从 1.2.3 版本开始支持 Swift 5。
从 1.2.0 版本开始支持 Swift 4。
如果您需要支持 Swift 2.3,请安装 v1.0.0。
如果您想支持 Swift 3,请安装 v1.0.2 及以上版本。
示例
查看示例项目。
作者
Alejandro Pasccon,[email protected]
许可协议
SearchTextField 适用于 MIT 许可协议。请参阅 LICENSE 文件以获取更多信息。