NSAttributedString — nedir, metin biçimlendirme ve iOS'ta nitelikler

NSAttributedString nedir?

NSAttributedString, biçimlendirilmiş metinle çalışmak için temel bir iOS/macOS sınıfıdır. Dizeye nitelikler (anahtarın bir NSAttributedStringKey sabiti (örneğin, .font, .foregroundColor) ve değerin karşılık gelen nesne (UIFont, UIColor) olduğu anahtar-değer çiftlerinden oluşan bir sözlük) ekleyerek NSString'ı genişletir. Dizedeki her karakter kendi nitelik kümesine sahip olabilir ve tek bir dize içinde karma biçimlendirmeye olanak tanır.

NSAttributedString mimarisi, nitelik çalıştırmaları (attribute runs) kavramına dayanır. 0..5 karakter aralığı için .font niteliğini UIFont.boldSystemFont(ofSize: 16) olarak ayarlarsanız, bu aralıktaki tüm karakterler kalın görünecektir. Diğer karakterler farklı bir yazı tipine sahip olabilir veya hiç niteliğe sahip olmayabilir. Nitelikli bir dize işlenirken, UIKit sistemi farklı aralıklardaki özellikleri birleştirir ve metni tekdüze bir şekilde işler.

NSAttributedString değişmezdir — oluşturulduktan sonra nitelikleri ve içeriği değiştirilemez. Değişiklik için, herhangi bir aralıkta nitelik ekleme, kaldırma ve değiştirme yöntemleri sağlayan NSMutableAttributedString alt sınıfı vardır. Bu ayrım çoklu iş parçacığı için önemlidir: değişmez NSAttributedString iş parçacığı güvenlidir, ancak NSMutableAttributedString değildir.

Metin biçimlendirmenin temel nitelikleri

NSAttributedString, NSAttributedStringKey içinde tanımlanmış yaklaşık 40 standart niteliği destekler. Her nitelik, metin görünümünün belirli bir yönünü etkiler: yazı tipi, renk, konum, alt çizgi, gölge, karakter aralığı, paragraf stili ve köprüler. Bir nitelik ayarlamak için bir NSAttributedStringKey sabiti kullanır ve ona karşılık gelen türde bir nesne atarsınız.

NSParagraphStyle — paragraf biçimlendirme

NSMutableParagraphStyle, bir paragrafın görsel özelliklerini yöneten bir nesnedir: hizalama (.alignment: .left, .center, .right, .justified), satır aralığı (.lineSpacing), paragraf aralığı (.paragraphSpacing), ilk satır girintisi (.firstLineHeadIndent), sol ve sağ girinti (.headIndent, .tailIndent) ve metin yönü (.baseWritingDirection). ParagraphStyle, tüm paragraf için aynı biçimlendirme gerekiyorsa, yeni satır karakterlerini içeren bir aralığa uygulanır.

Kodda NSAttributedString nasıl oluşturulur

NSAttributedString oluşturma, bir dize ve nitelik sözlüğü alan bir başlatıcı aracılığıyla yapılır. Nitelikler tüm dizeye uygulanır. Karma biçimlendirme (dizenin farklı bölümlerinde farklı nitelikler) için, belirli aralıklara niteliklerin daha sonra eklenmesiyle NSMutableAttributedString kullanılır. Objective-C bir NSAttributedStringKey: UIFont sözlüğü kullanırken, Swift tür güvenli [NSAttributedString.Key: Any] sözlüğü kullanır.

let plainText = "Hello, Swift!"

// Create with uniform attributes for the entire string
let attributes: [NSAttributedString.Key: Any] = [
    NSAttributedString.Key.font:
        UIFont.systemFont(ofSize: 18),
    NSAttributedString.Key.foregroundColor:
        UIColor.darkText,
    NSAttributedString.Key.kern: 1.5
]

let attributedString =
    NSAttributedString(string: plainText,
                        attributes: attributes)

NSMutableParagraphStyle ile oluşturma

Bir örnek, NSMutableParagraphStyle aracılığıyla paragraf biçimlendirmesini gösterir. Merkez hizalama, 8 punto satır aralığı, 12 punto paragraf sonrası boşluk ayarlanır. ParagraphStyle, .paragraphStyle anahtarı altında nitelik sözlüğüne eklenir. NSAttributedString iletilen paragraphStyle'ı kopyalar, bu nedenle dizeyi oluşturduktan sonra, zaten oluşturulmuş dizeyi etkilemeden onu değiştirebilirsiniz.

let paragraphStyle = NSMutableParagraphStyle()
paragraphStyle.alignment = NSTextAlignment.center
paragraphStyle.lineSpacing = 8.0
paragraphStyle.paragraphSpacing = 12.0
paragraphStyle.firstLineHeadIndent = 20.0

let attributed = NSAttributedString(
    string: "Centered paragraph with spacing",
    attributes: [NSAttributedString.Key.paragraphStyle: paragraphStyle])

NSMutableAttributedString ve nitelik değiştirme

NSMutableAttributedString, oluşturulduktan sonra içerik ve nitelikleri değiştirmeye izin veren NSAttributedString'in bir alt sınıfıdır. Ana yöntemler: bir aralığa tek bir nitelik eklemek için addAttribute(_:value:range:); birden çok nitelik eklemek için addAttributes(_:range:); bir aralıktaki tüm nitelikleri değiştirmek için setAttributes(_:range:); bir niteliği kaldırmak için removeAttribute(_:range:); metni değiştirmek için replaceCharacters(in:with:).

