NSAttributedString

この翻訳は2012-09-19のバージョンのものです。

スーパークラス：NSObJect
適合プロトコル：NSCopying, NSSecureCoding, NSObject, NSMutableCopying
フレームワーク：Foundation in iOS3.2 and later, More lerated items ...

概要

NSAttributedString オブジェクトは文字列とその属性（たとえばフォントやカーニングなど）を管理するもので、これは一つ一つの文字または文字列について、指定する範囲の文字に適用されます。文字とその属性が組になったものが属性付き文字列です。２つのパブリッククラスのクラスター、NSAttributedString とNSMutableAttributedString? があり、前者は読み専用の属性付き文字列、後者は読み書き可能な属性文字列へのプログラムインターフェイスを宣言しています。

属性付き文字列は名前で識別されいて、NSDictionay オブジェクトを使い、その名前をキーとして保持しています。お好みの名前／値のペアーを文字列の範囲に割り振ることができ、その名前をカスタム属性としてアプリ全体で使用可能です（属性付き文字列のプログラミングガイド NSMutableAttributedString? を参照してください）。Core Text フレームワークで属性付き文字列を使うと、そこで定義されている属性も利用できます。iOS においては、標準の属性が NSAttributedString UIKit Additions Reference? にある「定数」の項目に載っています。おなじように OSX では NSAttributedString Application Kit Additions Reference にあります。

属性付き文字列は、これを受け付ける API、たとえば Core Text で使用できます。Application Kit と UIKit でも NSMutableAttributedString のサブクラスである NSTextStorage? を提供しており、これはより拡張されたテキストの操作方法を備えています。iOS 6 以降では属性付き文字列を テキストビューやテキストフィールド、そのほかのコントロールでテキストを表示するのに使えます。AppKit および UIKit においては、必要不可欠な属性付き文字列にまでインターフェイスを拡張し、グラフィックコンテキストの中で、そのコンテキストを描画することができるようになります。

NSAttributedString オブジェクトのデフォルトフォントは Helvetica 12 ポイントですが、プラットフォームよっては違うフォントの可能性があります。したがって、開発しているアプリに適している、デフォルトではない属性の文字列がほしいときがあるでしょう。NSParagraphStyle? とそのサブクラスの NSMutableParagraphStyle? をパラグラフをカプセル化に使用することもできますが、NSAttributedString を使用して統一した属性を使用することもできます。

２つの NSAttributedString オブジェクトが厳密に同じかどうか isEqual: メソッドを使用するときは注意してください。ここでの比較には、一つ一つの文字の組が同じかどうか調べるとともに、それぞれの属性すべてもチェックします。この比較では、もし属性付き文字列に付加的属性やリスト、テーブルなどの属性がたくさん付いている場合には失敗するでしょう。

NSAttributedString クラスは、Core Foundation で対となる CFAttributedStringRef? と "toll-free bridged?” です。詳しくは[[Toll-Free Bridging>guide/Toll-Free Bridging]を参照してください。

タスク

NSAttributedString オブジェクトの生成

- initWithString:

属性情報を持たない文字列をから初期化した NSAttributedString オブジェクトを返す。

宣言
SWIFT

	init(string '''aString''': String)

OBJECTIVE-C

	- (instancetype)initWithString:(NSString *)aString

パラメータ

戻り値
属性情報を持たない aString 文字列をもって初期化した NSAttributedString オブジェクト。返されるオブジェクトは本来のレシーバとはちがう可能性があります。

- initWithAttributedString:

与えられた属性付き文字列の文字と属性をもった NSAttributedString オブジェクトを返します。

宣言
SWIFT

	init(attributedString attributedString: NSAttributedString)

OBJECTIVE-C

	- (instancetype)initWithAttributedString:(NSAttributedString *)attributedString

パラメータ

戻り値
与えられた属性付き文字列の文字と属性をもった NSAttributedString オブジェクト。返されるオブジェクトは本来のレシーバとは違う可能性があります。

- initWithString:attributes:

引数の文字列と属性で初期化された NSAttributedString オブジェクトを返します。

宣言
SWIFT

	init(string aString: String, attributes attributes: [NSObject : AnyObject]?)

OBJECTIVE-C

	- (instancetype)initWithString:(NSString *)aString attributes:(NSDictionary *)attributes

パラメータ

