Salta al contenuto principale Salta alla navigazione dei documenti
Check
in English

Convalida

Fornisci feedback utili e fruibili ai tuoi utenti con la convalida dei moduli HTML5, tramite comportamenti predefiniti del browser o stili personalizzati e JavaScript.

Su questa pagina
Siamo consapevoli che attualmente gli stili di convalida personalizzati e le descrizioni dei comandi lato client non sono accessibili, poiché non sono esposti alle tecnologie assistive. Mentre lavoriamo a una soluzione, ti consigliamo di utilizzare l'opzione lato server o il metodo di convalida del browser predefinito.

Come funziona

Ecco come funziona la convalida dei moduli con Bootstrap:

  • La convalida del modulo HTML viene applicata tramite le due pseudo-classi CSS :invalide :valid. Si applica agli elementi <input>, <select>, e <textarea>.
  • Bootstrap ha come ambito gli stili :invalide la classe padre, solitamente applicata alla classe . In caso contrario, qualsiasi campo obbligatorio senza un valore viene visualizzato come non valido al caricamento della pagina. In questo modo, puoi scegliere quando attivarli (in genere dopo aver tentato l'invio del modulo).:valid.was-validated<form>
  • Per ripristinare l'aspetto del modulo (ad esempio, nel caso di invii di moduli dinamici utilizzando AJAX), rimuovere nuovamente la .was-validatedclasse <form>dopo l'invio.
  • Come fallback, .is-invalide .is-validle classi possono essere utilizzate al posto delle pseudo-classi per la convalida lato server . Non richiedono una .was-validatedclasse genitore.
  • A causa dei vincoli nel modo in cui funziona CSS, non possiamo (attualmente) applicare stili a un <label>controllo che precede un modulo nel DOM senza l'aiuto di JavaScript personalizzato.
  • Tutti i browser moderni supportano l' API di convalida dei vincoli , una serie di metodi JavaScript per la convalida dei controlli dei moduli.
  • I messaggi di feedback possono utilizzare le impostazioni predefinite del browser (diverse per ciascun browser e non modificabili tramite CSS) o i nostri stili di feedback personalizzati con HTML e CSS aggiuntivi.
  • Puoi fornire messaggi di validità personalizzati con setCustomValidityJavaScript.

Tenendo presente ciò, considera le seguenti demo per i nostri stili di convalida dei moduli personalizzati, le classi lato server opzionali e le impostazioni predefinite del browser.

Stili personalizzati

Per i messaggi di convalida del modulo Bootstrap personalizzati, dovrai aggiungere l' novalidateattributo booleano al tuo file <form>. Ciò disabilita i suggerimenti di feedback predefiniti del browser, ma fornisce comunque l'accesso alle API di convalida dei moduli in JavaScript. Prova a inviare il modulo sottostante; il nostro JavaScript intercetterà il pulsante di invio e ti trasmetterà il feedback. Quando tenti di inviare, vedrai gli stili :invalide :validapplicati ai controlli del modulo.

Gli stili di feedback personalizzati applicano colori, bordi, stili di messa a fuoco e icone di sfondo personalizzati per comunicare meglio il feedback. Le icone di sfondo per <select>i messaggi sono disponibili solo con .form-selecte non .form-control.

Sembra buono!
Sembra buono!
@
Scegli un nome utente.
Si prega di fornire una città valida.
Seleziona uno stato valido.
Si prega di fornire un codice postale valido.
Devi essere d'accordo prima di inviare.
html 
<form class="row g-3 needs-validation" novalidate>
  <div class="col-md-4">
    <label for="validationCustom01" class="form-label">First name</label>
    <input type="text" class="form-control" id="validationCustom01" value="Mark" required>
    <div class="valid-feedback">
      Looks good!
    </div>
  </div>
  <div class="col-md-4">
    <label for="validationCustom02" class="form-label">Last name</label>
    <input type="text" class="form-control" id="validationCustom02" value="Otto" required>
    <div class="valid-feedback">
      Looks good!
    </div>
  </div>
  <div class="col-md-4">
    <label for="validationCustomUsername" class="form-label">Username</label>
    <div class="input-group has-validation">
      <span class="input-group-text" id="inputGroupPrepend">@</span>
      <input type="text" class="form-control" id="validationCustomUsername" aria-describedby="inputGroupPrepend" required>
      <div class="invalid-feedback">
        Please choose a username.
      </div>
    </div>
  </div>
  <div class="col-md-6">
    <label for="validationCustom03" class="form-label">City</label>
    <input type="text" class="form-control" id="validationCustom03" required>
    <div class="invalid-feedback">
      Please provide a valid city.
    </div>
  </div>
  <div class="col-md-3">
    <label for="validationCustom04" class="form-label">State</label>
    <select class="form-select" id="validationCustom04" required>
      <option selected disabled value="">Choose...</option>
      <option>...</option>
    </select>
    <div class="invalid-feedback">
      Please select a valid state.
    </div>
  </div>
  <div class="col-md-3">
    <label for="validationCustom05" class="form-label">Zip</label>
    <input type="text" class="form-control" id="validationCustom05" required>
    <div class="invalid-feedback">
      Please provide a valid zip.
    </div>
  </div>
  <div class="col-12">
    <div class="form-check">
      <input class="form-check-input" type="checkbox" value="" id="invalidCheck" required>
      <label class="form-check-label" for="invalidCheck">
        Agree to terms and conditions
      </label>
      <div class="invalid-feedback">
        You must agree before submitting.
      </div>
    </div>
  </div>
  <div class="col-12">
    <button class="btn btn-primary" type="submit">Submit form</button>
  </div>
</form>
// Example starter JavaScript for disabling form submissions if there are invalid fields
(() => {
  'use strict'

  // Fetch all the forms we want to apply custom Bootstrap validation styles to
  const forms = document.querySelectorAll('.needs-validation')

  // Loop over them and prevent submission
  Array.from(forms).forEach(form => {
    form.addEventListener('submit', event => {
      if (!form.checkValidity()) {
        event.preventDefault()
        event.stopPropagation()
      }

      form.classList.add('was-validated')
    }, false)
  })
})()

Impostazioni predefinite del browser

Non sei interessato ai messaggi di feedback di convalida personalizzati o alla scrittura di JavaScript per modificare i comportamenti dei moduli? Tutto bene, puoi usare le impostazioni predefinite del browser. Prova a inviare il modulo sottostante. A seconda del browser e del sistema operativo, vedrai uno stile di feedback leggermente diverso.

Sebbene questi stili di feedback non possano essere stilizzati con CSS, puoi comunque personalizzare il testo del feedback tramite JavaScript.

@
html 
<form class="row g-3">
  <div class="col-md-4">
    <label for="validationDefault01" class="form-label">First name</label>
    <input type="text" class="form-control" id="validationDefault01" value="Mark" required>
  </div>
  <div class="col-md-4">
    <label for="validationDefault02" class="form-label">Last name</label>
    <input type="text" class="form-control" id="validationDefault02" value="Otto" required>
  </div>
  <div class="col-md-4">
    <label for="validationDefaultUsername" class="form-label">Username</label>
    <div class="input-group">
      <span class="input-group-text" id="inputGroupPrepend2">@</span>
      <input type="text" class="form-control" id="validationDefaultUsername"  aria-describedby="inputGroupPrepend2" required>
    </div>
  </div>
  <div class="col-md-6">
    <label for="validationDefault03" class="form-label">City</label>
    <input type="text" class="form-control" id="validationDefault03" required>
  </div>
  <div class="col-md-3">
    <label for="validationDefault04" class="form-label">State</label>
    <select class="form-select" id="validationDefault04" required>
      <option selected disabled value="">Choose...</option>
      <option>...</option>
    </select>
  </div>
  <div class="col-md-3">
    <label for="validationDefault05" class="form-label">Zip</label>
    <input type="text" class="form-control" id="validationDefault05" required>
  </div>
  <div class="col-12">
    <div class="form-check">
      <input class="form-check-input" type="checkbox" value="" id="invalidCheck2" required>
      <label class="form-check-label" for="invalidCheck2">
        Agree to terms and conditions
      </label>
    </div>
  </div>
  <div class="col-12">
    <button class="btn btn-primary" type="submit">Submit form</button>
  </div>
</form>

Lato server

Si consiglia di utilizzare la convalida lato client, ma nel caso in cui sia necessaria la convalida lato server, è possibile indicare campi modulo non validi e validi con .is-invalide .is-valid. Nota che .invalid-feedbackè supportato anche con queste classi.

Per i campi non validi, assicurati che il feedback/messaggio di errore non valido sia associato al campo del modulo pertinente aria-describedby(notare che questo attributo consente di idfare riferimento a più di uno, nel caso in cui il campo punti già a un testo del modulo aggiuntivo).

Per risolvere i problemi con il raggio di confine , i gruppi di input richiedono una .has-validationclasse aggiuntiva.

Sembra buono!
Sembra buono!
@
Scegli un nome utente.
Si prega di fornire una città valida.
Seleziona uno stato valido.
Si prega di fornire un codice postale valido.
Devi essere d'accordo prima di inviare.
html 
<form class="row g-3">
  <div class="col-md-4">
    <label for="validationServer01" class="form-label">First name</label>
    <input type="text" class="form-control is-valid" id="validationServer01" value="Mark" required>
    <div class="valid-feedback">
      Looks good!
    </div>
  </div>
  <div class="col-md-4">
    <label for="validationServer02" class="form-label">Last name</label>
    <input type="text" class="form-control is-valid" id="validationServer02" value="Otto" required>
    <div class="valid-feedback">
      Looks good!
    </div>
  </div>
  <div class="col-md-4">
    <label for="validationServerUsername" class="form-label">Username</label>
    <div class="input-group has-validation">
      <span class="input-group-text" id="inputGroupPrepend3">@</span>
      <input type="text" class="form-control is-invalid" id="validationServerUsername" aria-describedby="inputGroupPrepend3 validationServerUsernameFeedback" required>
      <div id="validationServerUsernameFeedback" class="invalid-feedback">
        Please choose a username.
      </div>
    </div>
  </div>
  <div class="col-md-6">
    <label for="validationServer03" class="form-label">City</label>
    <input type="text" class="form-control is-invalid" id="validationServer03" aria-describedby="validationServer03Feedback" required>
    <div id="validationServer03Feedback" class="invalid-feedback">
      Please provide a valid city.
    </div>
  </div>
  <div class="col-md-3">
    <label for="validationServer04" class="form-label">State</label>
    <select class="form-select is-invalid" id="validationServer04" aria-describedby="validationServer04Feedback" required>
      <option selected disabled value="">Choose...</option>
      <option>...</option>
    </select>
    <div id="validationServer04Feedback" class="invalid-feedback">
      Please select a valid state.
    </div>
  </div>
  <div class="col-md-3">
    <label for="validationServer05" class="form-label">Zip</label>
    <input type="text" class="form-control is-invalid" id="validationServer05" aria-describedby="validationServer05Feedback" required>
    <div id="validationServer05Feedback" class="invalid-feedback">
      Please provide a valid zip.
    </div>
  </div>
  <div class="col-12">
    <div class="form-check">
      <input class="form-check-input is-invalid" type="checkbox" value="" id="invalidCheck3" aria-describedby="invalidCheck3Feedback" required>
      <label class="form-check-label" for="invalidCheck3">
        Agree to terms and conditions
      </label>
      <div id="invalidCheck3Feedback" class="invalid-feedback">
        You must agree before submitting.
      </div>
    </div>
  </div>
  <div class="col-12">
    <button class="btn btn-primary" type="submit">Submit form</button>
  </div>
</form>

Elementi supportati

Gli stili di convalida sono disponibili per i seguenti controlli e componenti del modulo:

  • <input>se s <textarea>con .form-control(incluso fino a uno .form-controlnei gruppi di input)
  • <select>s con.form-select
  • .form-checkS
Si prega di inserire un messaggio nell'area di testo.
Esempio di testo di feedback non valido
Altro testo di feedback non valido di esempio
Esempio di feedback di selezione non valido
Esempio di feedback sul file modulo non valido
html 
<form class="was-validated">
  <div class="mb-3">
    <label for="validationTextarea" class="form-label">Textarea</label>
    <textarea class="form-control" id="validationTextarea" placeholder="Required example textarea" required></textarea>
    <div class="invalid-feedback">
      Please enter a message in the textarea.
    </div>
  </div>

  <div class="form-check mb-3">
    <input type="checkbox" class="form-check-input" id="validationFormCheck1" required>
    <label class="form-check-label" for="validationFormCheck1">Check this checkbox</label>
    <div class="invalid-feedback">Example invalid feedback text</div>
  </div>

  <div class="form-check">
    <input type="radio" class="form-check-input" id="validationFormCheck2" name="radio-stacked" required>
    <label class="form-check-label" for="validationFormCheck2">Toggle this radio</label>
  </div>
  <div class="form-check mb-3">
    <input type="radio" class="form-check-input" id="validationFormCheck3" name="radio-stacked" required>
    <label class="form-check-label" for="validationFormCheck3">Or toggle this other radio</label>
    <div class="invalid-feedback">More example invalid feedback text</div>
  </div>

  <div class="mb-3">
    <select class="form-select" required aria-label="select example">
      <option value="">Open this select menu</option>
      <option value="1">One</option>
      <option value="2">Two</option>
      <option value="3">Three</option>
    </select>
    <div class="invalid-feedback">Example invalid select feedback</div>
  </div>

  <div class="mb-3">
    <input type="file" class="form-control" aria-label="file example" required>
    <div class="invalid-feedback">Example invalid form file feedback</div>
  </div>

  <div class="mb-3">
    <button class="btn btn-primary" type="submit" disabled>Submit form</button>
  </div>
</form>

Suggerimenti

Se il layout del tuo modulo lo consente, puoi scambiare le .{valid|invalid}-feedbackclassi con le .{valid|invalid}-tooltipclassi per visualizzare il feedback di convalida in una descrizione comando con stile. Assicurati di avere un genitore con position: relativeesso per il posizionamento del suggerimento. Nell'esempio seguente, le nostre classi di colonne lo hanno già, ma il tuo progetto potrebbe richiedere una configurazione alternativa.

Sembra buono!
Sembra buono!
@
Scegli un nome utente univoco e valido.
Si prega di fornire una città valida.
Seleziona uno stato valido.
Si prega di fornire un codice postale valido.
html 
<form class="row g-3 needs-validation" novalidate>
  <div class="col-md-4 position-relative">
    <label for="validationTooltip01" class="form-label">First name</label>
    <input type="text" class="form-control" id="validationTooltip01" value="Mark" required>
    <div class="valid-tooltip">
      Looks good!
    </div>
  </div>
  <div class="col-md-4 position-relative">
    <label for="validationTooltip02" class="form-label">Last name</label>
    <input type="text" class="form-control" id="validationTooltip02" value="Otto" required>
    <div class="valid-tooltip">
      Looks good!
    </div>
  </div>
  <div class="col-md-4 position-relative">
    <label for="validationTooltipUsername" class="form-label">Username</label>
    <div class="input-group has-validation">
      <span class="input-group-text" id="validationTooltipUsernamePrepend">@</span>
      <input type="text" class="form-control" id="validationTooltipUsername" aria-describedby="validationTooltipUsernamePrepend" required>
      <div class="invalid-tooltip">
        Please choose a unique and valid username.
      </div>
    </div>
  </div>
  <div class="col-md-6 position-relative">
    <label for="validationTooltip03" class="form-label">City</label>
    <input type="text" class="form-control" id="validationTooltip03" required>
    <div class="invalid-tooltip">
      Please provide a valid city.
    </div>
  </div>
  <div class="col-md-3 position-relative">
    <label for="validationTooltip04" class="form-label">State</label>
    <select class="form-select" id="validationTooltip04" required>
      <option selected disabled value="">Choose...</option>
      <option>...</option>
    </select>
    <div class="invalid-tooltip">
      Please select a valid state.
    </div>
  </div>
  <div class="col-md-3 position-relative">
    <label for="validationTooltip05" class="form-label">Zip</label>
    <input type="text" class="form-control" id="validationTooltip05" required>
    <div class="invalid-tooltip">
      Please provide a valid zip.
    </div>
  </div>
  <div class="col-12">
    <button class="btn btn-primary" type="submit">Submit form</button>
  </div>
</form>

Sass

Variabili

$form-feedback-margin-top:          $form-text-margin-top;
$form-feedback-font-size:           $form-text-font-size;
$form-feedback-font-style:          $form-text-font-style;
$form-feedback-valid-color:         $success;
$form-feedback-invalid-color:       $danger;

$form-feedback-icon-valid-color:    $form-feedback-valid-color;
$form-feedback-icon-valid:          url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'><path fill='#{$form-feedback-icon-valid-color}' d='M2.3 6.73.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/></svg>");
$form-feedback-icon-invalid-color:  $form-feedback-invalid-color;
$form-feedback-icon-invalid:        url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' width='12' height='12' fill='none' stroke='#{$form-feedback-icon-invalid-color}'><circle cx='6' cy='6' r='4.5'/><path stroke-linejoin='round' d='M5.8 3.6h.4L6 6.5z'/><circle cx='6' cy='8.2' r='.6' fill='#{$form-feedback-icon-invalid-color}' stroke='none'/></svg>");

Miscele

Due mixin vengono combinati insieme, attraverso il nostro ciclo , per generare i nostri stili di feedback di convalida dei moduli.

@mixin form-validation-state-selector($state) {
  @if ($state == "valid" or $state == "invalid") {
    .was-validated #{if(&, "&", "")}:#{$state},
    #{if(&, "&", "")}.is-#{$state} {
      @content;
    }
  } @else {
    #{if(&, "&", "")}.is-#{$state} {
      @content;
    }
  }
}