addAttribute ve addAttributes, önceden ayarlanmış nitelikleri kaldırmadan varolan niteliklere ekler. Bir aralıkta zaten aynı anahtara sahip bir nitelik varsa, değeri değiştirilir. setAttributes, bir aralık için nitelik sözlüğünü tamamen değiştirir — önceden ayarlanmış tüm nitelikler kaldırılır. Tek bir dizeyi sırayla biçimlendirirken bunu anlamak önemlidir: addAttributes daha güvenlidir çünkü önceden ayarlanmış yazı tiplerini ve renkleri sıfırlamaz.

Aralıklar (NSRange), NSRange(location: 0, length: 5) yapısı kullanılarak belirtilir. location başlangıç dizinidir (0 tabanlı), length karakter sayısıdır. Aralık dize sınırlarını aşarsa, NSMutableAttributedString bir NSRangeException fırlatır. Güvenli aralık işlemleri için, NSIntersectionRange ve NSUnionRange gibi Foundation'dan NSRange yöntemlerini kullanın.

let attributed = NSMutableAttributedString(
    string: "Bold and red text here")

// Apply bold font to first 9 characters
let boldRange = NSRange(location: 0, length: 9)
attributed.addAttribute(
    NSAttributedString.Key.font,
    value: UIFont.boldSystemFont(ofSize: 16),
    range: boldRange)

// Apply red color to characters 13-16 ("text")
let redRange = NSRange(location: 13, length: 4)
attributed.addAttribute(
    NSAttributedString.Key.foregroundColor,
    value: UIColor.red,
    range: redRange)

// Apply underline to the entire string
let fullRange = NSRange(location: 0,
                       length: attributed.length)
attributed.addAttribute(
    NSAttributedString.Key.underlineStyle,
    value: NSUnderlineStyle.single.rawValue,
    range: fullRange)

UILabel'da nitelikli dize görüntüleme örneği

NSAttributedString'i görüntülemenin en yaygın yolu, onu bir UILabel'in attributedText özelliğine atamaktır. text özelliğinin aksine, attributedText işleme için nitelikleri kullanır ve karma biçimlendirmeyi destekler. Önemli: attributedText ayarlanmışsa, UILabel font, textColor ve textAlignment özelliklerini yok sayar — tüm görsel özellikler NSAttributedString niteliklerinden gelir.

let label = UILabel()
label.numberOfLines = 0

let fullText = NSMutableAttributedString(
    string: "Price: $24.99 per month")

// Format "Price:" label with bold font
let priceLabelRange = NSRange(
    location: 0, length: 6)
fullText.addAttribute(
    NSAttributedString.Key.font,
    value: UIFont.boldSystemFont(ofSize: 16),
    range: priceLabelRange)

// Format "$24.99" with green color
let amountRange = NSRange(
    location: 7, length: 6)
fullText.addAttribute(
    NSAttributedString.Key.foregroundColor,
    value: UIColor.systemGreen(),
    range: amountRange)
fullText.addAttribute(
    NSAttributedString.Key.font,
    value: UIFont.boldSystemFont(ofSize: 22),
    range: amountRange)

// Apply gray color to "per month" text
let periodRange = NSRange(
    location: 14, length: 9)
fullText.addAttribute(
    NSAttributedString.Key.foregroundColor,
    value: UIColor.secondaryLabel,
    range: periodRange)

label.attributedText = fullText

Etkileşimli bağlantılarla UITextView'da görüntüleme

UITextView, NSAttributedString içinde etkileşimli bağlantıları destekler. NSURL ile .link niteliği metni tıklanabilir yapar. Dokunmaları işlemek için, textView(_:shouldInteractWith:in:interaction:) yöntemiyle UITextViewDelegate kullanılır. UITextView ayrıca metin seçimini ve standart işlemler (kopyalama, arama) için UIMenuController kullanımını da destekler.

NSAttributedString'i HTML ve RTF'ye dönüştürme

NSAttributedString, NSAttributedString.DocumentType aracılığıyla HTML ve RTF'den dönüştürmeyi destekler. HTML yüklemek için, documentAttributes parametresiyle başlatıcıyı kullanın: NSAttributedString(data: htmlData, options: [.documentType: .html], documentAttributes: nil). RTF için benzer şekilde: .rtf veya .rtfd. Bu mekanizma, WebView olmadan HTML içeriği görüntülemek için kullanışlıdır.

HTML'ye dışa aktarma için, bir aralık ve belge türüyle data(from:documentAttributes:) yöntemini kullanın. HTML dışa aktarma: try attributedString.data(from: fullRange, documentAttributes: [.documentType: .html]). Elde edilen veriler bir dosyaya kaydedilebilir, bir sunucuya gönderilebilir veya WebView'da görüntülenebilir. Dışa aktarma sırasında yazı tipleri, renkler, hizalama, listeler — tüm biçimlendirme nitelikleri — CSS stillerine dönüştürülür.

RTF desteği, RTF'nin standart zengin metin biçimi olduğu macOS uygulamaları için özellikle önemlidir. iOS ayrıca RTF okuma ve yazmayı destekler ancak bunu birincil biçim olarak kullanmaz. RTF ve RTFD arasındaki fark: RTFD, bir dizine paketlenmiş gömülü kaynakları (görüntüler) içerir. NSAttributedString her iki biçimi de tek bir arayüz aracılığıyla işleyebilir.

let htmlString = "<p><b>Bold<\/b> and <i>italic<\/i><\/p>"
guard let htmlData = htmlString.data(
    using: String.Encoding.utf8) else { return }

let options: [NSAttributedString.DocumentReadingOptionKey: Any] = [
    NSAttributedString.DocumentReadingOptionKey.documentType:
        NSAttributedString.DocumentType.html
]

let attributedFromHTML =
    try? NSAttributedString(
        data: htmlData,
        options: options,
        documentAttributes: nil)