Custom Field

使用 Custom Field 将多个组件包装为单个字段。

使用方法
样式

基础用法
值类型与格式
原生输入字段
尺寸变体

Custom Field 是一个用于将多个组件包装为单个字段的组件。它提供了标签、辅助信息、验证和数据绑定等标准输入字段功能。您可以使用它来创建自定义的输入组件。

Source code

DateRangePicker.javapackage com.vaadin.demo.component.customfield;

import com.vaadin.flow.component.Text;
import com.vaadin.flow.component.customfield.CustomField;
import com.vaadin.flow.component.datepicker.DatePicker;

// tag::snippet[]
public class DateRangePicker extends CustomField<LocalDateRange> {

    private DatePicker start;
    private DatePicker end;

    public DateRangePicker(String label) {
        this();
        setLabel(label);
    }

    public DateRangePicker() {
        start = new DatePicker();
        start.setPlaceholder("Start date");
        // Sets title for screen readers
        start.setAriaLabel("Start date");

        end = new DatePicker();
        end.setPlaceholder("End date");
        end.setAriaLabel("End date");

        // Enable manual validation on both date pickers to
        // be able to override their invalid state
        start.setManualValidation(true);
        end.setManualValidation(true);

        add(start, new Text(" – "), end);
    }

    @Override
    protected LocalDateRange generateModelValue() {
        return new LocalDateRange(start.getValue(), end.getValue());
    }

    @Override
    protected void setPresentationValue(LocalDateRange dateRange) {
        start.setValue(dateRange.getStartDate());
        end.setValue(dateRange.getEndDate());
    }

    @Override
    public void setInvalid(boolean invalid) {
        super.setInvalid(invalid);
        // Propagate invalid state to both date pickers so
        // that they show a red background
        start.setInvalid(invalid);
        end.setInvalid(invalid);
    }
}
// end::snippet[]
CustomFieldBasic.javapackage com.vaadin.demo.component.customfield;

import com.vaadin.demo.domain.Appointment;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.data.binder.Binder;
import com.vaadin.flow.router.Route;

import java.time.temporal.ChronoUnit;

@Route("custom-field-basic")
public class CustomFieldBasic extends Div {

    public CustomFieldBasic() {
        // tag::snippet[]
        DateRangePicker dateRangePicker = new DateRangePicker();
        dateRangePicker.setLabel("Enrollment period");
        dateRangePicker.setHelperText("Cannot be longer than 30 days");
        add(dateRangePicker);

        Binder<Appointment> binder = new Binder();
        binder.forField(dateRangePicker)
                .asRequired("Enter a start and end date")
                .withValidator(
                        localDateRange -> localDateRange.getStartDate() == null
                                || localDateRange.getEndDate() == null
                                || ChronoUnit.DAYS.between(
                                        localDateRange.getStartDate(),
                                        localDateRange.getEndDate()) <= 30,
                        "Dates cannot be more than 30 days apart")
                .withValidator(
                        localDateRange -> localDateRange.getStartDate() == null
                                || localDateRange.getEndDate() == null
                                || localDateRange.getStartDate()
                                        .isBefore(localDateRange.getEndDate()),
                        "Start date must be earlier than end date")
                .bind(appointment -> new LocalDateRange(
                        appointment.getStartDate(), appointment.getEndDate()),
                        (appointment, localDateRange) -> {
                            appointment.setStartDate(
                                    localDateRange.getStartDate());
                            appointment.setEndDate(localDateRange.getEndDate());
                        });
        // end::snippet[]
    }

}
LocalDateRange.javapackage com.vaadin.demo.component.customfield;

import java.time.LocalDate;

// tag::snippet[]
public class LocalDateRange {

    private LocalDate startDate;
    private LocalDate endDate;

    public LocalDateRange(LocalDate startDate, LocalDate endDate) {
        this.startDate = startDate;
        this.endDate = endDate;
    }

    public LocalDate getStartDate() {
        return startDate;
    }

    public void setStartDate(LocalDate startDate) {
        this.startDate = startDate;
    }

    public LocalDate getEndDate() {
        return endDate;
    }

    public void setEndDate(LocalDate endDate) {
        this.endDate = endDate;
    }
}
// end::snippet[]
Appointment.javapackage com.vaadin.demo.domain;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;


// tag::snippet[]
public class Appointment {

    private LocalTime startTime;

    private LocalDateTime startDateTime;

    private LocalDate startDate;

    private LocalTime endTime;

    private LocalDateTime endDateTime;

    private LocalDate endDate;

    private String enrollmentPeriod;

    private Integer id;

    public LocalTime getStartTime() {
        return startTime;
    }

    public void setStartTime(LocalTime startTime) {
        this.startTime = startTime;
    }

    public LocalDateTime getStartDateTime() {
        return startDateTime;
    }

