Attributed Text: co to jest, typy atrybutów i stylizacja

Czym jest Attributed Text w iOS?

NSAttributedString to klasa frameworka Foundation, która reprezentuje ciąg znaków z zestawem nazwanych atrybutów przypisanych do zakresów znaków. Każdy atrybut to para klucz-wartość: klucz jest zdefiniowany przez stałą (NSFontAttributeName, NSForegroundColorAttributeName), a wartość przez odpowiedni obiekt (UIFont, UIColor). Atrybuty są stosowane do zakresu znaków za pomocą NSRange.

Klasa jest dostępna na wszystkich platformach Apple: iOS (2.0+), macOS, tvOS, watchOS. NSAttributedString jest niezmienny — po utworzeniu jego atrybuty są ustalone. Do dynamicznej modyfikacji używa się NSMutableAttributedString, który dziedziczy z NSAttributedString i dodaje metody setAttributes, addAttributes, addAttribute, removeAttribute.

Różnica od NSString

NSString to prosty ciąg znaków bez informacji o stylu. Każdy tekst przekazany do UILabel przez text jest wyświetlany jedną czcionką, kolorem i rozmiarem. NSAttributedString przekazany przez attributedText pozwala każdemu znakowi mieć własny zestaw atrybutów. UILabel, UITextView i UITextField automatycznie rozpoznają NSAttributedString i renderują tekst zgodnie z atrybutami.

Format przechowywania

Wewnętrznie NSAttributedString przechowuje NSString z tekstem i tablicę zakresów atrybutów. Każdy zakres jest reprezentowany przez strukturę NSRange i słownik atrybutów. Podczas renderowania system przechodzi przez zakresy i stosuje odpowiednie atrybuty do każdego fragmentu. Wydajność zależy od liczby przełączeń atrybutów — częste zmiany na krótkich fragmentach zwiększają czas renderowania.

Atrybuty NSAttributedString

Atrybuty NSAttributedString to stałe zdefiniowane w UIKit (iOS) i AppKit (macOS), z których każda odpowiada określonemu aspektowi wizualnego formatowania tekstu. Wszystkie atrybuty są łańcuchami NSAttributedString.Key, a ich wartości są obiektami określonych klas. Atrybuty dzielą się na znakowe (wpływają na znaki) i akapitowe (wpływają na akapity).

Atrybuty znakowe obejmują czcionkę (NSFontAttributeName), kolor tekstu (NSForegroundColorAttributeName), kolor tła (NSBackgroundColorAttributeName), podkreślenie (NSUnderlineStyleAttributeName), przekreślenie (NSStrikethroughStyleAttributeName), cień (NSShadowAttributeName). Atrybuty akapitowe są ustawiane przez NSParagraphStyleAttributeName, który kontroluje wyrównanie, wcięcia, odstępy między wierszami i tabulację.

Atrybuty linków i interaktywności

NSLinkAttributeName tworzy klikalny link w tekście: wartość to URL lub ciąg znaków. UITextView automatycznie obsługuje takie linki, jeśli włączona jest interakcja. NSAttachmentAttributeName pozwala osadzić NSTextAttachment — obraz wewnątrz tekstu, który jest wyświetlany jako element inline. Jest to używane do tworzenia tekstów z ikonami, emotikonami lub niestandardowymi widokami wewnątrz ciągu.

Podstawowe atrybuty stylizacji

Każdy atrybut NSAttributedString ma ściśle typowaną wartość. Przyjrzyjmy się najczęściej używanym atrybutom w programowaniu iOS. Czcionka jest ustawiana przez obiekt UIFont, kolor przez UIColor, odstęp między wierszami przez NSMutableParagraphStyle, który pozwala skonfigurować wyrównanie, wcięcia i odstępy w jednym obiekcie.

NSParagraphStyle

NSParagraphStyle to kontener dla atrybutów akapitu: alignment, lineSpacing, paragraphSpacing, firstLineHeadIndent, lineBreakMode, minimumLineHeight i innych. Aby zmienić te parametry, tworzy się NSMutableParagraphStyle, konfiguruje odpowiednie właściwości, a obiekt przekazuje jako wartość atrybutu NSParagraphStyleAttributeName. To jedyny sposób zarządzania odstępem między wierszami w NSAttributedString.

