Skip to content

UITextView ​

UITextView 表示一块可以输入多行文字的区域。用户点它,系统键盘弹出;按回车是换行,不会结束输入。App 从 text 读出全部内容,从 selectedRange 读出光标的位置和选中的范围,通过事件得知内容变了、光标动了、输入开始和结束了。

多行输入是滚动视图:内容超过它自己的高度时可以上下滚动,滚动视图的属性和事件它都有。把 isScrollEnabled 设成 false 之后,它不再滚动,而是文字有几行就要多高。它不是控件,没有 isEnabled,也没有控件的那 16 个事件。只要一行的输入用 UITextField。

和单行输入框相比:

UITextFieldUITextView
行数一行多行,按回车换行
父类控件滚动视图
内容变了input 事件input 事件
开始、结束输入focus、blurfocus、blur
按回车派发 return换行,不派发事件
占位文字placeholder 属性没有,要自己叠一个标签
边框borderStyle 有四种样式没有可用的边框样式,用底色和圆角
在修改之前拦下beforeinput 等可取消的事件beforeinput 等可取消的事件
点了富文本里的链接没有linkclick 事件
光标和选中的范围selectedRangeselectedRange
光标或选区动了selectionchange 事件selectionchange 事件

九个键盘设置(keyboardType、textContentType 等)两边相同。

这一组页面里标「实测」的行为,是用不带界面的小程序在模拟器(iPhone Air,iOS 27.2)上量的。屏幕上的样子和真实键盘的行为标了「未在模拟器验证」。beforefocus、beforeinput、beforeblur、linkclick 四个事件页里的「实测」是在真机(iPhone 14,iOS 27.2)上量的,没量到的标了「未在真机验证」。

继承关系:EventTarget → NSObject → UIResponder → UIView → UIScrollView → UITextView

和它一起用的两个类:NSRange 表示一段文字的范围,NSTextContainer 表示文字排版的区域。

怎么做占位文字、跟着内容长高的输入框、收起键盘,见指南做一个多行输入框。

构造函数 ​

UITextView()

创建一块多行输入。没有内容,没有设字体,大小是 0。

实例属性 ​

还继承 UIScrollView 和 UIView 的属性。多行输入常用的继承属性是 isScrollEnabled、keyboardDismissMode、contentOffset、backgroundColor、isFirstResponder。

内容:

属性说明
text全部内容
attributedText带样式的内容
hasText 只读是否有内容
clearsOnInsertion插入文字时是否换掉全部内容
allowsEditingTextAttributes是否允许用户改文字的样式
dataDetectorTypes把哪几类内容变成可以点的链接

外观:

属性说明
font文字的字体
textColor文字的颜色
textAlignment文字靠哪边
textContainerInset文字离四边多远
textContainer 只读文字排版的区域
usesStandardTextScaling是否按标准的比例缩放文字

行为:

属性说明
isEditable用户能不能修改内容
isSelectable用户能不能选中文字
selectedRange选中的范围,或者光标的位置
markedTextRange 只读输入法正在组字的那一段,没在组字时是 null
isFindInteractionEnabled是否打开系统的查找和替换
isWritingToolsActive 只读写作工具是否正在工作
writingToolsBehavior写作工具能做到哪一步
allowedWritingToolsResultOptions写作工具可以写回哪几种内容

键盘:

属性说明
keyboardType弹出哪种键盘
returnKeyType回车键上显示什么字
keyboardAppearance键盘的明暗
enablesReturnKeyAutomatically没有内容时回车键是否变灰
isSecureTextEntry按密码的方式输入
autocapitalizationType自动大写的规则
autocorrectionType是否自动纠错
spellCheckingType是否检查拼写
textContentType这里装的是什么内容,用于自动填充
smartQuotesType是否把直引号换成弯引号
smartDashesType是否把连续的短横线换成破折号
smartInsertDeleteType粘贴和删除时是否自动调整空格
inlinePredictionType是否在光标后面显示预测的文字
mathExpressionCompletionType是否自动算出算式的结果
allowsNumberPadPopover是否允许用数字键盘的浮层
inputAccessoryView键盘弹出时贴在键盘上面的视图
inputView代替系统键盘弹出的视图

实例方法 ​

还继承 UIScrollView 和 UIView 的方法。多行输入常用的继承方法是 becomeFirstResponder()、resignFirstResponder(),说明见 UITextField 的焦点。

