Command
Paleta de comandos
Ou aperte o atalho, de qualquer lugar da tela.
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
| Prop | Tipo | Padrão |
|---|---|---|
groupsobrigatória0.4.0 | CommandGroup[] | sem padrão |
onOpenChangeobrigatória0.4.0 | (open: boolean) => void | sem padrão |
openobrigatória0.4.0 | boolean | sem padrão |
emptyMessage0.4.0Texto de quando a busca nao acha nada. | string | "Nada com esse nome" |
highlightMarca no rotulo de cada item o trecho que casou com a busca, com o `Highlight` da casa: caixa e acento nao importam. | boolean | false |
placeholder0.4.0 | string | "Buscar comando" |
shortcut0.4.0Atalho que abre, combinado com Ctrl ou Cmd. | string | null | "k" |
title0.4.0Titulo 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.