NSAttributedString — définition, formatage de texte et attributs dans iOS

Qu'est-ce que NSAttributedString ?

NSAttributedString est une classe fondamentale iOS/macOS pour travailler avec du texte formaté. Elle étend NSString en ajoutant des attributs à la chaîne — un dictionnaire de paires clé-valeur où la clé est une constante NSAttributedStringKey (par exemple, .font, .foregroundColor) et la valeur est l'objet correspondant (UIFont, UIColor). Chaque caractère de la chaîne peut avoir son propre ensemble d'attributs, permettant un formatage mixte au sein d'une seule chaîne.

L'architecture de NSAttributedString est basée sur le concept d'exécutions d'attributs (attribute runs). Si vous définissez l'attribut .font sur UIFont.boldSystemFont(ofSize: 16) pour la plage de caractères 0..5, tous les caractères de cette plage apparaîtront en gras. Les autres caractères peuvent avoir une police différente ou aucun attribut. Lors du rendu d'une chaîne attribuée, le système UIKit fusionne les caractéristiques de différentes plages et rend le texte uniformément.

NSAttributedString est immuable — après sa création, ses attributs et son contenu ne peuvent pas être modifiés. Pour la modification, il existe la sous-classe NSMutableAttributedString, qui fournit des méthodes pour ajouter, supprimer et modifier des attributs dans n'importe quelle plage. Cette distinction est importante pour le multithreading : l'NSAttributedString immuable est thread-safe, tandis que NSMutableAttributedString ne l'est pas.

Principaux attributs de formatage de texte

NSAttributedString prend en charge environ 40 attributs standard définis dans NSAttributedStringKey. Chaque attribut affecte un aspect spécifique de l'apparence du texte : police, couleur, position, soulignement, ombre, crénage, style de paragraphe et hyperliens. Pour définir un attribut, vous utilisez une constante NSAttributedStringKey et lui assignez un objet du type correspondant.

NSParagraphStyle — formatage de paragraphe

NSMutableParagraphStyle est un objet qui gère les caractéristiques visuelles d'un paragraphe : alignement (.alignment : .left, .center, .right, .justified), interligne (.lineSpacing), espacement entre paragraphes (.paragraphSpacing), retrait de première ligne (.firstLineHeadIndent), retrait gauche et droit (.headIndent, .tailIndent) et direction du texte (.baseWritingDirection). ParagraphStyle est appliqué à une plage qui inclut les caractères de nouvelle ligne si le même formatage est requis pour l'ensemble du paragraphe.

Comment créer NSAttributedString en code

La création d'un NSAttributedString se fait via un initialiseur qui prend une chaîne et un dictionnaire d'attributs. Les attributs sont appliqués à toute la chaîne. Pour un formatage mixte (attributs différents dans différentes parties de la chaîne), on utilise NSMutableAttributedString avec l'ajout ultérieur d'attributs à des plages spécifiques. Objective-C utilise un dictionnaire NSAttributedStringKey : UIFont, tandis que Swift utilise un dictionnaire [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)

Création avec NSMutableParagraphStyle

Un exemple illustre le formatage de paragraphe via NSMutableParagraphStyle. On définit un alignement centré, un interligne de 8 points, un espacement après paragraphe de 12 points. ParagraphStyle est ajouté au dictionnaire d'attributs sous la clé .paragraphStyle. NSAttributedString copie le paragraphStyle passé, donc après la création de la chaîne, vous pouvez le modifier sans affecter la chaîne déjà créée.

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 et modification des attributs

NSMutableAttributedString est une sous-classe de NSAttributedString qui permet de modifier le contenu et les attributs après la création. Méthodes principales : addAttribute(_:value:range:) pour ajouter un seul attribut à une plage ; addAttributes(_:range:) pour ajouter plusieurs attributs ; setAttributes(_:range:) pour remplacer tous les attributs d'une plage ; removeAttribute(_:range:) pour supprimer un attribut ; replaceCharacters(in:with:) pour remplacer du texte.

addAttribute et addAttributes ajoutent des attributs aux existants sans supprimer ceux déjà définis. Si une plage a déjà un attribut avec la même clé, sa valeur est remplacée. setAttributes remplace complètement le dictionnaire d'attributs pour une plage — tous les attributs précédemment définis sont supprimés. Ceci est important à comprendre lors du formatage séquentiel d'une seule chaîne : addAttributes est plus sûr car il ne réinitialise pas les polices et couleurs déjà définies.

Les plages (NSRange) sont spécifiées à l'aide de la structure NSRange(location : 0, length : 5). location est l'index de départ (basé sur 0), length est le nombre de caractères. Si la plage dépasse les limites de la chaîne, NSMutableAttributedString lève une exception NSRangeException. Pour des opérations sûres sur les plages, utilisez les méthodes NSRange de Foundation telles que NSIntersectionRange et 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)

Exemple d'affichage d'une chaîne attribuée dans UILabel

La façon la plus courante d'afficher un NSAttributedString est de l'affecter à la propriété attributedText d'un UILabel. Contrairement à la propriété text, attributedText utilise les attributs pour le rendu, prenant en charge le formatage mixte. Important : si attributedText est défini, UILabel ignore les propriétés font, textColor et textAlignment — toutes les caractéristiques visuelles proviennent des attributs de 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

Affichage dans UITextView avec liens interactifs

UITextView prend en charge les liens interactifs dans NSAttributedString. L'attribut .link avec une NSURL rend le texte cliquable. Pour gérer les tap, utilisez le délégué UITextViewDelegate avec la méthode textView(_:shouldInteractWith:in:interaction:). UITextView prend également en charge la sélection de texte et l'utilisation de UIMenuController pour les opérations standard (copier, rechercher).

Conversion de NSAttributedString en HTML et RTF

NSAttributedString prend en charge la conversion depuis HTML et RTF via NSAttributedString.DocumentType. Pour charger du HTML, utilisez l'initialiseur avec le paramètre documentAttributes : NSAttributedString(data : htmlData, options : [.documentType : .html], documentAttributes : nil). De même pour RTF : .rtf ou .rtfd. Ce mécanisme est utile pour afficher du contenu HTML sans WebView.

Pour l'export en HTML, utilisez la méthode data(from:documentAttributes:) avec une plage et un type de document. Export HTML : try attributedString.data(from : fullRange, documentAttributes : [.documentType : .html]). Les données résultantes peuvent être sauvegardées dans un fichier, envoyées à un serveur ou affichées dans un WebView. Lors de l'export, les polices, couleurs, alignement, listes — tous les attributs de formatage — sont convertis en styles CSS.

La prise en charge du RTF est particulièrement pertinente pour les applications macOS, où RTF est le format standard de texte enrichi. iOS prend également en charge la lecture et l'écriture de RTF mais ne l'utilise pas comme format principal. La différence entre RTF et RTFD : RTFD inclut des ressources embarquées (images) regroupées dans un répertoire. NSAttributedString peut gérer les deux formats via une interface unique.

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)