Sähköpostikenttä

Sähköpostikenttä on Text Fieldin laajennus, joka hyväksyy syötteeksi vain sähköpostiosoitteita.

Sähköpostikenttä on Text Fieldin laajennus, joka hyväksyy syötteeksi vain sähköpostiosoitteita. Jos annettu osoite on virheellinen, kenttä korostetaan punaisella ja syötteen alle ilmestyy virheilmoitus.

Open in a
new tab

Source code

EmailFieldBasic.javapackage com.vaadin.demo.component.emailfield;

import com.vaadin.flow.component.formlayout.FormLayout;
import com.vaadin.flow.component.textfield.EmailField;
import com.vaadin.flow.router.Route;

@Route("email-field-basic")
public class EmailFieldBasic extends FormLayout {

    public EmailFieldBasic() {
        setAutoResponsive(true);
        setAutoRows(true);

        // tag::snippet[]
        EmailField validEmailField = new EmailField();
        validEmailField.setLabel("Email address");
        validEmailField.getElement().setAttribute("name", "email");
        validEmailField.setValue("julia.scheider@email.com");
        validEmailField.setErrorMessage("Enter a valid email address");
        validEmailField.setClearButtonVisible(true);

        EmailField invalidEmailField = new EmailField();
        invalidEmailField.setLabel("Email address");
        invalidEmailField.getElement().setAttribute("name", "email");
        invalidEmailField.setValue("This is not an email");
        invalidEmailField.setErrorMessage("Enter a valid email address");
        invalidEmailField.setClearButtonVisible(true);

        add(validEmailField, invalidEmailField);
        // end::snippet[]
    }

}
email-field-basic.tsximport React from 'react';
import { EmailField, FormLayout } from '@vaadin/react-components';

function Example() {
  return (
    <FormLayout autoResponsive autoRows>
      {/* tag::snippet[] */}
      <EmailField
        label="Email address"
        name="email"
        value="julia.scheider@email.com"
        errorMessage="Enter a valid email address"
        clearButtonVisible
      />

      <EmailField
        label="Email address"
        name="email"
        value="This is not an email"
        errorMessage="Enter a valid email address"
        clearButtonVisible
        invalid
      />
      {/* end::snippet[] */}
    </FormLayout>
  );
}

