Estilizar entrada de rich text

Observação: as APIs discutidas nesta página estão disponíveis no Compose Foundation 1.12.0 e no Material 3 1.5.0-alpha28. Os estilos são salvos e restaurados em mudanças de configuração e encerramentos de processos a partir do Compose Foundation 1.13.0-alpha01.

A entrada de rich text permite que os usuários formatem o que digitam, incluindo colocar uma palavra em negrito, adicionar um título, alinhar um parágrafo ou inserir um @mention destacado. No Compose, você cria isso com base em campos de texto baseados em estado (BasicTextField e TextField). Os estilos ficam em TextFieldState junto com o texto, então eles resistem a edições, mudanças de seleção e recomposições, além de permanecerem sincronizados conforme o usuário digita, exclui e cola.

Nesta página, mostramos como aplicar, atualizar, consultar, extrair e remover estilos em um TextFieldState usando TextFieldBuffer e como controlar uma barra de ferramentas de formatação do TextFieldState.textStyles.

Observação: para aplicar uma formatação apenas visual que não seja salva em TextFieldState, como destaque de sintaxe ou formatação de número de telefone, chame addStyle dentro de um OutputTransformation. A estilização de rich text em TextFieldState.edit e InputTransformation é ativada por padrão no Compose Foundation 1.12.0 usando ComposeFoundationFlags.isBasicTextFieldStyledTextEnabled. Para mais informações sobre a formatação somente visual, consulte Formatar a entrada antes de ser exibida.

Aplicar estilos inline e de parágrafo

É possível aplicar formatação no nível de caracteres e de parágrafos em qualquer escopo de receptor TextFieldBuffer, incluindo TextFieldState.edit, InputTransformation.transformInput e OutputTransformation.transformOutput.

Controlar a expansão de limites com ExpandPolicy

Ao chamar addStyle, você pode transmitir um ExpandPolicy para definir como o intervalo estilizado se comporta quando o usuário insere novos caracteres diretamente no limite start ou end:

• Inserção dentro de (start, end): sempre expande o intervalo estilizado.
• Inserção antes de start: sempre desloca os deslocamentos start e end para a direita.
• Inserção direta em start ou end: controlada pelo ExpandPolicy especificado.

A tabela a seguir descreve as opções de ExpandPolicy disponíveis e os casos de uso típicos:

Política	Comportamento de limite	Casos de uso recomendados	Exemplo
ExpandPolicy.InsideOnly	O texto digitado em start ou end fica fora do intervalo estilizado.	Tokens discretos, como @mentions, #hashtags ou pílulas de plano de fundo, em que a digitação ao lado da tag não deve herdar a cor de fundo da tag.
ExpandPolicy.AtStart	O texto digitado em start herda o estilo, e o texto digitado em end permanece sem estilo.	O texto digitado diretamente na frente do texto estilizado também deve adotar a mesma formatação.
ExpandPolicy.AtEnd	O texto digitado em end herda o estilo, e o texto digitado em start permanece sem estilo.	Digitação padrão do editor de texto rich text, em que a formatação é mantida ao continuar digitando após uma palavra em negrito ou itálico.
ExpandPolicy.AtBoth	O texto digitado em start ou end expande o intervalo e herda o estilo.	Destaques ativos ou blocos formatados contínuos que devem crescer de qualquer borda.

Aplicar formatação de caracteres com SpanStyle

Use addStyle com um SpanStyle para aplicar formatação no nível do caractere, como cor do texto, destaque do plano de fundo, FontWeight, FontStyle ou sublinhado a um TextRange específico no buffer.

Principais comportamentos para intervalos de SpanStyle

• Ordem de camadas: os estilos são aplicados na ordem em que são adicionados ao buffer. Se vários intervalos SpanStyle sobrepostos definirem a mesma propriedade com valores diferentes, o estilo adicionado por último será renderizado por cima.
• Requisito de intervalo não vazio: é necessário transmitir um intervalo não recolhido em que start < end. Chamar addStyle em uma seleção recolhida de tamanho 0 não tem efeito, e transmitir índices invertidos ou fora dos limites gera uma IllegalArgumentException.

