Pular para o conteúdo
Formulário

TransferList

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

As permissões de um papel

Permissões7 itens
  • Reembolsar pedido
  • Cancelar pedido
  • Editar produto
  • Ajustar o estoque
  • Exportar relatórios
  • Convidar usuário
  • Excluir a conta
Concedidas1 item
  • Ver relatórios

Cidades de entrega, com busca sem acento

Disponíveis10 itens
  • São Paulo
  • Rio de Janeiro
  • Belo Horizonte
  • João Pessoa
  • Recife
  • Fortaleza
  • Porto Alegre
  • Curitiba
  • Manaus
  • Belém
Escolhidos0 itens

    Nenhum item

    Desabilitada

    Disponíveis3 itens
    • São Paulo
    • Rio de Janeiro
    • Belo Horizonte
    Escolhidos1 item
    • João Pessoa
    Importar
    import { TransferList } from '@rivocode/ui'

    Quando usar

    Duas listas lado a lado: à esquerda o que está disponível, à direita o que foi escolhido. A pessoa marca um ou vários itens e os passa de um lado para o outro. Permissões de um papel, colunas de um relatório, cidades de entrega, os produtos de uma tabela de preço.

    const [granted, setGranted] = useState<string[]>([])
    
    <TransferList
      items={[
        { value: 'pedidos.reembolsar', label: 'Reembolsar pedido' },
        { value: 'pedidos.cancelar', label: 'Cancelar pedido' },
        { value: 'conta.excluir', label: 'Excluir a conta', disabled: true },
      ]}
      value={granted}
      onValueChange={setGranted}
      labels={{ available: 'Permissões', chosen: 'Concedidas' }}
    />
    

    A peça é controlada: value são os value dos escolhidos, e onValueChange recebe a lista nova a cada movimento. O lado da direita aparece na ordem do value, e o que entra vai para o fim, na ordem de items. O lado da esquerda é items sem os escolhidos, na ordem de items.

    Mover

    Entre as duas listas ficam quatro botões: mover os marcados para a direita, mover todos para a direita, e os mesmos dois de volta. Cada um tem nome próprio ("Mover selecionados para Escolhidos") e a dica com o mesmo texto ao pousar o ponteiro. O botão fica apagado quando não há o que mover.

    "Mover todos" move o que está à mostra: com uma busca digitada, só o que a busca deixou na lista. O marcado que a busca escondeu também não é movido pelo "mover selecionados", para ninguém mover o que não está vendo.

    Item com disabled não se marca e não se move, nem pelo "mover todos": ele fica onde está. Serve para a permissão que o papel não pode perder ou ganhar.

    Depois de mover, a frase "3 itens movidos para Escolhidos" é dita numa região viva educada, com o plural certo e o nome da lista de destino. Se o botão apertado apagou (porque não sobrou nada para mover), o foco passa para a lista de destino, e não cai no começo da página.

    Estreita, empilha

    Abaixo de 640px as duas listas empilham, e os botões de mover viram uma fileira entre elas, com as setas apontando para baixo e para cima. A largura que conta é a de quem contém a peça, e não a da janela: num painel lateral de 400px de uma tela larga, ela empilha também. Antes da primeira medida, vale a janela.

    A contagem e a busca

    O cabeçalho de cada lista diz quantos itens ela tem ("10 itens") e, com itens marcados, quantos estão marcados ("3 de 10 selecionados"). A contagem é a descrição da lista para o leitor de tela.

    A busca no topo de cada lista ignora acento e caixa: "sao" acha "São Paulo" e "joao" acha "João Pessoa". Sem resultado, a lista diz "Nada encontrado"; vazia, diz "Nenhum item". searchable={false} tira as duas buscas, para listas curtas.

    Nome

    A peça inteira é um grupo (role="group"), e o nome dele vem de aria-label ou aria-labelledby: “Permissões do perfil”. Dentro de um Field, sem nenhum dos dois, o grupo toma o nome do FieldLabel. Cada lista continua com o próprio nome, o título dela.

    Teclado

    Cada lista é uma parada de Tab e anda pelo padrão de lista com seleção múltipla:

    Tecla O que faz
    Seta para cima e para baixo anda pela lista sem marcar
    Espaço marca ou desmarca o item atual
    Shift + seta anda e marca o caminho
    Home e End vão ao primeiro e ao último; com Shift, marcam o trecho
    Ctrl + A (⌘ + A) marca tudo o que está à mostra, ou desmarca se já estava
    Enter move os marcados para a outra lista
    Esc desmarca tudo

    Na busca, a seta para baixo desce para a lista.

    Textos

    labels troca os nomes das listas (available e chosen), as frases de vazio (empty e noResults), o texto de espera da busca (search), a contagem (count) e o anúncio (moved). Os nomes dos botões e das buscas acompanham os nomes das listas.

    Partes

    classNames alcança cada nó pelo nome: panel (cada lista com a moldura), header, search, list (a caixa que rola, com 240px de altura), option, actions (a coluna dos botões) e empty. A altura da lista se troca em classNames.list.

    No celular, as duas listas empilham, e as setas dos botões giram para apontar para cima e para baixo.

    Quando não usar

    • Marcar algumas opções de uma lista curta é CheckboxGroup. A TransferList vale quando a lista é longa e o que importa é ver, lado a lado, o que ficou de fora e o que entrou.
    • Escolher vários de uma lista longa sem precisar ver o que sobrou é Combobox com multiple: ele ocupa uma linha só e mostra o escolhido em fichas.
    • Pôr os escolhidos numa ordem que só a pessoa sabe é SortableList. A TransferList acrescenta no fim, e não arrasta.
    • Escolher dentro de uma árvore, como departamentos e equipes, é TreeSelect.

    No React Native

    Traduz, com os mesmos items, value, onValueChange, searchable, disabled e labels, e as mesmas frases de contagem e de anúncio.

    As listas empilham, e cada uma tem os próprios botões. No telefone não há largura para duas colunas com botões no meio: a lista de cima é a de disponíveis, a de baixo a de escolhidos, e cada uma fecha com “Mover selecionados para …” e “Mover todos para …”. Cada linha é uma caixa de marcar com alvo de 44 pontos, e a lista rola por dentro a partir de 288 pontos. O anúncio sai pelo leitor de tela do sistema.

    As partes vestem pelo mesmo classNames do web: panel, header, search, list, option, actions e empty. Como os botões moram em cada lista, actions veste a fileira embaixo de cada uma, e não uma coluna no meio.

    API

    PropTipoPadrão
    itemsobrigatória

    Todos os itens, dos dois lados.

    TransferListItem[]sem padrão
    onValueChangeobrigatória

    Recebe o `value` novo a cada movimento.

    (value: string[]) => voidsem padrão
    valueobrigatória

    Os `value` dos escolhidos, na ordem em que aparecem na lista da direita.

    string[]sem padrão
    classNames

    Classe por parte: `panel` (cada lista com a moldura), `header`, `search`, `list` (a caixa que rola), `option`, `actions` (a coluna dos botoes) e `empty`.

    Partial<Record<"actions" | "empty" | "header" | "list" | "option" | "panel" | "search", string>>sem padrão
    disabled

    Desliga as duas listas, as buscas e os botoes de mover.

    booleanfalse
    labels

    Os textos da peca, para trocar o nome das listas ou o anuncio.

    TransferListLabelssem padrão
    searchable

    Liga a busca no topo de cada lista, sem acento importar.

    booleantrue

    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.