Transfer List

• Introdução
• Começando
  • Entrada base
  • Rótulos
  • Definindo opções
  • Valores
  • Pesquisável
  • Máximo
  • Transferência ao selecionar
• Assincronia
  • Opções assíncronas
  • Carregador de opções
• Slots
  • Opções de origem e destino
• Exemplos
  • Ordem classificada
• Props & Atributos
• Seções
  • Invólucro da lista de transferência
  • Origem
  • Controles de transferência
  • Destino
• Acessibilidade
  • Interações com o Teclado

Introdução

A entrada de lista de transferência é ideal para situações onde o usuário final precisa selecionar e ordenar múltiplos valores de uma lista de opções. Neste exemplo, estamos permitindo que o usuário final selecione de um grupo de convidados e os mova para uma lista VIP:

Começando

Nesta seção, vamos cobrir o básico de como replicar o exemplo 'Convidados vs VIPs' acima.

Entrada base

Abaixo está um exemplo da entrada de lista de transferência com as propriedades mínimas necessárias. Como você pode ver, existem duas caixas de listagem: a caixa de listagem de origem e a caixa de listagem de destino. A caixa de listagem de origem conterá a lista de opções, e a caixa de listagem de destino conterá as opções selecionadas:

Rótulos

Vamos adicionar algumas propriedades de rótulo para deixar claro para o usuário final como usar a entrada de lista de transferência. Vamos adicionar uma propriedade label para explicar a diretiva ao usuário, e propriedades source-label e target-label para indicar qual caixa de listagem é a origem e qual é o destino:

Mensagens de vazio de origem e destino

Neste estado, sem opções passadas e sem valores selecionados, podemos exibir uma mensagem personalizada para o usuário definindo as propriedades source-empty-message e target-empty-message:

Definindo opções

A propriedade options pode aceitar três formatos diferentes de valores:

• Um array de objetos com chaves value e label
• Um array de strings 'A', 'B', 'C'
• Um objeto literal com pares chave-valor { a: 'A', b: 'B', c: 'C' }
• Uma função que retorna qualquer um dos acima

Vamos seguir em frente e popular as opções da lista de transferência com uma lista de nomes de convidados:

Valores

O valor da entrada da lista de transferência é um array. Valores de opções selecionadas da lista de origem serão anexados ao array. Para mostrar a mudança de valor no exemplo abaixo, vamos envolver a entrada da lista de transferência em um formulário FormKit, definir o nome da entrada da lista de transferência para vips e mostrar o valor do próprio formulário em uma tag <pre> (se você não está familiarizado com formulários FormKit, pode ler mais aqui):

Valores iniciais

A entrada da lista de transferência pode ser pré-populada com valores definindo a propriedade value na própria transferlist ou em um form ou group que a envolva. Lembre-se de que os valores que você passa para a propriedade value precisam corresponder às chaves dos valores na sua lista de opções:

Pesquisável

A entrada da lista de transferência pode ser tornada pesquisável definindo a propriedade searchable. Neste exemplo, vamos definir a propriedade searchable e também definir uma propriedade placeholder para a entrada de pesquisa:

Filtragem

A entrada da lista de transferência filtrará opções com sua própria função de pesquisa interna. Você pode substituir essa função de pesquisa fornecendo à propriedade filter uma função sua. Sua função receberá dois argumentos, a opção que está sendo iterada e o valor atual da pesquisa:

Limpar ao selecionar

Por padrão, a entrada da lista de transferência limpará a entrada de pesquisa ao selecionar. Você pode alterar esse comportamento definindo a propriedade clear-on-select como false:

Máximo

A entrada da lista de transferência pode ser limitada a um número máximo de valores selecionados definindo a propriedade max. Apenas para este exemplo, vamos definir a propriedade max para 2 para limitar o número de VIPs que podem ser selecionados:

Transferência ao selecionar

Por padrão, a entrada da lista de transferência adicionará ou removerá opções ao clicar. Você pode alterar esse comportamento definindo a propriedade transfer-on-select como false. Agora, a lista de transferência se comportará mais como uma lista de transferência tradicional:

Assincronia

Opções assíncronas

Aqui temos uma entrada de lista de transferência que carrega suas opções a partir de uma função assíncrona. A função é chamada quando o componente é montado e as opções são subsequentemente carregadas na caixa de lista de origem:

Paginação

Agora vamos supor que nossa solicitação à API não busca todas as opções de que precisamos, mas em vez disso retorna uma resposta paginada. A entrada da lista de transferência pode lidar com a paginação com uma configuração mínima para a função assíncrona.

Ao atribuir a propriedade de opções a uma função assíncrona, a função será chamada com o objeto de contexto do FormKit como seu primeiro argumento. Este objeto de contexto contém uma propriedade page (a página atual que estamos tentando carregar) que é rastreada pela entrada da lista de transferência, e hasNextPage, que é uma função de retorno de chamada que podemos usar para informar à lista de transferência que há mais opções para carregar:

Pesquisa

A entrada da lista de transferência também pode carregar opções assincronamente quando o usuário pesquisa. Neste exemplo, vamos adicionar de volta a propriedade searchable e mudar getGuests() para searchGuests(). Quando o usuário pesquisar, searchGuests() será chamado com o mesmo objeto de contexto de antes, mas desta vez, vamos desestruturar apenas a propriedade search. Além disso, modificaremos getGuests() para retornar convidados apenas quando um valor de pesquisa for fornecido:

Carregador de opções

Reidratando valores

A entrada da lista de transferência também fornece uma propriedade optionLoader que permite reidratar valores que não estão na lista de opções. Neste exemplo, forneceremos à lista de transferência um valor inicial (um ID de convidado) e atribuiremos o optionLoader a uma função que fará uma solicitação à API para buscar os dados individuais do convidado:

Observe no exemplo acima que a função optionLoader getGuest recebe dois argumentos: o valor da opção selecionada (neste caso, o ID do filme) e o cachedOption. O cachedOption é usado para prevenir buscas desnecessárias; se o cachedOption não for null, significa que a opção selecionada já foi carregada, e você pode retornar o cachedOption diretamente.

Buscando dados adicionais

Você também pode usar o optionLoader para buscar dados adicionais sobre valores selecionados que não estão na lista de opções. Neste exemplo, após selecionar uma opção, vamos realizar uma busca para carregar a idade do convidado selecionado:

Slots

Assim como qualquer outro input do FormKit, o input de lista de transferência permite que você utilize slots para personalizar sua marcação.

Opções de origem e destino

Agora que estamos carregando dados adicionais sobre valores selecionados (a idade e o endereço de e-mail do convidado selecionado), vamos personalizar a aparência dos valores selecionados usando os slots target-option:

Exemplos

Ordem classificada

O input de lista de transferência pode ser usado para criar uma lista classificada, vamos fazer isso com os maiores jogadores da NBA:

Props & Atributos

Seções

Você pode direcionar uma seção específica de uma entrada usando a "chave" dessa seção, permitindo que você modifique as classes dessa seção, HTML (via :sections-schema), ou conteúdo (via slots). Leia mais sobre seções aqui.

Invólucro da lista de transferência

Origem

Controles de transferência

Destino

Acessibilidade

Todos os campos de entrada do FormKit são projetados levando em consideração as seguintes considerações de acessibilidade. Ajude-nos a melhorar continuamente a acessibilidade para todos, relatando problemas de acessibilidade aqui:

Interações com o Teclado