Recursos no Compose

O Jetpack Compose pode acessar os recursos definidos no seu projeto Android. Este documento explica algumas das APIs que o Compose oferece para fazer isso.

Recursos são os arquivos complementares e o conteúdo estático usado pelo seu código, como bitmaps, definições de layout, strings da interface do usuário, instruções de animação, entre outras coisas. Se você não está familiarizado com os recursos no Android, consulte o guia sobre visão geral de recursos de apps.

Strings

O tipo mais comum de recurso são as strings. Use a API stringResource para recuperar uma string definida estaticamente nos recursos XML.

// In the res/values/strings.xml file
// <string name="compose">Jetpack Compose</string>

// In your Compose code
Text(
    text = stringResource(R.string.compose)
)
ResourcesSnippets.kt

stringResource também funciona ao definir o formato de posicionamento.

// In the res/values/strings.xml file
// <string name="congratulate">Happy %1$s %2$d</string>

// In your Compose code
Text(
    text = stringResource(R.string.congratulate, "New Year", 2021)
)
ResourcesSnippets.kt

Plurais de strings (recurso experimental)

Use a API pluralStringResource para carregar um plural com determinada quantidade.

// In the res/strings.xml file
// <plurals name="runtime_format">
//    <item quantity="one">%1$d minute</item>
//    <item quantity="other">%1$d minutes</item>
// </plurals>

// In your Compose code
Text(
    text = pluralStringResource(
        R.plurals.runtime_format,
        quantity,
        quantity
    )
)
ResourcesSnippets.kt

Ao usar o método pluralStringResource, você precisa passar a contagem duas vezes se a string contém formatação com um número. Por exemplo, para a string %1$d minutes, o primeiro parâmetro de contagem seleciona o plural adequado, e o segundo parâmetro de contagem é inserido no marcador de posição %1$d. Se as strings de plural não incluírem formatação de string, não vai ser necessário transmitir o terceiro parâmetro para pluralStringResource.

Para ver mais informações sobre plurais, consulte a documentação da string de quantidade.

Dimensões

Da mesma forma, use a API dimensionResource para ver as dimensões de um arquivo XML de recurso.

// In the res/values/dimens.xml file
// <dimen name="padding_small">8dp</dimen>

// In your Compose code
val smallPadding = dimensionResource(R.dimen.padding_small)
Text(
    text = "...",
    modifier = Modifier.padding(smallPadding)
)
ResourcesSnippets.kt

Cores

Se você estiver adotando o Compose gradualmente no app, use a API colorResource para receber cores de um arquivo XML de recursos.

// In the res/colors.xml file
// <color name="purple_200">#FFBB86FC</color>

// In your Compose code
Divider(color = colorResource(R.color.purple_200))
ResourcesSnippets.kt

colorResource funciona da forma esperada com cores estáticas, mas nivela os recursos da lista de estados de cores.

Aviso: priorize as cores do tema e não as cores codificadas. Embora seja possível acessar cores usando a função colorResource, é recomendável que as cores do app sejam definidas em um MaterialTheme que possa ser acessado a partir de elementos combináveis, como MaterialTheme.colors.primary: Saiba mais sobre isso na documentação de sistemas de design no Compose.

Recursos de vetor e recursos de imagem

Use a API painterResource para carregar drawables vetoriais ou formatos de recursos rasterizados, como PNGs. Não é necessário saber o tipo de drawable, basta usar painterResource em Image que podem ser compostas ou modificadores paint.

// Files in res/drawable folders. For example:
// - res/drawable-nodpi/ic_logo.xml
// - res/drawable-xxhdpi/ic_logo.png

// In your Compose code
Icon(
    painter = painterResource(id = R.drawable.ic_logo),
    contentDescription = null // decorative element
)
ResourcesSnippets.kt

painterResource decodifica e analisa o conteúdo do recurso na linha de execução principal.

Observação: Diferente de Context.getDrawable, painterResource só pode carregar tipos de Drawable de plataforma BitmapDrawable e VectorDrawable.

Drawables vetoriais animados