    public void setStartDateTime(LocalDateTime startDateTime) {
        this.startDateTime = startDateTime;
    }

    public LocalDate getStartDate() {
        return startDate;
    }

    public void setStartDate(LocalDate startDate) {
        this.startDate = startDate;
    }

    public LocalTime getEndTime() {
        return endTime;
    }

    public void setEndTime(LocalTime endTime) {
        this.endTime = endTime;
    }

    public LocalDateTime getEndDateTime() {
        return endDateTime;
    }

    public void setEndDateTime(LocalDateTime endDateTime) {
        this.endDateTime = endDateTime;
    }

    public LocalDate getEndDate() {
        return endDate;
    }

    public void setEndDate(LocalDate endDate) {
        this.endDate = endDate;
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    @Override
    public int hashCode() {
        return id;
    }

    @Override
    public boolean equals(Object obj) {
        if (this == obj) {
            return true;
        }
        if (!(obj instanceof Appointment)) {
            return false;
        }
        Appointment other = (Appointment) obj;
        return id == other.id;
    }

    public String getEnrollmentPeriod() {
        return enrollmentPeriod;
    }

    public void setEnrollmentPeriod(String enrollmentPeriod) {
        this.enrollmentPeriod = enrollmentPeriod;
    }
}
// end::snippet[]
custom-field-basic.tsximport React from 'react';
import { differenceInDays, isAfter, parseISO } from 'date-fns';
import { useForm, useFormPart } from '@vaadin/hilla-react-form';
import { CustomField } from '@vaadin/react-components/CustomField.js';
import { DatePicker } from '@vaadin/react-components/DatePicker.js';
import AppointmentModel from 'Frontend/generated/com/vaadin/demo/domain/AppointmentModel';

function Example() {
  const { model, field } = useForm(AppointmentModel);
  const periodField = useFormPart(model.enrollmentPeriod);

  periodField.addValidator({
    message: 'Dates cannot be more than 30 days apart',
    validate: (enrollmentPeriod: string) => {
      const [from, to] = enrollmentPeriod.split('\t');

      if (from === '' || to === '') {
        return true;
      }

      return differenceInDays(parseISO(to), parseISO(from)) <= 30;
    },
  });

  periodField.addValidator({
    message: 'Start date must be earlier than end date',
    validate: (enrollmentPeriod: string) => {
      const [from, to] = enrollmentPeriod.split('\t');

      if (from === '' || to === '') {
        return true;
      }

      return isAfter(parseISO(to), parseISO(from));
    },
  });

  return (
    // tag::snippet[]
    <CustomField
      label="Enrollment period"
      helperText="Cannot be longer than 30 days"
      required
      {...field(model.enrollmentPeriod)}
    >
      <DatePicker accessibleName="Start date" placeholder="Start date" />
      &ndash;
      <DatePicker accessibleName="End date" placeholder="End date" />
    </CustomField>
    // end::snippet[]
  );
}

custom-field-basic.tsimport '@vaadin/custom-field';
import '@vaadin/date-picker';
import { differenceInDays, isAfter, parseISO } from 'date-fns';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { Binder, field } from '@vaadin/hilla-lit-form';
import AppointmentModel from 'Frontend/generated/com/vaadin/demo/domain/AppointmentModel';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('custom-field-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  private binder = new Binder(this, AppointmentModel);

  protected override firstUpdated() {
    this.binder.for(this.binder.model.enrollmentPeriod).addValidator({
      message: 'Dates cannot be more than 30 days apart',
      validate: (enrollmentPeriod: string) => {
        const [from, to] = enrollmentPeriod.split('\t');

        if (from === '' || to === '') {
          return true;
        }

        return differenceInDays(parseISO(to), parseISO(from)) <= 30;
      },
    });
    this.binder.for(this.binder.model.enrollmentPeriod).addValidator({
      message: 'Start date must be earlier than end date',
      validate: (enrollmentPeriod: string) => {
        const [from, to] = enrollmentPeriod.split('\t');

        if (from === '' || to === '') {
          return true;
        }

        return isAfter(parseISO(to), parseISO(from));
      },
    });
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-custom-field
        label="Enrollment period"
        helper-text="Cannot be longer than 30 days"
        required
        ${field(this.binder.model.enrollmentPeriod)}
      >
        <vaadin-date-picker
          accessible-name="Start date"
          placeholder="Start date"
        ></vaadin-date-picker>
        &ndash;
        <vaadin-date-picker accessible-name="End date" placeholder="End date"></vaadin-date-picker>
      </vaadin-custom-field>
      <!-- end::snippet[] -->
    `;
  }
}

基础用法

Custom Field 已针对以下组件的封装进行了优化：

它还可以用于为自身不带有标签、辅助信息等字段功能的组件（如List Box）提供这些特性。

值类型与格式

Custom Field 值的类型、格式及传播方式在 Java 与 Lit 和 React 中有所不同。以下两个部分解释了如何根据您偏好的编程语言或方法，配置这些内容。

Java

Custom Field 是一个泛型类，可以接受任意类型作为值类型。值类型支持任意类型：字符串（String）、列表（List）、bean 或其他。

指定类型后，您需要建立 Custom Field 的值如何传播到子组件，以及子组件的值如何反过来更新 Custom Field 的值。值传播严重依赖于 Custom Field 所包含的组件、结构以及组件类型。因此，并未提供默认实现，而由 Custom Field 提供两个必须手动实现的方法： generateModelValue 和 setPresentationValue。

generateModelValue 方法负责定义如何从子组件值生成 Custom Field 值。当子组件在客户端触发 DOM 更改事件时，Custom Field 会执行该方法以更新自身值。在此方法中，通常需要收集所有子组件的值，并基于这些值返回一个单一的 Custom Field 类型对象。

setPresentationValue 方法接收一个 Custom Field 值，并定义如何将该值分发至子组件。当 Custom Field 的值在服务端程序变动时，它会触发此方法以更新子组件值。在此方法中，通常需要将给定的值拆分，并分别设置到各个子组件。

以下示例演示了如何设置值传播，使用了一个 bean 作为值类型：

Source code

Javaclass Phone {
    private final String code;
    private final String number;

    public Phone(String code, String number) {
        this.code = code;
        this.number = number;
    }

    public String getCode() {
        return code;
    }

    public String getNumber() {
        return number;
    }
}

class PhoneField extends CustomField<Phone> {
    private final Select code = new Select();
    private final TextField number = new TextField();

    public PhoneField() {
        ...

        add(code, number);
    }

    @Override
    protected Phone generateModelValue() {
        return new Phone(code.getValue(), number.getValue());
    }

    @Override
    protected void setPresentationValue(Phone value) {
        code.setValue(value.getCode());
        number.setValue(value.getNumber());
    }
}

Lit 和 React

Custom Field 只支持字符串值。然而，它提供了对值的格式进行控制的 parser 和 formatter。parser 和 formatter 定义了 Custom Field 的值如何拆分至子组件以及如何由子组件值合并形成整体值。当子组件触发更改事件或者 Custom Field 值被程序修改时, Custom Field 会根据 parser 或 formatter 执行相应的值传播操作。

Parser

当 Custom Field 值被程序修改时，Custom Field 会将该值传递给 parser。parser 应将其转换为子组件值的数组，这些值的顺序应与它们在 DOM 中的呈现顺序一致。Custom Field 聚合这些值，并使用子组件的 value 属性分配它们。

默认的 parser 使用 \t 字符将值拆分为各个子组件的值。

Formatter

当 Custom Field 检测到子组件触发的更改事件时，它收集所有子组件的 value 属性，并按照子组件在 DOM 中的顺序作为一个数组传递给 formatter。formatter 应该将这个数组转换为单个字符串值，Custom Field 随后使用 formatter 返回的字符串更新自身值。

默认的 formatter 使用 \t 字符连接各个子组件的值。

您可以定义自己的 parser 和 formatter 来自定义值的格式，如下所示：

Source code

tsxfunction Example() {
  return (
    // Phone Custom Field
    <CustomField
      formatValue={([code, number]: unknown[]) => (code && number ? [code, number].join('|') : '')}
      parseValue={(value: string) => (value ? value.split('|') : ['', ''])}
    >
      {/* Country code */}
      <Select />

      {/* Phone number */}
      <TextField />
    </CustomField>
  );
}
tsx
tsrender() {
  return html`
    <!-- Phone Custom Field -->
    <vaadin-custom-field
      .formatValue="${([code, number]: unknown[]) => {
        return code && number ? [code, number].join('|') : '';
      }}"
      .parseValue="${(value: string) => {
        return value ? value.split('|') : ['', ''];
      }}"
    >
      <!-- Country code -->
      <vaadin-select></vaadin-select>

      <!-- Phone number -->
      <vaadin-text-field></vaadin-text-field>
    </vaadin-custom-field>
  `
}
ts

原生输入字段

Custom Field 同样可以配合原生 HTML 元素使用。当用于 Custom Field 内部的组件没有外部边距时，可以使用 whitespace 变体，以弥补标签与组件之间缺失的空间。

尺寸变体

可以使用 small 主题变体缩小 Custom Field 的标签、辅助信息及错误信息。Custom Field 不会将其主题变体自动传播至其内部组件，每个内部组件的主题变体都需要单独设置。

CB7FDF39-7653-4DF0-A0C0-9C2A2EE7EDBA

Docs

Docs

Custom Field

基础用法

值类型与格式

Java

Lit 和 React

Parser

Formatter

原生输入字段

尺寸变体