200506--iOS之NSAttributedString类

Class

NSAttributedString

A string that has associated attributes (such as visual style, hyperlinks, or accessibility data) for portions of its text.

          --一种字符串，它的部分文本具有相关属性（如视觉样式、超链接或辅助功能数据）。

Declaration

class NSAttributedString : NSObject

Overview      --概览

An NSAttributedString object manages character strings and associated sets of attributes (for example, font and kerning) that apply to individual characters or ranges of characters in the string. An association of characters and their attributes is called an attributed string. The cluster’s two public classes, NSAttributedString and NSMutableAttributedString, declare the programmatic interface for read-only attributed strings and modifiable attributed strings, respectively.

     NSAttributedString对象管理字符串以及与字符串相关的属性集(例如，字体和字距)，这些属性应用于字符串中的单个字符或某范围内的字符。字符及其关联的属性称为带属性的字符串。集群的两个公共类 NSAttributedString 和 NSMutableAttributedString 分别声明只读带属性字符串和可修改带属性字符串的编程接口。

An attributed string identifies attributes by name, using an NSDictionary object to store a value under the given name. You can assign any attribute name/value pair you wish to a range of characters—it is up to your application to interpret custom attributes (see Attributed String Programming Guide). If you are using attributed strings with the Core Text framework, you can also use the attribute keys defined by that framework.

          --属性字符串按名称标识属性，使用NSDictionary对象在给定名称下存储值。您可以将想要的属性的 名/值 对 分配给某范围内的字符，由app来解释自定义属性（请参阅Attributed String Programming Guide）。如果在核心文本框架中使用属性字符串，也可以使用该框架定义的属性键。

You use attributed strings with any APIs that accept them, such as Core Text. The AppKit and UIKit frameworks also provide a subclass of NSMutableAttributedString, called NSTextStorage, to provide the storage for the extended text-handling system. In iOS 6 and later you can use attributed strings to display formatted text in text views, text fields, and some other controls. Both AppKit and UIKit also define extensions to the basic attributed string interface that allows you to draw their contents in the current graphic context.

        --你可以将属性字符串与接受它们的api（如Core Text）一起使用。AppKit和UIKit框架还提供了NSMutableAttributedString的一个子类，称为NSTextStorage，为扩展文本处理系统提供存储。在iOS 6和更高版本中，可以使用属性化字符串在text views, text fields和一些其他控件中显示格式化文本。AppKit和UIKit还定义了基本属性字符串接口的extensions，该接口允许您在当前图形上下文中绘制它们的内容。

The default font for NSAttributedString objects is Helvetica 12-point, which may differ from the default system font for the platform. Thus, you might want to create new strings with non-default attributes suitable for your application. You can also use the NSParagraphStyle class and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes.

      --NSAttributedString对象的默认字体是Helvetica 12-point,，它可能与平台的默认系统字体不同。因此，您可能希望创建没有默认属性的新字符串。那么，你可以使用NSParagraphStyle类及其子类NSMutableParagraphStyle来封装NSAttributedString类使用的段落或标尺属性。

Be aware that comparisons of NSAttributedString objects using the isEqual(_:) method look for exact equality. The comparison includes both a character-by-character string equality check and an equality check of all attributes. Such a comparison is not likely to yield a match if the string has many attributes, such as attachments, lists, and tables, for example.

      --请注意，使用isEqual（:）方法对NSAttributedString对象进行比较会寻找完全相等的值。比较包括逐个字符串的相等检查和所有属性的相等检查。如果字符串具有许多属性（例如附件、列表和表），则这样的比较 可能。产生不匹配。

The NSAttributedString class is “toll-free bridged” with its Core Foundation counterpart, CFAttributedString. See Toll-Free Bridging for more information.

      --NSAttributedString类与其核心基础对应项CFAttributedString是“免费桥接”的。有关详细信息，请参阅免费桥接。

 

Topics            --专题

Creating an NSAttributedString Object           --创建一个NSAttributedString对象

init(string: String)

Returns an NSAttributedString object initialized with the characters of a given string and no attribute information.

init(string: String, attributes: [NSAttributedString.Key : Any]?)

Returns an NSAttributedString object initialized with a given string and attributes.

init(attributedString: NSAttributedString)

Returns an NSAttributedString object initialized with the characters and attributes of another given attributed string.