email-field-basic.tsimport '@vaadin/email-field';
import '@vaadin/form-layout';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('email-field-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <vaadin-form-layout auto-responsive auto-rows>
        <!-- tag::snippet[] -->
        <vaadin-email-field
          label="Email address"
          name="email"
          value="julia.scheider@email.com"
          error-message="Enter a valid email address"
          clear-button-visible
        ></vaadin-email-field>

        <vaadin-email-field
          label="Email address"
          name="email"
          value="This is not an email"
          error-message="Enter a valid email address"
          clear-button-visible
          invalid
        ></vaadin-email-field>
        <!-- end::snippet[] -->
      </vaadin-form-layout>
    `;
  }
}

Sähköpostiosoitteiden oikeellisuus tarkistetaan RFC 5322 -standardin mukaisesti, joka määrittelee sähköpostiosoitteiden muodon.

Perusominaisuudet

Seuraavat ominaisuudet, jotka ovat yleisiä useimmille syötekenttäkomponenteille, ovat tuettuja:

Tunniste

Tunnistetta käytetään syötekentän yksilöimiseen. Se tukee pelkkää tekstiä, ja sen pituus on rajoitettu kentän leveyteen. Avustajat ja Vihjetekstit voivat tarjota lisätietoa, joka ei mahdu tunnisteeseen.

Näkyvät tunnisteet ovat vahvasti suositeltavia kaikille syötekentille. Jos sisäänrakennettua tunnistetta ei voida käyttää, ulkoinen elementti voidaan liittää kentän tunnisteeksi aria-labelledby -attribuutin avulla. Kentät, joilla ei ole näkyvää tunnistetta, tulisi varustaa näkymättömällä tunnisteella avustavia teknologioita varten käyttämällä aria-label -attribuuttia.

Avustaja

Avustajia käytetään tarjoamaan lisätietoa, jota käyttäjä voi tarvita kenttään syöttämiseen, kuten muotovaatimuksia tai selityksiä kentän tarkoituksesta kentän alapuolella.

Tyylivariaatio on saatavilla avustajan näyttämiseksi kentän yläpuolella.

Pelkkä tekstin lisäksi avustajat voivat sisältää komponentteja ja HTML-elementtej ä. Kuitenkin monimutkainen ja interaktiivinen sisältö voi aiheuttaa saavutettavuusongelmia.

Paikkamerkki

Paikkamerkki on teksti, joka näytetään, kun kenttä on tyhjä. Sen ensisijainen tarkoitus on antaa lyhyt syöttövinkki (esim. odotettu muoto) tilanteissa, joissa Avustajaa ei voida käyttää.

Paikkamerkkejä ei tulisi käyttää näkyvän tunnisteen korvikkeena. Ne voidaan sekoittaa käsin syötettyyn arvoon. Katso Tunniste vaihtoehdoista sisäänrakennetulle kentän tunnisteelle.

Poistopainike

Poistopainike — joka näytetään, kun kenttä ei ole tyhjä — tyhjentää kentän nykyisen arvon. Vaikka painiketta ei voi valita näppäimistöllä, poistotoiminto voidaan suorittaa Esc-näppäimellä, kun kenttä on valittuna. Poistopainike voi olla erityisen hyödyllinen haku- ja suodatuskentissä, joissa käyttäjien täytyy usein tyhjentää arvo. Tavallisissa lomakkeissa se on kuitenkin vähemmän hyödyllinen.

Etuliite & Jälkiliite

Etuliite- ja jälkiliite-elementtejä — jotka näytetään kentän kummassakin päässä — voidaan käyttää yksiköiden, kuvakkeiden ja muiden kentän tarkoitukseen tai muotoon liittyvien visuaalisten vihjeiden näyttämiseen.

Etuliite- ja jälkiliite-elementit eivät yleensä toimi hyvin avustavien teknologioiden, kuten ruudunlukijoiden, kanssa. Siksi niiden välittämä tieto tulisi esittää myös muilla keinoilla, kuten Tunnisteessa, Avustajassa tai ARIA-attribuuttien kautta kentässä.

Ulkoinen & Näkymätön tunniste (ARIA)

Näkyvät tunnisteet ovat vahvasti suositeltavia kaikille syötekentille. Jos sisäänrakennettua tunnistetta ei voida käyttää, ulkoinen elementti voidaan liittää kentän tunnisteeksi sen elementin id:n avulla. Kentille, joilla ei ole näkyvää tunnistetta, tulisi tarjota näkymätön tunniste avustavia teknologioita, kuten ruudunlukijoita, varten.

Source code

HTML<!-- Liittää ulkoisen elementin nimenä: -->
<label id="external-label">Tämä on nimiö</label>
<vaadin-email-field accessible-name-ref="external-label">...

<!-- Näkymätön nimiö ruudunlukijoille: -->
<vaadin-email-field accessible-name="Tämä on nimiö">...
Java// Liittää ulkoisen elementin nimenä:
NativeLabel label = new NativeLabel("Tämä on nimiö");
label.setId("external-label");
field.setAriaLabelledBy("external-label");

// Näkymätön nimiö ruudunlukijoille:
field.setAriaLabel("Tämä on nimiö");

Open in a
new tab

Source code

EmailFieldBasicFeatures.javapackage com.vaadin.demo.component.emailfield;

import com.vaadin.flow.component.icon.VaadinIcon;
import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
import com.vaadin.flow.component.textfield.EmailField;
import com.vaadin.flow.router.Route;

@Route("email-field-basic-features")
public class EmailFieldBasicFeatures extends HorizontalLayout {

    public EmailFieldBasicFeatures() {
        setPadding(false);

        // tag::snippet[]
        EmailField field = new EmailField();
        field.setLabel("Label");
        field.setHelperText("Helper text");
        field.setPlaceholder("Placeholder");
        field.setTooltipText("Tooltip text");
        field.setClearButtonVisible(true);
        field.setPrefixComponent(VaadinIcon.ENVELOPE.create());
        // end::snippet[]

        add(field);
    }

}
email-field-basic-features.tsximport '@vaadin/icons';
import React from 'react';
import { EmailField } from '@vaadin/react-components/EmailField.js';
import { Icon } from '@vaadin/react-components/Icon.js';
import { Tooltip } from '@vaadin/react-components/Tooltip.js';

function Example() {
  return (
    // tag::snippet[]
    <EmailField label="Label" helperText="Helper text" placeholder="Placeholder" clearButtonVisible>
      <Tooltip slot="tooltip" text="Tooltip text" />
      <Icon slot="prefix" icon="vaadin:envelope" />
    </EmailField>
    // end::snippet[]
  );
}

email-field-basic-features.tsimport '@vaadin/email-field';
import '@vaadin/icon';
import '@vaadin/icons';
import '@vaadin/tooltip';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('email-field-basic-features')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-email-field
        label="Label"
        helper-text="Helper text"
        placeholder="Placeholder"
        clear-button-visible
      >
        <vaadin-tooltip slot="tooltip" text="Tooltip text"></vaadin-tooltip>
        <vaadin-icon slot="prefix" icon="vaadin:envelope"></vaadin-icon>
      </vaadin-email-field>
      <!-- end::snippet[] -->
    `;
  }
}

