textField 文本框

textField 是一个输入控件，用于编辑文本或其他支持的类型值。

XML 元素

textField

Java 类

TypedTextField

基本用法

在线示例

下面的示例定义了一个标准的文本字段和一个最大输入长度受限的字段：

<textField id="textField" label="TextField"/>
<textField id="textLengthField" label="MaxLength = 10" maxLength="10"/>

不同的数据类型

在线示例

textField 是一个带类型的组件，即可以支持输入不同类型的内容。具体的数据类型可以通过与特定类型的实体属性 绑定 或通过 datatype 属性设置。

<textField id="stringTextField" label="String"
           datatype="string"/>
<textField id="integerTextField" label="Integer"
           datatype="int"/>
<textField id="doubleTextField" label="Double"
           datatype="double"/>

组件提供了处理带类型值的方法：setTypedValue() 和 getTypedValue()。这些方法可以用来设置或读取特定类型的值，例如 Integer 或 Long 等。

当处理组件值变化事件时，建议使用 TypedValueChangeEvent，而不要使用 ComponentValueChangeEvent。这样可以确保拿到的值是正确的类型避免额外的数据类型转换或检查。

数据感知的 textField

在线示例

如需将 textField 与数据连接，请使用 dataContainer 和 property 属性。

XML
<data>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"
              fetchPlan="_local"/>
</data>
<layout>
    <textField id="textField" label="Name"
               dataContainer="customerDc" property="name"/>
    <hbox>
        <span text="Value in the container:"/>
        <span id="spanValue"/>
    </hbox>
</layout>
Java
@ViewComponent
protected InstanceContainer<Customer> customerDc;
@ViewComponent
protected Span spanValue;

@Autowired
protected Metadata metadata;

@Subscribe
protected void onInit(InitEvent event) {
    Customer customer = metadata.create(Customer.class);
    customer.setName("John");
    customerDc.setItem(customer);
}

@Subscribe("textField")
protected void onTextFieldValueChange(TypedValueChangeEvent<TypedTextField<String>, String> changeEvent) {
    spanValue.setText(customerDc.getItem().getName());
}

上面的示例中，视图为 Department 实体定义了 departmentDc 数据容器，其中包含 name 属性。textField 组件通过 dataContainer 属性与数据容器进行连接，同时 property 属性包含了在 textField 中展示的实体属性名称。

值变更模式

在线示例

使用 valueChangeMode 和 valueChangeTimeout 控制当用户输入内容时，如何更新服务器端的值。示例中还使用值变更事件处理器在用户输入时更新帮助文本。

XML
<details summaryText="Default value change" opened="true" width="AUTO">
    <textField id="textField" placeholder="Start typing"/>
</details>
<details summaryText="Custom value change" opened="true" width="50%">
    <vbox padding="false">
        <textField id="valueChangeModeTextField" maxLength="140" helperText="0/140"/>
        <radioButtonGroup id="valueChangeModeRadioButtonGroup" label="ValueChangeMode"/>
    </vbox>
</details>
Java
@ViewComponent
protected TypedTextField<String> valueChangeModeTextField;
@ViewComponent
protected JmixRadioButtonGroup<ValueChangeMode> valueChangeModeRadioButtonGroup;

@Autowired
protected Notifications notifications;

@Subscribe
protected void onInit(InitEvent event) {
    ComponentUtils.setItemsMap(valueChangeModeRadioButtonGroup, getValueChangeModeItemsMap());
    valueChangeModeRadioButtonGroup.setValue(ValueChangeMode.ON_CHANGE);
}

@Subscribe("valueChangeModeRadioButtonGroup")
protected void onValueChangeModeRadioButtonValueChange(
        ComponentValueChangeEvent<JmixRadioButtonGroup<ValueChangeMode>, ValueChangeMode> event) {
    valueChangeModeTextField.setValueChangeMode(event.getValue());
}