Observação: como addStyle não tem efeito em uma seleção recolhida, pressionar um botão Negrito apenas com um cursor ainda não pode estilizar nada. Para deixar os próximos caracteres digitados em negrito, rastreie um SpanStyle pendente no detentor de estado e aplique-o a cada novo intervalo em changes dentro de um InputTransformation, conforme mostrado no exemplo a seguir.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation {
        for (i in 0 until changes.changeCount) {
            val range = changes.getRange(i)
            if (!range.collapsed) {
                addStyle(
                    spanStyle = SpanStyle(
                        fontWeight = FontWeight.ExtraBold,
                        fontStyle = FontStyle.Italic,
                        color = Color.Red,
                    ),
                    range = range,
                    expandPolicy = ExpandPolicy.AtEnd
                )
            }
        }
    }
)
RichTextInput.kt

Figura 1. Aplicar formatação em negrito e itálico vermelho à entrada do usuário de forma dinâmica.

Aplicar formatação de bloco com ParagraphStyle

Use addStyle com um ParagraphStyle para aplicar formatação estrutural no nível do bloco, como textAlign, lineHeight, textDirection ou textIndent, a um intervalo de parágrafos.

fun setParagraphAlignment(state: TextFieldState, alignment: TextAlign) {
    val targetRange = if (state.selection.collapsed) {
        TextRange(0, state.text.length)
    } else {
        state.selection
    }
    if (targetRange.collapsed) return
    state.edit {
        // 1. Remove existing paragraph styles in this range
        getParagraphStyles(targetRange).forEach { removeStyle(it) }
        // 2. Apply the new paragraph alignment
        addStyle(
            paragraphStyle = ParagraphStyle(textAlign = alignment),
            range = targetRange,
            expandPolicy = ExpandPolicy.InsideOnly
        )
    }
}
RichTextInput.kt

Figura 2. Alternar o alinhamento do parágrafo entre início, centro e fim usando ParagraphStyle.

Atenção: os intervalos de ParagraphStyle no Compose precisam ser estritamente não sobrepostos ou completamente aninhados. Sobreposições parciais, como [0, 10) e [5, 15), são inválidas e fazem com que a medição de layout gere um IllegalArgumentException. Sempre remova ou ajuste os intervalos ParagraphStyle atuais antes de aplicar um novo ao mesmo parágrafo.

Armadilhas que devem ser evitadas com ParagraphStyle

Como ParagraphStyle se aplica a blocos inteiros de texto, evite usá-lo nos seguintes cenários:

• Expansão para parágrafos adjacentes: defina ExpandPolicy com cuidado para que os intervalos ParagraphStyle adjacentes não se sobreponham após as edições do usuário. Por exemplo, se [0, 5) usar ExpandPolicy.AtEnd e [5, 10) usar ExpandPolicy.AtStart, a inserção de texto no índice 5 vai expandir os dois estilos em uma sobreposição e gerar um IllegalArgumentException.
• Aninhamento de intervalos ParagraphStyle: embora intervalos completamente aninhados (como [0, 10) e [2, 8)) sejam válidos em AnnotatedString, evite aninhar intervalos ParagraphStyle em um campo de texto. O layout divide os intervalos aninhados em parágrafos separados, e as edições subsequentes podem transformar acidentalmente os intervalos aninhados em uma sobreposição parcial.

Observação: no Compose 1.12.0, os limites de ParagraphStyle funcionam como quebras de parágrafo, correspondendo ao comportamento estático de AnnotatedString em Text. Aplicar um ParagraphStyle a um subintervalo de um parágrafo ou diretamente adjacente a um caractere de nova linha (\n) pode inserir uma quebra de linha visual extra. Ao estilizar textos com vários parágrafos, alinhe o intervalo de ParagraphStyle com os limites completos do parágrafo.

Atualizar um estilo no lugar com TrackedRange

Chamar addStyle com um TextRange e ExpandPolicy retorna um identificador TrackedRange, que pode ser TrackedRange<SpanStyle> ou TrackedRange<ParagraphStyle>. Um TrackedRange é uma referência dinâmica a um intervalo de estilo no TextFieldBuffer que atualiza automaticamente os deslocamentos de caracteres start e end à medida que o texto é inserido, excluído ou substituído ao redor dele.

Mutabilidade no local