init(data: Data, options: [NSAttributedString.DocumentReadingOptionKey : Any], documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes and returns a new attributed string object from the data contained in the given data object.

init?(docFormat: Data, documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes and returns a new NSAttributedString object from Microsoft Word format data contained in the given NSData object.

init?(html: Data, documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes and returns a new NSAttributedString object from HTML contained in the given data object.

init?(html: Data, baseURL: URL, documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes and returns a new NSAttributedString object from the HTML contained in the given object and base URL.

init?(html: Data, options: [NSAttributedString.DocumentReadingOptionKey : Any], documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes and returns a new attributed string object from HTML contained in the given data object.

init?(rtf: Data, documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes a new attributed string object by decoding the stream of RTF commands and data contained in the given data object.

init?(rtfd: Data, documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes a new attributed string object by decoding the stream of RTFD commands and data contained in the given data object.

init?(rtfdFileWrapper: FileWrapper, documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes a new attributed string object from the specified file wrapper containing an RTFD document.

init(url: URL, options: [NSAttributedString.DocumentReadingOptionKey : Any], documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes a new NSAttributedString object from the contents of the given URL.

init(attachment: NSTextAttachment)

Creates an attributed string with an attachment.

 

Retrieving Character Information        --获取字符信息

var string: String

The character contents of the receiver as an NSString object.

var length: Int

The length of the receiver’s string object.

 

Retrieving Attribute Information       --获取字符属性信息

func attributes(at: Int, effectiveRange: NSRangePointer?) -> [NSAttributedString.Key : Any]

Returns the attributes for the character at a given index.

func attributes(at: Int, longestEffectiveRange: NSRangePointer?, in: NSRange) -> [NSAttributedString.Key : Any]

Returns the attributes for the character at a given index, and by reference the range over which the attributes apply.

func attribute(NSAttributedString.Key, at: Int, effectiveRange: NSRangePointer?) -> Any?

Returns the value for an attribute with a given name of the character at a given index, and by reference the range over which the attribute applies.

func attribute(NSAttributedString.Key, at: Int, longestEffectiveRange: NSRangePointer?, in: NSRange) -> Any?

Returns the value for the attribute with a given name of the character at a given index, and by reference the range over which the attribute applies.

 

Comparing Attributed Strings              --比较属性字符串

func isEqual(to: NSAttributedString) -> Bool

Returns a Boolean value that indicates whether the receiver is equal to another given attributed string.

 

Extracting a Substring               --抽取子字符串

func attributedSubstring(from: NSRange) -> NSAttributedString

Returns an NSAttributedString object consisting of the characters and attributes within a given range in the receiver.

 

Enumerating over Attributes in a String          --枚举字符串的属性

func enumerateAttribute(NSAttributedString.Key, in: NSRange, options: NSAttributedString.EnumerationOptions, using: (Any?, NSRange, UnsafeMutablePointer<ObjCBool>) -> Void)

Executes the specified closure for each range of a particular attribute in the attributed string.

func enumerateAttributes(in: NSRange, options: NSAttributedString.EnumerationOptions, using: ([NSAttributedString.Key : Any], NSRange, UnsafeMutablePointer<ObjCBool>) -> Void)

Executes the specified closure for each range of attributes in the attributed string.

 

Retrieving Font Attribute Information            --获取字体属性信息

func fontAttributes(in: NSRange) -> [NSAttributedString.Key : Any]

Returns the font attributes in effect for the character at the given location.

func rulerAttributes(in: NSRange) -> [NSAttributedString.Key : Any]

Returns the ruler (paragraph) attributes in effect for the characters within the given range.

 

Calculating Linguistic Units             --计算语言单位

func doubleClick(at: Int) -> NSRange

Returns the range of characters that form a word (or other linguistic unit) surrounding the given index, taking language characteristics into account.

func lineBreak(before: Int, within: NSRange) -> Int

Returns the appropriate line break when the character at the index won’t fit on the same line as the character at the beginning of the range.

func lineBreakByHyphenating(before: Int, within: NSRange) -> Int

Returns the index of the closest character before the given index, and within the given range, that can be placed on a new line by hyphenating.

func nextWord(from: Int, forward: Bool) -> Int

Returns the index of the first character of the word after or before the given index.

 

Calculating Ranges                --计算字符范围

func itemNumber(in: NSTextList, at: Int) -> Int

Returns the index of the item at the given location within the list.

func range(of: NSTextBlock, at: Int) -> NSRange

Returns the range of the individual text block that contains the given location.

func range(of: NSTextList, at: Int) -> NSRange

Returns the range of the given text list that contains the given location.

func range(of: NSTextTable, at: Int) -> NSRange

Returns the range of the given text table that contains the given location

 

Generating Data           --生成数据

func data(from: NSRange, documentAttributes: [NSAttributedString.DocumentAttributeKey : Any]) -> Data

Returns an data object that contains a text stream corresponding to the characters and attributes within the given range.

func fileWrapper(from: NSRange, documentAttributes: [NSAttributedString.DocumentAttributeKey : Any]) -> FileWrapper

Returns an NSFileWrapper object that contains a text stream corresponding to the characters and attributes within the given range.

func docFormat(from: NSRange, documentAttributes: [NSAttributedString.DocumentAttributeKey : Any]) -> Data?

Returns a data object that contains a Microsoft Word–format stream corresponding to the characters and attributes within the specified range.

func rtf(from: NSRange, documentAttributes: [NSAttributedString.DocumentAttributeKey : Any]) -> Data?

Returns an NSData object that contains an RTF stream corresponding to the characters and attributes within the given range, omitting all attachment attributes.

func rtfd(from: NSRange, documentAttributes: [NSAttributedString.DocumentAttributeKey : Any]) -> Data?

Returns a data object that contains an RTFD stream corresponding to the characters and attributes within the range.

func rtfdFileWrapper(from: NSRange, documentAttributes: [NSAttributedString.DocumentAttributeKey : Any]) -> FileWrapper?

Returns an NSFileWrapper object that contains an RTFD document corresponding to the characters and attributes within the given range.

 

Drawing the String           --绘制字符串

func draw(at: CGPoint)

Draws the attributed string starting at the specified point in the current graphics context.

func draw(in: CGRect)

Draws the attributed string inside the specified bounding rectangle in the current graphics context.

func draw(with: CGRect, options: NSStringDrawingOptions, context: NSStringDrawingContext?)

Draws the attributed string in the specified bounding rectangle using the provided options.

 

Getting Metrics for the String          --获取字符串的量度

func size() -> CGSize

Returns the size required to draw the string.

func boundingRect(with: CGSize, options: NSStringDrawingOptions, context: NSStringDrawingContext?) -> CGRect

Returns the bounding rectangle required to draw the string.

func containsAttachments(in: NSRange) -> Bool

Returns a Boolean value that indicates if the attributed string contains a property configured in the specified range.

 

Testing String Data Sources           --测试字符串的数据源

class var textTypes: [String]

Returns an array of UTI strings identifying the file types supported by the receiver, either directly or through a user-installed filter service.

class var textUnfilteredTypes: [String]

Returns an array of UTI strings identifying the file types supported directly by the receiver.

 

Constants             --常量

struct NSAttributedString.Key

Attributes that you can apply to text in an attributed string.

struct NSAttributedString.DocumentAttributeKey

Attributes that apply to a document.

struct NSAttributedString.DocumentType

Constants that can be returned for the document type in the document attributes dictionary.

struct NSAttributedString.DocumentReadingOptionKey

Options for importing documents

struct NSAttributedString.TextLayoutSectionKey

Values for the textLayoutSections key.

struct NSAttributedString.TextEffectStyle

A value for the textEffect key.

enum NSAttributedString.SpellingState

Values for the spellingState attribute key.

enum NSWritingDirectionFormatType

Options for specifying writing direction used with writingDirection.

enum NSTextWritingDirection

Options for specifying text writing direction used with writingDirection.

Deprecatedstruct NSUnderlineStyle

Constants for specifying both the underlineStyle and strikethroughStyle attributes of an attributed string.

struct NSAttributedString.EnumerationOptions

These constants describe the options available to the enumerateAttribute(_:in:options:using:) and enumerateAttributes(in:options:using:) methods.

 

Attributes for Generating HTML

These document-wide attributes provide control over the form of generated HTML—you use them only for writing HTML

 

Deprecated Methods         --已经被丢弃了的方法

init?(path: String, documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes a new attribute string object from RTF or RTFD data contained in the file at the given path.

Deprecatedinit?(url: URL, documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes a new attributed string object from the data at the given URL.

Deprecatedinit(fileURL: URL, options: [AnyHashable : Any], documentAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>?)

Initializes a new attributed string object from the data at the given URL.

Deprecatedvar containsAttachments: Bool

Returns whether the attribute string contains any attachment attributes.

Deprecatedfunc url(at: Int, effectiveRange: NSRangePointer) -> URL?

Returns a URL, either from a link attribute or from text at the given location that appears to be a URL string, for use in automatic link detection.

Deprecatedfunc draw(with: NSRect, options: NSString.DrawingOptions)

Draws the receiver with the specified options, within the given rectangle in the current graphics context.

Deprecatedfunc boundingRect(with: NSSize, options: NSString.DrawingOptions) -> NSRect

Calculates and returns bounding rectangle for the receiver drawn using the options specified, within the given rectangle in the current graphics context.

Deprecated

 

Type Aliases         --类型别名

typealias NSAttributedString.CompletionHandler

 

Type Methods         --类方法

class func loadFromHTML(data: Data, options: [NSAttributedString.DocumentReadingOptionKey : Any], completionHandler: NSAttributedString.CompletionHandler)

class func loadFromHTML(fileURL: URL, options: [NSAttributedString.DocumentReadingOptionKey : Any], completionHandler: NSAttributedString.CompletionHandler)

class func loadFromHTML(request: URLRequest, options: [NSAttributedString.DocumentReadingOptionKey : Any], completionHandler: NSAttributedString.CompletionHandler)

class func loadFromHTML(string: String, options: [NSAttributedString.DocumentReadingOptionKey : Any], completionHandler: NSAttributedString.CompletionHandler)

 

Relationships           --继承关系

Inherits From

NSObject

Conforms To

• CVarArg

• Equatable

• Hashable

• NSCopying

• NSItemProviderReading

• NSItemProviderWriting

• NSMutableCopying

• NSPasteboardReading

• NSPasteboardWriting

• NSSecureCoding

See Also

Strings with Metadata

class NSMutableAttributedString

A mutable string object that also contains attributes (such as visual style, hyperlinks, or accessibility data) associated with various portions of its text content.