Skip to content

UILabel ​

UILabel 表示屏幕上一段只读的文字,称为标签。标题、说明、列表里每一行的文字都由标签显示。用户能看到标签上的文字,不能编辑、选中或复制它。

一个标签显示一段文字。用 text 设置时,整段文字用同一种字体、同一种颜色;要让其中几个字加粗或换颜色,用 attributedText 设一段富文本。文字里可以同时有中文和英文,验收用的界面里标签显示的就是中英文混排的文字。表情符号能否正常显示未在模拟器验证。

改了 text、font 或其他属性之后,屏幕上的文字自动更新,不需要调用任何刷新方法。

UILabel 自己不派发任何事件。它的属性都只会被 App 的代码修改,所以没有变化通知。

继承关系:EventTarget → NSObject → UIResponder → UIView → UILabel

怎么用标签显示标题、多行说明、量文字大小,见指南显示文字。

构造函数 ​

UILabel()

创建一个没有文字、宽高是 0 的标签。

实例属性 ​

还继承 UIView 的属性。标签常用的继承属性是 frame、backgroundColor、isHidden、intrinsicContentSize。isUserInteractionEnabled 在标签上的默认值是 false,和普通视图不同,见触摸。

文字和外观:

属性说明
text显示的文字
attributedText带样式的文字,一段里可以混用几种字体和颜色
font字体,包含字号和粗细
textColor文字颜色
textAlignment文字在标签宽度内的水平对齐

行数和截断:

属性说明
numberOfLines最多显示几行。0 表示不限
lineBreakMode文字放不下时怎么处理
preferredMaxLayoutWidth多行标签计算固有尺寸时使用的换行宽度

自动缩小字号:

属性说明
adjustsFontSizeToFitWidth文字放不下时是否缩小字号
minimumScaleFactor字号最小缩到原字号的多少
baselineAdjustment字号缩小之后,文字在垂直方向上怎么摆放

阴影和状态:

属性说明
shadowColor文字阴影的颜色
shadowOffset文字阴影相对文字的偏移
isEnabled是否显示成可用的样子
isHighlighted是否处于高亮状态
highlightedTextColor高亮状态下的文字颜色

实例方法 ​

UILabel 自己没有声明方法。量文字大小用继承自 UIView 的方法,它们在标签上的含义如下:

成员在标签上返回什么
intrinsicContentSize只读的 CGSize,单位 pt。文字的固有尺寸。同步读出
sizeThatFits(size)CGSize,单位 pt。宽度不超过 size.width 时文字需要的大小,受 numberOfLines 限制。同步返回,不改变标签
sizeToFit()无返回值。把标签的大小改成刚好容纳文字,位置不变

sizeThatFits(size) 的 size 可以是 CGSize,也可以是 { width, height }。缺字段时抛 TypeError: sizeThatFits is missing width, or it is not a finite number。

这两个量尺寸的成员都不改变标签。标签不需要先加到页面上,新建之后就可以量。

文字放不下时 ​

标签默认只显示一行。 文字比标签宽时不换行,放不下的部分在末尾换成省略号「…」。

文字放不下时有三种处理方式,由不同的属性控制:

处理方式写法
截断默认行为。省略号的位置由 lineBreakMode 决定
换行numberOfLines 设成 0(不限行数),或者一个大于 1 的数(最多这么多行)
缩小字号adjustsFontSizeToFitWidth 设成 true

三种方式可以组合:先换行,行数用完之后截断;先缩小,缩到下限之后截断。哪种内容该用哪种,见指南显示文字。

行数、换行和截断 ​

三样东西共同决定文字怎么排:

作用
标签的宽度一行能放多少字
numberOfLines最多排几行。0 是不限
lineBreakMode排到最后一行还放不下时,怎么处理剩下的文字