Validointi

Sähköpostikenttä tarjoaa validointimekanismin, joka perustuu rajoitteisiin. Rajoitteiden avulla voidaan määritellä kriteerit, joiden tulee täyttyä, jotta arvo katsotaan kelvolliseksi. Validointi tapahtuu tyypillisesti, kun käyttäjä käynnistää arvon muutoksen, esimerkiksi syöttämällä tietoja ja painamalla Enter. Jos arvo on virheellinen, kenttä korostetaan punaisella ja syötteen alle ilmestyy virheilmoitus.

Alla on luettelo tuetuista rajoitteista ja tarkempaa tietoa niistä:

Pakollinen

Pakolliset kentät merkitään tunnisteen viereen tulevalla indikaattorilla, ja ne muuttuvat virheellisiksi, jos arvo ensin syötetään ja sitten poistetaan.

Lomakkeen yläosaan suositellaan ohjetekstiä, joka selittää pakollisen kentän indikaattorin. Indikaattoria voi muokata --vaadin-input-field-required-indicator -tyyliominaisuudella.

Kuvio

Kuvio on säännöllinen lauseke, joka määrittelee sähköpostiosoitteen muodon. Mikä tahansa arvo, joka ei vastaa sähköpostimuotoa, tekee kentästä virheellisen. Oletuksena käytetään RFC 5322 -standardin kuviota. Voit kuitenkin muokata tätä kuviota lisätäksesi rajoituksia (esim. vaatiaksesi tietyn verkkotunnuksen).

Alla olevassa esimerkissä käytetään muokattua RFC 5322 -kuviota ja hyväksytään vain example.com -verkkotunnuksen osoitteet.

Seuraava esimerkki havainnollistaa, kuinka nämä rajoitteet määritellään ja virheilmoitukset annetaan:

Open in a
new tab

Source code

EmailFieldValidation.javapackage com.vaadin.demo.component.emailfield;

import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
import com.vaadin.flow.component.textfield.EmailField;
import com.vaadin.flow.component.textfield.EmailField.EmailFieldI18n;
import com.vaadin.flow.router.Route;

@Route("email-field-validation")
public class EmailFieldValidation extends HorizontalLayout {

    public EmailFieldValidation() {
        setPadding(false);

        // tag::snippet[]
        EmailField field = new EmailField("Email address");
        field.setRequiredIndicatorVisible(true);
        field.setPattern(
                "^[a-zA-Z0-9_\\-+]+(?:\\.[a-zA-Z0-9_\\-+]+)*@example\\.com$");

        field.setI18n(new EmailFieldI18n()
                .setRequiredErrorMessage("Field is required")
                .setPatternErrorMessage(
                        "Enter a valid example.com email address"));
        // end::snippet[]
        field.setHelperText("Only example.com addresses allowed");

        add(field);
    }

}
email-field-validation.tsximport React from 'react';
import { useSignal } from '@vaadin/hilla-react-signals';
import { EmailField, type EmailFieldElement } from '@vaadin/react-components/EmailField.js';

function Example() {
  const errorMessage = useSignal('');

  return (
    // tag::snippet[]
    <EmailField
      required
      pattern="^[a-zA-Z0-9_\-+]+(?:\.[a-zA-Z0-9_\-+]+)*@example\.com$"
      label="Email address"
      helperText="Only example.com addresses allowed"
      errorMessage={errorMessage.value}
      onValidated={(event) => {
        const field = event.target as EmailFieldElement;
        const { validity } = field.inputElement as HTMLInputElement;
        if (validity.valueMissing) {
          errorMessage.value = 'Field is required';
        } else if (validity.patternMismatch) {
          errorMessage.value = 'Enter a valid example.com email address';
        } else {
          errorMessage.value = '';
        }
      }}
    />
    // end::snippet[]
  );
}

