Chip

O componente Chip é um elemento de interface compacto e interativo. Ele representa entidades complexas, como um contato ou uma tag, geralmente com um ícone e um rótulo. Ela pode ser marcável, dispensável ou clicável.

Confira os quatro tipos de chips e onde eles podem ser usados:

  • Assistir: orienta o usuário durante uma tarefa. Geralmente aparece como um elemento temporário da interface do usuário em resposta à entrada do usuário.
  • Filtro: permite que os usuários refinem o conteúdo de um conjunto de opções. Eles podem ser selecionados ou desmarcados e podem incluir um ícone de marca de seleção quando selecionados.
  • Entrada: representa informações fornecidas pelo usuário, como seleções em um menu. Eles podem conter um ícone e texto, além de fornecer um X para remoção.
  • Sugestão: oferece recomendações ao usuário com base na atividade ou entrada recente dele. Normalmente aparecem abaixo de um campo de entrada para solicitar ações do usuário.
Um exemplo de cada um dos quatro componentes de ícone, com suas características exclusivas destacadas.
Figura 1. Os quatro componentes de chip.

Superfície da API

Há quatro elementos combináveis que correspondem aos quatro tipos de chips. As seções a seguir descrevem esses elementos combináveis e suas diferenças em detalhes. No entanto, eles compartilham os seguintes parâmetros:

  • label: a string que aparece no ícone.
  • icon: o ícone exibido no início do ícone de opção. Alguns elementos combináveis específicos têm parâmetros leadingIcon e trailingIcon separados.
  • onClick: a lambda que o ícone de ação chama quando o usuário pressiona.

Ícone de assistência

O elemento combinável AssistChip oferece uma maneira simples de criar um chip de assistência que direciona o usuário em uma direção específica. Um recurso distintivo é o parâmetro leadingIcon, que permite mostrar um ícone no lado esquerdo do ícone. O exemplo a seguir demonstra como implementar:

@Composable
fun AssistChipExample() {
    AssistChip(
        onClick = { Log.d("Assist chip", "hello world") },
        label = { Text("Assist chip") },
        leadingIcon = {
            Icon(
                Icons.Filled.Settings,
                contentDescription = "Localized description",
                Modifier.size(AssistChipDefaults.IconSize)
            )
        }
    )
}
Chip.kt

Esta implementação aparece da seguinte maneira.

Um ícone principal e um rótulo de texto simples em um ícone de ajuda.
Figura 2. Ícone de assistência.

Ícone de filtro

O elemento combinável FilterChip exige que você acompanhe se o ícone está selecionado ou não. O exemplo a seguir demonstra como mostrar um ícone de marcação à esquerda somente quando o usuário seleciona o ícone:

@Composable
fun FilterChipExample() {
    var selected by remember { mutableStateOf(false) }

    FilterChip(
        onClick = { selected = !selected },
        label = {
            Text("Filter chip")
        },
        selected = selected,
        leadingIcon = if (selected) {
            {
                Icon(
                    imageVector = Icons.Filled.Done,
                    contentDescription = "Done icon",
                    modifier = Modifier.size(FilterChipDefaults.IconSize)
                )
            }
        } else {
            null
        },
    )
}
Chip.kt

Esta implementação aparece assim quando não está selecionada:

Um ícone de filtro não selecionado, sem marca de seleção e com um plano de fundo simples.
Figura 3. Ícone de filtro desmarcado.

E aparece assim quando selecionado:

Chip de filtro selecionado, com uma marca de seleção e um plano de fundo colorido.
Figura 4. Ícone de filtro selecionado.

Ícone de entrada

Use o elemento combinável InputChip para criar chips que resultam da interação do usuário. Por exemplo, em um cliente de e-mail, quando o usuário está escrevendo uma mensagem, um ícone de entrada pode representar um contato adicionado ao campo "Para:".

A implementação a seguir demonstra um ícone de entrada que já está em um estado selecionado. O usuário dispensa o ícone ao pressioná-lo.

@Composable
fun InputChipExample(
    text: String,
    onDismiss: () -> Unit,
) {
    var enabled by remember { mutableStateOf(true) }
    if (!enabled) return

    InputChip(
        onClick = {
            onDismiss()
            enabled = !enabled
        },
        label = { Text(text) },
        selected = enabled,
        avatar = {
            Icon(
                Icons.Filled.Person,
                contentDescription = "Localized description",
                Modifier.size(InputChipDefaults.AvatarSize)
            )
        },
        trailingIcon = {
            Icon(
                Icons.Default.Close,
                contentDescription = "Localized description",
                Modifier.size(InputChipDefaults.AvatarSize)
            )
        },
    )
}
Chip.kt

Esta implementação aparece da seguinte maneira.

Um ícone de entrada com um avatar e um ícone à direita.
Figura 5. Ícone de entrada.

Chip de sugestão

O elemento combinável SuggestionChip é o mais básico dos elementos listados nesta página, tanto na definição da API quanto nos casos de uso comuns. Os chips de sugestão apresentam dicas geradas dinamicamente. Por exemplo, em um app de chat de IA, você pode usar chips de sugestão para apresentar possíveis respostas à mensagem mais recente.

Considere esta implementação de SuggestionChip:

@Composable
fun SuggestionChipExample() {
    SuggestionChip(
        onClick = { Log.d("Suggestion chip", "hello world") },
        label = { Text("Suggestion chip") }
    )
}
Chip.kt

Esta implementação aparece da seguinte maneira:

Um chip de sugestão simples.
Figura 6. Chip de sugestão de resposta.

Ícone elevado

Todos os exemplos neste documento usam os elementos combináveis básicos que têm uma aparência simples. Se você quiser um ícone com aparência elevada, use um dos três elementos combináveis a seguir:

Outros recursos