考察
引数の aString 文字列と attributes 属性で初期化された NSAttributedString オブジェクトを返します。返されるオブジェクトは本来のレシーバとは違う可能性があります。

@import Foundation;

import Foundation

文字情報の取得

string Property

レシーバーがもつ文字列を NSString オブジェクトとして表現したもの（読み専用）。

宣言
SWIFT

	var string: String { get }

OBJECTIVE-C

	@property(readonly, copy) NSString *string

考察
このプロパティは、付加されている文字が取り除かれていません。

パフォーマンスを上げるために、この属性付き文字列のオブジェクトが内部で保存している領域から直接に、このプロパティを返しています。オブジェクトを保存しつつ、このプロパティの文字列を操作する場合は、適切なコピーを使用すべきでしょう。

この基本的なプロパティは属性付き文字列の文字を効率よく取得しなくてはなりません。したがって、このクラスのサブクラスを作成したら、O(1) time 以内に取得できるようにすべきでしょう。

@import Foundation;

import Foundation

length Property

レシーバが持つ文字列オブジェクトの長さ（読み専用）。

宣言
SWIFT

	var length: Int { get }

OBJECTIVE-C

	@property(readonly) NSUInteger length

@import Foundation;

import Foundation

属性情報の取得

- attributesAtIndex:effectiveRange:

引数のインデックス位置にある属性を返す。

宣言
SWIFT

	func attributesAtIndex(_ index: Int, effectiveRange aRange: NSRangePointer) -> [NSObject : AnyObject]

OBJECTIVE-C

	- (NSDictionary *)attributesAtIndex:(NSUInteger)index effectiveRange:(NSRangePointer)aRange

パラメータ

戻り値
インデックスの位置にある文字の属性。

考察
レシーバーの文字の終わりを越えたインデックスを与えると、NSRangeException が発生します。

返された辞書にある属性キーを調べたい場合は、この書類の概要部分を参照してください。

@import Foundation;

import Foundation

- attributesAtIndex:longestEffectiveRange:inRange:

引数インデックスの位置にある文字列の属性かえします。属性が適用されている範囲をリファレンスを使って格納します。

宣言
SWIFT

	func attributesAtIndex(_
		index: Int,
		longestEffectiveRange aRange: NSRangePointer,
		inRange rangeLimit: NSRange) -> [NSObject : AnyObject]

OBJECTIVE-C

	- (NSDictionary *)attributesAtIndex:
		(NSUInteger)index
		longestEffectiveRange:(NSRangePointer)aRange
		inRange:(NSRange)rangeLimit

パラメータ

考察
インデックスかrangeLimitがレシーバ文字の終わり以降を指定すると、NSRangeException が発生します。

範囲の情報を必要としないなら、attributesAtIndex:effectiveRange: メソッドを使う方がよいでしょう。

返される辞書での属性名を調べるには、この文章の概要部分を参照してください。

@import Foundation;

import Foundation

- attribute:atIndex:effectiveRange:

インデックスの位置にある文字につけられている属性のうち、引数の属性名の値を返す。くわえて、属性が適用されている範囲を参照で返します。

宣言
SWIFT

	func attribute(_
		attributeName: String,
		atIndex index: Int,
		effectiveRange aRange: NSRangePointer) -> AnyObject?

OBJECTIVE-C

	- (id)attribute:
		(NSString *)attributeName
		atIndex:(NSUInteger)index
		effectiveRange:(NSRangePointer)aRange

パラメータ

|aRange|NULL でない場合

• インデックスの位置に名前付きの属性があれば、aRange には名前付き属性の値が適用されている範囲が入れられます。
• インデックスの位置に名前付きの属性がなければ、aRange には指定した属性が存在していない範囲が入れられます。|
  
  

この範囲は、attributeName が適用されている最大範囲である必要がなく、実行範囲は実装に依存しています。最大範囲が必要なら、attribute:atIndex:longestEffectiveRange:inRange: メソッドを使ってください。この値が不要なら、NULL を渡してください。|

戻り値
The value for the attribute named attributeName of the character at index index, or nil if there is no such attribute.
indexの位置にある文字において、属性名attributeNameの値を返します。属性名が見当たらないなら、nilを返します。

考察
インデックスがレシーバ文字の終わりを越えているなら、NSRangeException が発生します。
返される辞書にある属性名については、この書類の概要部分をお読みください。

@import Foundation;

