Attributed Text: o que é, tipos de atributos e estilização

O que é Attributed Text no iOS?

NSAttributedString é uma classe do framework Foundation que representa uma string com um conjunto de atributos nomeados vinculados a intervalos de caracteres. Cada atributo é um par chave-valor: a chave é definida por uma constante (NSFontAttributeName, NSForegroundColorAttributeName), e o valor é o objeto correspondente (UIFont, UIColor). Os atributos são aplicados a um intervalo de caracteres via NSRange.

A classe está disponível em todas as plataformas Apple: iOS (2.0+), macOS, tvOS, watchOS. NSAttributedString é imutável — uma vez criado, seus atributos são fixos. Para alterações dinâmicas, utiliza-se NSMutableAttributedString, que herda de NSAttributedString e adiciona os métodos setAttributes, addAttributes, addAttribute, removeAttribute.

Diferença do NSString

NSString é uma string simples de caracteres sem informação de estilo. Qualquer texto passado para UILabel via text é exibido com uma única fonte, cor e tamanho. NSAttributedString, passado via attributedText, permite que cada caractere tenha seu próprio conjunto de atributos. UILabel, UITextView e UITextField reconhecem automaticamente NSAttributedString e renderizam o texto de acordo com seus atributos.

Formato de Armazenamento

Internamente, NSAttributedString armazena um NSString com o texto e um array de intervalos de atributos. Cada intervalo é representado por uma estrutura NSRange e um dicionário de atributos. Durante a renderização, o sistema percorre os intervalos e aplica os atributos correspondentes a cada seção. A eficiência depende do número de trocas de atributos — mudanças frequentes em seções curtas aumentam o tempo de renderização.

Atributos do NSAttributedString

Os atributos do NSAttributedString são constantes definidas em UIKit (iOS) e AppKit (macOS), cada uma correspondendo a um aspecto específico da estilização visual do texto. Todos os atributos são strings NSAttributedString.Key, e seus valores são objetos de classes específicas. Os atributos são divididos em nível de caractere (afetam caracteres) e nível de parágrafo (afetam parágrafos).

Atributos de nível de caractere incluem fonte (NSFontAttributeName), cor do texto (NSForegroundColorAttributeName), cor de fundo (NSBackgroundColorAttributeName), sublinhado (NSUnderlineStyleAttributeName), tachado (NSStrikethroughStyleAttributeName), sombra (NSShadowAttributeName). Atributos de nível de parágrafo são definidos via NSParagraphStyleAttributeName, que controla alinhamento, recuo, espaçamento entre linhas e tabulação.

Atributos de Link e Interatividade

NSLinkAttributeName cria um link clicável no texto: o valor é uma URL ou string. UITextView lida automaticamente com esses links se a interação estiver habilitada. NSAttachmentAttributeName permite incorporar um NSTextAttachment — uma imagem dentro do texto que é renderizada como elemento inline. Isso é usado para criar texto com ícones, emojis ou visualizações personalizadas dentro de uma string.

Atributos Básicos de Estilização

Cada atributo de NSAttributedString tem um valor estritamente tipado. Vamos ver os atributos mais usados no desenvolvimento iOS. A fonte é definida através de um objeto UIFont, a cor através de UIColor, o espaçamento entre linhas através de NSMutableParagraphStyle, que permite configurar alinhamento, recuo e espaçamento em um único objeto.

NSParagraphStyle

NSParagraphStyle é um contêiner para atributos de parágrafo: alignment, lineSpacing, paragraphSpacing, firstLineHeadIndent, lineBreakMode, minimumLineHeight e outros. Para modificar esses parâmetros, cria-se um NSMutableParagraphStyle, configuram-se as propriedades desejadas e o objeto é passado como valor do atributo NSParagraphStyleAttributeName. Esta é a única forma de controlar o espaçamento entre linhas no NSAttributedString.

Sombra e Efeitos

NSShadow permite adicionar uma sombra ao texto: os parâmetros shadowOffset, shadowBlurRadius, shadowColor definem o deslocamento, desfoque e cor da sombra. Atributos de sublinhado e tachado aceitam combinações de estilos: NSUnderlineStyle.single, .double, .thick, .patternDash, .patternDot. Para controle preciso da espessura e cor das linhas, utiliza-se NSUnderlineColorAttributeName e NSStrikethroughColorAttributeName.

Como Usar NSAttributedString no Código

A criação de um NSAttributedString em Swift é feita através de um inicializador com o texto e um dicionário de atributos, ou através de NSMutableAttributedString com aplicação passo a passo de estilos. A abordagem básica é definir um dicionário de atributos para todo o texto, depois adicionar ou modificar atributos para intervalos específicos.

Criação com Atributos para Todo o Texto

