FXLabel 1.5.9

FXLabel 1.5.9

测试已测试
Lang语言 Obj-CObjective C
许可证 zlib
发布最新发布2016年5月

Nick Lockwood维护。



FXLabel 1.5.9

  • 作者:
  • Nick Lockwood

关于iOS 7的说明

iOS 7引入了一个新的、更强大的文本渲染框架TextKit,这使得FXLabel的大部分绘制API和渲染系统变得过时。出于向后兼容的原因,FXLabel有意识地保持了iOS 6相同的渲染行为,但除非您仍然需要支持iOS 6,否则在TextKit之上创建文本效果会更好。

FXLabel也不支持iOS 6中引入的标注字符串/富文本功能。

目的

标准iOS UILabel在视觉定制方面相当有限;您可以设置字体、颜色和硬边阴影,然后就是这些了。

FXLabel通过提供一个子类来扩展标准UILabel,该子类支持柔边阴影、内阴影和渐变填充,并且可以轻松替换任何标准UILabel。

FXLabel还提供了更多对布局选项的控制,例如行间距(leading)和字距(kerning),以及自动避免孤行(多行标签的最后一行上的孤立单词)。

支持的iOS和SDK版本

  • 支持的构建目标 - iOS 9.3 (Xcode 7.3, Apple LLVM编译器7.1)
  • 最早支持的部署目标 - iOS 7.0
  • 最早兼容的部署目标 - iOS 4.3

注意:'支持'意味着库与这个版本已进行了测试。'兼容'意味着库应该可以在此iOS版本上运行(即它不依赖于任何不可用的SDK功能),但不再进行兼容性测试,可能需要调整或错误修复才能正确运行。

ARC兼容性

从版本1.4开始,FXLabel需要ARC。如果您希望在非ARC项目中使用FXLabel,只需将-fobjc-arc编译器标志添加到FXLabel.m类即可。要做到这一点,请转到目标设置中的构建阶段标签,打开编译源代码组,在列表中双击FXLabel.m,然后在弹出的窗口中输入-fobjc-arc。

如果您希望将整个项目转换为ARC,请注释掉FXLabel.m中的#error行,然后运行Xcode中的编辑>重构>将Objective-C转换为ARC...工具,并确保所有想要使用ARC的文件都已勾选(包括FXLabel.m)。

安装

要使用FXLabel,只需将类文件拖拽到您的项目中。您可以通过代码创建FXLabel,或在界面构建器中拖拽一个普通的UILabel到视图中,并将其类设置为FXLabel。

如果您正在使用界面构建器,要设置FXLabel的自定义属性(这些属性不支持常规的UILabel),您可以创建一个IBOutlet为您标签并代码中设置属性,或者使用界面构建器中的用户定义运行时属性功能(Xcode 4.2及更高版本的iOS 5+引入)。

NSString扩展

FXLabel通过以下方法扩展了NSString:

- (CGSize)sizeWithFont:(UIFont *)font
           minFontSize:(CGFloat)minFontSize
        actualFontSize:(CGFloat *)actualFontSize
              forWidth:(CGFloat)width
         lineBreakMode:(NSLineBreakMode)lineBreakMode
      characterSpacing:(CGFloat)characterSpacing
          kerningTable:(NSDictionary *)kerningTable;

此方法计算使用FXLabel的字符间距和字距调整表渲染的字符串的大小。此方法适用于计算单行字符串的渲染大小,不适用于多行字符串。如果您不需要该功能,请传入nil作为字距调整表。

- (CGSize)drawAtPoint:(CGPoint)point
             forWidth:(CGFloat)width
             withFont:(UIFont *)font
          minFontSize:(CGFloat)minFontSize
       actualFontSize:(CGFloat *)actualFontSize
        lineBreakMode:(NSLineBreakMode)lineBreakMode
   baselineAdjustment:(UIBaselineAdjustment)baselineAdjustment
     characterSpacing:(CGFloat)characterSpacing
         kerningTable:(NSDictionary *)kerningTable;