email-field-validation.tsimport '@vaadin/email-field';
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import type { EmailField, EmailFieldValidatedEvent } from '@vaadin/email-field';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('email-field-validation')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  @state()
  private errorMessage = '';

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-email-field
        required
        pattern="^[a-zA-Z0-9_\\-+]+(?:\\.[a-zA-Z0-9_\\-+]+)*@example\\.com$"
        label="Email address"
        helper-text="Only example.com addresses allowed"
        .errorMessage="${this.errorMessage}"
        @validated="${(event: EmailFieldValidatedEvent) => {
          const field = event.target as EmailField;
          const { validity } = field.inputElement as HTMLInputElement;
          if (validity.valueMissing) {
            this.errorMessage = 'Field is required';
          } else if (validity.patternMismatch) {
            this.errorMessage = 'Enter a valid example.com email address';
          } else {
            this.errorMessage = '';
          }
        }}"
      ></vaadin-email-field>
      <!-- end::snippet[] -->
    `;
  }
}

On tärkeää varmistaa, että jokaiselle rajoitteen rikkomiselle on määritelty sopiva virheilmoitus, jotta käyttäjälle annetaan selkeää palautetta.

Note	Datan sidonta & Mukautettu validointi Flow ja Hilla tarjoavat kehittyneen Binder-rajapinnan, jonka avulla voit sitoa dataa ja lisätä mukautettuja validointisääntöjä useille kentille, luoden lomakkeita. Lisätietoja Binderista löydät vastaavista Flow ja Hilla artikkeleista.

Vain luku & Poistettu käytöstä

Kentät, joita käytetään arvojen näyttämiseen, tulisi asettaa vain luku -tilaan, jotta muokkaaminen estetään. Vain luku -kentät ovat valittavissa ja näkyvät ruudunlukijoille. Niissä voidaan näyttää vihjetekstejä. Niiden arvot voidaan valita ja kopioida.

Kentät, jotka eivät ole tällä hetkellä käytettävissä, tulisi asettaa poistettu käytöstä -tilaan. Poistettujen kenttien heikompi kontrasti tekee niistä sopimattomia tiedon näyttämiseen. Niitä ei voi valita eikä niissä voi näyttää vihjetekstejä. Ne ovat näkymättömiä ruudunlukijoille, eikä niiden arvoja voi valita tai kopioida.

Poistetut kentät voivat olla hyödyllisiä tilanteissa, joissa ne voidaan ottaa käyttöön jonkin käyttäjän toiminnon perusteella. Harkitse kenttien piilottamista kokonaan, jos käyttäjä ei voi tehdä mitään muuttaakseen niiden muokattavuutta.

Open in a
new tab

Source code

EmailFieldReadonlyAndDisabled.javapackage com.vaadin.demo.component.emailfield;

import com.vaadin.flow.component.formlayout.FormLayout;
import com.vaadin.flow.component.textfield.EmailField;
import com.vaadin.flow.router.Route;

@Route("email-field-readonly-and-disabled")
public class EmailFieldReadonlyAndDisabled extends FormLayout {

    public EmailFieldReadonlyAndDisabled() {
        setAutoResponsive(true);
        setAutoRows(true);

        // tag::snippet[]
        EmailField readonlyField = new EmailField();
        readonlyField.setReadOnly(true);
        readonlyField.setLabel("Read-only");
        readonlyField.setValue("example@example.com");

        EmailField disabledField = new EmailField();
        disabledField.setEnabled(false);
        disabledField.setLabel("Disabled");
        // end::snippet[]
        add(readonlyField, disabledField);
    }

}
email-field-readonly-and-disabled.tsximport React from 'react';
import { EmailField, FormLayout } from '@vaadin/react-components';

function Example() {
  return (
    <FormLayout autoResponsive autoRows>
      {/* tag::snippet[] */}
      <EmailField readonly label="Read-only" value="example@example.com" />

      <EmailField disabled label="Disabled" />
      {/* end::snippet[] */}
    </FormLayout>
  );
}

email-field-readonly-and-disabled.tsimport '@vaadin/email-field';
import '@vaadin/form-layout';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('email-field-readonly-and-disabled')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <vaadin-form-layout auto-responsive auto-rows>
        <!-- tag::snippet[] -->
        <vaadin-email-field
          readonly
          label="Read-only"
          value="example@example.com"
        ></vaadin-email-field>

        <vaadin-email-field disabled label="Disabled"></vaadin-email-field>
        <!-- end::snippet[] -->
      </vaadin-form-layout>
    `;
  }
}

CC0AAD7F-3E1C-4A8E-A331-52F2AEDDD907

Docs

Docs

Sähköpostikenttä

Perusominaisuudet

Validointi

Vain luku & Poistettu käytöstä