import Foundation

I

- attribute:atIndex:longestEffectiveRange:inRange:

インデックスの位置にある文字について、属性名に対応する属性の値を返します。くわえて、その属性が適用されている範囲の参照も得られます。

宣言
SWIFT

func attribute(_
		attributeName: String,
		atIndex index: Int,
		longestEffectiveRange aRange: NSRangePointer,
		inRange rangeLimit: NSRange) -> AnyObject?

OBJECTIVE-C

- (id) attribute:(NSString *)attributeName
		atIndex:(NSUInteger)index
		longestEffectiveRange:(NSRangePointer)aRange
		inRange:(NSRange)rangeLimit

パラメータ

|aRange|NULL でない場合

	・インデックスの位置に名前付きの属性があれば、aRange には名前付き属性の値が適用されている範囲が入れられます。
	・インデックスの位置に名前付きの属性がなければ、aRange には指定した属性が存在していない範囲が入れられます。

この値が不要なら、NULL を渡してください。|

戻り値
インデックス位置にある文字に適用されている 属性名 attributeName の値。属性名に対応するものがない場合は nil。

考察
インデックスかrangeLimit のどれもがレシーバの文字の終わりを越える場合は、NSRangeException が発生します。

もっとも長い適用範囲を必要としないなら、属性値を得るのには attribute:atIndex:effectiveRange: メソッドの方が効率がはるかによいです。

返される辞書にある属性名については、この文章の概要部分を読んでください。

@import Foundation;

import Foundation

属性付き文字列を比較する

- isEqualToAttributedString:

引数の属性付き文字列とレシーバが同じかどうかを示すブール値を返す。

宣言
SWIFT

func isEqualToAttributedString(_ otherString: NSAttributedString) -> Bool

OBJECTIVE-C

- (BOOL)isEqualToAttributedString:(NSAttributedString *)otherString

パラメータ

戻り値
レシーバと otherString が同じなら YES、違うなら NO。

考察
ふたつの属性付き文字列が同じとは、すべてで文字と属性が一致するということです。

@import Foundation;

import Foundation

文字列を抽出する。

- attributedSubstringFromRange:

レシーバのうち、引数の範囲にある文字と属性からなる NSAttributeSting オブジェクトを返す。

宣言
SWIFT

func attributedSubstringFromRange(_ aRange: NSRange) -> NSAttributedString

OBJECTIVE-C

- (NSAttributedString *)attributedSubstringFromRange:(NSRange)aRange
&br;

パラメータ

戻り値
レシーバのうち、aRange 範囲にある属性付き文字列からなる NSAttributedString オブジェクト。

考察
aRange がレシーバ文字の終わりを越えるなら、NSRangeException が発生します。このメソッドでは、文字の長さを有効な範囲として扱い、空白部分は空の文字列として返します。

@import Foundation;

import Foundation

文字列にある属性を列挙する

- enumerateAttribute:inRange:options:usingBlock:

指定する範囲において、特定の属性に作用するブロックを実行する。

宣言
SWIFT

func enumerateAttribute(_ attrName: String,
				nRange enumerationRange: NSRange,
				options opts: NSAttributedStringEnumerationOptions,
				usingBlock block: (AnyObject!,
								NSRange,
								UnsafeMutablePointer<ObjCBool>) -> Void)

OBJECTIVE-C

- (void)enumerateAttribute:(NSString *)attrName
				inRange:(NSRange)enumerationRange
				options:(NSAttributedStringEnumerationOptions)opts
				usingBlock:(void (^)(id value,
								NSRange range,
				BOOL *stop))block

パラメータ

block
属性付き文字列のなかにある、決められた範囲の属性に適用するブロック。
ブロックは三つの引数を取ります。

考察
このメソッドが NSMutableAttributedString のインスタンスに送られたときのみ、ミューテーション（削除、追加、変更）が許されており、それはまたブロックへ指定された範囲の中のみです。ミューテーションをすると、これを適用した範囲の次へ連続的に列挙をおこなって行きます。つまり、処理が完了した長さはミューテーションに合わせていきます。（列挙体は基本的に特定の範囲で起こっている長さは変更されていると仮定しています）。

たとえば、ブロックが N のインデックス位置で始め、ブロックが与えられた範囲の文字をすべて削除した場合、ブロックが次に呼ばれたときにもまた範囲のインデックスが N として渡されます。