规则是:

  • numberOfLines 是 1 时不换行。放不下就按 lineBreakMode 处理。
  • numberOfLines 大于 1 或等于 0 时,文字在标签的宽度内自动换行。
  • 标签的高度不够显示 numberOfLines 行时,只显示放得下的行数,最后一行按 lineBreakMode 处理。未在模拟器验证。
  • 标签的高度比文字高时,文字在标签内垂直居中。UILabel 没有垂直对齐的属性。未在模拟器验证。
  • adjustsFontSizeToFitWidth 是 true 时,先缩小字号,缩到 minimumScaleFactor 的下限仍然放不下,再按 lineBreakMode 处理。未在模拟器验证。

固有尺寸 ​

固有尺寸是视图按自己的内容算出来的大小。普通的 UIView 没有内容,没有固有尺寸。UILabel 的内容是文字,它的固有尺寸由四样东西决定:text、font、numberOfLines、preferredMaxLayoutWidth。

固有尺寸是一个可以读的值(intrinsicContentSize)。它只在用约束定位时自动生效:

定位方式标签的大小从哪里来
Auto Layout 约束没有约束宽或高时,系统使用固有尺寸。所以只约束位置就够了
直接写 frame完全由 frame 决定。新建的标签宽高是 0。固有尺寸不会自动生效,要自己量再写进去

约束和固有尺寸冲突时(比如约束出来的宽度比文字窄),约束优先,文字按 numberOfLines 和 lineBreakMode 换行或截断。

标签多大程度上坚持固有尺寸,由内容优先级决定,见 UIView。UILabel 的默认值和普通 UIView 一样:不愿被拉大的优先级是 250,不愿被压小的优先级是 750(实测)。

「标签的大小随文字自动调整」来自 iOS 的定义,验收用例没有专门的断言,未在模拟器验证。固有尺寸本身的数值是实测的。

多行文字和宽度 ​

单行文字的大小是确定的。多行文字不是:同一段文字可以排成一行很宽,也可以排成很多行很窄。所以量多行文字时必须给出宽度。给宽度的途径有三个:

场景宽度从哪里来
调 sizeThatFits(size)参数 size.width
用约束定位,标签的宽度被约束确定约束算出的宽度
用约束定位,标签的宽度没有被约束确定preferredMaxLayoutWidth

preferredMaxLayoutWidth 是 0(默认值)并且没有其他途径给出宽度时,固有尺寸按「全部文字排成一行」计算。未在模拟器验证。

触摸 ​

以下属性继承自 UIView,但 UILabel 的默认值不同:

属性UIView 的默认值UILabel 的默认值影响
isUserInteractionEnabledtruefalse标签默认不接收触摸,触摸落到它后面的视图上

要让标签响应点按,把它设成 true 再加一个手势识别器。

出错的情况 ​

  • 属性名拼错时运行时不报错(类型检查会报错)。在不是由构造函数创建的对象上调用会抛 Illegal invocation。这些对所有视图都一样,见 UIView。
  • 枚举属性(textAlignment、lineBreakMode、baselineAdjustment)和颜色属性写错时不抛异常,控制台输出一条警告,属性保持原值。各自的警告原文在成员页上。

示例 ​

标题和两行说明 ​

从空白 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 title = new UILabel();
  title.text = 'Hello, Nacre';
  title.font = UIFont.systemFontOfSize(34, { weight: 'bold' });
  title.textAlignment = 'center';

  const body = new UILabel();
  body.text = '这是一段刻意写得很长的说明文字,用来演示多行排版、行数限制和' +
              '尾部截断。两行放不下的部分不显示,第二行的末尾是省略号。';
  body.font = UIFont.systemFontOfSize(15);
  body.textColor = 'secondaryLabel';
  body.numberOfLines = 2;

  title.translatesAutoresizingMaskIntoConstraints = false;
  body.translatesAutoresizingMaskIntoConstraints = false;
  page.view.addSubview(title);
  page.view.addSubview(body);

  const safe = page.view.safeAreaLayoutGuide;
  NSLayoutConstraint.activateConstraints([
    title.topAnchor.constraintEqualToAnchor(safe.topAnchor, { constant: 16 }),
    title.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 24 }),
    title.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor, { constant: -24 }),
    body.topAnchor.constraintEqualToAnchor(title.bottomAnchor, { constant: 12 }),
    body.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 24 }),
    body.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor, { constant: -24 }),
  ]);
});