方法说明
insertText()按用户打字的方式在光标处插入文字
deleteBackward()按用户按删除键的方式删除
scrollRangeToVisible()滚动到一段文字看得见为止

事件 ​

用 addEventListener() 监听。多行输入自己的事件有八个,分成两组。

内容、焦点和选区变了之后的通知:

事件什么时候派发
focus它成为 first responder,开始输入
input用户的输入改了内容,或者代码调了 insertText()、deleteBackward()
selectionchange选区或者光标的位置变了
blur它不再是 first responder,结束输入

系统当场来问「要不要做」的事件,监听器里调 preventDefault() 就是不要:

事件什么时候派发
beforefocus即将开始输入。取消就不进入编辑
beforeinput用户的输入即将改变内容。取消就不改
beforeblur即将结束输入。取消就留住焦点
linkclick用户点了富文本里的链接。取消就不打开

继承来的事件:

事件什么时候派发
scroll 等滚动视图的八个事件,继承自 UIScrollView
traitchange外观特征变化,继承自 UIView

focus、input、selectionchange、blur 四个通知共同的规则:

  • 事件对象的 type 是事件名,target 是这块多行输入。事件对象不带内容,也不带改了哪里。内容读 text,光标读 selectedRange。
  • 不能取消,preventDefault() 不起作用。要阻止某个字符进入,用 beforeinput。
  • 回调不是在事件发生的那一刻同步执行,而是稍后执行,见回调的执行时机。调完 insertText() 的下一行,回调还没有执行。
  • 回调里抛出异常不影响多行输入,同一事件的其他回调照常执行。异常在 application 上派发 error;没有监听器取消时,控制台输出以 Uncaught 开头的日志。
  • 没有监听器时没有开销。
  • 滚动视图的事件可以和这八个同时监听,互不影响(实测)。
  • 监听别的名字不会报错:它被当成自定义事件,只有自己用 dispatchEvent() 派发时才会触发。

beforefocus、beforeinput、beforeblur、linkclick 四个可取消的事件共同的规则:

  • 监听器是当场执行的。系统派发事件之后等监听器全部执行完,再决定做不做。监听器里只做判断,不做耗时的事。
  • 只要有一个监听器调了 preventDefault(),系统就不做。
  • 监听器抛出异常不等于 preventDefault()。
  • 没有监听器时系统照默认的做法处理。

代码改内容和用户改内容 ​

怎么改的派发 input 吗
用户打字、删除、粘贴派发(未在模拟器验证)
insertText()、deleteBackward()派发(实测)
写 text不派发(实测)

所以用代码写 text 之后,依赖内容的界面(字数、占位文字)要自己更新一次。反过来,在 input 的回调里写 text 不会再次触发回调。

大小 ​

默认情况下多行输入的大小由 App 给:用约束或 frame 定出宽和高,内容超过这个高度就在里面滚动。

把 isScrollEnabled 设成 false 之后,它不再滚动,而是有了自己想要的高度:文字有几行,它就要多高。用约束定位时只给左右和顶边,不给高度,它的高度跟着文字变(实测)。这一条在放进窗口之后才成立:没有放进窗口的多行输入,改了文字之后重新布局,高度还是原来的(实测)。

实测 17 pt 的字:一行 36 pt,三行 77 pt,五行 118 pt,六行 138 pt。没有设字体时一行是 30 pt。

示例 ​

带字数的多行输入 ​

从空白 App 开始,在屏幕上方放一块多行输入,下面一行字显示内容的长度。

js
application.addEventListener('sceneconnect', (e) => {
  const win = new UIWindow(e.scene);
  const page = new UIViewController();
  page.view.backgroundColor = 'systemBackground';
  win.rootViewController = page;
  win.makeKeyAndVisible();

  const input = new UITextView();
  input.font = UIFont.systemFontOfSize(17);
  input.backgroundColor = 'secondarySystemBackground';
  input.layer.cornerRadius = 10;
  input.keyboardDismissMode = 'onDrag';

  const counter = new UILabel();
  counter.text = '长度 0';
  counter.textColor = 'secondaryLabel';

  input.addEventListener('input', () => {
    counter.text = '长度 ' + input.text.length;
  });
  input.addEventListener('blur', () => {
    console.log('输入的是:' + input.text);
  });

  input.translatesAutoresizingMaskIntoConstraints = false;
  counter.translatesAutoresizingMaskIntoConstraints = false;
  page.view.addSubview(input);
  page.view.addSubview(counter);
  const safe = page.view.safeAreaLayoutGuide;
  NSLayoutConstraint.activateConstraints([
    input.topAnchor.constraintEqualToAnchor(safe.topAnchor, { constant: 24 }),
    input.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 16 }),
    input.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor, { constant: -16 }),
    input.heightAnchor.constraintEqualToConstant(160),
    counter.topAnchor.constraintEqualToAnchor(input.bottomAnchor, { constant: 8 }),
    counter.leadingAnchor.constraintEqualToAnchor(input.leadingAnchor),
  ]);
});