此方法使用FXLabel的字符间距和字距调整表属性渲染字符串。此方法适用于渲染单行字符串,不适用于多行字符串。如果您不需要该功能,请传入nil作为字距调整表。

- (CGSize)sizeWithFont:(UIFont *)font
     constrainedToSize:(CGSize)size
         lineBreakMode:(NSLineBreakMode)lineBreakMode
           lineSpacing:(CGFloat)lineSpacing
      characterSpacing:(CGFloat)characterSpacing
          kerningTable:(NSDictionary *)kerningTable
          allowOrphans:(BOOL)allowOrphans;

此方法计算使用FXLabel的行间距、字符间距、字距调整表和允许孤行属性的渲染字符串的大小。它适用于使用多行字符串。如果您不需要该功能,请传入nil作为字距调整表。

- (CGSize)drawInRect:(CGRect)rect
            withFont:(UIFont *)font
       lineBreakMode:(NSLineBreakMode)lineBreakMode
           alignment:(NSTextAlignment)alignment
         lineSpacing:(CGFloat)lineSpacing
    characterSpacing:(CGFloat)characterSpacing
        kerningTable:(NSDictionary *)kerningTable
        allowOrphans:(BOOL)allowOrphans;

此方法使用FXLabel的行间距、字符间距、字距调整表和允许孤行属性渲染字符串。它适用于使用多行字符串。如果您不需要该功能,请传入nil作为字距调整表。

FXLabel属性

@property (nonatomic) CGFloat shadowBlur;

文本阴影的柔度。默认值为零,创建一个硬阴影,与标准UILabel阴影相同。请注意,阴影的其他属性,如阴影偏移量和阴影颜色,是从UILabel继承的,可在标准的Apple文档中找到。

@property (nonatomic) CGFloat innerShadowBlur;

文本内阴影的柔度。默认值为零,创建一个硬阴影。

@property (nonatomic) CGSize innerShadowOffset;

内阴影的偏移量。与shadowOffset的行为相同。

@property (nonatomic, strong) UIColor *innerShadowColor;

内阴影的颜色。默认值为透明色。

@property (nonatomic, copy) NSArray *gradientColors;

用于在文本上产生渐变效果的颜色的数组。您可以指定的渐变色数的最小值是两个 - 如果数组中包含的颜色少于两个,则会被忽略。如果任何颜色的alpha分量小于1.0,它将与textColor混合。不支持模式、索引或HSV颜色。渐变的方向由gradientStartPoint和gradientEndPoint属性控制。默认方向是垂直的。

@property (nonatomic, strong) UIColor *gradientStartColor;

渐变的起始/上颜色。这是对gradientColors数组中第一个元素的方便访问器。

@property (nonatomic, strong) UIColor *gradientEndColor;

渐变的结束/下颜色。这是对gradientColors数组中最后一个元素的方便访问器。

@property (nonatomic) CGPoint gradientStartPoint;

渐变的起始位置。x和y坐标的范围是0到1,其中(0,0)是文本的左上角,(1,1)是右下角。这意味着您可以为多个字符串使用相同的设置,渐变将缩放以适应。默认值是(0.5, 0.0),即顶部,中央。

@property (nonatomic) CGPoint gradientEndPoint;

渐变的结束位置。x和y坐标的范围是0到1,其中(0,0)是文本的左上角,(1,1)是右下角。这意味着您可以为多个字符串使用相同的设置,渐变将缩放以适应。默认值是(0.5, 0.75),对于大多数字符串,这是基线的中心。对于有许多悬垂部分(低于基线的字符)的字符串,您可能会发现(0.5, 1.0)的值看起来更好。

@property (nonatomic) NSUInteger oversampling;

