Pular para o conteúdo
Dados

SortableList

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

A fila de prioridades

  • Corrigir o login pelo celular

    Tarefa 211 · Bruna · prazo 26/09

    3 hPróxima
  • Atualizar a página de preços

    Tarefa 212 · Caio · prazo 27/09

    1 h
  • Responder o chamado da Vila Verde

    Tarefa 213 · Denise · prazo 30/09

    30 min
  • Migrar o banco de testes

    Tarefa 214 · Otávio · prazo 02/10

    1 dia
  • Preparar a demonstração de outubro

    Tarefa 215 · Bruna · prazo 05/10

    4 h

Horizontal, com a linha inteira como alça

  • 1Separar o pedido
  • 2Embalar
  • 3Gerar a etiqueta de frete
  • 4Entregar à transportadora

Desabilitada enquanto salva

  • Corrigir o login pelo celular

  • Atualizar a página de preços

  • Responder o chamado da Vila Verde

Importar
import { SortableList } from '@rivocode/ui/dnd'

Quando usar

A lista que a pessoa põe em ordem com as próprias mãos: a prioridade das tarefas do time, as etapas de um processo, a ordem das aulas de um curso. Arrasta com o ponteiro, com o dedo e com o teclado, e o leitor de tela ouve cada passo. Vive em @rivocode/ui/dnd, atrás do @dnd-kit/core e do @dnd-kit/sortable, que são dependências opcionais: só quem importa este caminho as instala.

npm install @dnd-kit/core @dnd-kit/sortable
import { SortableList } from '@rivocode/ui/dnd'

const [tasks, setTasks] = useState(initialTasks)

<SortableList
  aria-label="Ordem de prioridade"
  items={tasks}
  getKey={(task) => task.id}
  getLabel={(task) => `Tarefa ${task.number}`}
  onReorder={setTasks}
  renderItem={(task) => (
    <Item>
      <ItemContent>
        <ItemTitle>{task.title}</ItemTitle>
        <ItemDescription>Prazo {task.due}</ItemDescription>
      </ItemContent>
    </Item>
  )}
/>

A peça é controlada

items entra, a ordem nova sai pronta em onReorder(items, { key, from, to }), e a peça desenha o que voltar. Ela não guarda ordem nenhuma sozinha: sem o pai trocar items, o item volta para o lugar ao ser solto. É isso que deixa a ordem ir ao servidor antes de mudar na tela, e voltar atrás se ele recusar.

Soltar no mesmo lugar e cancelar com Esc não chamam onReorder.

getKey é a identidade do item, e tem que ser única e estável: a chave que anda com o item, e não a posição dele.

Teclado e leitor de tela

O teclado não é uma alternativa de segunda: é o caminho de quem não usa mouse.

Tecla O que faz
Espaço ou Enter pega o item com o foco na alça
Setas movem o item uma posição
Espaço ou Enter solta no lugar novo
Esc cancela, e o item volta para onde estava

Cada passo é anunciado numa região viva, com o nome que getLabel devolve: "Item Tarefa 213 pego. Posição 2 de 8.", "Item Tarefa 213 movido para a posição 3 de 8.", "Item Tarefa 213 solto na posição 3 de 8.". A alça se chama "Reordenar Tarefa 213", e a instrução de teclado fica ligada a ela por aria-describedby, para o leitor ler ao chegar e não a cada passo.

labels troca qualquer um desses textos, inclusive a palavra "Item", quando a lista é de outra coisa:

<SortableList
  items={steps}
  getKey={(step) => step.id}
  getLabel={(step) => step.name}
  onReorder={setSteps}
  labels={{
    moved: (label, position, total) => `Etapa ${label} agora é a ${position}ª de ${total}.`,
  }}
  renderItem={(step) => step.name}
/>

Mover sem arrastar

Arrastar não pode ser o único caminho: a WCAG 2.5.7 pede um jeito de ponteiro único, sem segurar, para quem usa um dedo só, o mouse sem prender o botão ou o controle por voz. E o teclado sozinho não cumpre esse pedido.

Por isso cada item traz, no fim da linha, o botão "Mover Tarefa 213", que abre um Menu com Para o início, Para cima, Para baixo e Para o fim. O menu mostra só o que anda: o primeiro item não tem subida, e o segundo não repete "Para o início" ao lado de "Para cima". Escolher chama o mesmo onReorder(items, { key, from, to }) do arrasto, anuncia "Item Tarefa 213 movido para a posição 1 de 8." e devolve o foco ao botão do item no lugar novo, para o próximo passo sair dali.

O botão vem ligado, com ou sem handle. Ele mora fora da alça e fora do renderItem, então a linha toda que recebe handleProps continua sendo um controle só. Na horizontal os passos se chamam Para a esquerda e Para a direita. Some quando a lista está disabled ou tem um item só, e moveMenu={false} o desliga quando a tela já dá outro caminho (um campo de posição, por exemplo). Os textos trocam por labels: move, first, earlier, later e last.

A alça

handle, ligado por padrão, desenha um IconButton com o ícone de pegar no início de cada linha, e só ele arrasta. O resto da linha continua clicável, selecionável e, no celular, rolável: é a alça que trava a rolagem enquanto o dedo está nela, e não a linha inteira.

