NSAttributedString — co to je, formátování textu a atributy v iOS

Co je NSAttributedString?

NSAttributedString — je fundamentální třída iOS/macOS pro práci s formátovaným textem. Rozšiřuje možnosti NSString přidáním atributů k řetězci — slovníku párů klíč-hodnota, kde klíč je konstanta NSAttributedStringKey (např. .font, .foregroundColor) a hodnota je odpovídající objekt (UIFont, UIColor). Každý znak v řetězci může mít vlastní sadu atributů, což umožňuje smíšené formátování v jednom řetězci.

Architektura NSAttributedString je založena na konceptu atributových rozsahů (attribute runs). Pokud nastavíte atribut .font = UIFont.boldSystemFont(ofSize: 16) pro rozsah znaků 0..5, všechny znaky tohoto rozsahu se zobrazí tučným písmem. Ostatní znaky mohou mít jiné písmo nebo nemusí mít atribut vůbec. Při zobrazení atributovaného řetězce systém UIKit kombinuje vlastnosti z různých rozsahů a text vykresluje jednotně.

NSAttributedString je neměnný — po vytvoření nelze jeho atributy a obsah měnit. Pro úpravy existuje podtřída NSMutableAttributedString, která poskytuje metody pro přidávání, odebírání a změnu atributů v libovolných rozsazích. Tento rozdíl je důležitý pro vícevláknové zpracování: neměnný NSAttributedString je thread-safe, zatímco NSMutableAttributedString nikoli.

Hlavní atributy formátování textu

NSAttributedString podporuje přibližně 40 standardních atributů definovaných v NSAttributedStringKey. Každý atribut ovlivňuje určitý aspekt vzhledu textu: písmo, barva, pozice, podtržení, stín, mezera mezi znaky, styl odstavce a hypertextové odkazy. Pro nastavení atributu se používá konstanta NSAttributedStringKey, které je přiřazen objekt odpovídajícího typu.

NSParagraphStyle — formátování odstavce

NSMutableParagraphStyle — objekt, který spravuje vizuální vlastnosti odstavce: zarovnání (.alignment: .left, .center, .right, .justified), řádkování (.lineSpacing), vzdálenost mezi odstavci (.paragraphSpacing), odsazení prvního řádku (.firstLineHeadIndent), levé a pravé odsazení (.headIndent, .tailIndent) a směr textu (.baseWritingDirection). ParagraphStyle se aplikuje na rozsah, který zahrnuje znaky nového řádku, pokud je požadováno stejné formátování pro celý odstavec.

Jak vytvořit NSAttributedString v kódu

Vytvoření NSAttributedString se provádí pomocí inicializátoru, který přijímá řetězec a slovník atributů. Atributy se aplikují na celý řetězec. Pro smíšené formátování (různé atributy v různých částech řetězce) se používá NSMutableAttributedString s následným přidáním atributů ke konkrétním rozsahům. Objective-C používá slovník NSAttributedStringKey: UIFont, zatímco Swift používá typově bezpečný slovník [NSAttributedString.Key: Any].

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)

Vytvoření s NSMutableParagraphStyle

Příklad demonstruje formátování odstavce pomocí NSMutableParagraphStyle. Nastavuje se zarovnání na střed, řádkování 8 bodů, mezera za odstavcem 12 bodů. ParagraphStyle se přidá do slovníku atributů pod klíčem .paragraphStyle. NSAttributedString kopíruje předaný paragraphStyle, takže po vytvoření řetězce jej lze měnit bez ovlivnění již vytvořeného řetězce.

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 a změna atributů

NSMutableAttributedString — je podtřída NSAttributedString, která umožňuje měnit obsah a atributy po vytvoření. Hlavní metody: addAttribute(_:value:range:) pro přidání jednoho atributu k rozsahu; addAttributes(_:range:) pro přidání více atributů; setAttributes(_:range:) pro nahrazení všech atributů v rozsahu; removeAttribute(_:range:) pro odstranění atributu; replaceCharacters(in:with:) pro nahrazení textu.

addAttribute a addAttributes přidávají atributy ke stávajícím, aniž by odstraňovaly již nastavené. Pokud v rozsahu již existuje atribut se stejným klíčem, jeho hodnota je nahrazena. setAttributes zcela nahrazuje slovník atributů pro rozsah — všechny dříve nastavené atributy jsou odstraněny. To je důležité při sekvenčním formátování jednoho řetězce: addAttributes je bezpečnější, protože neruší již nastavená písma a barvy.

Rozsahy (NSRange) jsou definovány strukturou NSRange(location: 0, length: 5). location — počáteční index (0-založený), length — počet znaků. Pokud rozsah překročí hranice řetězce, NSMutableAttributedString vygeneruje výjimku NSRangeException. Pro bezpečnou práci s rozsahy se používají metody NSRange z Foundation, jako NSIntersectionRange a NSUnionRange.

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)

Příklad zobrazení atributovaného řetězce v UILabel

Nejběžnější způsob zobrazení NSAttributedString — přiřazení k vlastnosti attributedText UILabel. Na rozdíl od vlastnosti text, attributedText používá atributy pro vykreslování a podporuje smíšené formátování. Důležité: pokud je attributedText nastaven, UILabel ignoruje vlastnosti font, textColor, textAlignment — všechny vizuální vlastnosti pocházejí z atributů NSAttributedString.

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

Zobrazení v UITextView s interaktivními odkazy

UITextView podporuje interaktivní odkazy v NSAttributedString. Atribut .link s NSURL činí text klikatelným. Pro zpracování kliknutí se používá delegát UITextViewDelegate s metodou textView(_:shouldInteractWith:in:interaction:). UITextView také podporuje výběr textu a použití UIMenuController pro standardní operace (kopírování, hledání).

Konverze NSAttributedString do HTML a RTF

NSAttributedString podporuje konverzi z HTML a RTF přes NSAttributedString.DocumentType. Pro načtení HTML se používá inicializátor s parametry documentAttributes: NSAttributedString(data: htmlData, options: [.documentType: .html], documentAttributes: nil). Podobně pro RTF: .rtf nebo .rtfd. Tento mechanismus je užitečný pro zobrazení HTML obsahu bez WebView.

Pro export do HTML se používá metoda data(from:documentAttributes:) s rozsahem a typem dokumentu. HTML export: try attributedString.data(from: fullRange, documentAttributes: [.documentType: .html]). Získaná data lze uložit do souboru, odeslat na server nebo zobrazit ve WebView. Při exportu jsou zachována písma, barvy, zarovnání, seznamy — všechny atributy formátování jsou převedeny do CSS stylů.

Podpora RTF je obzvláště relevantní pro macOS aplikace, kde je RTF standardním formátem bohatého textu. iOS také podporuje čtení a zápis RTF, ale nepoužívá jej jako primární formát. Rozdíl mezi RTF a RTFD: RTFD obsahuje vnořené zdroje (obrázky) zabalené v adresáři. NSAttributedString může zpracovávat oba formáty přes jednotné rozhraní.

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)