您可能会发现,对于某些效果的组合,文本边缘的质量可能会较差,尤其是在非Retina设备上,并且在使用内阴影时。在这种情况下,您可以使用超采样属性,这将导致文本以更高的分辨率绘制,然后降级以提高绘图质量,虽然会对性能略有影响。超采样属性的默认值(和最小值)与[UIScreen mainScreen].scale的值匹配。为了获得最佳效果,将超采样设置为二的幂,即1、2、4、8、16等。由于性能原因,您应该使用产生可接受结果的最小值。

@property (nonatomic) UIEdgeInsets textInsets;

FX标签效果不能在标签视图的外部绘制。对于不在中心对齐的标签,您可能需要使用textInsets属性将文本从视图边缘缩进,以便文本效果(如阴影)不会被裁剪。

@property (nonatomic) CGFloat lineSpacing;

行间距属性允许您控制标签中行之间的空间量。默认为0。注意:从版本1.5开始,此值相对于字体的大小点数,而不是按绝对点数指定。

@property (nonatomic) CGFloat characterSpacing;

字符间距属性允许您控制标签中字母之间的空间量。默认值为零,并且相对于字体的大小点数。因此,如果您正在使用minimumFontSize/minimumScaleFactor功能,则字符间距也会随着字体大小的缩小成比例减少。

@property (nonatomic) CGFloat baselineOffset;

基线偏移属性调整文本相对于标签框架的垂直偏移量。此属性对于修复在字体文件中将基线设置错误的字体非常有用。它只会影响文本的显示方式,而不会对标签框架或文本度量、换行等产生影响。基线偏移值的默认值为零,并且相对于字体的大小点数。

@property (nonatomic, copy) NSDictionary *kerningTable;

紧密度属性表用于单独控制字体中每个字符的间距。该字典由按字符字符串键的NSNumber值组成。值相对于字体的大小点数。例如,如果您想将字母“a”的间距增加到点大小的一半,则将紧密度表值设置为`@{ @"a": @0.5 }`。如果您想将感叹号的间距减少到点大小的25%,则使用`@{ @"!": @-0.25 }`。

@property (nonatomic) BOOL allowOrphans;

允许孤儿属性允许您防止一个单词出现在段落最后一行的常见布局问题。默认情况下,允许孤儿设置为YES,但如果您将其设置为NO,FXLabel将自动确保每个段落的最后一行至少出现两个单词。

FXLabel方法

- (void)setUp;

您不应该直接调用此方法。当在代码或从nib文件中创建FXlabel实例时,会调用此方法。您可以在分派而不是在initWithFrame:和initWithCoder:中重复设置代码时,覆盖此方法(确保在实现中调用super setUp)。

注释

FX标签具有一个很好的额外布局功能,即与UILabel不同,它们尊重内容模式属性,在垂直布局方面。将内容模式设置为顶部、居中或底部分别垂直对齐文本到视图的顶部、居中或底部。请注意,然而,对于水平对齐,FXLabel忽略了内容模式,而是选择文本对齐属性。

FX标签效果不能在标签视图的外部绘制。对于具有阴影模糊或阴影偏移值的标签,您需要增加标签框的大小以防止阴影被裁剪。如果您的文本不是居中对齐的,您还需要使用textInsets属性将文本从视图边缘缩进,以防止文本效果被裁剪。

渐变颜色属性不支持图案、索引或HSV颜色。

发布说明

版本 1.5.9

  • 修复了Xcode 7.3上的警告。
  • 添加了IB_DESIGNABLE注释。
  • 添加了可空性和轻量级泛型。

版本 1.5.8

  • 修复了针对iOS 7或更高版本时的自动收缩问题。

版本 1.5.7

  • 修复了iOS 7.1下的一些额外警告。

版本 1.5.6

  • 修复了版本1.5.5中引入的性能回归问题。
  • 由于性能原因,取消了半透明重叠文本修复。
  • 使用标签背景颜色时,性能得到改善。