@Subscribe("textField")
protected void onTextFieldValueChange(TypedValueChangeEvent<TypedTextField<String>, String> event) {
    notifications.show("Text Changed: " + event.getValue());
}

@Subscribe("valueChangeModeTextField")
protected void onValueChangeModeTextFieldValueChange(TypedValueChangeEvent<TypedTextField<String>, String> event) {
    TypedTextField<String> sourceTextField = event.getSource();
    sourceTextField.setHelperText(Strings.nullToEmpty(event.getValue()).length() + "/" + sourceTextField.getMaxLength());
}

protected Map<ValueChangeMode, String> getValueChangeModeItemsMap() {
    return Arrays.stream(ValueChangeMode.values())
            .collect(Collectors.toMap(Function.identity(), mode -> mode.name().replace('_', ' ')));
}

验证

在线示例

添加内部的验证器检查字段值。下面的示例使用了内置的数值范围验证器和一个自定义的验证器。

XML
<textField id="integerTextField" label="Positive TextField"
           helperText="Value must be positive"
           datatype="int">
    <validators>
        <custom bean="uisamples_PositiveIntegerValidator"/>
    </validators>
</textField>
<textField id="doubleTextField" label="Double range validator"
           helperText="Value must be between 1.0 and 100.0"
           datatype="double">
    <validators>
        <doubleMin value="1.0" inclusive="true"/>
        <doubleMax value="100.0" inclusive="true"/>
    </validators>
</textField>
Java
@Override
public void accept(Integer value) {
    if (value != null) {
        if (value <= 0) {
            fireValidationException(
                    messages.getMessage("validation.constraints.positive"),
                    ParamsMap.of("value", value)
            );
        }
    }
}

样式版本

使用 themeNames 属性配置一个或多个样式。

样式 描述 支持的主题

align-left

字段值左对齐。

Aura, Lumo

align-center

字段值居中对齐。

Aura, Lumo

align-right

字段值右对齐。

Aura, Lumo

align-start

根据当前文本方向，将字段值向起始侧对齐。

Aura

align-end

根据当前文本方向，将字段值向末尾侧对齐。

Aura

helper-above-field

帮助文字显示在字段上方，标题下方。

Aura, Lumo

small

组件更小。

Aura, Lumo

XML 属性

下面是 textField 的特殊属性：

名称 描述 默认值

autoselect

当设置为 true 时，如果组件获得了焦点，将自动选中组件的值。

—

clearButtonVisible

设置是否显示清除按钮。

false

trimEnabled

如果为 true，则组件会删除输入字符串的开头和结尾的空格。在使用 EAGER、LAZY 或 TIMEOUT valueChangeMode 时，需考虑与 trimEnabled 的相互作用。

—

value

设置组件的值。

—

下面是 textField 支持的其他通用属性：

id - alignSelf - allowedCharPattern - ariaLabel - ariaLabelledBy - autocapitalize - autocomplete - autocorrect - autofocus - classNames - colspan - css - dataContainer - datatype - enabled - errorMessage - focusShortcut - height - helperText - label - maxHeight - maxLength - maxWidth - minHeight - minLength - minWidth - pattern - placeholder - property - readOnly - required - requiredMessage - themeNames - title - valueChangeMode - valueChangeTimeout - visible - width

事件和处理器

下面是 textField 的特殊事件和处理器：

名称 描述

validator

验证组件值。

下面是 textField 支持的其他通用事件：

AttachEvent - BlurEvent - ClientValidatedEvent - ComponentValueChangeEvent - CompositionEndEvent - CompositionStartEvent - CompositionUpdateEvent - DetachEvent - FocusEvent - InputEvent - KeyDownEvent - KeyPressEvent - KeyUpEvent - statusChangeHandler - TypedValueChangeEvent

XML 内部元素

一个 textField 可以包含 tooltip、validator、prefix 和 suffix 作为其内部元素。

参考