Foundation框架 —— NSAttributedString

/*

 * @ NSAttributeString类的作用是管理字符串和与字符串属性有关联的集合(例如，字体和字距)，它适用于单个字符，或字符串某些范围的子字符。字符串与它们的属性相关联后称为属性字符串。本框架下有两个接口，NSAttributeString和 NSMutableAttributedString, 前者用于只读的属性字符串，后者用于可变的属性字符串

 

 * @ 一个属性字符串由属性名称标示其属性，用一个 NSDictionary对象来存储给定名称下的属性值。对一个字符串，你可以指定其任意范围内字符的属性的名称/值对，这是由应用程序来指定的自定义属性(see Attributed String Programming Guide详见属性字符串编程指南)。如果你使用的是 Core TextFramework框架下的属性字符串，你还可以使用该框架已经定义好的属性名称。在ios开发中，标准的属性key名称在 UIKit框架下 NSAttirbuteString 类中定义；在 OS X开发中，其定义在 Application Kit框架下 NSAttirbuteString类中。

 

 * @ 你可以使用任何支持属性字符串的API，例如 Core Text框架。UIKit框架和 Application Kit框架还提供了一个 NSMutableAttributeStirng的子类，名为 NSTextStorage，其作用是提供扩展处理文本系统的场所。在 IOS 6及以后的版本中，你可以使用 TtextView、TtextField，和其他一些控件来显示属性字符串的文本样式。UIKit和 APPKit这两个框架还定义了属性字符串的扩展接口，用以在当前的图形上下文中绘制它们所包含的内容。

 

 * @ NSAttributedString 类的默认字体是 Helvetica体，大小为12-point，这可能与系统平台的默认字体有所不同。因此，你可能需要使用非默认的属性创建新的字符串以适合您的应用。您也可以使用NSParagraphStyle类及其子类NSMutableParagraphStyle封装所用的NSAttributedString类的段落或行距属性。

 

 * @ 请注意，比较 NSAttributeString类时应使用 isEqual:方法进行对比。对比的内容包括两个方面：一是，对逐个字符进行比较；二是，对对应字符的属性进行比较。如果一个字符串包含很多属性，例如attachments, lists, and tables，这样是不容已得到相匹配的结果的。

 */

#import <Foundation/NSString.h>

#import <Foundation/NSDictionary.h>

NS_CLASS_AVAILABLE(10_0,3_2)

@interface NSAttributedString :NSObject <NSCopying,NSMutableCopying,NSSecureCoding>

@property (readonly,copy)NSString *string;

- (NSDictionary *)attributesAtIndex:(NSUInteger)location effectiveRange:(NSRangePointer)range;

@end

@interface NSAttributedString (NSExtendedAttributedString)

@property (readonly)NSUInteger length;

/*

 * @ 检索属性信息

 */

// 返回属性字符串给定索引处的字符属性

// @ location 需要返回属性处的下标，这个值必须在所接收的字符串索引范围内

// @ range ：（如果不为NULL: 1.如果指定索引处存在属性，那么将返回有效索引范围内的属性名称。2.如果指定索引处不存在属性，那么返回范围内的属性也不存在.）（range并不是必须的，可以传入NULL）

- (id)attribute:(NSString *)attrName atIndex:(NSUInteger)location effectiveRange:(NSRangePointer)range;

/*

 * @ 提取子字符串

 */

- (NSAttributedString *)attributedSubstringFromRange:(NSRange)range;

- (NSDictionary *)attributesAtIndex:(NSUInteger)location longestEffectiveRange:(NSRangePointer)range inRange:(NSRange)rangeLimit;

- (id)attribute:(NSString *)attrName atIndex:(NSUInteger)location longestEffectiveRange:(NSRangePointer)range inRange:(NSRange)rangeLimit;

/*

 * @ 比较属性字符串

 */

- (BOOL)isEqualToAttributedString:(NSAttributedString *)other;

/*

 * @ 初始化 NSAttributedString类

 * @ attrs，新属性字符串的属性键-值信息，见于 UIKit 框架下 NSAttirbuteString类

 */

// 返回一个用不含属性信息的给定字符串初始化的 NSAttributedString对象

- (instancetype)initWithString:(NSString *)str;

// 返回一个用指定属性信息及给定字符串初始化的 NSAttributedString对象

- (instancetype)initWithString:(NSString *)str attributes:(NSDictionary *)attrs;

// 返回一个用给定字符串及其所带属性初始化的 NSAttributedString对象

- (instancetype)initWithAttributedString:(NSAttributedString *)attrStr;

typedefNS_OPTIONS(NSUInteger, NSAttributedStringEnumerationOptions) 

{

  NSAttributedStringEnumerationReverse = (1UL <<1),

  NSAttributedStringEnumerationLongestEffectiveRangeNotRequired = (1UL <<20)

};

/*

 *  @ 列举字符串的属性

 */

- (void)enumerateAttributesInRange:(NSRange)enumerationRange 

              options:(NSAttributedStringEnumerationOptions)opts 

                        usingBlock:(void (^)(NSDictionary *attrs,NSRange range, BOOL *stop))block NS_AVAILABLE(10_6,4_0);

- (void)enumerateAttribute:(NSString *)attrName

                   inRange:(NSRange)enumerationRange 

                   options:(NSAttributedStringEnumerationOptions)opts

                usingBlock:(void (^)(id value,NSRange range, BOOL *stop))block NS_AVAILABLE(10_6,4_0);

@end

NS_CLASS_AVAILABLE(10_0,3_2)

@interface NSMutableAttributedString :NSAttributedString

- (void)replaceCharactersInRange:(NSRange)range withString:(NSString *)str;

- (void)setAttributes:(NSDictionary *)attrs range:(NSRange)range;

@end

@interface NSMutableAttributedString (NSExtendedMutableAttributedString)

@property (readonly,retain)NSMutableString *mutableString;

- (void)addAttribute:(NSString *)name value:(id)value range:(NSRange)range;

- (void)addAttributes:(NSDictionary *)attrs range:(NSRange)range;

- (void)removeAttribute:(NSString *)name range:(NSRange)range;

- (void)replaceCharactersInRange:(NSRange)range withAttributedString:(NSAttributedString *)attrString;

- (void)insertAttributedString:(NSAttributedString *)attrString atIndex:(NSUInteger)loc;

- (void)appendAttributedString:(NSAttributedString *)attrString;

- (void)deleteCharactersInRange:(NSRange)range;

- (void)setAttributedString:(NSAttributedString *)attrString;

- (void)beginEditing;

- (void)endEditing;

@end