Um exemplo simples — definir fonte, cor e alinhamento para toda a string. O dicionário de atributos é passado ao inicializador do NSAttributedString. As chaves do dicionário são constantes NSAttributedString.Key, os valores são objetos UIKit correspondentes. Este é o caso básico quando todo o texto é formatado uniformemente.

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

O texto será exibido com systemFont 16, cor cinza escuro, alinhamento centralizado e espaçamento entre linhas de 4pt. Esta abordagem é conveniente para cabeçalhos e botões estáticos.

Aplicação a um Intervalo

NSMutableAttributedString permite aplicar diferentes estilos a diferentes partes do texto. O método addAttribute adiciona um único atributo a um intervalo, addAttributes adiciona um dicionário de atributos. O método setAttributes substitui todos os atributos existentes de um intervalo por novos. Esta é a principal ferramenta para criar texto com destaque.

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

A palavra “1999” será verde e em negrito, o restante do texto será padrão. NSRange é calculado manualmente — é importante contar corretamente o comprimento em caracteres, especialmente ao trabalhar com emojis e caracteres Unicode compostos.

Estilos Dinâmicos com NSMutableAttributedString

NSMutableAttributedString fornece métodos para alterar dinamicamente texto e atributos: append, insert, replace, delete, setAttributes, addAttribute, removeAttribute, enumerateAttributes. Isso permite construir texto a partir de diferentes fontes, combinar estilos e responder a eventos da interface.

Ao contrário do NSAttributedString imutável, a versão mutável suporta alteração de conteúdo sem criar um novo objeto. Isso é crítico para editores de texto, chats e formulários onde o usuário pode editar o texto enquanto os estilos devem ser preservados.

Combinação de Estilos em um Chat

Em mensageiros, cada mensagem contém o nome do usuário (negrito), o texto da mensagem (normal), a hora (cor cinza). NSMutableAttributedString permite construir essa string de uma só vez, adicionando partes na ordem desejada com os atributos correspondentes.

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

O resultado é uma única string com três seções estilizadas. Append calcula NSRange automaticamente, as posições não precisam ser calculadas manualmente. Esta abordagem escala para qualquer número de fragmentos.

Enumeração de Atributos

O método enumerateAttributes(in:options:using:) percorre todos os intervalos de atributos no intervalo especificado. Isso é útil para análise de formatação: encontrar todos os links, alterar a cor de atributos específicos ou exportar texto para HTML. No closure, são recebidos o dicionário de atributos e o NSRange da seção atual.

Attributed Text em Componentes UI do UIKit

Todos os principais componentes de UI para exibir texto no UIKit suportam NSAttributedString através da propriedade attributedText. UILabel exibe texto estilizado estático, UITextView suporta edição e links, UITextField aceita atributos para o placeholder e o texto inserido separadamente.

UILabel com attributedText

UILabel é o componente mais leve para exibir texto estilizado. Ele suporta todos os atributos de nível de caractere, mas não lida com links clicáveis automaticamente (para isso, é necessário UITextView). UILabel é ideal para cabeçalhos, rótulos e textos curtos formatados.

UITextView com Links

UITextView lida com NSLinkAttributeName e exibe links como elementos interativos. Para habilitar essa funcionalidade, defina isSelectable = true e isEditable = false. Ao tocar em um link, o delegado recebe a chamada textView(_:shouldInteractWith:in:interaction:). UITextView também suporta NSTextAttachment para imagens dentro do texto.

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

Após configurar isSelectable e isEditable, a área de texto se comporta como um bloco de texto estático, mas os links permanecem ativos. UITextViewDelegate controla o comportamento ao tocar.

Integração com Core Text

Core Text é um framework de baixo nível da Apple para renderização de texto que trabalha diretamente com NSAttributedString. Ao contrário do UIKit, Core Text não usa NSAttributedString diretamente como objeto de exibição — em vez disso, converte-o em CTFramesetter, depois CTFrame e renderiza em um contexto Core Graphics. Isso dá controle total sobre o layout de linhas e glifos.

O uso de Core Text é justificado para layouts de texto personalizados: colunas, ajuste de imagens, rotação de texto, quebras de linha não padronizadas. O NSMutableParagraphStyle do Core Text inclui atributos não disponíveis no UIKit: kCTParagraphStyleSpecifierMaximumLineSpacing, kCTParagraphStyleSpecifierLineBreakMode com modos adicionais.

Conversão entre UIKit e Core Text

NSAttributedString transfere-se perfeitamente entre UIKit e Core Text, já que ambos os frameworks trabalham com o mesmo tipo. Atributos do UIKit (NSFontAttributeName, NSForegroundColorAttributeName) são automaticamente reconhecidos pelo Core Text, e vice-versa — atributos do Core Text (kCTFontAttributeName) são lidos pelo UIKit. Isso permite usar UIKit para tarefas simples e Core Text para renderização personalizada no mesmo objeto NSAttributedString.