Foundation
/* NSAttributedString.h
Copyright (c) 1994-2015, Apple Inc. All rights reserved.
*/
#import <Foundation/NSString.h>
#import <Foundation/NSDictionary.h>
NS_ASSUME_NONNULL_BEGIN
NS_CLASS_AVAILABLE(10_0, 3_2)
@interface NSAttributedString : NSObject <NSCopying, NSMutableCopying, NSSecureCoding>
// 字符串
@property (readonly, copy) NSString *string;
// 通过一个位置和一个有效的范围来获取字符串的预设属性
- (NSDictionary<NSString *, id> *)attributesAtIndex:(NSUInteger)location effectiveRange:(nullable NSRangePointer)range;
@end
@interface NSAttributedString (NSExtendedAttributedString) 扩展属性字符串
// 字符串的长度
@property (readonly) NSUInteger length;
- (nullable id)attribute:(NSString *)attrName atIndex:(NSUInteger)location effectiveRange:(nullable NSRangePointer)range;
//
- (NSAttributedString *)attributedSubstringFromRange:(NSRange)range;
- (NSDictionary<NSString *, id> *)attributesAtIndex:(NSUInteger)location longestEffectiveRange:(nullable NSRangePointer)range inRange:(NSRange)rangeLimit;
- (nullable id)attribute:(NSString *)attrName atIndex:(NSUInteger)location longestEffectiveRange:(nullable NSRangePointer)range inRange:(NSRange)rangeLimit;
// 比较两个 NSAttributedString 字符串是否相等
- (BOOL)isEqualToAttributedString:(NSAttributedString *)other;
// NSAttributedString 的创建方法
/*
- 1. 通过 NSString 字符串来创建
- 2. 通过 NSString 和 attribute 字典来创建
- 3. 通过一个 NSAttributedString 来创建
*/
- (instancetype)initWithString:(NSString *)str;
- (instancetype)initWithString:(NSString *)str attributes:(nullable NSDictionary<NSString *, id> *)attrs;
- (instancetype)initWithAttributedString:(NSAttributedString *)attrStr;
typedef NS_OPTIONS(NSUInteger, NSAttributedStringEnumerationOptions) {
NSAttributedStringEnumerationReverse = (1UL << 1),
NSAttributedStringEnumerationLongestEffectiveRangeNotRequired = (1UL << 20)
};
- (void)enumerateAttributesInRange:(NSRange)enumerationRange options:(NSAttributedStringEnumerationOptions)opts usingBlock:(void (^)(NSDictionary<NSString *, id> *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 __nullable 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:(nullable NSDictionary<NSString *, id> *)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<NSString *, id> *)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
NS_ASSUME_NONNULL_END
UIKit
//
// NSAttributedString.h
// UIKit
//
// Copyright (c) 2011-2015, Apple Inc. All rights reserved.
//
#import <Foundation/NSAttributedString.h>
#import <UIKit/UIKitDefines.h>
@class NSFileWrapper;
@class NSURL;
NS_ASSUME_NONNULL_BEGIN
/************************ Attributes * 这下面就是一些属性的 key 值 ***********************/
// Predefined character attributes for text. If the key is not in the dictionary, then use the default values as described below.
// 预定义的文本字符属性，如果这个key 不在字典里面，那么文本将使用下面描述的默认值。
UIKIT_EXTERN NSString * const NSFontAttributeName NS_AVAILABLE(10_0, 6_0);
// UIFont, default Helvetica(Neue) 12
（字体 默认：Helvetica(Neue) 12 ）
UIKIT_EXTERN NSString * const NSParagraphStyleAttributeName NS_AVAILABLE(10_0, 6_0);
// NSParagraphStyle, default defaultParagraphStyle
（段落样式 默认： defaultParagraphStyle）
UIKIT_EXTERN NSString * const NSForegroundColorAttributeName NS_AVAILABLE(10_0, 6_0);
// UIColor, default blackColor
（字体显示的颜色（前景颜色） 默认： 黑色）
UIKIT_EXTERN NSString * const NSBackgroundColorAttributeName NS_AVAILABLE(10_0, 6_0);
// UIColor, default nil: no background
（字体的背景颜色 默认： 没有颜色）
UIKIT_EXTERN NSString * const NSLigatureAttributeName NS_AVAILABLE(10_0, 6_0);
// NSNumber containing integer, default 1: default ligatures, 0: no ligatures
（连体字 默认是 1 ：连体字，0：不是连体字。系统字体不包含对连体字的支持）
UIKIT_EXTERN NSString * const NSKernAttributeName NS_AVAILABLE(10_0, 6_0);
// NSNumber containing floating point value, in points; amount to modify default kerning. 0 means kerning is disabled.
UIKIT_EXTERN NSString * const NSStrikethroughStyleAttributeName NS_AVAILABLE(10_0, 6_0);
// NSNumber containing integer, default 0: no strikethrough
UIKIT_EXTERN NSString * const NSUnderlineStyleAttributeName NS_AVAILABLE(10_0, 6_0);
// NSNumber containing integer, default 0: no underline
(下划线 默认 0 ： 没有下划线)
UIKIT_EXTERN NSString * const NSStrokeColorAttributeName NS_AVAILABLE(10_0, 6_0);
// UIColor, default nil: same as foreground color
(文字边框的颜色 默认：和前景颜色是一样的，和前景颜色不一致，前景颜色失效。只有在边框宽度设置了后才有效果)
UIKIT_EXTERN NSString * const NSStrokeWidthAttributeName NS_AVAILABLE(10_0, 6_0);
// NSNumber containing floating point value, in percent of font point size, default 0: no stroke; positive for stroke alone, negative for stroke and fill (a typical value for outlined text would be 3.0)
(文字边框的宽度，使用的是浮点主，字体大小的百分比。 默认是 0 ，没有边框)
UIKIT_EXTERN NSString * const NSShadowAttributeName NS_AVAILABLE(10_0, 6_0);
// NSShadow, default nil: no shadow
(阴影 默认是没有阴影)
UIKIT_EXTERN NSString *const NSTextEffectAttributeName NS_AVAILABLE(10_10, 7_0);
// NSString, default nil: no text effect
(文本效果 默认是 nil ，没有效果)
UIKIT_EXTERN NSString * const NSAttachmentAttributeName NS_AVAILABLE(10_0, 7_0);
// NSTextAttachment, default nil
UIKIT_EXTERN NSString * const NSLinkAttributeName NS_AVAILABLE(10_0, 7_0);
// NSURL (preferred) or NSString
UIKIT_EXTERN NSString * const NSBaselineOffsetAttributeName NS_AVAILABLE(10_0, 7_0);
// NSNumber containing floating point value, in points; offset from baseline, default 0
(文字的基准线，表明文字相对于其他文字基准线向上的偏移量)
UIKIT_EXTERN NSString * const NSUnderlineColorAttributeName NS_AVAILABLE(10_0, 7_0);
// UIColor, default nil: same as foreground color
(下划线的颜色，默认是 nil ，和前景颜色一样的颜色)
UIKIT_EXTERN NSString * const NSStrikethroughColorAttributeName NS_AVAILABLE(10_0, 7_0);
// UIColor, default nil: same as foreground color
UIKIT_EXTERN NSString * const NSObliquenessAttributeName NS_AVAILABLE(10_0, 7_0);
// NSNumber containing floating point value; skew to be applied to glyphs, default 0: no skew
UIKIT_EXTERN NSString * const NSExpansionAttributeName NS_AVAILABLE(10_0, 7_0);
// NSNumber containing floating point value; log of expansion factor to be applied to glyphs, default 0: no expansion
UIKIT_EXTERN NSString * const NSWritingDirectionAttributeName NS_AVAILABLE(10_6, 7_0);
/*
NSArray of NSNumbers representing the nested levels of writing direction overrides as defined by Unicode LRE, RLE, LRO, and RLO characters.
The control characters can be obtained by masking NSWritingDirection and NSTextWritingDirection values.
LRE: NSWritingDirectionLeftToRight|NSWritingDirectionEmbedding,
RLE: NSWritingDirectionRightToLeft|NSWritingDirectionEmbedding,
LRO: NSWritingDirectionLeftToRight|NSWritingDirectionOverride,
RLO: NSWritingDirectionRightToLeft|NSWritingDirectionOverride,
*/
(文字的书写方向)
UIKIT_EXTERN NSString * const NSVerticalGlyphFormAttributeName NS_AVAILABLE(10_7, 6_0);
/*
An NSNumber containing an integer value. 0 means horizontal text.
1 indicates vertical text.
If not specified, it could follow higher-level vertical orientation settings.
Currently on iOS, it's always horizontal.
The behavior for any other value is undefined.
*/
/************************ Attribute values * 这下面就是一些属性的 key 对应的值***********************/
// This defines currently supported values for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName. NSUnderlineStyle*, NSUnderlinePattern*, and NSUnderlineByWord are or'ed together to produce an underline style.
下划线的样式
typedef NS_ENUM(NSInteger, NSUnderlineStyle) {
NSUnderlineStyleNone = 0x00, // 没有下划线
NSUnderlineStyleSingle = 0x01, // 单行
NSUnderlineStyleThick NS_ENUM_AVAILABLE(10_0, 7_0) = 0x02, // 单行加粗
NSUnderlineStyleDouble NS_ENUM_AVAILABLE(10_0, 7_0) = 0x09, // 双行
NSUnderlinePatternSolid NS_ENUM_AVAILABLE(10_0, 7_0) = 0x0000,
NSUnderlinePatternDot NS_ENUM_AVAILABLE(10_0, 7_0) = 0x0100,
NSUnderlinePatternDash NS_ENUM_AVAILABLE(10_0, 7_0) = 0x0200,
NSUnderlinePatternDashDot NS_ENUM_AVAILABLE(10_0, 7_0) = 0x0300,
NSUnderlinePatternDashDotDot NS_ENUM_AVAILABLE(10_0, 7_0) = 0x0400,
NSUnderlineByWord NS_ENUM_AVAILABLE(10_0, 7_0) = 0x8000
} NS_ENUM_AVAILABLE(10_0, 6_0);
// NSWritingDirectionFormatType values used by NSWritingDirectionAttributeName. It is or'ed with either NSWritingDirectionLeftToRight or NSWritingDirectionRightToLeft. Can specify the formatting controls defined by Unicode Bidirectional Algorithm.
typedef NS_ENUM(NSInteger, NSWritingDirectionFormatType) {
NSWritingDirectionEmbedding = (0 << 1),
NSWritingDirectionOverride = (1 << 1)
} NS_ENUM_AVAILABLE(10_11, 9_0);
// NSTextEffectAttributeName values
UIKIT_EXTERN NSString *const NSTextEffectLetterpressStyle NS_AVAILABLE(10_10, 7_0);
/************************ Attribute fixing ************************/
@interface NSMutableAttributedString (NSAttributedStringAttributeFixing)
// This method fixes attribute inconsistencies inside range. It ensures NSFontAttributeName covers the characters, NSParagraphStyleAttributeName is only changing at paragraph boundaries, and NSTextAttachmentAttributeName is assigned to NSAttachmentCharacter. NSTextStorage automatically invokes this method via -ensureAttributesAreFixedInRange:.
- (void)fixAttributesInRange:(NSRange)range NS_AVAILABLE(10_0, 7_0);
@end
/************************ Document formats ************************/
// Supported document types for the NSDocumentTypeDocumentAttribute key in the document attributes dictionary.
UIKIT_EXTERN NSString * const NSPlainTextDocumentType NS_AVAILABLE(10_0, 7_0);
UIKIT_EXTERN NSString * const NSRTFTextDocumentType NS_AVAILABLE(10_0, 7_0);
UIKIT_EXTERN NSString * const NSRTFDTextDocumentType NS_AVAILABLE(10_0, 7_0);
UIKIT_EXTERN NSString * const NSHTMLTextDocumentType NS_AVAILABLE(10_0, 7_0);
// Keys for NSLayoutOrientationSectionsAttribute.
UIKIT_EXTERN NSString * const NSTextLayoutSectionOrientation NS_AVAILABLE(10_7, 7_0);
// NSNumber containing NSTextLayoutOrientation value. default: NSTextLayoutOrientationHorizontal
UIKIT_EXTERN NSString * const NSTextLayoutSectionRange NS_AVAILABLE(10_7, 7_0);
// NSValue containing NSRange representing a character range. default: a range covering the whole document
// Keys for options and document attributes dictionaries. They are in and out document properties used by both read/write methods.
UIKIT_EXTERN NSString * const NSDocumentTypeDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"DocumentType", one of the document types declared above. For reader methods, this key in options can specify the document type for interpreting the contents. Upon return, the document attributes can contain this key for indicating the actual format used to read the contents. For write methods, this key specifies the format for generating the data.
// NSPlainTextDocumentType document attributes
UIKIT_EXTERN NSString * const NSCharacterEncodingDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"CharacterEncoding", NSNumber containing integer specifying NSStringEncoding for the file; default for plain text is the default encoding. This key in options can specify the string encoding for reading the data. Upon return, the document attributes can contain the actual encoding used. For writing methods, this value is used for generating the plain text data.
UIKIT_EXTERN NSString * const NSDefaultAttributesDocumentAttribute NS_AVAILABLE(10_11, 7_0);
// @"DefaultAttributes", NSDictionary containing attributes to be applied to plain files. Used by reader methods. This key in options can specify the default attributes applied to the entire document contents. The document attributes can contain this key indicating the actual attributes used.
// NSRTFTextDocumentType and NSRTFDTextDocumentType document attributes
// Document dimension
// They are document attributes used by read/write methods.
UIKIT_EXTERN NSString * const NSPaperSizeDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"PaperSize", NSValue containing CGSize (in points)
UIKIT_EXTERN NSString * const NSPaperMarginDocumentAttribute NS_AVAILABLE_IOS(7_0);
// @"PaperMargin", NSValue containing UIEdgeInsets
UIKIT_EXTERN NSString * const NSViewSizeDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"ViewSize", NSValue containing CGSize (in points)
UIKIT_EXTERN NSString * const NSViewZoomDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"ViewZoom", NSNumber containing floating point value (100 == 100% zoom)
UIKIT_EXTERN NSString * const NSViewModeDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"ViewMode", NSNumber containing integer; 0 = normal; 1 = page layout
// Document settings
// They are document attributes used by read/write methods.
UIKIT_EXTERN NSString * const NSReadOnlyDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"ReadOnly", NSNumber containing integer; if missing, or 0 or negative, not readonly; 1 or more, readonly. Note that this has nothing to do with the file system protection on the file, but instead, on how the file should be displayed to the user
UIKIT_EXTERN NSString * const NSBackgroundColorDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"BackgroundColor", UIColor, representing the document-wide page background color
UIKIT_EXTERN NSString * const NSHyphenationFactorDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"HyphenationFactor", NSNumber containing floating point value (0=off, 1=full hyphenation)
UIKIT_EXTERN NSString * const NSDefaultTabIntervalDocumentAttribute NS_AVAILABLE(10_0, 7_0);
// @"DefaultTabInterval", NSNumber containing floating point value, representing the document-wide default tab stop interval, in points
UIKIT_EXTERN NSString * const NSTextLayoutSectionsAttribute NS_AVAILABLE(10_7, 7_0);
// NSArray of dictionaries. Each dictionary describing a layout orientation section. The dictionary can have two attributes: NSTextLayoutSectionOrientation and NSTextLayoutSectionRange. When there is a gap between sections, it's assumed to have NSTextLayoutOrientationHorizontal.
@interface NSAttributedString (NSAttributedStringDocumentFormats)
// Methods initializing the receiver contents with an external document data. options specify document attributes for interpreting the document contents. NSDocumentTypeDocumentAttribute, NSCharacterEncodingDocumentAttribute, and NSDefaultAttributesDocumentAttribute are supported options key. When they are not specified, these methods will examine the data and do their best to detect the appropriate attributes. If dict is non-NULL, it will return a dictionary with various document-wide attributes accessible via NS...DocumentAttribute keys.
- (nullable instancetype)initWithURL:(NSURL *)url options:(NSDictionary<NSString *, id> *)options documentAttributes:(NSDictionary<NSString *, id> * __nullable * __nullable)dict error:(NSError **)error NS_AVAILABLE(10_11, 9_0);
- (nullable instancetype)initWithData:(NSData *)data options:(NSDictionary<NSString *, id> *)options documentAttributes:(NSDictionary<NSString *, id> * __nullable * __nullable)dict error:(NSError **)error NS_AVAILABLE(10_0, 7_0);
// Generates an NSData object for the receiver contents in range. It requires a document attributes dict specifying at least the NSDocumentTypeDocumentAttribute to determine the format to be written.
- (nullable NSData *)dataFromRange:(NSRange)range documentAttributes:(NSDictionary<NSString *, id> *)dict error:(NSError **)error NS_AVAILABLE(10_0, 7_0);
// Returns an NSFileWrapper object for the receiver contents in range. It requires a document attributes dict specifying at least the NSDocumentTypeDocumentAttribute to determine the format to be written. The method returns a directory file wrapper for those document types represented by a file package such as NSRTFDTextDocumentType; otherwise, it returns a regular-file file wrapper.
- (nullable NSFileWrapper *)fileWrapperFromRange:(NSRange)range documentAttributes:(NSDictionary<NSString *, id> *)dict error:(NSError **)error NS_AVAILABLE(10_0, 7_0);
@end
@interface NSMutableAttributedString (NSMutableAttributedStringDocumentFormats)
// Methods replacing the receiver contents with an external document data. options specify document attributes for interpreting the document contents. NSDocumentTypeDocumentAttribute, NSCharacterEncodingDocumentAttribute, and NSDefaultAttributesDocumentAttribute are supported options key. When they are not specified, these methods will examine the data and do their best to detect the appropriate attributes. If dict is non-NULL, it will return a dictionary with various document-wide attributes accessible via NS...DocumentAttribute keys.
- (BOOL)readFromURL:(NSURL *)url options:(NSDictionary<NSString *, id> *)opts documentAttributes:(NSDictionary<NSString *, id> * __nullable * __nullable)dict error:(NSError **)error NS_AVAILABLE(10_11, 9_0);
- (BOOL)readFromData:(NSData *)data options:(NSDictionary<NSString *, id> *)opts documentAttributes:(NSDictionary<NSString *, id> * __nullable * __nullable)dict error:(NSError **)error NS_AVAILABLE(10_0, 7_0);
@end
/************************ Misc methods ************************/
@interface NSAttributedString (NSAttributedStringKitAdditions)
// Returns YES if the receiver contains a property configured (NSAttachmentAttributeName with NSAttachmentCharacter) in range
- (BOOL)containsAttachmentsInRange:(NSRange)range NS_AVAILABLE(10_11, 9_0);
@end
/************************ Deprecated ************************/
typedef NS_ENUM(NSInteger, NSTextWritingDirection) {
NSTextWritingDirectionEmbedding = (0 << 1),
NSTextWritingDirectionOverride = (1 << 1)
} NS_ENUM_DEPRECATED_IOS(7_0, 9_0, "Use NSWritingDirectionFormatType instead") __TVOS_PROHIBITED;
@interface NSAttributedString(NSDeprecatedKitAdditions)
- (nullable instancetype)initWithFileURL:(NSURL *)url options:(NSDictionary *)options documentAttributes:(NSDictionary* __nullable * __nullable)dict error:(NSError **)error NS_DEPRECATED_IOS(7_0, 9_0, "Use -initWithURL:options:documentAttributes:error: instead") __TVOS_PROHIBITED;
@end
@interface NSMutableAttributedString (NSDeprecatedKitAdditions)
- (BOOL)readFromFileURL:(NSURL *)url options:(NSDictionary *)opts documentAttributes:(NSDictionary* __nullable * __nullable)dict error:(NSError **)error NS_DEPRECATED_IOS(7_0, 9_0, "Use -readFromURL:options:documentAttributes:error: instead") __TVOS_PROHIBITED;
@end
NS_ASSUME_NONNULL_END
网友评论