效果

  • 屏幕上方、状态栏下面 16 pt 的位置,出现一行粗体的大字「Hello, Nacre」,水平居中。
  • 标题下面 12 pt 的位置是一段灰色的小字,左右各离屏幕边缘 24 pt。
  • 说明文字排成两行。第二行的末尾是「…」,后面的文字不显示。
  • 两个标签的高度都没有写。标题的高度等于一行文字的高度,说明文字的高度等于两行文字的高度。
  • 深色模式下,文字颜色自动换成浅色。

这段代码没有作为一个整体在模拟器运行过。其中用到的每个 API 都在验收用例里运行过。

safe 是安全区的 layout guide,表示屏幕上不被刘海、状态栏和底部横条遮挡的那块区域,见 UIView。约束的写法见 Auto Layout。

更多写法见指南显示文字。

对应的 iOS API ​

ObjCJS
[[UILabel alloc] init]new UILabel()
label.text = @"Hello"label.text = 'Hello'
label.font = [UIFont systemFontOfSize:34 weight:UIFontWeightBold]label.font = UIFont.systemFontOfSize(34, { weight: 'bold' })
label.textColor = UIColor.labelColorlabel.textColor = 'label'
label.textAlignment = NSTextAlignmentCenterlabel.textAlignment = 'center'
label.lineBreakMode = NSLineBreakByTruncatingTaillabel.lineBreakMode = 'byTruncatingTail'
label.numberOfLines = 0label.numberOfLines = 0
label.adjustsFontSizeToFitWidth = YESlabel.adjustsFontSizeToFitWidth = true
label.baselineAdjustment = UIBaselineAdjustmentAlignCenterslabel.baselineAdjustment = 'alignCenters'
label.highlighted = YESlabel.isHighlighted = true
label.enabled = NOlabel.isEnabled = false
label.shadowOffset = CGSizeMake(0, -1)label.shadowOffset = new CGSize(0, -1)
label.attributedText = textlabel.attributedText = text
[label sizeThatFits:CGSizeMake(402, 999)]label.sizeThatFits(new CGSize(402, 999))

规则有三条:

  • 枚举写成字符串:ObjC 常量去掉类型前缀,首字母小写。NSTextAlignmentCenter 是 'center',NSLineBreakByTruncatingTail 是 'byTruncatingTail'。见枚举。
  • 颜色写成字符串,不用 UIColor 的常量。
  • ObjC 里声明成 getter=isXxx 的布尔属性,JS 用 isXxx 这个名字读和写。

与浏览器写法的对照 ​

HTML / CSSUILabel
<span>、<p> 里的纯文本text
默认自动换行默认只显示一行。换行要设 numberOfLines
-webkit-line-clamp: 3numberOfLines = 3
text-overflow: ellipsislineBreakMode = 'byTruncatingTail'(默认值)
text-overflow: cliplineBreakMode = 'byClipping'
text-aligntextAlignment
text-shadow,带模糊半径shadowColor 和 shadowOffset,没有模糊半径
在文字中间嵌套 <b>、<span style>attributedText
用户可以选中和复制文字不可以
元素按内容收缩后的大小intrinsicContentSize,只在用约束定位时自动生效

参见 ​

  • 显示文字:多行、截断、自动缩小、量大小、阴影的写法
  • UIView:标签的父类,位置、大小、底色、约束都在那里
  • UIFont:font 的值
  • UIColor:颜色字符串的全部写法,写错时的行为
  • NSAttributedString:attributedText 的值
  • Auto Layout:固有尺寸在约束里怎么起作用
  • UIButton:按钮上的文字由一个 UILabel 显示,通过 titleLabel 取到
  • UITextField:可以编辑的单行文字
  • 单位:pt 是什么