cień i efekty

NSShadow pozwala dodać cień do tekstu: parametry shadowOffset, shadowBlurRadius, shadowColor ustawiają przesunięcie, rozmycie i kolor cienia. Atrybuty podkreślenia i przekreślenia przyjmują kombinacje stylów: NSUnderlineStyle.single, .double, .thick, .patternDash, .patternDot. Do precyzyjnego sterowania grubością i kolorem linii używa się NSUnderlineColorAttributeName i NSStrikethroughColorAttributeName.

Jak używać NSAttributedString w kodzie

Tworzenie NSAttributedString w Swift wykonuje się przez inicjalizator z podaniem tekstu i słownika atrybutów albo przez NSMutableAttributedString z krokowym stosowaniem stylów. Podstawowe podejście polega na zdefiniowaniu słownika atrybutów dla całego tekstu, a następnie dodaniu lub zmianie atrybutów dla poszczególnych zakresów.

Tworzenie z atrybutami dla całego tekstu

Prosty przykład — ustawienie czcionki, koloru i wyrównania dla całego ciągu. Słownik atrybutów jest przekazywany do inicjalizatora NSAttributedString. Klucze słownika to stałe NSAttributedString.Key, wartości to odpowiednie obiekty UIKit. To podstawowy wariant, gdy cały tekst jest formatowany jednolicie.

let attributes: [NSAttributedString.Key: Any] = [
    .font: UIFont.systemFont(ofSize: 16),
    .foregroundColor: UIColor.darkGray,
    .paragraphStyle: let style = NSMutableParagraphStyle()
    style.alignment = .center
    style.lineSpacing = 4
    return style
]
let attributedString = NSAttributedString(
    string: "Hello world",
    attributes: attributes
)
label.attributedText = attributedString

Tekst wyświetli się czcionką systemFont 16, ciemnoszarym kolorem, z wyrównaniem do środka i odstępem między wierszami 4pt. Takie podejście jest wygodne dla statycznych nagłówków i przycisków.

Stosowanie do zakresu

NSMutableAttributedString pozwala zastosować różne style do różnych fragmentów tekstu. Metoda addAttribute dodaje jeden atrybut do zakresu, addAttributes — słownik atrybutów. Metoda setAttributes zastępuje wszystkie atrybuty zakresu nowymi. To podstawowe narzędzie do tworzenia tekstu z wyróżnieniami.

let text = "Price: 1999 rubles"
let attributed = NSMutableAttributedString(string: text)
attributed.addAttribute(.foregroundColor,
    value: UIColor.green, range: NSRange(location: 6, length: 4))
attributed.addAttribute(.font,
    value: UIFont.boldSystemFont(ofSize: 20), range: NSRange(location: 6, length: 4))
label.attributedText = attributed

Słowo „1999“ będzie zielone i pogrubione, reszta tekstu — standardowa. NSRange jest obliczany ręcznie — ważne jest prawidłowe liczenie długości w znakach, szczególnie przy pracy z emotikonami i złożonymi znakami Unicode.

Dynamiczne style z NSMutableAttributedString

NSMutableAttributedString udostępnia metody do dynamicznej modyfikacji tekstu i atrybutów: append, insert, replace, delete, setAttributes, addAttribute, removeAttribute, enumerateAttributes. Pozwala to budować tekst z różnych źródeł, łączyć style i reagować na zdarzenia interfejsu.

W przeciwieństwie do niezmiennego NSAttributedString, wersja mutable obsługuje zmianę zawartości bez tworzenia nowego obiektu. Jest to kluczowe dla edytorów tekstu, czatów i formularzy, gdzie użytkownik może edytować tekst, a style muszą być zachowane.

Łączenie stylów w czacie

W komunikatorach każda wiadomość zawiera nazwę użytkownika (pogrubiona), treść wiadomości (zwykła), czas (szary kolor). NSMutableAttributedString pozwala zbudować taki ciąg za jednym razem, dodając części w odpowiedniej kolejności z odpowiednimi atrybutami.

