Recursos de string

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Os recursos de string fornecem strings de texto para o aplicativo com estilo e formatação de texto opcionais. Existem três tipos de recursos que podem fornecer strings ao seu aplicativo:

String
Recurso XML que fornece uma só string.
Matriz de strings
Recurso XML que fornece uma matriz de strings.
Strings de quantidade (plurais)
Recurso XML que contém diferentes strings para pluralização.

Todas as strings podem aplicar algumas marcações de estilo e argumentos de formatação. Para saber mais sobre estilos e formatação de strings, consulte a seção sobre Formatação e estilo.

String

É uma string única que pode ser referenciada do aplicativo ou de outros arquivos de recurso (como um layout XML).

Observação: uma string é um recurso simples que é referenciado usando o valor fornecido no atributo name (e não no nome do arquivo XML). Dessa forma, é possível combinar recursos de string com outros recursos simples em um arquivo XML, em um elemento <resources>.

localização do arquivo:
res/values/filename.xml
O nome do arquivo é arbitrário. O name do elemento <string> é usado como o ID do recurso.
tipo de dados do recurso compilado:
Ponteiro do recurso para um String.
referência de recurso:
Em Java: R.string.string_name
Em XML:@string/string_name
sintaxe:
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string
        name="string_name"
        >text_string</string>
</resources>
elementos:
<resources>
Obrigatório. Precisa ser o nó raiz.

Nenhum atributo.

<string>
É uma string que pode conter tags de estilo. Você precisa executar o escape de apóstrofos e aspas. Para saber mais sobre como ajustar corretamente o estilo e a formatação das strings, consulte Formatação e estilo abaixo.

atributos:

name
String. É o nome da string. Esse nome é usado como o ID do recurso.
exemplo:
Arquivo XML salvo em res/values/strings.xml:
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello!</string>
</resources>

Esse XML de layout aplica uma string em uma visualização:

<TextView
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:text="@string/hello" />

Esse código do aplicativo extrai uma string:

Kotlin

val string: String = getString(R.string.hello)

Java

String string = getString(R.string.hello);

Você pode usar getString(int) ou getText(int) para extrair uma string. O getText(int) mantém qualquer estilo de texto avançado aplicado à string.

Matriz de strings

É a matriz de strings que pode ser referenciada pelo aplicativo.

Observação: uma matriz de strings é um recurso simples que é referenciado usando o valor fornecido no atributo name (e não o nome do arquivo XML). Em um arquivo XML, você pode combinar os recursos da matriz de strings com outros recursos simples em um único elemento <resources>.

localização do arquivo:
res/values/filename.xml
O nome do arquivo é arbitrário. O name do elemento <string-array> é usado como o ID do recurso.
tipo de dados do recurso compilado:
Ponteiro de recurso para uma matriz de Strings.
referência de recurso:
Em Java: R.array.string_array_name
Em XML: @[package:]array/string_array_name
sintaxe:
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array
        name="string_array_name">
        <item
            >text_string</item>
    </string-array>
</resources>
elementos:
<resources>
Obrigatório. Precisa ser o nó raiz.

Nenhum atributo.

<string-array>
Define uma matriz de strings. Contém um ou mais elementos <item>.

atributos:

name
String. Um nome para a matriz. O nome do arquivo é usado como o ID do recurso para referenciar a matriz.
<item>
É uma string que pode conter tags de estilo. O valor pode ser uma referência a outro recurso de string. Precisa ser um filho de um elemento <string-array>. Você precisa executar o escape de apóstrofos e aspas. Para saber mais sobre o ajuste correto do estilo e da formatação de strings, consulte Formatação e estilo abaixo.

Nenhum atributo.

exemplo:
Arquivo XML salvo em res/values/strings.xml:
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="planets_array">
        <item>Mercury</item>
        <item>Venus</item>
        <item>Earth</item>
        <item>Mars</item>
    </string-array>
</resources>

Esse código do aplicativo extrai uma matriz de strings:

Kotlin