@mixin form-validation-state(
  $state,
  $color,
  $icon,
  $tooltip-color: color-contrast($color),
  $tooltip-bg-color: rgba($color, $form-feedback-tooltip-opacity),
  $focus-box-shadow: 0 0 $input-btn-focus-blur $input-focus-width rgba($color, $input-btn-focus-color-opacity)
) {
  .#{$state}-feedback {
    display: none;
    width: 100%;
    margin-top: $form-feedback-margin-top;
    @include font-size($form-feedback-font-size);
    font-style: $form-feedback-font-style;
    color: $color;
  }

  .#{$state}-tooltip {
    position: absolute;
    top: 100%;
    z-index: 5;
    display: none;
    max-width: 100%; // Contain to parent when possible
    padding: $form-feedback-tooltip-padding-y $form-feedback-tooltip-padding-x;
    margin-top: .1rem;
    @include font-size($form-feedback-tooltip-font-size);
    line-height: $form-feedback-tooltip-line-height;
    color: $tooltip-color;
    background-color: $tooltip-bg-color;
    @include border-radius($form-feedback-tooltip-border-radius);
  }

  @include form-validation-state-selector($state) {
    ~ .#{$state}-feedback,
    ~ .#{$state}-tooltip {
      display: block;
    }
  }

  .form-control {
    @include form-validation-state-selector($state) {
      border-color: $color;

      @if $enable-validation-icons {
        padding-right: $input-height-inner;
        background-image: escape-svg($icon);
        background-repeat: no-repeat;
        background-position: right $input-height-inner-quarter center;
        background-size: $input-height-inner-half $input-height-inner-half;
      }

      &:focus {
        border-color: $color;
        box-shadow: $focus-box-shadow;
      }
    }
  }

  // stylelint-disable-next-line selector-no-qualifying-type
  textarea.form-control {
    @include form-validation-state-selector($state) {
      @if $enable-validation-icons {
        padding-right: $input-height-inner;
        background-position: top $input-height-inner-quarter right $input-height-inner-quarter;
      }
    }
  }

  .form-select {
    @include form-validation-state-selector($state) {
      border-color: $color;

      @if $enable-validation-icons {
        &:not([multiple]):not([size]),
        &:not([multiple])[size="1"] {
          padding-right: $form-select-feedback-icon-padding-end;
          background-image: escape-svg($form-select-indicator), escape-svg($icon);
          background-position: $form-select-bg-position, $form-select-feedback-icon-position;
          background-size: $form-select-bg-size, $form-select-feedback-icon-size;
        }
      }

      &:focus {
        border-color: $color;
        box-shadow: $focus-box-shadow;
      }
    }
  }

  .form-control-color {
    @include form-validation-state-selector($state) {
      @if $enable-validation-icons {
        width: add($form-color-width, $input-height-inner);
      }
    }
  }

  .form-check-input {
    @include form-validation-state-selector($state) {
      border-color: $color;

      &:checked {
        background-color: $color;
      }

      &:focus {
        box-shadow: $focus-box-shadow;
      }

      ~ .form-check-label {
        color: $color;
      }
    }
  }
  .form-check-inline .form-check-input {
    ~ .#{$state}-feedback {
      margin-left: .5em;
    }
  }

  .input-group {
    > .form-control:not(:focus),
    > .form-select:not(:focus),
    > .form-floating:not(:focus-within) {
      @include form-validation-state-selector($state) {
        @if $state == "valid" {
          z-index: 3;
        } @else if $state == "invalid" {
          z-index: 4;
        }
      }
    }
  }
}