Com handle={false} a peça não desenha alça, e quem arrasta é o elemento onde você espalhar handleProps: a sua própria alça, ou a linha toda. Nesse modo o toque pede para segurar o item antes de ele sair do lugar, e deslizar sem segurar continua rolando a tela.

<SortableList
  items={tasks}
  getKey={(task) => task.id}
  onReorder={setTasks}
  handle={false}
  renderItem={(task, { handleProps, isDragging }) => (
    <div {...handleProps} className={isDragging ? 'shadow-2' : undefined}>
      {task.title}
    </div>
  )}
/>

Horizontal

orientation="horizontal" vira uma fileira que rola de lado quando não cabe, e as setas que andam passam a ser esquerda e direita.

Movimento

Os vizinhos abrem espaço com a mola espacial dos tokens (--rc-duration-spatial e --rc-ease-spatial), e o item arrastado sobe com shadow-2. Com "reduzir movimento" ligado no sistema a duração dos tokens vai a zero: os vizinhos trocam de lugar sem deslizar, e a rolagem que o teclado provoca ao chegar à borda também deixa de ser suave.

Estados

  • Vazia: a lista monta sem nenhum item e sem alça. Diga o que falta com um EmptyState no lugar dela.
  • disabled: a alça sai desabilitada e nada arrasta, nem pelo teclado. Use enquanto a ordem anterior ainda está sendo salva.

Partes

classNames alcança item (o li que anda), handle (a alça) e content (a caixa em volta do que renderItem desenha).

Quando não usar

  • Ordem por critério é DataTable. Se a pessoa quer ver as tarefas por prazo ou por responsável, a coluna sortable resolve com um clique e sem ninguém mexer em nada. A SortableList é para a ordem que só a pessoa sabe, e que não sai de campo nenhum.
  • Mudar de grupo é Kanban. Quando o item muda de situação ("A fazer" para "Em andamento") e não só de posição, as colunas são a informação, e o quadro mostra as duas coisas.
  • Hierarquia é Tree. Pôr um item dentro de outro não é reordenar.

No React Native

Traduz, no caminho próprio @rivocode/ui-native/dnd, com os mesmos items, getKey, renderItem, onReorder, getLabel, handle, orientation, disabled, moveMenu e labels.

Sem peer novo. O gesto é o PanResponder do React Native, o mesmo do Slider, e não o react-native-gesture-handler: arrastar pela alça, num eixo só, é um gesto que o core resolve sozinho. A alça tem 44pt e segura o gesto até o dedo sair (ela não cede à rolagem da tela no meio do arrasto), e o resto da linha continua rolando a lista, como na alça de reordenar do iOS. Por isso, no celular, só a alça arrasta: com a linha inteira como alça, todo toque para rolar viraria um arrasto.

O leitor de tela não arrasta: ele move. Cada alça traz duas ações, "Mover para cima" e "Mover para baixo" (ou esquerda e direita, na horizontal), e cada uma anda um passo e anuncia a posição nova com o mesmo texto do web: "Item Tarefa 1043 movido para a posição 3 de 8". O arrasto também anuncia ao pegar, a cada posição e ao soltar.

Quem não arrasta, nem usa leitor de tela, toca em "Mover". O botão de 44pt no fim de cada item abre uma Sheet com o início, um passo para cada lado e o fim, só o que anda, e escolher chama o mesmo onReorder e anuncia a posição nova. É o moveMenu do web, ligado de saída. Aqui as ações dizem "Mover para o início", "Mover para cima" e assim por diante, as mesmas palavras das ações do leitor de tela.

Durante o arrasto uma cópia do item segue o dedo por cima da lista, e os vizinhos abrem espaço com a duração base dos tokens, sem movimento quando o sistema pede para reduzir. handleProps são o gesto e as ações, para espalhar numa View sua com handle={false}.

API

PropTipoPadrão
getKeyobrigatória

A identidade de cada item.

(item: Item) => UniqueIdentifiersem padrão
itemsobrigatória

Os itens, na ordem de agora.

readonly Item[]sem padrão
onReorderobrigatória

A ordem nova, ja montada, ao soltar num lugar diferente de onde o item saiu.

(items: Item[], move: SortableListMove) => voidsem padrão
renderItemobrigatória

O desenho de cada item.

(item: Item, state: SortableItemState) => ReactNodesem padrão
classNamesPartial<Record<"content" | "handle" | "item", string>>sem padrão
disabled

Trava o arrasto inteiro, e a alca sai desabilitada.

booleanfalse
getLabel

O nome do item nos anuncios e no nome da alca: "Pedido 1043" vira "Item Pedido 1043 movido para a posicao 3 de 8".

((item: Item) => string)sem padrão
handle

Desenha a alca, um `IconButton` com o icone de pegar, no inicio de cada item, e so ela arrasta.

booleantrue
labels

Os textos dos anuncios, da instrucao, do nome da alca e do menu de mover (`move`, `first`, `earlier`, `later`, `last`), para outra lingua ou outro nome de coisa ("Etapa" em vez de "Item").

Partial<SortableListLabels>sem padrão
moveMenu

O botao "Mover" no fim de cada item, que abre um menu com o inicio, um passo para cada lado e o fim.

booleantrue
orientation

O eixo da lista.

"horizontal" | "vertical""vertical"

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.