val array: Array = resources.getStringArray(R.array.planets_array)

Java

Resources res = getResources();
String[] planets = res.getStringArray(R.array.planets_array);

Strings de quantidade (plurais)

Diferentes idiomas têm diferentes regras de concordância gramatical de número. Em inglês, por exemplo, a quantidade 1 é um caso especial. Escrevemos "1 book" (1 livro), mas, para qualquer outra quantidade, "n books" (n livros). Essa distinção entre singular e plural é muito comum, mas outros idiomas fazem distinções mais precisas. O conjunto completo permitido pelo Android é zero, one, two, few, many e other.

As regras para decidir qual caso usar para determinado idioma e quantidade podem ser muito complexas. O Android fornece métodos como o getQuantityString() para selecionar o recurso apropriado para seu caso de uso.

Apesar de serem historicamente conhecidas como "strings de quantidade" (ainda chamadas assim na API), elas precisam ser usadas somente para plurais. Seria um erro usar strings de quantidade para implementar algo como a "Caixa de entrada" do Gmail em vez de "Caixa de Entrada (12)" quando houver mensagens não lidas, por exemplo. Pode parecer conveniente usar strings de quantidade em vez de uma instrução if. No entanto, é importante observar que alguns idiomas (como o chinês) não fazem essas distinções gramaticais. Por isso, você sempre vai receber a string other.

A seleção da string é feita exclusivamente com base na necessidade gramatical. Em inglês, uma string para zero é ignorada mesmo que a quantidade seja 0, porque 0 não é gramaticalmente diferente de 2 ou de qualquer outro número, exceto 1 ("zero books", "1 book", "2 books" e assim por diante). Por outro lado, em coreano, apenas a string other é usada.

Não se engane pelo fato de que, por exemplo, two parece ser aplicável somente para a quantidade 2: um idioma pode exigir que 2, 12, 102 (e assim por diante) sejam tratados da mesma forma, mas de forma diferente de outras quantidades. Converse com um tradutor para identificar quais são as distinções obrigatórias de cada idioma.

Se a mensagem não tiver um número de quantidade, provavelmente não é uma boa opção para um plural. Por exemplo, em lituano, a forma singular é usada para 1 e 101. Portanto, "1 livro" é traduzido como "1 knyga", e "101 livros" é traduzido como "101 knyga". Já "um livro" é "knyga" e "vários livros" é "daug knygų". Se uma mensagem plural em inglês contiver "a book" (singular) e "many books" (plural) sem o número real, ela pode ser traduzida como "knyga" (um livro)/"daug knygų" (vários livros). No entanto, seguindo as regras da Lituânia, a mensagem vai mostrar "knyga" (um único livro), quando o número for 101.

Geralmente, é possível evitar strings de quantidade usando formulações de quantidade neutra, como "Livros: 1". Isso vai facilitar seu trabalho e o dos tradutores, caso seja um estilo compatível com seu aplicativo.

Na API 24 ou versões mais recentes, é possível usar a classe ICU MessageFormat, que é muito mais eficiente.

Observação: uma coleção de plurais é um recurso simples que é referenciado usando o valor fornecido no atributo name (e não no nome do arquivo XML). Em um arquivo XML, você pode combinar plurais com outros recursos simples em um único elemento <resources>.

localização do arquivo:
res/values/filename.xml
O nome do arquivo é arbitrário. O name do elemento <plurals> é usado como o ID do recurso.
referência de recurso:
Em Java: R.plurals.plural_name
sintaxe:
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <plurals
        name="plural_name">
        <item
            quantity=["zero" | "one" | "two" | "few" | "many" | "other"]
            >text_string</item>
    </plurals>
</resources>
elementos:
<resources>
Obrigatório. Precisa ser o nó raiz.

Nenhum atributo.

<plurals>
Uma coleção que fornece uma string de acordo com a quantidade de um item. Contém um ou mais elementos <item>.

atributos:

name
String. É o nome do par de strings. Esse nome é usado como o ID do recurso.
<item>
Indica se uma string é plural ou singular. O valor pode ser uma referência a outro recurso de string. Precisa ser um filho de um elemento <plurals>. Você precisa executar o escape de apóstrofos e aspas. Para saber mais sobre o ajuste correto do estilo e da formatação das suas strings, consulte Formatação e estilo abaixo.

atributos:

quantity
Palavra-chave. É o valor que indica quando é preciso usar a string. Valores válidos, com exemplos entre parênteses:
ValorDescrição
zeroIndica se o idioma exige tratamento especial para o número 0 (como em árabe).
oneIndica se o idioma exige tratamento especial para números como 1 (como em inglês e na maioria dos idiomas). Em russo, qualquer número terminado em 1, mas não em 11, se encontra nessa classe.
twoIndica se o idioma exige tratamento especial para números como 2 (como 2 em galês ou 102 em esloveno).
fewIndica se o idioma exige tratamento especial para números "pequenos" (como 2, 3 e 4 em tcheco ou números terminados em 2, 3 ou 4, mas não 12, 13 ou 14, em polonês).
manyQuando o idioma exige tratamento especial para números "grandes", como números que terminam de 11 a 99 em maltês.
otherIndica se o idioma não exige tratamento especial na quantidade em questão (como com todos os números em chinês ou 42 em inglês).
exemplo:
Arquivo XML salvo em res/values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <plurals name="numberOfSongsAvailable">
        <!--
             As a developer, you should always supply "one" and "other"
             strings. Your translators will know which strings are actually
             needed for their language. Always include %d in "one" because
             translators will need to use %d for languages where "one"
             doesn't mean 1 (as explained above).
          -->
        <item quantity="one">%d song found.</item>
        <item quantity="other">%d songs found.</item>
    </plurals>
</resources>

Arquivo XML salvo em res/values-pl/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <plurals name="numberOfSongsAvailable">
        <item quantity="one">Znaleziono %d piosenkę.</item>
        <item quantity="few">Znaleziono %d piosenki.</item>
        <item quantity="other">Znaleziono %d piosenek.</item>
    </plurals>
</resources>

Uso:

Kotlin

val count = getNumberOfSongsAvailable()
val songsFound = resources.getQuantityString(R.plurals.numberOfSongsAvailable, count, count)

Java

int count = getNumberOfSongsAvailable();
Resources res = getResources();
String songsFound = res.getQuantityString(R.plurals.numberOfSongsAvailable, count, count);

Ao usar o método getQuantityString(), você precisa transmitir o count duas vezes se a string tiver formatação com um número. Por exemplo, para a string %d songs found, o primeiro parâmetro count seleciona a string plural apropriada, e o segundo parâmetro count é inserido no marcador %d. Se as strings de plural não tiverem formatação de string, você não vai precisar transmitir o terceiro parâmetro para getQuantityString.

Formato e estilo

Apresentamos abaixo alguns itens importantes sobre como definir a formatação e o estilo dos seus recursos de string.

Processar caracteres especiais

Quando uma string contém caracteres que têm uso especial em XML, é necessário que eles tenham um escape de acordo com as regras padrão de XML/HTML. Se você precisar de escape para um caractere que tenha um significado especial no Android, use uma barra invertida no início.

Por padrão, o Android procura sequências de caracteres de espaço em branco e as transforma em um único espaço. Para evitar isso, coloque a parte relevante da string entre aspas duplas. Nesse caso, todos os caracteres de espaço em branco (incluindo novas linhas) vão ser preservados dentro da região entre aspas. Aspas duplas também permitem o uso de aspas simples sem escape comuns.