Não é necessário chamar removeStyle e addStyle para atualizar um estilo atual ou ajustar os limites dele. Em um escopo TextFieldBuffer, TrackedRange fornece propriedades de extensão que atualizam o intervalo no local, preservando a ordem de camadas original em relação a outros estilos:

• TrackedRange<SpanStyle>.spanStyle: lê ou substitui o payload SpanStyle em um TrackedRange<SpanStyle>.
• TrackedRange<ParagraphStyle>.paragraphStyle: lê ou substitui o payload ParagraphStyle em um TrackedRange<ParagraphStyle>.
• TrackedRange<*>.textRange: lê ou atualiza os limites atuais de TextRange no local. Definir um intervalo recolhido, invertido ou fora dos limites gera um IllegalArgumentException.
• TrackedRange<*>.expandPolicy: lê ou atualiza o ExpandPolicy no local.
• TrackedRange<*>.isValid: retorna true se o intervalo de estilo ainda estiver ativo no buffer ou false se as edições tiverem causado o colapso do comprimento para 0 ou se ele tiver sido removido.

// Trim an existing bold span in place when the selection overlaps one edge
val range = style.textRange
if (range.start < selection.min && range.end <= selection.max) {
    // Selection covers the end of the span - shrink end boundary in place
    style.textRange = TextRange(range.start, selection.min)
} else if (range.start >= selection.min && range.end > selection.max) {
    // Selection covers the start of the span - shrink start boundary in place
    style.textRange = TextRange(selection.max, range.end)
}
RichTextInput.kt

Confinamento de escopo e regras de ciclo de vida

Lembre-se das seguintes regras de escopo e ciclo de vida ao trabalhar com instâncias de TrackedRange:

• Restritas a TextFieldBuffer: as propriedades de extensão TrackedRange só existem no escopo TextFieldBuffer em que o identificador foi criado ou consultado.
• Remoção automática ao recolher: se as edições do usuário excluírem todos os caracteres cobertos por um TrackedRange, o comprimento dele será reduzido para 0, isValid retornará false e o estilo será removido do buffer.

Atenção: não armazene instâncias de TrackedRange em propriedades de longa duração de ViewModel ou detentores de estado externos. Um TrackedRange é vinculado a uma única sessão de edição de TextFieldBuffer, não tem propriedades acessíveis fora desse bloco e se torna permanentemente inválido se o intervalo for excluído, desfeito ou restaurado. Para observar estilos fora de um bloco de edição, leia TextFieldState.textStyles.

Consultar e remover estilos

O Compose oferece duas maneiras de inspecionar estilos ativos, dependendo se você está modificando o buffer ou lendo o estado da IU:

• Dentro de um bloco TextFieldBuffer: chame getSpanStyles e getParagraphStyles diretamente no receptor TextFieldBuffer para receber identificadores TrackedRange mutáveis.
• Fora de um bloco de edição: leia TextFieldState.textStyles, que retorna listas AnnotatedString.Range imutáveis que refletem o estado confirmado.

Atenção: não consulte state.textStyles dentro de um bloco state.edit. state.textStyles reflete apenas o estado confirmado antes da sessão de edição e não inclui mudanças em andamento no buffer.

Consultar estilos de interseção em TextFieldBuffer

TextFieldBuffer.getSpanStyles e TextFieldBuffer.getParagraphStyles retornam todas as instâncias de TrackedRange que se cruzam com o TextRange fornecido, ordenadas por quando foram adicionadas ao buffer.

Por exemplo, é possível consultar getSpanStyles(selection) dentro de state.edit para inspecionar ou atualizar estilos que abrangem a seleção atual do usuário:

state.edit {
    if (selection.collapsed) return@edit
    // Query all bold spans that overlap with the current selection
    val boldStyles: List<TrackedRange<SpanStyle>> = getSpanStyles(selection).filter {
        it.spanStyle.fontWeight == FontWeight.Bold
    }
    // ...
}
RichTextInput.kt

Os intervalos de estilo usam um intervalo matemático semiaberto [start, end). O retorno de um estilo de toque depende se você consulta uma seleção ou um único ponto de cursor:

• Para uma seleção não vazia [start, end):
  • Retornado: qualquer estilo que se sobreponha, contenha ou esteja dentro do intervalo de seleção. Por exemplo, a consulta [5, 15) corresponde a [0, 20), [8, 12) ou [0, 10).
  • Não retornados: estilos que tocam apenas as bordas externas sem sobrepor caracteres. Por exemplo, a consulta [5, 15) exclui [0, 5) e [15, 25).
