[翻译] WPAttributedMarkup

WPAttributedMarkup

https://github.com/nigelgrange/WPAttributedMarkup

WPAttributedMarkup is a simple utility category that can be used to easily create an attributed string from text with markup tags and a style dictionary.

WPAttributedMarkup是一个简单而实用的category,你可以很方便的来用他来创建富文本,通过用标签的方式,还有属性字典的方式.

The category allows you to turn text such as:

这个category允许你用以下的方式来设置富文本:

<bold>Bold</bold> text

into "Bold" text by using a style dictionary such as:

转换到"粗体",你可以用以下的属性字典:

  NSAttributedString *as = [@"<bold>Bold</bold" attributedStringWithStyleBook:@{@"body":[UIFont fontWithName:@"HelveticaNeue" size:18.0],
  @"bold":[UIFont fontWithName:@"HelveticaNeue-Bold" size:18.0]}];

In this example, the style associated with "body" is applied to the whole text, whereas the style associated with "bold" is applied to the text contained within < bold > tags.

在这个例子中,与"body"相关的样式,<bold>*****</bold的*****都被设置成了字体对应的样式.

All tags (with the exception of 'body') are user-defined.

所有的标签都是用户事先定义好的.

The dictionary is called a 'style book' as the intention is for it to contain all of the application fonts, colours etc in a single place.

这个字典文件被称作"样式书",里面包含了程序的自提,颜色等属性诸如此类的设置.

FAQ

Q. Can this convert html to styled text?

问:这个可以讲html转换成富文本么?

A. In general, no. The syntax is html-like, but all tags are user-defined. If the html is correctly formatted, and uses a strict set of tags, you could convert html to attributed text by defining an appropriate set of tags (b, h1, h2, etc).

答:大体上,不行.也许这个格式看起来像html风格的标签,但是,这些都是用户自定义.如果html是标准格式的,或者说是用了个严谨的完整的标签格式,你可以通过自定义标签的方式来将html转换成富文本.

Q. Doesn't NSAttributedString already convert html text using something like:

问:富文本不是本身就支持将网页转换么?

[NSAttributedString alloc] initWithData:[htmlString dataUsingEncoding:NSUTF8StringEncoding]
                             options:@{NSDocumentTypeDocumentAttribute: NSHTMLTextDocumentType,
                                       NSCharacterEncodingDocumentAttribute: @(NSUTF8StringEncoding)}
                  documentAttributes:nil error:nil];

A. It does. However, the above approach is very slow (it uses a WebView in the background) and runs asynchronously (just try creating one in a UITableViewCell and scroll the table too fast...).

In addition, any styles must be set in the document css, rather than being able to pass in standard colour and font classes that your application already uses.

答:富文本确实本身就支持直接的html转换,但是,上面的转换非常的缓慢.(它在后台使用了WebView来转化),并且是异步执行的(你在tableView上滑动时候就知道那玩意有多慢了.....).

What styles are supported?

The following objects can be used in the style dictionary:

以下的这些属性可以被设置到属性字典当中:

UIColor : For colouring a section of text. 给文本设置颜色

@"red": [UIColor redColor]

UIFont : For setting the font for a section of text. 给文本设置字体

@"bold":[UIFont fontWithName:@"HelveticaNeue-Bold" size:18.0]

NSDictionary : Applies an attributed string style key/pair to the section of text. This can be used for applying underline, strikethrough, paragraph styles, etc as well as custom attributes. 根据键值对给文本设置属性.这个可以用来设置下划线,中划线,段落样式等.

@"u": @{NSUnderlineStyleAttributeName : @(kCTUnderlineStyleSingle|kCTUnderlinePatternSolid)}

NSArray : An array of any style items, all of which are applied to the section of text. 一个用来设置样式的数组,里面由小样式组成.

@"u": @[[UIColor blueColor],
@{NSUnderlineStyleAttributeName : @(kCTUnderlineStyleSingle|kCTUnderlinePatternSolid)} ]

NSString : Applies a named style to the section of text. Useful for applying an existing style in addition to some new attributes without needing to copy the existing attributes.

 @"red": [UIColor redColor],
 @"redunderline": @[ @{NSUnderlineStyleAttributeName : @(kCTUnderlineStyleSingle|kCTUnderlinePatternSolid)}, @"red" ]

UIImage : Inserts the UIImage into the text at the section of text. Note: The text inside the image tags must contain only a single character, which will be replaced by the image. 插入一张图片

@"thumb":[UIImage imageNamed:@"thumbIcon"]