Caractere Formas de escape
@ \@
? \?
Nova linha \n
Tab \t
Caractere Unicode U+XXXX \uXXXX
Aspas simples (')

Uma destas opções:

  • \'
  • Coloque toda a string entre aspas duplas ("This'll work", por exemplo).
Aspas duplas (") \"

Não é possível inserir a string entre aspas simples.

A redução dos espaços em branco e o escape de Android acontecem depois que o arquivo de recurso é analisado como XML. Isso significa que <string> &#32; &#8200; &#8195;</string> (espaço, pontuação, espaço Unicode Em) são reduzidos em um único espaço (" "), porque todos são espaços Unicode após a análise do arquivo como um XML. Para preservar esses espaços como estão, você pode os colocar entre aspas (<string>" &#32; &#8200; &#8195;"</string>) ou usar o escape do Android (<string> \u0032 \u8200 \u8195</string>).

Observação: do ponto de vista do analisador de XML, não há diferença entre <string>"Test this"</string> e <string>&quot;Test this&quot;</string>. Os dois formatos não mostram aspas, mas acionam a cota de preservação de espaços em branco do Android, o que não vai ter efeito prático neste caso.

Como formatar strings

Se você precisar formatar suas strings, é possível colocar os argumentos de formato nos recursos delas, conforme demonstrado no exemplo abaixo.

<string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string>

Nesse exemplo, a string de formatação tem dois argumentos: %1$s é uma string e %2$d é um número decimal. Depois, a string é formatada chamando getString(int, Object...). Exemplo:

Kotlin

var text = getString(R.string.welcome_messages, username, mailCount)

Java

String text = getString(R.string.welcome_messages, username, mailCount);

Aplicar estilo com marcação HTML

Você pode adicionar estilo às suas strings com marcações HTML. Exemplo:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="welcome">Welcome to <b>Android</b>!</string>
</resources>

Os elementos HTML abaixo têm suporte:

  • Negrito: <b>, <em>
  • Itálico: <i>, <cite>, <dfn>
  • Texto 25% maior: <big>
  • Texto 20% menor: <small>
  • Definição das propriedades da fonte: <font face=”font_family“ color=”hex_color”>. Exemplos de possíveis famílias de fontes incluem monospace, serif e sans_serif.
  • Família de fontes monoespaçadas: <tt>
  • Tachado: <s>, <strike>, <del>
  • Sublinhado: <u>
  • Sobrescrito: <sup>
  • Subscrito: <sub>
  • Marcador: <ul>, <li>
  • Quebras de linha: <br>
  • Divisão: <div>
  • Estilo CSS: <span style=”color|background_color|text-decoration”>
  • Parágrafos: <p dir=”rtl | ltr” style=”…”>

Se você não estiver aplicando uma formatação, vai poder definir diretamente o texto da TextView chamando setText(java.lang.CharSequence). Em alguns casos, você pode criar um recurso de texto com estilo que também é usado como uma string de formatação. Normalmente, isso não funciona porque os métodos format(String, Object...) e getString(int, Object...) tiram todas as informações de estilo da string. A solução para esse problema é criar tags HTML com entidades com escape, que são então extraídas com fromHtml(String), após a realização da formatação. Exemplo:

  1. Armazene seu recurso de texto com estilo como uma string HTML com escape:
    <resources>
      <string name="welcome_messages">Hello, %1$s! You have &lt;b>%2$d new messages&lt;/b>.</string>
    </resources>
    

    Nessa string formatada, é adicionado um elemento <b>. O colchete de abertura tem escape HTML usando a notação &lt;.

  2. Em seguida, formate a string normalmente, mas também chame fromHtml(String) para converter o texto HTML em texto com estilo:

    Kotlin

    val text: String = getString(R.string.welcome_messages, username, mailCount)
    val styledText: Spanned = Html.fromHtml(text, FROM_HTML_MODE_LEGACY)
    

    Java

    String text = getString(R.string.welcome_messages, username, mailCount);
    Spanned styledText = Html.fromHtml(text, FROM_HTML_MODE_LEGACY);
    

Como o método fromHtml(String) vai formatar todas as entidades HTML, não esqueça de usar htmlEncode(String) para executar o escape de qualquer caractere HTML possível nas strings usadas com o texto formatado. Por exemplo, se você estiver formatando uma string que contém caracteres como "<" ou "&", eles precisam de escape antes da formatação, para que, quando a string formatada for transmitida por fromHtml(String), os caracteres apareçam como foram escritos originalmente. Exemplo:

Kotlin

val escapedUsername: String = TextUtils.htmlEncode(username)

val text: String = getString(R.string.welcome_messages, escapedUsername, mailCount)
val styledText: Spanned = Html.fromHtml(text, FROM_HTML_MODE_LEGACY)

Java

String escapedUsername = TextUtils.htmlEncode(username);

String text = getString(R.string.welcome_messages, escapedUsername, mailCount);
Spanned styledText = Html.fromHtml(text);

Criar estilo com spannables

Um Spannable é um objeto de texto que pode receber estilo com propriedades typeface, como cor e peso da fonte. O SpannableStringBuilder é usado para criar o texto e aplicar estilos definidos no pacote android.text.style ao texto.

Você pode usar os métodos auxiliares abaixo para realizar grande parte da criação do texto spannable:

Kotlin

/**
 * Returns a CharSequence that concatenates the specified array of CharSequence
 * objects and then applies a list of zero or more tags to the entire range.
 *
 * @param content an array of character sequences to apply a style to
 * @param tags the styled span objects to apply to the content
 *        such as android.text.style.StyleSpan
 */
private fun apply(content: Array<out CharSequence>, vararg tags: Any): CharSequence {
    return SpannableStringBuilder().apply {
        openTags(tags)
        content.forEach { charSequence ->
            append(charSequence)
        }
        closeTags(tags)
    }
}

/**
 * Iterates over an array of tags and applies them to the beginning of the specified
 * Spannable object so that future text appended to the text will have the styling
 * applied to it. Do not call this method directly.
 */
private fun Spannable.openTags(tags: Array<out Any>) {
    tags.forEach { tag ->
        setSpan(tag, 0, 0, Spannable.SPAN_MARK_MARK)
    }
}

/**
 * "Closes" the specified tags on a Spannable by updating the spans to be
 * endpoint-exclusive so that future text appended to the end will not take
 * on the same styling. Do not call this method directly.
 */
private fun Spannable.closeTags(tags: Array<out Any>) {
    tags.forEach { tag ->
    if (length > 0) {
            setSpan(tag, 0, length, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE)
        } else {
            removeSpan(tag)
        }
    }
}

Java

/**
 * Returns a CharSequence that concatenates the specified array of CharSequence
 * objects and then applies a list of zero or more tags to the entire range.
 *
 * @param content an array of character sequences to apply a style to
 * @param tags the styled span objects to apply to the content
 *        such as android.text.style.StyleSpan
 *
 */
private static CharSequence applyStyles(CharSequence[] content, Object[] tags) {
    SpannableStringBuilder text = new SpannableStringBuilder();
    openTags(text, tags);
    for (CharSequence item : content) {
        text.append(item);
    }
    closeTags(text, tags);
    return text;
}

/**
 * Iterates over an array of tags and applies them to the beginning of the specified
 * Spannable object so that future text appended to the text will have the styling
 * applied to it. Do not call this method directly.
 */
private static void openTags(Spannable text, Object[] tags) {
    for (Object tag : tags) {
        text.setSpan(tag, 0, 0, Spannable.SPAN_MARK_MARK);
    }
}

/**
 * "Closes" the specified tags on a Spannable by updating the spans to be
 * endpoint-exclusive so that future text appended to the end will not take
 * on the same styling. Do not call this method directly.
 */
private static void closeTags(Spannable text, Object[] tags) {
    int len = text.length();
    for (Object tag : tags) {
        if (len > 0) {
            text.setSpan(tag, 0, len, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
        } else {
            text.removeSpan(tag);
        }
    }
}

Os métodos bold, italic e color abaixo envolvem os métodos auxiliares acima e mostram exemplos específicos de aplicação de estilos definidos no pacote android.text.style. Você pode criar métodos semelhantes para outros tipos de estilos de texto.

Kotlin

/**
 * Returns a CharSequence that applies boldface to the concatenation
 * of the specified CharSequence objects.
 */
fun bold(vararg content: CharSequence): CharSequence = apply(content, StyleSpan(Typeface.BOLD))

/**
 * Returns a CharSequence that applies italics to the concatenation
 * of the specified CharSequence objects.
 */
fun italic(vararg content: CharSequence): CharSequence = apply(content, StyleSpan(Typeface.ITALIC))

/**
 * Returns a CharSequence that applies a foreground color to the
 * concatenation of the specified CharSequence objects.
 */
fun color(color: Int, vararg content: CharSequence): CharSequence =
        apply(content, ForegroundColorSpan(color))

Java

/**
 * Returns a CharSequence that applies boldface to the concatenation
 * of the specified CharSequence objects.
 */
public static CharSequence bold(CharSequence... content) {
    return apply(content, new StyleSpan(Typeface.BOLD));
}

/**
 * Returns a CharSequence that applies italics to the concatenation
 * of the specified CharSequence objects.
 */
public static CharSequence italic(CharSequence... content) {
    return apply(content, new StyleSpan(Typeface.ITALIC));
}

/**
 * Returns a CharSequence that applies a foreground color to the
 * concatenation of the specified CharSequence objects.
 */
public static CharSequence color(int color, CharSequence... content) {
    return apply(content, new ForegroundColorSpan(color));
}

Confira um exemplo de como agrupar esses métodos para aplicar vários estilos a palavras individuais em uma frase:

Kotlin

// Create an italic "hello, " a red "world",
// and bold the entire sequence.
val text: CharSequence = bold(italic(getString(R.string.hello)),
        color(Color.RED, getString(R.string.world)))

Java

// Create an italic "hello, " a red "world",
// and bold the entire sequence.
CharSequence text = bold(italic(getString(R.string.hello)),
    color(Color.RED, getString(R.string.world)));

O módulo core-ktx do Kotlin também contém funções de extensão que facilitam ainda mais o trabalho com períodos. Confira a documentação do pacote android.text (link em inglês) no GitHub para mais detalhes.

Para mais informações sobre como trabalhar com períodos, consulte os links abaixo (em inglês):

Estilo com anotações

Você pode aplicar estilos complexos ou personalizados usando a classe Annotation com a tag <annotation> nos arquivos de recurso strings.xml. A tag de anotação permite marcar partes da string para estilo personalizado definindo pares de chave-valor personalizados no XML que a biblioteca converte em períodos da Annotation. Você pode extrair essas anotações e usar a chave e o valor para aplicar o estilo.

Ao criar anotações, adicione a tag <annotation> para todas as traduções da string em todos os arquivos strings.xml.


Como aplicar um typeface personalizado à palavra “texto” em todos os idiomas

Exemplo: como adicionar um typeface personalizado

  1. Adicione uma tag <annotation> e defina o par de chave-valor. Nesse caso, a chave é font, e o valor é o tipo de fonte que queremos usar: title_emphasis

    // values/strings.xml
    <string name="title">Best practices for <annotation font="title_emphasis">text</annotation> on Android</string>
    
    // values-es/strings.xml
    <string name="title"><annotation font="title_emphasis">Texto</annotation> en Android: mejores prácticas</string>
    
  2. Carregue o recurso da string e encontre as anotações com a chave font. Em seguida, crie um período personalizado e substitua o existente.

    Kotlin

    // get the text as SpannedString so we can get the spans attached to the text
    val titleText = getText(R.string.title) as SpannedString
    
    // get all the annotation spans from the text
    val annotations = titleText.getSpans(0, titleText.length, Annotation::class.java)
    
    // create a copy of the title text as a SpannableString.
    // the constructor copies both the text and the spans. so we can add and remove spans
    val spannableString = SpannableString(titleText)
    
    // iterate through all the annotation spans
    for (annotation in annotations) {
       // look for the span with the key font
       if (annotation.key == "font") {
          val fontName = annotation.value
          // check the value associated to the annotation key
          if (fontName == "title_emphasis") {
             // create the typeface
             val typeface = getFontCompat(R.font.permanent_marker)
             // set the span at the same indices as the annotation
             spannableString.setSpan(CustomTypefaceSpan(typeface),
                titleText.getSpanStart(annotation),
                titleText.getSpanEnd(annotation),
                Spannable.SPAN_EXCLUSIVE_EXCLUSIVE)
          }
       }
    }
    
    // now, the spannableString contains both the annotation spans and the CustomTypefaceSpan
    styledText.text = spannableString
    

    Java

    // get the text as SpannedString so we can get the spans attached to the text
    SpannedString titleText = (SpannedString) getText(R.string.title);
    
    // get all the annotation spans from the text
    Annotation[] annotations = titleText.getSpans(0, titleText.length(), Annotation.class);
    
    // create a copy of the title text as a SpannableString.
    // the constructor copies both the text and the spans. so we can add and remove spans
    SpannableString spannableString = new SpannableString(titleText);
    
    // iterate through all the annotation spans
    for (Annotation annotation: annotations) {
      // look for the span with the key font
      if (annotation.getKey().equals("font")) {
        String fontName = annotation.getValue();
        // check the value associated to the annotation key
        if (fontName.equals("title_emphasis")) {
        // create the typeface
        Typeface typeface = ResourcesCompat.getFont(this, R.font.roboto_mono);
        // set the span at the same indices as the annotation
        spannableString.setSpan(new CustomTypefaceSpan(typeface),
          titleText.getSpanStart(annotation),
          titleText.getSpanEnd(annotation),
          Spannable.SPAN_EXCLUSIVE_EXCLUSIVE);
        }
      }
    }
    
    // now, the spannableString contains both the annotation spans and the CustomTypefaceSpan
    styledText.text = spannableString;
    

Se você estiver usando o mesmo texto várias vezes, vai precisar construir o objeto SpannableString uma vez e o reutilizar conforme necessário para evitar possíveis problemas de desempenho e memória.

Para mais exemplos de uso de anotações, consulte Como estilizar texto internacionalizado no Android (link em inglês).

Períodos de anotação e parcelamento de texto

Como os períodos de Annotation também são ParcelableSpans, os pares de chave-valor podem ser parcelados ou não. Desde que o receptor da parcela saiba como interpretar as anotações, você pode usar períodos de Annotation para aplicar estilos personalizados ao texto parcelado.

Para manter seu estilo personalizado ao transmitir o texto para um Intent Bundle, primeiro é necessário adicionar períodos de Annotation ao texto. Você pode fazer isso nos recursos XML usando a tag <annotation>, como mostrado no exemplo acima, ou no código, criando uma nova Annotation e a configurando como um período, conforme mostrado abaixo:

Kotlin

val spannableString = SpannableString("My spantastic text")
val annotation = Annotation("font", "title_emphasis")
spannableString.setSpan(annotation, 3, 7, Spannable.SPAN_EXCLUSIVE_EXCLUSIVE)

// start Activity with text with spans
val intent = Intent(this, MainActivity::class.java)
intent.putExtra(TEXT_EXTRA, spannableString)
startActivity(intent)

Java

SpannableString spannableString = new SpannableString("My spantastic text");
Annotation annotation = new Annotation("font", "title_emphasis");
spannableString.setSpan(annotation, 3, 7, 33);

// start Activity with text with spans
Intent intent = new Intent(this, MainActivity.class);
intent.putExtra(TEXT_EXTRA, spannableString);
this.startActivity(intent);

Extraia o texto do Bundle com uma SpannableString e, em seguida, analise as anotações anexadas, conforme mostrado no exemplo acima.

Kotlin

// read text with Spans
val intentCharSequence = intent.getCharSequenceExtra(TEXT_EXTRA) as SpannableString

Java

// read text with Spans
SpannableString intentCharSequence = (SpannableString)intent.getCharSequenceExtra(TEXT_EXTRA);

Para mais informações sobre estilo de texto, consulte os links abaixo (em inglês):