O FormKit vem com um plugin de entrada de múltiplas etapas de primeira parte disponível no pacote @formkit/addons. Esta entrada permite que você construa um assistente ou divida facilmente seus formulários em várias etapas. Dividir formulários em múltiplas etapas pode melhorar a experiência do usuário em formulários maiores, mantendo-os pequenos e acessíveis em comparação a listar todas as entradas de uma vez.
Para usar este plugin com o FormKit, instale @formkit/addons:
yarn add @formkit/addons
Depois de instalar o pacote de addons, você precisará registrar o plugin com o FormKit e incluir os estilos CSS de suporte:
// formkit.config.js
import { defaultConfig } from '@formkit/vue'
import { createMultiStepPlugin } from '@formkit/addons'
import '@formkit/addons/css/multistep'
const config = defaultConfig({
plugins: [createMultiStepPlugin()],
})
export default config
multi-step em ação:A função createMultiStepPlugin registra dois novos tipos de entrada para você usar com o componente FormKit.
multi-step: O grupo de envolvimento para a entrada de múltiplas etapas inteira. Esta entrada acompanha qual etapa está ativa, validação e erros por etapa, e deve conter apenas entradas do tipo step como seus filhos imediatos.step: O grupo de envolvimento para uma determinada etapa dentro da sua entrada de múltiplas etapas. Deve ser apenas um filho imediato de uma entrada multi-step. Seus filhos serão renderizados como o conteúdo da etapa.Usar essas entradas juntas é tão simples quanto envolver qualquer marcação que você deseja ter presente dentro de uma etapa em um formulário de múltiplas etapas.
<FormKit type="multi-step">
<FormKit type="step" name="stepOne">
<!-- conteúdo para stepOne vai aqui! -->
</FormKit>
</FormKit>
Por padrão, a entrada multi-step pai rastreará a validade das entradas contidas em cada entrada step filha e impedirá o avanço para a próxima step até que a etapa atual seja válida. A contagem total de validações bloqueadoras e erros será mostrada ao lado do nome da etapa atual se um usuário tentar avançar para a próxima etapa ou enviar o formulário antes de satisfazer as validações de entrada da etapa atual.
O input multi-step vem com dois estilos de aba disponíveis.
tab: A experiência padrão de aba. Cada nome de etapa é mostrado em uma aba com um estado ativo. A contagem de erros é mostrada no canto superior direito da aba.progress: Um estilo de barra de progresso onde cada etapa é um "nó" em uma linha do tempo de etapas totais. Com esse modo de exibição, você também pode usar a propriedade hide-progress-labels para ocultar os nomes das etapas.Por padrão, o input multi-step usará o atributo name de seus inputs step filhos para gerar rótulos para as etapas. Se você deseja mais controle sobre a exibição dos nomes das suas etapas, você pode usar a propriedade label. Você também pode personalizar os rótulos que aparecem na seção stepActions do seu step usando as propriedades previous-label e next-label.
label: Uma substituição para o nome da etapa que deve aparecer nas abas multi-step.previous-label: uma substituição para o rótulo do botão stepPrevious que por padrão é Back.next-label: uma substituição para o rótulo do botão stepNext que por padrão é Next.Por padrão, o input multi-step permitirá avançar para etapas posteriores mesmo que a etapa atual ou uma etapa entre a etapa atual e a etapa alvo tenha mensagens de validação bloqueadoras. Para impedir que um usuário avance, defina a propriedade allow-incomplete como false.
Quando uma etapa é concluída sem erros de validação, o input multi-step — por padrão — renderizará um ícone de verificação mostrando que a etapa é válida e nenhuma ação adicional é necessária. O valid-step-icon é um Ícone FormKit e pode ser alterado através de uma propriedade como qualquer outro ícone FormKit.
Você pode:
valid-step-icon no input multi-step para mudar o ícone para todas as etapas dentro do input.valid-step-icon em um input step para mudar ou substituir o ícone apenas para aquela etapa.Cada step em uma entrada multi-step tem botões padrões renderizados para movimentação entre as etapas. Por padrão, o primeiro step em um multi-step terá apenas um botão de ação stepNext renderizado, e o último step terá apenas um botão de ação stepPrevious. Isso permite que um multi-step atue como um grupo autocontido dentro do contexto de um formulário maior.
Se você deseja adicionar uma ação personalizada, como um envio de formulário a um multi-step — útil se você estiver usando o multi-step como seu formulário inteiro — você pode fazer isso substituindo o slot stepNext na etapa desejada. Neste caso, adicionaremos uma entrada submit à última etapa em nossa entrada multi-step para enviar o formulário.
As seções stepNext e stepPrevious têm acesso ao manipulador incrementStep — que retorna uma função chamável — para habilitar a navegação programática.
Por padrão, o stepNext em uma entrada multi-step usa ouvintes de eventos para capturar a navegação por abas via teclado e permitir que os usuários percorram todas as etapas disponíveis dentro de um multi-step.
Se você deseja preservar esse comportamento em sua própria implementação de stepNext, certifique-se de adicionar um atributo data-next="true" ao seu elemento focalizável que aciona a navegação de etapas.
Às vezes você precisa fazer algo com os dados do seu formulário entre as etapas. Talvez você queira enviar cada etapa independentemente para o seu back-end ou precise registrar eventos de análise para determinar até onde os usuários estão avançando no seu formulário. Em casos como esses, você pode usar o evento beforeStepChange. beforeStepChange aceita uma função e é fornecido um objeto de contexto com as seguintes chaves:
currentStep: O objeto de contexto do nó da etapa ativa atual de onde o usuário está navegando para longe.targetStep: O objeto de contexto do nó da etapa para a qual o usuário está navegando.delta: A distância entre as etapas. Inteiros positivos representam avançar, inteiros negativos representam retroceder.Sua função beforeStepChange deve retornar um Boolean. Retornar false irá impedir que a mudança de etapa ocorra.
beforeStepChange pode ser usado em sua entrada multi-step, caso em que se aplicará a todas as etapas. Além disso, você pode usar beforeStepChange em uma entrada step específica para executar sua função apenas ao navegar para longe da etapa que tem a função atribuída. beforeStepChange aplicado a um step substituirá qualquer beforeStepChange definido em um multi-step pai, se um existir.
O nó de múltiplos passos está equipado com funções auxiliares convenientes projetadas para facilitar a navegação programática entre quaisquer um de seus passos. Essas funções incluem:
next: Avança para o próximo passo a partir do passo atualmente selecionado.previous: Retorna para o passo anterior a partir do passo atualmente selecionado.goTo: Aceita um argumento passo para mover-se para esse passo a partir do passo atualmente selecionado, aceitando o índice ou o nome do passo.| Prop | Type | Padrão | Descrição |
|---|---|---|---|
| allowIncomplete | boolean | true | Quando true, permite que os usuários naveguem entre os passos mesmo se o passo atual estiver inválido. |
| tabStyle | string | tab | Usado para definir um atributo de dados para criar estilos de aba. O tema padrão vem com suporte para estilos de aba tab e progress. |
| hideProgressLabels | boolean | false | Quando verdadeiro, oculta os rótulos para o estilo de aba progress. |
| validStepIcon | string | check | Especifica um ícone para colocar na seção badge quando um passo é válido. Quando aplicado ao multi-step, o ícone será aplicado a todos os inputs de step filhos. |
| beforeStepChange | function | undefined | Uma função a ser executada antes da mudança do passo ativo. A função é fornecida com um objeto de contexto contendo currentStep e targetStep, que são ambos objetos de contexto de nó do FormKit. Além disso, delta é fornecido como um inteiro que reflete a distância entre currentStep e targetStep. Quando fornecido ao multi-step, esta função será acionada em cada mudança de step. |
| Mostrar Universal props | |||
| config | Object | {} | Opções de configuração a serem fornecidas para o nó do input e qualquer nó descendente deste input. |
| delay | Number | 20 | Número de milissegundos para debounce do valor do input antes de despachar o commit hook. |
| dirtyBehavior | string | touched | Determina como o indicador "dirty" deste input é definido. Pode ser configurado como touched ou compare - touched (o padrão) é mais performático, mas não detectará quando o formulário corresponder novamente ao seu estado inicial. |
| errors | Array | [] | Array de strings para exibir como mensagens de erro neste campo. |
| help | String | '' | Texto para o texto de ajuda associado ao input. |
| id | String | input_{n} | O ID único do input. Fornecer um ID também permite acesso global ao nó do input. |
| ignore | Boolean | false | Impede que um input seja incluído em qualquer pai (grupo, lista, formulário etc). Útil ao usar inputs para a interface do usuário em vez de valores reais. |
| index | Number | undefined | Permite que um input seja inserido no índice fornecido, se o pai for uma lista. Se o valor do input for indefinido, ele herda o valor dessa posição de índice. Se ele tiver um valor, ele o insere nos valores da lista no índice fornecido. |
| label | String | '' | Texto para o elemento label associado ao input. |
| name | String | input_{n} | O nome do input como identificado no objeto de dados. Isso deve ser único dentro de um grupo de campos. |
| parent | FormKitNode | contextual | Por padrão, o pai é um grupo, lista ou formulário de envolvimento, mas essa prop permite a atribuição explícita do nó pai. |
| prefix-icon | String | '' | Especifica um ícone para colocar na seção prefixIcon. |
| preserve | boolean | false | Preserva o valor do input em um grupo pai, lista ou formulário quando o input é desmontado. |
| preserve-errors | boolean | false | Por padrão, os erros definidos em inputs usando setErrors são automaticamente limpos no input. Definir essa prop como true mantém o erro até que ele seja explicitamente limpo. |
| sections-schema | Object | {} | Um objeto de chaves de seção e valores parciais de esquema, em que cada esquema parcial é aplicado à seção respectiva. |
| suffix-icon | String | '' | Especifica um ícone para colocar na seção suffixIcon. |
| type | String | text | O tipo de input a ser renderizado pela biblioteca. |
| validation | String, Array | [] | As regras de validação a serem aplicadas ao input. |
| validation-visibility | String | blur | Determina quando mostrar as regras de validação com falha de um input. Os valores válidos são blur, dirty e live. |
| validation-label | String | {label prop} | Determina qual rótulo usar nas mensagens de erro de validação, por padrão, usa a propriedade label, se disponível, caso contrário, usa a propriedade name. |
| validation-rules | Object | {} | Regras de validação personalizadas adicionais para disponibilizar na propriedade de validação. |
| value | Any | undefined | Inicializa o valor do input e/ou de seus filhos. Não é reativo. Pode inicializar grupos inteiros (formulários) e listas.. |
| Prop | Type | Padrão | Descrição |
|---|---|---|---|
| label | string | Usado para alterar o rótulo da aba do passo. Se nenhum rótulo personalizado for fornecido, o name do passo será usado. | |
| previousLabel | string | Anterior | Usado para alterar o rótulo do botão padrão de ação previousAction. |
| nextLabel | string | Próximo | Usado para alterar o rótulo do botão padrão de ação nextAction. |
| previousAttrs | object | [object Object] | Usado para aplicar atributos ao input do botão padrão de ação previousAction. |
| nextAttrs | object | [object Object] | Usado para aplicar atributos ao input do botão padrão de ação nextAction. |
| validStepIcon | string | check | Especifica um ícone para colocar na seção badge quando o passo é válido. Quando aplicado a um step, o ícone será aplicado apenas ao step alvo. |
| beforeStepChange | function | undefined | Uma função a ser executada antes da mudança do passo ativo. A função é fornecida com um objeto de contexto contendo currentStep e targetStep, que são ambos objetos de contexto de nó do FormKit. Além disso, delta é fornecido como um inteiro que reflete a distância entre currentStep e targetStep. Quando fornecido a um step, esta função será acionada apenas ao navegar para fora do step especificado. |
| Mostrar Universal props | |||
| config | Object | {} | Opções de configuração a serem fornecidas para o nó do input e qualquer nó descendente deste input. |
| delay | Number | 20 | Número de milissegundos para debounce do valor do input antes de despachar o commit hook. |
| dirtyBehavior | string | touched | Determina como o indicador "dirty" deste input é definido. Pode ser configurado como touched ou compare - touched (o padrão) é mais performático, mas não detectará quando o formulário corresponder novamente ao seu estado inicial. |
| errors | Array | [] | Array de strings para exibir como mensagens de erro neste campo. |
| help | String | '' | Texto para o texto de ajuda associado ao input. |
| id | String | input_{n} | O ID único do input. Fornecer um ID também permite acesso global ao nó do input. |
| ignore | Boolean | false | Impede que um input seja incluído em qualquer pai (grupo, lista, formulário etc). Útil ao usar inputs para a interface do usuário em vez de valores reais. |
| index | Number | undefined | Permite que um input seja inserido no índice fornecido, se o pai for uma lista. Se o valor do input for indefinido, ele herda o valor dessa posição de índice. Se ele tiver um valor, ele o insere nos valores da lista no índice fornecido. |
| label | String | '' | Texto para o elemento label associado ao input. |
| name | String | input_{n} | O nome do input como identificado no objeto de dados. Isso deve ser único dentro de um grupo de campos. |
| parent | FormKitNode | contextual | Por padrão, o pai é um grupo, lista ou formulário de envolvimento, mas essa prop permite a atribuição explícita do nó pai. |
| prefix-icon | String | '' | Especifica um ícone para colocar na seção prefixIcon. |
| preserve | boolean | false | Preserva o valor do input em um grupo pai, lista ou formulário quando o input é desmontado. |
| preserve-errors | boolean | false | Por padrão, os erros definidos em inputs usando setErrors são automaticamente limpos no input. Definir essa prop como true mantém o erro até que ele seja explicitamente limpo. |
| sections-schema | Object | {} | Um objeto de chaves de seção e valores parciais de esquema, em que cada esquema parcial é aplicado à seção respectiva. |
| suffix-icon | String | '' | Especifica um ícone para colocar na seção suffixIcon. |
| type | String | text | O tipo de input a ser renderizado pela biblioteca. |
| validation | String, Array | [] | As regras de validação a serem aplicadas ao input. |
| validation-visibility | String | blur | Determina quando mostrar as regras de validação com falha de um input. Os valores válidos são blur, dirty e live. |
| validation-label | String | {label prop} | Determina qual rótulo usar nas mensagens de erro de validação, por padrão, usa a propriedade label, se disponível, caso contrário, usa a propriedade name. |
| validation-rules | Object | {} | Regras de validação personalizadas adicionais para disponibilizar na propriedade de validação. |
| value | Any | undefined | Inicializa o valor do input e/ou de seus filhos. Não é reativo. Pode inicializar grupos inteiros (formulários) e listas.. |
| Section-key | Descrição |
|---|---|
| tabs | Um invólucro ao redor de todas as abas. |
| tab | Um elemento botão que contém o nome da aba e o decorador para refletir o estado de validação. |
| tabLabel | Um elemento span que contém o nome da aba. |
| badge | Um elemento span usado como um decorador para mostrar o estado de validade da aba atual. |
| steps | Um invólucro ao redor de todas as etapas. |
| step | Um invólucro ao redor do conteúdo da etapa do slot padrão e dos botões de ação da etapa. Cada etapa tem estilos de visibilidade aplicados automaticamente dependendo se é a etapa ativa atual. |
| stepInner | Um invólucro ao redor do conteúdo do slot padrão para uma etapa. |
| stepActions | Um invólucro ao redor dos botões de ação para mover entre as etapas. |
| stepPrevious | Um invólucro ao redor do botão de ação para navegar para a etapa anterior. |
| stepNext | Um invólucro ao redor do botão de ação para navegar para a próxima etapa. |
| Mostrar Universal section keys | |
| outer | O elemento de envolvimento mais externo. |
| wrapper | Um invólucro ao redor do rótulo e do input. |
| label | O rótulo do input. |
| prefix | Por padrão, não gera saída, mas permite conteúdo diretamente antes de um elemento input. |
| prefixIcon | Um elemento para gerar um ícone antes da seção de prefixo. |
| inner | Um invólucro ao redor do próprio elemento input. |
| suffix | Por padrão, não gera saída, mas permite conteúdo diretamente após um elemento input. |
| suffixIcon | Um elemento para gerar um ícone após a seção de sufixo. |
| input | O próprio elemento input. |
| help | O elemento que contém o texto de ajuda. |
| messages | Um invólucro ao redor de todas as mensagens. |
| message | O elemento (ou muitos elementos) que contém uma mensagem - na maioria das vezes mensagens de validação e erros. |