效果

  • 屏幕上方出现一块灰色的圆角区域,下面一行灰色的字「长度 0」。
  • 点灰色区域,键盘弹出,区域里出现光标。
  • 每打一个字,下面那行字里的数字跟着变。按回车换到下一行。
  • 文字超过 160 pt 的高度之后,可以在区域里上下滚动。
  • 手指按住文字往下拖,键盘收起,控制台输出 输入的是: 加上全部内容。

这段代码没有作为一个整体在模拟器运行过,上面五条未在模拟器验证。其中每个属性的读写、input 和 blur 的派发在不带界面的小程序里量过。

注意:模拟器连着电脑的硬件键盘时,屏幕上的软键盘不弹出。这是模拟器的行为。要看到软键盘,在模拟器菜单里关掉硬件键盘连接。

对应的 iOS API ​

ObjCJS
[[UITextView alloc] init]new UITextView()
view.textinput.text
view.hasTextinput.hasText
[view insertText:@"你好"]input.insertText('你好')
[view deleteBackward]input.deleteBackward()
view.font = [UIFont systemFontOfSize:17]input.font = UIFont.systemFontOfSize(17)
view.textColor = UIColor.labelColorinput.textColor = 'label'
view.textAlignment = NSTextAlignmentCenterinput.textAlignment = 'center'
view.textContainerInset = UIEdgeInsetsMake(12, 12, 12, 12)input.textContainerInset = new UIEdgeInsets(12, 12, 12, 12)
view.textContainer.lineFragmentPadding = 0input.textContainer.lineFragmentPadding = 0
view.textContainer.maximumNumberOfLines = 3input.textContainer.maximumNumberOfLines = 3
view.editable = NOinput.isEditable = false
view.selectable = NOinput.isSelectable = false
view.selectedRange = NSMakeRange(0, 5)input.selectedRange = new NSRange(0, 5)
[view scrollRangeToVisible:range]input.scrollRangeToVisible(range)
view.keyboardDismissMode = UIScrollViewKeyboardDismissModeOnDraginput.keyboardDismissMode = 'onDrag'
view.inputAccessoryView = toolbarinput.inputAccessoryView = toolbar
换了 inputAccessoryView 之后调 [view reloadInputViews]不需要。写 inputAccessoryView 当场生效
view.scrollEnabled = NOinput.isScrollEnabled = false

枚举的写法:去掉类型前缀,首字母小写。见枚举。

UITextViewDelegate 的方法和通知,与 JS 的对应:

ObjCJS
textViewDidBeginEditing:、UITextViewTextDidBeginEditingNotificationfocus 事件
textViewDidChange:、UITextViewTextDidChangeNotificationinput 事件
textViewDidEndEditing:、UITextViewTextDidEndEditingNotificationblur 事件
textViewDidChangeSelection:selectionchange 事件
textView:shouldChangeTextInRange:replacementText:beforeinput 事件
textViewShouldBeginEditing:beforefocus 事件
textViewShouldEndEditing:beforeblur 事件
textView:primaryActionForTextItem:defaultAction:,点的是链接linkclick 事件

与浏览器 <textarea> 的对照 ​

这张表只用来查对应关系,给熟悉 HTML 表单的人用。

浏览器Nacre差别
textarea.valueinput.text—
input 事件input 事件事件对象不带内容,要读 input.text
focus / blur 事件focus / blur 事件—
selectionStart、selectionEndselectedRange是起点加长度,不是起点加终点
setRangeText()insertText()只能换掉当前选中的部分
readonlyisEditable = false—
placeholder没有叠一个标签
maxlength没有在 beforeinput 里拦下超长的修改
rows没有高度由约束决定,或者关掉滚动让它跟着内容走
selectionchange 事件selectionchange 事件派发在这块多行输入上,不在 document 上。事件对象不带选区,要读 input.selectedRange

参见 ​