Recursos de string

Os recursos de string fornecem strings de texto para o aplicativo com estilo e formatação de texto opcional. 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

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

Observação: Strings são recursos simples que são referenciados usando o valor fornecido no atributo name (não o 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 atributo filename é arbitrário. O name do elemento <string> será usado como o código do recurso.

tipo de dados do recurso compilado:

Ponteiro do recurso para um String.

referência do 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:

a seguir:

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 de aplicativo recupera uma string:

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

Você pode usar getString(int) ou getText(int) para recuperar uma string. getText(int) manterá qualquer estilo de texto avançado aplicado à string.

Matriz de strings

Matriz de strings que pode ser referenciada pelo aplicativo.

Observação: Matriz de strings é um recurso simples referenciado usando o valor fornecido no atributo name (não o nome do arquivo XML). Dessa forma, você pode 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 atributo filename é arbitrário. O name do elemento <string-array> será usado como o código do recurso.

tipo de dados do recurso compilado:

Ponteiro de recurso para uma matriz de Strings.

referência do recurso:

Em Java: R.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:

a seguir:

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 de aplicativo recupera uma matriz de strings:

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. Escreve-se "1 book", mas, para qualquer outra quantidade, "n books". 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, portanto, o Android fornece métodos como o getQuantityString() para selecionar o recurso apropriado para você.

Apesar de serem historicamente chamadas de “strings de quantidade” (ainda chamadas assim na API), elas devem ser usadas apenas para plurais. Seria um erro usar strings de quantidade para implementar algo como as strings "Inbox”/"Inbox (12)” do Gmail para quando há mensagens não lidas, por exemplo. Pode parecer conveniente usar strings de quantidade em vez de uma declaração if, mas importante observar que alguns idiomas (como o chinês) não fazem essas distinções gramaticais, portanto, você sempre receberá a string other.

A seleção de qual string usar é feita exclusivamente de acordo com a necessidade gramatical. No inglês, uma string para zero será ignorada mesmo que a quantidade seja 0, pois 0 não é gramaticalmente diferente de 2 ou de qualquer número exceto 1 ("zero books", "one book", "two books” e assim por diante). Por outro lado, em coreano, apenas a string other será usada em qualquer ocasião.

Não se engane pelo fato de que, por exemplo, two parece ser aplicável apenas 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. Baseie-se em seu tradutor para identificar quais são as distinções obrigatórias de seu idioma.

Frequentemente, é possível evitar strings de quantidade usando formulações de quantidade neutra, como "Books: 1". Isso facilitará as coisas para você e seus tradutores se for um estilo adequado para seu aplicativo.

Observação: A coleção de plurais é um recurso simples referenciado com o valor fornecido no atributo name (não o nome do arquivo XML). Dessa forma, você pode combinar plurais com outros recursos simples em um arquivo XML, em um elemento <resources>.

localização do arquivo:

res/values/filename.xml
O atributo filename é arbitrário. O name do elemento <plurals> será usado como o código do recurso.

referência do 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. Deve ser o nó raiz.

Nenhum atributo.

<plurals>

Coleção de strings em que uma string é fornecida de acordo com a quantidade de um item. Contém um ou mais elementos <item>.

atributos:

name: String. Nome do par de strings. Esse nome será usado como código do recurso.

<item>

String plural ou singular. O valor pode ser uma referência a outro recurso de string. Deve ser um filho de um elemento <plurals>. Você deve executar o escape de apóstrofes 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

Keyword. Valor que indica quando usar a string. Valores válidos, com exemplos entre parênteses:

Valor	Descrição
`zero`	Quando o idioma exige tratamento especial para o número 0 (como em árabe).
`one`	Quando 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).
`two`	Quando o idioma exige tratamento especial para números como 2 (como 2 em galês ou 102 em esloveno).
`few`	Quando 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).
`many`	Quando o idioma exige tratamento especial para números “grandes” (como números terminados em 11 a 99 em maltês).
`other`	Quando 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).

a seguir:

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>

Código Java:

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

Ao usar o método getQuantityString(), você precisa passar o count duas vezes se a string contiver 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 contêm formatação de string, você não precisa passar o terceiro parâmetro para getQuantityString.

Formatação e estilo

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

Executar o escape de apóstrofes e aspas

Se a string contiver um apóstrofo ('), você deve executar o escape com uma barra invertida (\') ou inserir a string em aspas duplas (""). Veja exemplos de strings que funcionam e que não funcionam:

<string name="good_example">This\'ll work</string>
<string name="good_example_2">"This'll also work"</string>
<string name="bad_example">This doesn't work</string>
    <!-- Causes a compile error -->

Se tiver aspas duplas em sua string, execute o escape (\"). Colocar a string entre aspas simples não funciona.

<string name="good_example">This is a \"good string\".</string>
<string name="bad_example">This is a "bad string".</string>
    <!-- Quotes are stripped; displays as: This is a bad string. -->
<string name="bad_example_2">'This is another "bad string".'</string>
    <!-- Causes a compile error -->

Formatar strings

Se precisar formatar suas strings usando String.format(String, Object...), coloque os argumentos de formatação no recurso de string. Por exemplo, com o seguinte recurso:

<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. Você pode formatar a string com argumentos do seu aplicativo, assim:

Resources res = getResources();
String text = String.format(res.getString(R.string.welcome_messages), username, mailCount);

Aplicar estilo com marcação HTML

Você pode adicionar estilo às suas strings com marcação HTML. Por exemplo:

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

São elementos HTML permitidos:

<b> para texto em negrito.
<i> para texto em itálico.
<u> para sublinhar o texto.

Ocasionalmente, você pode criar um recurso de texto com estilo que também é usado como uma string de formatação. Normalmente, isso não funcionaria porque o método String.format(String, Object...) remove 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 recuperadas com fromHtml(String), após a realização da formatação. Por exemplo:

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, adiciona-se um elemento <b>. Observe que o colchete de abertura tem escape HTML usando a notação <.

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

Resources res = getResources();
String text = String.format(res.getString(R.string.welcome_messages), username, mailCount);
CharSequence styledText = Html.fromHtml(text);

Como o método fromHtml(String) formatará todas as entidades HTML, não deixe de executar o escape de qualquer caractere HTML possível nas strings usadas com o texto formatado usando htmlEncode(String). Por exemplo, se pretende passar um argumento de string para String.format() que possa conter caracteres como "<" ou "&", execute o escape antes da formatação para que a string formatada passe por fromHtml(String) e os caracteres apareçam como foram escritos originalmente. Por exemplo:

String escapedUsername = TextUtil.htmlEncode(username);

Resources res = getResources();
String text = String.format(res.getString(R.string.welcome_messages), escapedUsername, mailCount);
CharSequence styledText = Html.fromHtml(text);

Criar estilo com Spannables

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

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

/**
 * 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 apply(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 a seguir mostram como chamar os métodos auxiliares para aplicar estilos definidos no pacote android.text.style. Você pode criar métodos semelhantes para outros tipos de estilos de texto.

/**
 * 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));
}

Veja um exemplo de como encadear esses métodos para criar uma sequência de caracteres com diferentes tipos de estilo aplicados a palavras individuais:

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

Style