版本 1.5.5

  • 修复了针对iOS7+时的无限循环问题。
  • 修复了针对iOS7+时的文本颜色错误。
  • 修复了针对iOS7+时的换行和剪辑问题。
  • 如果由于紧密字距而导致文本重叠,半透明文本不再被错误渲染。
  • 如果不使用自定义行间距,基线调整现在可以正确工作。
  • 现在符合-Weverything警告级别。

版本 1.5.4

  • 修复了使用带渐变的textInset时的失真问题。

版本 1.5.3

  • 修复了使用字符换行时的行包裹问题。
  • 现在可以无弃用警告编译iOS 7+。
  • 现在符合-Wall和-WExtra警告级别。

版本 1.5.2

  • 修复了在程序创建标签(而不是使用nib)时自动收缩逻辑中的错误。

版本 1.5.1

  • 修复了由于四舍五入错误导致的多行标签布局不正确的问题。

版本 1.5

  • 添加了内部阴影模糊属性。
  • 添加了字符间距属性。
  • 添加了针对每个字符间距的kerningTable属性。
  • 添加了基线偏移属性。
  • 行间距属性现在相对于pointSize。

版本 1.4.2

  • 修复了调用sizeToFit或sizeThatFits:方法时的崩溃问题。
  • 修复了当标签高度小于单行高度时的崩溃问题。
  • 修复了多行标签的文本对齐问题。

版本 1.4.1

  • 修复了当部署目标 < 6.0 时的错误。
  • 将setUp方法设置为公开,以帮助子类化。

版本 1.4

  • FXLabel现在要求ARC(有关详细信息,请参阅README)。
  • 现在可以控制多行标签的行间距。
  • FXLabel现在可以自动避免孤词(在标签的最后一行独占一个词)。
  • 改进了布局算法,使其更接近单行标签的UILabel行为。
  • sizeToFit方法现在考虑文本内边距。

版本 1.3.7

  • 将ARCHelper宏移出.h文件,这样它们就不会影响其他类中的非ARC代码。

版本 1.3.6

  • 修复了当文本自动收缩时的基线对齐问题。
  • 修复了使用textInset属性可能导致文本外观挤压或拉伸的错误。

版本 1.3.5

  • 修复了iOS 6下的弃用警告。
  • 更新ARC Helper到版本2.1。

版本 1.3.4

  • 更新ARC Helper到版本1.3。
  • 修复了Apple LLVM编译器4.0下的警告。

版本 1.3.3

  • 修复了1.3.2版本中引入的ARC崩溃。

版本 1.3.2

  • 修复了使用非RGB混合颜色(例如[UIColor blackColor])时的错误。
  • 修复了当背景颜色不透明时,内部阴影应用到标签框架的问题。

版本 1.3.1

  • 添加了对ARC编译目标的自动支持。
  • 现在需要Apple LLVM编译器3.0目标。

版本 1.3

  • 添加了新gradientColors数组以指定多部分渐变。
  • 添加了新textInsets属性以防止效果被截断。
  • 修复了多行字段被截断为单行的问题。
  • 当设置highlighted属性时,现在尊重高亮颜色。
  • 将过采样属性替换为允许开发者指定所需过采样程度的过采样属性
  • 添加了额外的示例项目

版本 1.2

  • 添加过采样属性以提高某些效果绘制质量
  • 修复了未绘制没有任何效果或阴影的标签的问题

版本 1.1

  • 添加 gradientStartPoint 和 gradientEndPoint 属性。
  • 渐变颜色现在支持单色和颜色常量(例如 [UIColor whiteColor])。
  • 通过在绘制前将渐变色与文本颜色预先混合消除了渐变字体周围的虚假彩色晕环。
  • 阴影不透明度现在在不同的字体设置中更加一致。
  • 修复了无内阴影的字体绘制故障。
  • 修复了一些内存泄露。
  • 通过减少重绘略有提高了性能。

版本 1.0

  • 首次发布