UITextField
UITextField 表示一个单行输入框。用户点它,系统键盘从屏幕底部弹出,输入的文字显示在框里。App 从 text 读出框里的内容,从 selectedRange 读出光标的位置和选中的范围,通过事件得知内容变了、光标动了、输入开始和结束了、用户按了回车。
输入框只有一行,按回车不会换行。多行输入用 UITextView。
新建的输入框没有边框、没有内容、没有占位文字,放到页面上看不出哪里可以点。边框用 borderStyle 设。输入框没有内建的长度限制、格式校验和只读模式:keyboardType 只决定弹出哪种键盘,不校验内容;要在修改发生之前拦下它,监听 beforeinput。
键盘弹出时盖在页面上面,页面的大小和位置不变。让内容避开键盘用视图的 keyboardLayoutGuide,它是一个 UIKeyboardLayoutGuide。
输入框是控件:禁用和 focus、input、return、blur 这些事件来自 UIControl。控件又是视图:位置、大小、底色来自 UIView。
继承关系:EventTarget → NSObject → UIResponder → UIView → UIControl → UITextField
怎么做一个能用的输入框、怎么收起键盘、怎么不被键盘挡住、怎么做表单,见指南做一个输入框。
构造函数
创建一个输入框。没有边框,没有内容,大小是 0。
实例属性
还继承 UIControl 和 UIView 的属性。输入框常用的继承属性是 isEnabled、isFirstResponder、tintColor、keyboardLayoutGuide。
内容:
| 属性 | 说明 |
|---|---|
text | 框里的内容 |
placeholder | 没有内容时显示的提示 |
attributedText | 带样式的内容 |
attributedPlaceholder | 带样式的提示 |
isEditing 只读 | 是否正在输入 |
hasText 只读 | 是否有内容 |
clearsOnBeginEditing | 每次开始输入时是否清空原有内容 |
clearsOnInsertion | 插入文字时是否换掉全部内容 |
allowsEditingTextAttributes | 是否允许用户改文字的样式 |
选区:
| 属性 | 说明 |
|---|---|
selectedRange | 选中的范围,或者光标的位置 |
markedTextRange 只读 | 输入法正在组字的那一段,没在组字时是 null |
键盘:
| 属性 | 说明 |
|---|---|
keyboardType | 弹出哪种键盘 |
returnKeyType | 回车键上显示什么字 |
keyboardAppearance | 键盘的明暗 |
enablesReturnKeyAutomatically | 没有内容时回车键是否变灰 |
inputAccessoryView | 键盘弹出时贴在键盘上面的视图 |
inputView | 代替系统键盘弹出的视图 |
allowsNumberPadPopover | 是否允许用数字键盘的浮层 |
输入行为:
| 属性 | 说明 |
|---|---|
isSecureTextEntry | 把内容显示成圆点,用于密码 |
autocapitalizationType | 自动大写的规则 |
autocorrectionType | 是否自动纠错 |
spellCheckingType | 是否检查拼写 |
textContentType | 框里装的是什么内容,系统据此自动填充 |
smartQuotesType | 是否把直引号换成弯引号 |
smartDashesType | 是否把连续的短横线换成破折号 |
smartInsertDeleteType | 粘贴和删除时是否自动调整空格 |
inlinePredictionType | 是否在光标后面显示预测的文字 |
mathExpressionCompletionType | 是否自动算出算式的结果 |
writingToolsBehavior | 写作工具能做到哪一步 |
allowedWritingToolsResultOptions | 写作工具可以写回哪几种内容 |
外观:
| 属性 | 说明 |
|---|---|
borderStyle | 边框的样子 |
clearButtonMode | 右侧的清除按钮什么时候显示 |
textAlignment | 文字的水平对齐 |
font | 文字的字体和字号 |
textColor | 文字的颜色 |
adjustsFontSizeToFitWidth | 内容比框宽时是否缩小字号 |
minimumFontSize | 缩小字号时最小到多少 |
background | 背景图 |
disabledBackground | 禁用时的背景图 |
leftView | 框里左端的视图 |
leftViewMode | 左端的视图什么时候显示 |
rightView | 框里右端的视图 |
rightViewMode | 右端的视图什么时候显示 |
实例方法
还继承 UIControl 和 UIView 的方法。输入框常用的继承方法是 becomeFirstResponder()、resignFirstResponder()、addEventListener(),见焦点。
改内容:
| 方法 | 说明 |
|---|---|
insertText() | 按用户打字的方式在光标处插入文字 |
deleteBackward() | 按用户按删除键的方式删除 |
算各部分的位置。这几个方法返回输入框按给定的范围摆放某一部分时用的矩形:
| 方法 | 说明 |
|---|---|
borderRectForBounds() | 边框的矩形 |
textRectForBounds() | 显示文字的矩形 |
placeholderRectForBounds() | 显示提示的矩形 |
editingRectForBounds() | 正在输入时文字的矩形 |
clearButtonRectForBounds() | 清除按钮的矩形 |
leftViewRectForBounds() | 左端视图的矩形 |
rightViewRectForBounds() | 右端视图的矩形 |
事件
用 addEventListener() 监听。输入框的事件有三组:控件事件告诉 App 发生了什么,selectionchange 告诉 App 光标或选区动了,可取消的事件在事情发生之前问 App 要不要。
控件事件继承自 UIControl,输入框用到的是这四个:
| 事件 | 什么时候派发 |
|---|---|
focus | 输入框成为 first responder,开始输入 |
input | 用户的输入让内容变了一次 |
return | 用户按了回车键 |
blur | 输入框不再是 first responder,结束输入 |
输入框自己的事件:
| 事件 | 什么时候派发 |
|---|---|
selectionchange | 选区或光标的位置变了 |
beforefocus | 即将开始输入。可以取消 |
beforeblur | 即将结束输入。可以取消 |
beforeinput | 用户的输入即将改变内容。可以取消 |
beforeclear | 用户点了清除按钮,即将清空。可以取消 |
beforereturn | 用户按了回车键,即将按默认方式处理。可以取消 |
系统派发的是 UIControl 列出的 16 个控件事件、traitchange、selectionchange 和五个可取消的事件。监听别的名字不会报错:它被当成自定义事件,只有自己用 dispatchEvent() 派发时才会触发,见事件名的限制。
焦点
first responder 是 iOS 里「当前接收键盘输入的那个对象」,也就是焦点所在的对象。同一时刻最多只有一个。键盘跟着 first responder 走:输入框成为 first responder 时键盘弹出,它不再是 first responder 时键盘收起。没有单独「显示键盘」「隐藏键盘」的方法。
| 想做的事 | 写法 |
|---|---|
| 让输入框聚焦 | field.becomeFirstResponder() |
| 让输入框失焦 | field.resignFirstResponder(),或者 page.view.endEditing(true) |
| 判断输入框是否聚焦 | field.isFirstResponder |
| 得知输入框聚焦了、失焦了 | focus、blur 事件 |
这几个成员定义在 UIResponder 和 UIView 上,所有视图都有:
becomeFirstResponder()返回布尔。true表示已经成为 first responder;false表示系统拒绝了,什么都没有发生,键盘不弹出。resignFirstResponder()返回布尔。true表示已经不是 first responder。对象本来就不是 first responder 时的返回值未在模拟器验证。isFirstResponder只读。新建的输入框是false。canBecomeFirstResponder只读。输入框是true,普通的UIView是false。这两个值未在模拟器验证。endEditing(true)让一棵视图树里正在输入的那个输入框失焦,不需要知道是哪一个。
becomeFirstResponder() 在不同情况下的结果:
| 情况 | 结果 | 依据 |
|---|---|---|
| 页面已经显示,没有切换在进行 | 返回 true,随后派发 focus | 实测 |
| 输入框已经是 first responder | 返回 true | 验收用例依赖这一点反复调用,没有单独的断言 |
| 页面正在切换(模态页面弹出或关闭的动画期间) | 返回 false | 实测 |
在 sceneconnect 的回调里,页面还没显示出来 | 返回 true,isEditing 是 true,但不派发 focus | 实测 |
| 输入框还没加到页面上 | 返回 false | 未在模拟器验证 |
另外两件事:
- 用户点输入框时,聚焦发生在手指按下的那一刻,不等手指抬起(实测)。
- 点别处不会自动失焦。 输入框保持 first responder,键盘留在屏幕上,直到有代码让它失焦,或者用户点了另一个输入框。未在模拟器验证。
一次输入派发哪些事件
| 用户的操作 | 派发 |
|---|---|
| 点输入框 | focus。实测在手指按下的那一刻 |
| 打三个字 | input 三次。未在模拟器验证 |
| 按回车 | return。未在模拟器验证 |
| 键盘收起 | blur |
可取消的事件排在对应的控件事件前面:实测聚焦一次的顺序是 beforefocus → focus。
return 和 blur 谁先谁后未在模拟器验证。用代码调 becomeFirstResponder() 和 endEditing() 时同样派发 focus 和 blur,这一点在验收用例里验证过。
控件事件的规则:
- 事件对象的
type是事件名,target是这个输入框。事件对象不带输入的内容,不带按了哪个键,也不带触点位置。内容从field.text读。 - 不能取消,
preventDefault()不起作用。要阻止某件事发生,用可取消的事件。 - 回调不是在事件发生的那一刻同步执行,而是稍后执行,见回调的执行时机。回调里读到的
field.text是执行时的内容;用户打字很快时,一次回调里读到的内容可能已经包含了后面几次按键。未在模拟器验证。 - 用代码改
text不派发input,这个事件只在用户的输入改变内容时派发。未在模拟器验证。 - 「用户输入完了」用
blur。没有「内容确认修改」这样单独的事件。 - 使用中文拼音这类输入法时,用户还没选字的拼音字母算在
text里,拼音每变一次都派发input。回调里读markedTextRange:不是null就是用户还没选字。这两条是用代码模拟输入法组字验证的,未用真实的输入法验证。 - 回调里抛出异常不影响输入框,同一事件的其他回调照常执行。异常在
application上派发error;没有监听器取消时,控制台输出以Uncaught开头的日志。
选区和光标
选区是输入框里选中的那一段文字。没有选中文字时,选区是一个长度为 0 的位置,也就是光标。selectedRange 用一个 NSRange 表示它:location 是起点,length 是长度,单位是 UTF-16 码元,和 JS 字符串的下标相同,所以 field.text.slice(location, location + length) 就是选中的文字。
输入框任何时候都有选区,没有在输入时也读得到、写得进去(实测)。没有在输入时屏幕上不显示光标和选中的底色。
表情和一部分汉字占两个码元。把光标放在这两个码元中间不会抛错,也不会被纠正:内容是 'a😀b' 时写 (2, 0),读回来还是 (2, 0)(实测)。多行输入上实测在这样的位置插入文字会把这个字符拆成两半。自己算位置时要避开。
大小
输入框是视图,定位方式和其他视图一样,见 Auto Layout。所有尺寸的单位都是点(pt)。
- 用约束时,高度可以不给,宽度要自己给。 输入框按字体算出自己的高度。宽度不给时,它按内容算宽度,内容是空的就很窄,并且会随着输入变宽。所以要约束左右两边,或者给一个固定宽度。未在模拟器验证。
- 用
frame时,宽高都要自己给。 不给的话宽高是 0,屏幕上什么都没有。
示例
输入名字
从空白 App 开始,在屏幕上方放一个输入框。用户每打一个字,下面的文字跟着变。按回车收起键盘。
application.addEventListener('sceneconnect', (e) => {
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
const field = new UITextField();
field.placeholder = '输入你的名字';
field.borderStyle = 'roundedRect';
field.returnKeyType = 'done';
const greeting = new UILabel();
greeting.text = '你好';
field.addEventListener('input', () => {
greeting.text = field.text === '' ? '你好' : `你好,${field.text}`;
});
field.addEventListener('return', () => {
field.resignFirstResponder();
console.log('输入的是:' + field.text);
});
field.translatesAutoresizingMaskIntoConstraints = false;
greeting.translatesAutoresizingMaskIntoConstraints = false;
page.view.addSubview(field);
page.view.addSubview(greeting);
const safe = page.view.safeAreaLayoutGuide;
NSLayoutConstraint.activateConstraints([
field.topAnchor.constraintEqualToAnchor(safe.topAnchor, { constant: 24 }),
field.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 16 }),
field.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor, { constant: -16 }),
greeting.topAnchor.constraintEqualToAnchor(field.bottomAnchor, { constant: 16 }),
greeting.leadingAnchor.constraintEqualToAnchor(field.leadingAnchor),
]);
});效果
- 屏幕上方出现一个圆角边框的输入框,里面是灰色的「输入你的名字」。下面一行字是「你好」。
- 点输入框,键盘从屏幕底部弹出,框里出现光标。
- 每打一个字,下面那行字变成「你好,」加上框里的内容。内容删光后变回「你好」。
- 按键盘右下角的回车键,键盘收起,控制台输出
输入的是:加上框里的内容。
这段代码没有作为一个整体在模拟器运行过。其中用到的每个 API 都在验收用例里运行过。外观(边框、占位文字的颜色、回车键上的字)和「每打一个字派发一次 input」未在模拟器验证。
注意:模拟器连着电脑的硬件键盘时,屏幕上的软键盘不弹出。这是模拟器的行为。要看到软键盘,在模拟器菜单里关掉硬件键盘连接。
密码框
const secret = new UITextField();
secret.placeholder = '密码';
secret.borderStyle = 'roundedRect';
secret.textContentType = 'password';
secret.isSecureTextEntry = true;
secret.returnKeyType = 'done';效果:打的每个字显示成圆点。点输入框时,系统可能在键盘上方列出保存过的账号。未在模拟器验证。
对应的 iOS API
| ObjC | JS |
|---|---|
[[UITextField alloc] init] | new UITextField() |
field.text | field.text |
field.placeholder = @"账号" | field.placeholder = '账号' |
field.secureTextEntry = YES | field.isSecureTextEntry = true |
field.keyboardType = UIKeyboardTypeNumberPad | field.keyboardType = 'numberPad' |
field.returnKeyType = UIReturnKeyDone | field.returnKeyType = 'done' |
field.textContentType = UITextContentTypeOneTimeCode | field.textContentType = 'oneTimeCode' |
field.autocapitalizationType = UITextAutocapitalizationTypeNone | field.autocapitalizationType = 'none' |
field.autocorrectionType = UITextAutocorrectionTypeNo | field.autocorrectionType = 'no' |
field.borderStyle = UITextBorderStyleRoundedRect | field.borderStyle = 'roundedRect' |
field.clearButtonMode = UITextFieldViewModeWhileEditing | field.clearButtonMode = 'whileEditing' |
field.textColor = UIColor.labelColor | field.textColor = 'label' |
field.editing | field.isEditing |
field.hasText | field.hasText |
[field insertText:@"你好"] | field.insertText('你好') |
[field deleteBackward] | field.deleteBackward() |
field.inputAccessoryView = toolbar | field.inputAccessoryView = toolbar |
换了 inputAccessoryView 之后调 [field reloadInputViews] | 不需要。写 inputAccessoryView 当场生效 |
field.selectedTextRange,再用 offsetFromPosition:toPosition: 换成偏移 | field.selectedRange |
field.selectedTextRange = [field textRangeFromPosition:start toPosition:end] | field.selectedRange = new NSRange(location, length) |
[field addTarget:self action:@selector(changed) forControlEvents:UIControlEventEditingChanged] | field.addEventListener('input', changed) |
[field becomeFirstResponder] | field.becomeFirstResponder() |
[field resignFirstResponder] | field.resignFirstResponder() |
field.isFirstResponder | field.isFirstResponder |
[view endEditing:YES] | view.endEditing(true) |
view.keyboardLayoutGuide.topAnchor | view.keyboardLayoutGuide.topAnchor |
枚举的写法:去掉类型前缀,首字母小写。UIKeyboardTypeEmailAddress 写成 'emailAddress'。见枚举。
UITextFieldDelegate 的方法和 JS 的对应:
| ObjC 的 delegate 方法 | JS |
|---|---|
textFieldDidBeginEditing: | focus 事件 |
textFieldDidChangeSelection: | selectionchange 事件 |
textFieldDidEndEditing: | blur 事件 |
textFieldShouldReturn: 里收键盘 | return 事件里调 resignFirstResponder() |
textFieldShouldBeginEditing: 返回 NO | beforefocus 事件里调 event.preventDefault() |
textFieldShouldEndEditing: 返回 NO | beforeblur 事件里调 event.preventDefault() |
textField:shouldChangeCharactersInRange:replacementString: 返回 NO | beforeinput 事件里调 event.preventDefault()。两个参数在 event.range 和 event.replacementString |
textFieldShouldClear: 返回 NO | beforeclear 事件里调 event.preventDefault() |
textFieldShouldReturn: 返回 NO | beforereturn 事件里调 event.preventDefault() |
ObjC 里用 UITextRange 和 UITextPosition 表示选区的两端,JS 里选区是从内容开头数的 NSRange,读写 selectedRange。
与浏览器 <input> 的对照
这张表只用来查对应关系,给熟悉 HTML 表单的人用。
| 浏览器 | Nacre | 差别 |
|---|---|---|
input.value | field.text | 没有内容时是空字符串,不是 null |
placeholder | placeholder | 没设时读到 null |
type="password" | isSecureTextEntry = true | 是一个布尔属性,不是一种类型 |
inputmode | keyboardType | 只决定弹出哪种键盘,不校验内容 |
autocomplete | textContentType | 取值是 iOS 定的一组名字 |
enterkeyhint | returnKeyType | 只改回车键上的字,不改行为 |
input 事件 | input 事件 | 事件对象不带内容,要读 field.text |
focus / blur 事件 | focus / blur 事件 | — |
keydown 里判断 Enter | return 事件 | — |
el.focus() / el.blur() | becomeFirstResponder() / resignFirstResponder() | 有返回值,表示是否成功 |
document.activeElement === el | field.isFirstResponder | — |
selectionStart、selectionEnd、setSelectionRange() | selectedRange | 是起点加长度,不是起点加终点 |
selectionchange 事件 | selectionchange 事件 | 事件对象不带选区,要读 field.selectedRange |
disabled | isEnabled = false | — |
maxlength、pattern、required、readonly | 没有 | 在 beforeinput 或 input 的回调里自己检查 |
| 表单的提交 | 没有 | 按回车派发 return,做什么由回调决定 |
参见
- 做一个输入框:读内容、收起键盘、避开键盘、限制输入、表单页
UIControl:输入框的父类,isEnabled和全部 16 个事件UIView:endEditing()、keyboardLayoutGuide和安全区UIKeyboardLayoutGuide:让内容避开键盘NSRange:selectedRange的类型UITextView:多行输入UISearchBar:搜索框,里面是一个输入框- 富文本:
attributedText和attributedPlaceholder的类型