NSAttributedString — cosa sono, formattazione del testo e attributi in iOS

Cosa sono NSAttributedString?

NSAttributedString è una classe fondamentale di iOS/macOS per lavorare con testo formattato. Estende NSString aggiungendo attributi alla stringa — un dizionario di coppie chiave-valore dove la chiave è una costante NSAttributedStringKey (ad esempio, .font, .foregroundColor) e il valore è l'oggetto corrispondente (UIFont, UIColor). Ogni carattere nella stringa può avere il proprio insieme di attributi, consentendo la formattazione mista all'interno di una singola stringa.

L'architettura di NSAttributedString si basa sul concetto di esecuzioni di attributi (attribute runs). Se si imposta l'attributo .font su UIFont.boldSystemFont(ofSize: 16) per l'intervallo di caratteri 0..5, tutti i caratteri di quell'intervallo appariranno in grassetto. Altri caratteri possono avere un font diverso o nessun attributo. Durante il rendering di una stringa attribuita, il sistema UIKit unisce le caratteristiche di diversi intervalli e rende il testo uniformemente.

NSAttributedString è immutabile — dopo la creazione, i suoi attributi e contenuti non possono essere modificati. Per la modifica esiste la sottoclasse NSMutableAttributedString, che fornisce metodi per aggiungere, rimuovere e modificare attributi in qualsiasi intervallo. Questa distinzione è importante per il multithreading: NSAttributedString immutabile è thread-safe, mentre NSMutableAttributedString non lo è.

Attributi principali di formattazione del testo

NSAttributedString supporta circa 40 attributi standard definiti in NSAttributedStringKey. Ogni attributo influenza un aspetto specifico dell'aspetto del testo: font, colore, posizione, sottolineatura, ombra, crenatura, stile di paragrafo e collegamenti ipertestuali. Per impostare un attributo, si usa una costante NSAttributedStringKey e le si assegna un oggetto del tipo corrispondente.

NSParagraphStyle — formattazione del paragrafo

NSMutableParagraphStyle è un oggetto che gestisce le caratteristiche visive di un paragrafo: allineamento (.alignment: .left, .center, .right, .justified), interlinea (.lineSpacing), spaziatura tra paragrafi (.paragraphSpacing), rientro della prima riga (.firstLineHeadIndent), rientro sinistro e destro (.headIndent, .tailIndent) e direzione del testo (.baseWritingDirection). ParagraphStyle viene applicato a un intervallo che include caratteri di nuova riga se è richiesta la stessa formattazione per l'intero paragrafo.

Come creare NSAttributedString nel codice

La creazione di un NSAttributedString avviene tramite un inizializzatore che accetta una stringa e un dizionario di attributi. Gli attributi vengono applicati all'intera stringa. Per la formattazione mista (attributi diversi in parti diverse della stringa), si usa NSMutableAttributedString con la successiva aggiunta di attributi a intervalli specifici. Objective-C usa un dizionario NSAttributedStringKey: UIFont, mentre Swift usa un dizionario [NSAttributedString.Key: Any] type-safe.

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)

Creazione con NSMutableParagraphStyle

Un esempio dimostra la formattazione del paragrafo tramite NSMutableParagraphStyle. Si imposta allineamento centrato, interlinea di 8 punti, spaziatura dopo il paragrafo di 12 punti. ParagraphStyle viene aggiunto al dizionario degli attributi sotto la chiave .paragraphStyle. NSAttributedString copia il paragraphStyle passato, quindi dopo aver creato la stringa è possibile modificarlo senza influenzare la stringa già creata.

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 e modifica degli attributi

NSMutableAttributedString è una sottoclasse di NSAttributedString che consente di modificare contenuto e attributi dopo la creazione. Metodi principali: addAttribute(_:value:range:) per aggiungere un singolo attributo a un intervallo; addAttributes(_:range:) per aggiungere più attributi; setAttributes(_:range:) per sostituire tutti gli attributi in un intervallo; removeAttribute(_:range:) per rimuovere un attributo; replaceCharacters(in:with:) per sostituire il testo.

addAttribute e addAttributes aggiungono attributi a quelli esistenti senza rimuovere quelli già impostati. Se un intervallo ha già un attributo con la stessa chiave, il suo valore viene sostituito. setAttributes sostituisce completamente il dizionario degli attributi per un intervallo — tutti gli attributi precedentemente impostati vengono rimossi. Questo è importante da capire quando si formatta sequenzialmente una singola stringa: addAttributes è più sicuro perché non reimposta font e colori già configurati.

Gli intervalli (NSRange) vengono specificati usando la struttura NSRange(location: 0, length: 5). location è l'indice iniziale (basato su 0), length è il numero di caratteri. Se l'intervallo supera i limiti della stringa, NSMutableAttributedString genera un'eccezione NSRangeException. Per operazioni sicure sugli intervalli, usare i metodi NSRange di Foundation come NSIntersectionRange e 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)

Esempio di visualizzazione di stringa attribuita in UILabel

Il modo più comune per visualizzare un NSAttributedString è assegnarlo alla proprietà attributedText di un UILabel. A differenza della proprietà text, attributedText usa gli attributi per il rendering, supportando la formattazione mista. Importante: se attributedText è impostato, UILabel ignora le proprietà font, textColor e textAlignment — tutte le caratteristiche visive provengono dagli attributi di 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

Visualizzazione in UITextView con collegamenti interattivi

UITextView supporta collegamenti interattivi in NSAttributedString. L'attributo .link con un NSURL rende il testo cliccabile. Per gestire i tocchi, si usa il delegato UITextViewDelegate con il metodo textView(_:shouldInteractWith:in:interaction:). UITextView supporta anche la selezione del testo e l'uso di UIMenuController per operazioni standard (copia, ricerca).

Conversione di NSAttributedString in HTML e RTF

NSAttributedString supporta la conversione da HTML e RTF tramite NSAttributedString.DocumentType. Per caricare HTML, si usa l'inizializzatore con il parametro documentAttributes: NSAttributedString(data: htmlData, options: [.documentType: .html], documentAttributes: nil). Analogamente per RTF: .rtf o .rtfd. Questo meccanismo è utile per visualizzare contenuto HTML senza WebView.

Per l'esportazione in HTML, si usa il metodo data(from:documentAttributes:) con un intervallo e tipo di documento. Esportazione HTML: try attributedString.data(from: fullRange, documentAttributes: [.documentType: .html]). I dati risultanti possono essere salvati in un file, inviati a un server o visualizzati in un WebView. Durante l'esportazione, font, colori, allineamento, elenchi — tutti gli attributi di formattazione — vengono convertiti in stili CSS.

Il supporto per RTF è particolarmente rilevante per le applicazioni macOS, dove RTF è il formato standard di testo ricco. iOS supporta anche la lettura e scrittura di RTF ma non lo usa come formato principale. La differenza tra RTF e RTFD: RTFD include risorse incorporate (immagini) impacchettate in una directory. NSAttributedString può gestire entrambi i formati attraverso un'unica interfaccia.

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)