Used in the text as:

 <thumb> </thumb>

Extras

Some extra utility classes are included which may also be of use in association with WPAttributedMarkup. In particular, the WPHotspotLabel class can be used to apply block methods to any part of the attributed string, allowing trivial application-specific links to be created.

还有些额外的很实用的类,可以和WPAttributedMarkup配合使用.WPHotspotLabel 可以用来接受block方法方法,用来设置富文本.

WPAttributedStyleAction - A class which wraps a block and allows insertion into an attributed string using the styledAction method. This actually adds a link style to the text, so the text will also inherit the attributed defined in the link style, if defined.

WPAttributedStyleAction 给文本添加了超链接属性,如果定义了的话.

This can be used as follows:

@"help":[WPAttributedStyleAction styledActionWithAction:^{
                             NSLog(@"Help action");
                         }]

WPTappableLabel - A simple UILabel subclass which allows an onTap block to be set, which is called when the label is tapped.

WPTappableLabel 一个简单的UILabel的子类,允许你设置点击事件.

WPHotspotLabel - A subclass of WPTappableLabel which detects the attributes of the text at the tapped position, and executes the action if a WPAttributedStyleAction attribute is found.

WPHotspotLabel 是WPTappableLabel 的子类,用以检查属性点击区域,以及执行点击事件,如果设置了点击事件的话.

Note that these classes have not been tested as exhaustively, so it is possible that these do not behave as expected under all conditions. In particular, WPHotspotLabel uses CoreText layout to detect the attributes of the tapped position, which could potentially result in different layout than the one being displayed. Under all tests performed so far with simple labels and formatting, the detection does work correctly, but you have been warned!

注意,这些类并没有经过完整的测试,所以,有时候某些类并不能达到你想要的效果.WPHotspotLabel是使用了CoreText的自动布局来检测属性点击的区域,这个也许会在不同的布局当中显示异常.目前所进行的所有测试当中,包括了文本的格式相关的都没有什么问题.当点击事件区域的检测也许会出现异常,这里已经给你提醒了哦!

Example

// Example using fonts and colours
NSDictionary* style1 = @{@"body":[UIFont fontWithName:@"HelveticaNeue" size:18.0],
                         @"bold":[UIFont fontWithName:@"HelveticaNeue-Bold" size:18.0],
                         @"red": [UIColor redColor]};

 // Example using arrays of styles, dictionary attributes for underlining and image styles

 NSDictionary* style2 = @{@"body" :
                             @[[UIFont fontWithName:@"HelveticaNeue-Bold" size:18.0],
                               [UIColor darkGrayColor]],
                            @"u": @[[UIColor blueColor],
                                @{NSUnderlineStyleAttributeName : @(kCTUnderlineStyleSingle|kCTUnderlinePatternSolid)}
                                 ],
                            @"thumb":[UIImage imageNamed:@"thumbIcon"] };

// Example using blocks for actions when text is tapped. Uses the 'link' attribute to style the links

NSDictionary* style3 = @{@"body":[UIFont fontWithName:@"HelveticaNeue" size:22.0],
                         @"help":[WPAttributedStyleAction styledActionWithAction:^{
                             NSLog(@"Help action");
                         }],
                         @"settings":[WPAttributedStyleAction styledActionWithAction:^{
                             NSLog(@"Settings action");
                         }],
                         @"link": [UIColor orangeColor]};

self.label1.attributedText = [@"Attributed <bold>Bold</bold> <red>Red</red> text" attributedStringWithStyleBook:style1];

self.label2.attributedText = [@"<thumb> </thumb> Multiple <u>styles</u> text <thumb> </thumb>" attributedStringWithStyleBook:style2];

self.label3.attributedText = [@"Tap <help>here</help> to show help or <settings>here</settings> to show settings" attributedStringWithStyleBook:style3];

How it works

The utility consists of two categories:

实用功能包含了以下两个category:

NSMutableString+TagReplace : Used internally to strip all tags out of a NSMutableString, building an array of tags with start and end ranges.

进行tag值的替换类.

NSString+WPAttributedMarkup : Contains a single public method:

-(NSAttributedString*)attributedStringWithStyleBook:(NSDictionary*)styleBook;

This builds an arrange of tags using NSMutableString+TagReplace, then iterates through each of the tags and applies the styles found in the style book.

If no style is found for a tag, then the tag is simply stripped from the string with no style applied.

If the body tag is found in the style book, then this is applied to the entire string before any other styles are applied.