@import Foundation;

import Foundation

- enumerateAttributesInRange:options:usingBlock:

与えられた範囲にあるすべての属性に対してブロックを実行する。

- enumerateAttributesInRange:options:usingBlock:

与えられた範囲にあるすべての属性に対してブロックを実行する。

宣言
SWIFT

func enumerateAttributesInRange(_ enumerationRange: NSRange,
				options opts: NSAttributedStringEnumerationOptions,
				usingBlock block: ([NSObject : AnyObject]!,
				NSRange,
				UnsafeMutablePointer<ObjCBool>) -> Void)

OBJECTIVE-C

- (void)enumerateAttributesInRange:(NSRange)enumerationRange
				options:(NSAttributedStringEnumerationOptions)opts
				usingBlock:(void (^)(NSDictionary *attrs,
				NSRange range,
				BOOL *stop))block

パラメータ

block
属性付き文字列のなかにある属性へ適用するブロック。
ブロックは三つの引数を取る。

考察
このメソッドが NSMutableAttributedString のインスタンスに送られたときのみ、ミューテーション（削除、追加、変更）が許されており、ブロックへ指定する範囲の中のみです。ミューテーションをすると、これを適用した範囲の直後から続けて列挙をおこなって行きます。つまり、処理が完了した長さはミューテーションに合わせていきます。（列挙体は基本的に特定の範囲で起こっている長さは変更されていると仮定しています）。
たとえば、ブロックが N のインデックス位置で始め、ブロックが与えられた範囲の文字をすべて削除した場合、ブロックが次に呼ばれたときにもまた範囲のインデックスが N として渡されます。

@import Foundation;

import Foundation

宣言
SWIFT

func enumerateAttributesInRange(_ enumerationRange: NSRange,
				options opts: NSAttributedStringEnumerationOptions,
				usingBlock block: ([NSObject : AnyObject]!,
				NSRange,
				UnsafeMutablePointer<ObjCBool>) -> Void)

OBJECTIVE-C

- (void)enumerateAttributesInRange:(NSRange)enumerationRange
				options:(NSAttributedStringEnumerationOptions)opts
				usingBlock:(void (^)(NSDictionary *attrs,
				NSRange range,
				BOOL *stop))block

パラメータ

block
属性付き文字列のなかにある属性へ適用するブロック。
ブロックは三つの引数を取る。

考察
このメソッドが NSMutableAttributedString のインスタンスに送られたときのみ、ミューテーション（削除、追加、変更）が許されており、ブロックへ指定する範囲の中のみです。ミューテーションをすると、これを適用した範囲の直後から続けて列挙をおこなって行きます。つまり、処理が完了した長さはミューテーションに合わせていきます。（列挙体は基本的に特定の範囲で起こっている長さは変更されていると仮定しています）。
たとえば、ブロックが N のインデックス位置で始め、ブロックが与えられた範囲の文字をすべて削除した場合、ブロックが次に呼ばれたときにもまた範囲のインデックスが N として渡されます。

@import Foundation;

import Foundation

定数

NSAttributedStringEnumerationOptions

これらの定数は enumerateAttribute:inRange:options:usingBlock: と enumerateAttributesInRange:options:usingBlock: メソッドで使用するオプションです。

宣言
SWIFT

struct NSAttributedStringEnumerationOptions : RawOptionSetType {
				init(_ rawValue: UInt)
				init(rawValue rawValue: UInt)
				static var Reverse: NSAttributedStringEnumerationOptions { get }
				static var LongestEffectiveRangeNotRequired: NSAttributedStringEnumerationOptions { get }
}

OBJECTIVE-C

enum {
				NSAttributedStringEnumerationReverse = (1UL << 1),
				NSAttributedStringEnumerationLongestEffectiveRangeNotRequired = (1UL << 20)
};
typedef NSUInteger NSAttributedStringEnumerationOptions;

定数

• NSAttributedStringEnumerationReverse
  列挙を逆順におこないます
  Available in iOS 4.0 and later.
  
  

• NSAttributedStringEnumerationLongestEffectiveRangeNotRequired
  このオプション定数が与えられると、最も長い有効範囲での操作がおこなわれません。ブロックは同じ属性値を持つ一続きの属性について操作をおこないます。
  Available in iOS 4.0 and later.
  
  

@import Foundation;

import Foundation

Document Revision History