Carta geografica

Questa è la mappa Sass di validazione da _variables.scss. Eseguire l'override o estenderlo per generare stati diversi o aggiuntivi.

$form-validation-states: (
  "valid": (
    "color": $form-feedback-valid-color,
    "icon": $form-feedback-icon-valid
  ),
  "invalid": (
    "color": $form-feedback-invalid-color,
    "icon": $form-feedback-icon-invalid
  )
);

Le mappe di $form-validation-statespossono contenere tre parametri opzionali per sovrascrivere le descrizioni comandi e gli stili di messa a fuoco.

Ciclo continuo

Utilizzato per eseguire iterazioni sui $form-validation-statesvalori della mappa per generare i nostri stili di convalida. Qualsiasi modifica alla mappa Sass sopra si rifletterà nel CSS compilato tramite questo ciclo.

@each $state, $data in $form-validation-states {
  @include form-validation-state($state, $data...);
}

Personalizzazione

Gli stati di validazione possono essere personalizzati via Sass con la $form-validation-statesmappa. Situata nel nostro _variables.scssfile, questa mappa Sass è il modo in cui generiamo gli stati di default valid/ invalidconvalida. È inclusa una mappa nidificata per personalizzare il colore, l'icona, il colore della descrizione comando e l'ombra di messa a fuoco di ogni stato. Sebbene nessun altro stato sia supportato dai browser, coloro che utilizzano stili personalizzati possono facilmente aggiungere feedback di moduli più complessi.