• Para um cursor recolhido [index, index]:
  • Retornado: qualquer estilo que contenha o cursor ou que comece na posição dele. Por exemplo, um cursor em 10 corresponde a [0, 20) e [10, 20).
  • Não retornado (regra de fim de toque): qualquer estilo que termine na posição do cursor. Por exemplo, um cursor em 10 exclui [0, 10).

Observação: getSpanStyles e getParagraphStyles avaliam os limites de intervalo semiaberto [start, end) e ignoram ExpandPolicy. Para inspecionar um estilo que toca o limite final em um cursor recolhido (index > 0), consulte a janela de caracteres anterior. Como TextRange conta unidades de código UTF-16 e um único emoji pode abranger várias delas, calcule o início da janela com BreakIterator.getCharacterInstance() em vez de index - 1 para que a consulta nunca comece no meio de um caractere.

Remover ou alternar estilos com removeStyle

Transmita um identificador TrackedRange para removeStyle para excluir esse intervalo de estilo específico do TextFieldBuffer.

removeStyle retorna true se o TrackedRange foi encontrado e removido ou false se ele já foi removido ou pertencia a um buffer diferente. Ele remove apenas o identificador TrackedRange segmentado, deixando outros estilos sobrepostos intactos.

fun toggleBold(state: TextFieldState) {
    state.edit {
        if (selection.collapsed) return@edit
        // Query all bold spans that overlap with the current selection
        val boldStyles: List<TrackedRange<SpanStyle>> = getSpanStyles(selection).filter {
            it.spanStyle.fontWeight == FontWeight.Bold
        }
        if (boldStyles.isNotEmpty()) {
            // Remove or trim existing bold spans covering the selection
            for (style in boldStyles) {
                val range = style.textRange
                if (range.start >= selection.min && range.end <= selection.max) {
                    removeStyle(style)
                } else if (range.start < selection.min && range.end > selection.max) {
                    val oldEnd = range.end
                    style.textRange = TextRange(range.start, selection.min)
                    addStyle(
                        spanStyle = SpanStyle(fontWeight = FontWeight.Bold),
                        range = TextRange(selection.max, oldEnd),
                        expandPolicy = ExpandPolicy.AtEnd
                    )
                } else if (range.start < selection.min) {
                    style.textRange = TextRange(range.start, selection.min)
                } else {
                    style.textRange = TextRange(selection.max, range.end)
                }
            }
        } else {
            // No bold spans intersect the selection - apply bold
            addStyle(
                spanStyle = SpanStyle(fontWeight = FontWeight.Bold),
                range = selection,
                expandPolicy = ExpandPolicy.AtEnd
            )
        }
    }
}
RichTextInput.kt

Figura 3. Alternar entre texto em negrito e sem negrito.

Extrair ou serializar rich text

Para mostrar a entrada formatada em um elemento de composição Text somente leitura ou serializá-la em um serviço de back-end, leia TextFieldState.textStyles fora de um bloco de edição.

state.textStyles.getSpanStyles e state.textStyles.getParagraphStyles retornam List<AnnotatedString.Range<SpanStyle>> e List<AnnotatedString.Range<ParagraphStyle>>, que podem ser transmitidos diretamente para o construtor AnnotatedString:

fun TextFieldState.toAnnotatedString(): AnnotatedString {
    val fullRange = TextRange(0, text.length)
    return AnnotatedString(
        text = text.toString(),
        spanStyles = textStyles.getSpanStyles(fullRange),
        paragraphStyles = textStyles.getParagraphStyles(fullRange)
    )
}
RichTextInput.kt

Exemplo completo no Jetchat

Para conferir uma implementação completa que combina estilos de caracteres inline (negrito, itálico, sublinhado, tachado e cor), consulte o exemplo Jetchat no GitHub:

• RichTextState.kt: encapsula consultas de estilo TextFieldState, alternância de span, corte ou divisão entre limites de seleção e muito mais.
• UserInput.kt: conecta RichTextState à barra de ferramentas de formatação de rich text e ao campo de entrada de mensagens.

Figura 4. Edição de rich text no Jetchat.