Use a API AnimatedImageVector.animatedVectorResource para carregar um XML de drawables vetoriais animados. O método retorna uma instância de AnimatedImageVector. Se quiser mostrar a imagem animada, use o método rememberAnimatedVectorPainter para criar um Painter que possa ser usado nos elementos Image e Icon. O parâmetro booleano atEnd do método rememberAnimatedVectorPainter indica se a imagem deve ser desenhada no final de todas as animações. Se usado com um estado mutável, trocar esse valor acionará a animação correspondente.

// Files in res/drawable folders. For example:
// - res/drawable/ic_hourglass_animated.xml

// In your Compose code
val image =
    AnimatedImageVector.animatedVectorResource(R.drawable.ic_hourglass_animated)
val atEnd by remember { mutableStateOf(false) }
Icon(
    painter = rememberAnimatedVectorPainter(image, atEnd),
    contentDescription = null // decorative element
)
ResourcesSnippets.kt

Ícones

O Jetpack Compose inclui o objeto Icons, que é o ponto de entrada para usar ícones do Material Design no Compose (link em inglês). Existem cinco temas de ícones diferentes Preenchido, Contornado, Arredondado, TwoTone e Pontiagudo. Cada tema contém os mesmos ícones, mas com um estilo visual diferente. Em geral, um tema é escolhido e usado em todo o app para manter a consistência.

Para desenhar um ícone, você pode usar o Icon que pode ser composto, que aplica tonalidade e fornece um tamanho do layout que corresponda ao ícone.

Icon(Icons.Rounded.Menu, contentDescription = "Localized description")
ResourcesSnippets.kt

Alguns dos ícones mais usados estão disponíveis como parte da dependência androidx.compose.material. Para usar qualquer um dos outros ícones do Material Design, adicione a dependência material-icons-extended ao arquivo build.gradle.

dependencies {
  def composeBom = platform('androidx.compose:compose-bom:2024.10.01')
  implementation composeBom

  implementation 'androidx.compose.material:material-icons-extended'
}

Observação: os ícones mantêm os mesmos nomes definidos pelo Material Design, mas com o nome snake_case convertido para PascalCase. Por exemplo, add_alarm passa a ser AddAlarm. Os ícones que começam com um número, como 360, recebem o prefixo _ e passam a ser _360.

Aviso: material-icons-extended é uma biblioteca grande e pode afetar o tamanho do APK. Por esse motivo, considere usar o R8/Proguard em builds em produção para remover os recursos que não são usados. Além disso, devido ao grande tamanho, o tempo de compilação do projeto e o tempo de carregamento de visualizações do Android Studio podem aumentar durante o desenvolvimento. Por outro lado, material-icons-extended permite que você itere mais rapidamente usando o acesso rápido às versões mais recentes de todos os ícones. Você também pode usar essa biblioteca para copiar o código-fonte do ícone para ter uma cópia fixa no app ou, como alternativa, importar os ícones usando o recurso de importação de recursos de vetor do Android Studio.

Fontes

Para usar fontes no Compose, faça o download e agrupe os arquivos de fontes diretamente nos APKs, colocando-os na pasta res/font.

Carregue cada fonte usando a API Font e crie uma FontFamily, para usar em instâncias de TextStyle e criar uma Typography própria. O código a seguir foi extraído da amostra de composição Crane e do arquivo Typography.kt (links em inglês).

// Define and load the fonts of the app
private val light = Font(R.font.raleway_light, FontWeight.W300)
private val regular = Font(R.font.raleway_regular, FontWeight.W400)
private val medium = Font(R.font.raleway_medium, FontWeight.W500)
private val semibold = Font(R.font.raleway_semibold, FontWeight.W600)

// Create a font family to use in TextStyles
private val craneFontFamily = FontFamily(light, regular, medium, semibold)

// Use the font family to define a custom typography
val craneTypography = Typography(
    titleLarge = TextStyle(
        fontFamily = craneFontFamily
    ) /* ... */
)

// Pass the typography to a MaterialTheme that will create a theme using
// that typography in the part of the UI hierarchy where this theme is used
@Composable
fun CraneTheme(content: @Composable () -> Unit) {
    MaterialTheme(typography = craneTypography) {
        content()
    }
}
ResourcesSnippets.kt

Para usar fontes para download no Compose, consulte a página Fontes para download.

Para saber mais sobre tipografia, consulte a documentação Temas no Compose.