用途:本技能用于在 Vaadin 25 Flow(Java)中指导代理构建表单并实现稳健校验,当用户要求创建表单、绑定数据对象或处理校验时使用。
主要能力:
- Binder 基础:将实现 HasValue 的组件(TextField、ComboBox、DatePicker、Checkbox 等)绑定到表单数据对象(Java bean、record 或 DTO),负责读写值、类型转换与多层级校验。
- 两种模式:缓冲模式用 readBean 填充、writeBeanIfValid 写回,适合带保存/取消的表单;直写模式用 setBean,字段变更立即写入,适合设置面板或简单筛选。
- 绑定:推荐显式绑定 binder.forField(...).asRequired().withValidator(...).withConverter(...).bind(Getter, Setter),链式顺序即执行顺序;也可用简写 binder.bind(...)。若 bean 使用 Jakarta 校验注解(@NotEmpty、@Max、@Email 等),可用 BeanValidationBinder 并通过 bindInstanceFields 自动绑定。
- 转换器:字段类型与属性类型不一致时用 withConverter,转换失败会作为校验错误显示;可配合领域基元模式实现类型安全。
- 校验层级:必填 asRequired;绑定级单字段校验(内置 StringLengthValidator、EmailValidator、RegexpValidator、数值/日期范围校验器等,或自定义 Validator 与 lambda);组件默认校验器可用 withDefaultValidator(false) 关闭;Binder 级跨字段校验用 binder.withValidator。
- 触发与错误处理:绑定级校验在值变更时自动运行;可调用 binder.validate()、isValid()、writeBeanIfValid()。绑定级错误自动显示在字段旁,Binder 级错误需 setStatusLabel 指定显示区域。
- 布局与封装:字段放入 FormLayout 自动响应式排版(详见 vaadin-form-layout 技能);建议用继承 Composite<FormLayout> 的类封装 Binder、字段与数据对象,对外暴露 setFormDataObject / getFormDataObject。
使用方式:不确定 API 细节时用 Vaadin MCP 工具(search_vaadin_docs、get_component_java_api)查询,并设 vaadin_version 为 "25"、ui_language 为 "java";查 Javadoc 与源码用 javadoc MCP。
适用场景与限制:适用于 Vaadin 25 Flow Java 表单开发。资料未提及其他版本兼容性、收费或价格信息;完整内置校验器列表、转换器模式与表单模板见 references/form-patterns.md。