Pular para o conteúdo
Navegação

Command

/componentes/command.mdmarkdown cru, para quem lê com agent em vez de olho

Paleta de comandos

Ou aperte o atalho, de qualquer lugar da tela.

Importar
import { Command } from '@rivocode/ui'

Quando usar

A paleta de comandos: um campo, uma lista e o teclado.

Ela existe para quem trabalha o dia inteiro na mesma tela e já sabe para onde quer ir. Navegar por menu custa três cliques e a memória de onde a opção mora; aqui custa o nome da coisa.

<Command
  open={aberta}
  onOpenChange={setAberta}
  groups={[
    { label: 'Ir para', items: [{ id: 'pacientes', label: 'Pacientes', onSelect: irParaPacientes }] },
  ]}
/>

A busca

Ignora acento e caixa, e lê também as keywords do item. "ficha", "prontuário" e "cadastro" levando a Pacientes é o que separa uma paleta útil de uma que só acha quem já sabe o nome exato, que é justamente quem menos precisa dela.

highlight marca no rótulo de cada item o trecho que casou, com o Highlight da casa: "fisc" pinta o "fisc" de "Notas fiscais". A busca continua sendo por texto, sobre label, description e keywords; só o rótulo ganha a marca, e item achado por palavra-chave sai sem marca, porque o trecho não está à vista.

<Command open={open} onOpenChange={setOpen} groups={groups} highlight />

Cada abertura começa limpa. Paleta que guarda a busca da vez passada abre mostrando o resultado de outra pergunta.

Buscar e não achar nada também precisa ser dito. A contagem de resultados e a mensagem de vazio saem numa região role="status" fora da lista: sem ela, digitar uma busca sem resultado produz silêncio, com o foco parado no campo e nenhuma pista de que a lista esvaziou. O title é o nome do campo e o da lista, e é ele que o leitor de tela anuncia ao abrir: o placeholder some ao digitar e não serve de rótulo.

O atalho

Ctrl+K, ou Cmd+K no Mac, registrado por ela mesma. Passe shortcut={null} para registrar na sua aplicação, ou outra letra para trocar; maiúscula e minúscula são a mesma tecla.

O atalho não dispara dentro de um campo de texto nem do RichTextEditor, onde o Ctrl+K é link, nem quando outra peça já tratou a tecla. A exceção é o próprio campo da paleta aberta: ali o mesmo atalho a fecha. Enquanto um método de entrada compõe (japonês, chinês, acentos pelo IME), o Enter confirma a composição e não executa o comando.

A lista é dado, não filho

Os itens vêm por groups, e não como componentes aninhados. A filtragem, a ordem em que a seta anda e o aria-activedescendant moram todos num lugar só; a forma composta obrigaria a peça a adivinhar o texto de cada filho para poder filtrar por ele.

Quando não usar

Menos de dez destinos não justificam. Com essa quantidade a Sidebar mostra tudo de uma vez, e a paleta vira um passo a mais para chegar no mesmo lugar.

Para escolher um valor dentro de um formulário, e não ir a um lugar ou disparar uma ação, é Combobox: ele guarda a escolha e vive no campo, enquanto a paleta some depois de agir.

No React Native

Não porta. A paleta de comandos é um gesto de mesa (abre por atalho, anda por seta, confirma por Enter), e nenhuma das três coisas existe no toque. No celular a porta equivalente é a tela de busca do router, com o campo no topo e o resultado levando direto para a tela.

API

PropTipoPadrão
groupsobrigatória0.4.0CommandGroup[]sem padrão
onOpenChangeobrigatória0.4.0(open: boolean) => voidsem padrão
openobrigatória0.4.0booleansem padrão
emptyMessage0.4.0

Texto de quando a busca nao acha nada.

string"Nada com esse nome"
highlight

Marca no rotulo de cada item o trecho que casou com a busca, com o `Highlight` da casa: caixa e acento nao importam.

booleanfalse
placeholder0.4.0string"Buscar comando"
shortcut0.4.0

Atalho que abre, combinado com Ctrl ou Cmd.

string | null"k"
title0.4.0

Titulo lido pelo leitor de tela.

string"Paleta de comandos"

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.