let result = NSMutableAttributedString()
let name = NSAttributedString(string: "Anna: ",
    attributes: [.font: UIFont.boldSystemFont(ofSize: 15)])
let message = NSAttributedString(string: "Hello, how are you?",
    attributes: [.font: UIFont.systemFont(ofSize: 15)])
let time = NSAttributedString(string: " 12:30",
    attributes: [.foregroundColor: UIColor.gray])
result.append(name)
result.append(message)
result.append(time)
label.attributedText = result

Wynik — jeden ciąg z trzema fragmentami o różnych stylach. Append poprawnie oblicza NSRange automatycznie, pozycje nie muszą być obliczane ręcznie. Takie podejście skaluje się na dowolną liczbę fragmentów.

Iteracja po atrybutach

Metoda enumerateAttributes(in:options:using:) przechodzi przez wszystkie zakresy atrybutów w określonym przedziale. Jest to przydatne do analizy formatowania: znalezienia wszystkich linków, zmiany koloru niektórych atrybutów lub eksportu tekstu do HTML. W domknięciu przekazywane są słownik atrybutów i NSRange bieżącego fragmentu.

Attributed Text w komponentach UIKit

Wszystkie podstawowe komponenty do wyświetlania tekstu w UIKit obsługują NSAttributedString przez właściwość attributedText. UILabel wyświetla statyczny stylizowany tekst, UITextView obsługuje edycję i linki, UITextField przyjmuje atrybuty dla placeholder i wprowadzonego tekstu osobno.

UILabel z attributedText

UILabel to najlżejszy komponent do wyświetlania stylizowanego tekstu. Obsługuje wszystkie atrybuty znakowe, ale nie przetwarza klikalnych linków automatycznie (do tego potrzebny jest UITextView). UILabel idealnie nadaje się do nagłówków, etykiet i krótkich tekstów z formatowaniem.

UITextView z linkami

UITextView obsługuje NSLinkAttributeName i wyświetla linki jako interaktywne elementy. Aby włączyć tę funkcjonalność, ustaw isSelectable = true i isEditable = false. Po kliknięciu linku delegat otrzymuje wywołanie textView(_:shouldInteractWith:in:interaction:). UITextView obsługuje również NSTextAttachment dla obrazów wewnątrz tekstu.

let text = "Details on developer.apple.com"
let attributed = NSMutableAttributedString(string: text)
attributed.addAttribute(.link,
    value: URL(string: "https://developer.apple.com")!,
    range: NSRange(location: 0, length: text.count))
textView.attributedText = attributed
textView.isSelectable = true
textView.isEditable = false

Po skonfigurowaniu isSelectable i isEditable obszar tekstowy zachowuje się jak statyczny blok tekstu, ale linki pozostają aktywne. Delegat UITextViewDelegate zarządza zachowaniem po kliknięciu.

Integracja z Core Text

Core Text to niskopoziomowy framework Apple do renderowania tekstu, który pracuje bezpośrednio z NSAttributedString. W przeciwieństwie do UIKit, Core Text nie używa NSAttributedString bezpośrednio jako obiektu do wyświetlenia, ale przekształca go na CTFramesetter, następnie CTFrame i renderuje w kontekście Core Graphics. Daje to pełną kontrolę nad rozmieszczeniem wierszy i glifów.

Użycie Core Text jest uzasadnione dla niestandardowych układów tekstu: kolumny, opływanie obrazów, obracanie tekstu, niestandardowe łamanie wierszy. NSMutableParagraphStyle Core Text zawiera atrybuty, których nie ma w UIKit: kCTParagraphStyleSpecifierMaximumLineSpacing, kCTParagraphStyleSpecifierLineBreakMode z dodatkowymi trybami.

Konwersja między UIKit i Core Text

NSAttributedString bezproblemowo przechodzi między UIKit i Core Text, ponieważ oba frameworki pracują z tym samym typem. Atrybuty UIKit (NSFontAttributeName, NSForegroundColorAttributeName) są automatycznie rozpoznawane przez Core Text i odwrotnie — atrybuty Core Text (kCTFontAttributeName) są odczytywane przez UIKit. Pozwala to używać UIKit do prostych zadań i Core Text do niestandardowego renderowania na tym samym obiekcie NSAttributedString.