TextField 文本框

TextField - 文本框 是用于文本编辑的组件，可以用于处理实体属性，也可用于输入/显示任何文本信息。

组件的 XML 名称：textField。

基本用法

示例：

<textField id="nameField"
           caption="Name"/>

如需创建关联至数据的 TextField，可以用 XML 的 dataContainer 和 property 属性：

<data>
    <instance id="customerDc" class="ui.ex1.entity.Customer">
        <loader/>
    </instance>
</data>

<layout>
    <vbox margin="true" spacing="true">
    <textField dataContainer="customerDc"
               property="firstName"
               caption="Name"/>
</layout>

如上所示，界面描述中为具有 firstName 属性的 Customer 定义了数据容器 customerDc。TextField 通过 dataContainer 属性连接到数据容器，property 属性设置为要显示在 TextField 中的实体属性的名称。

属性

datatype

如果文本框没有连接到任何实体属性（即，未设置数据容器和属性名称），可以使用 datatype 属性设置数据类型。数据类型用来格式化控件值。datatype 属性值可以是应用程序元数据中注册的任何数据类型。

通常，TextField 使用下面的数据类型：

decimal
double
int
long

<textField id="integerField"
           datatype="int"
           caption="Integer field"/>

maxLength

如果 TextField 连接到实体属性（通过 dataContainer 和 property），并且实体属性具有定义在 @Column JPA 注解中的 length 参数，那么 TextField 将相应地限制输入文本的最大长度。

如果 TextField 未链接到属性，或者属性未定义 length 值，或者需要覆盖此值，则可以使用 maxLength 属性限制输入文本的最大长度。值 "-1" 表示没有限制。示例：

<textField id="shortTextField"
           maxLength="10"/>

trim

默认情况下，TextField 会截去字符串的前后空格。例如，用户输入 " aaa bbb "，则 getValue() 方法返回并保存到连接实体属性的控件值将为 "aaa bbb"。可以将 trim 属性设置为 false 来禁用此功能。

请注意，去除空格仅在用户输入新值时起作用。如果连接属性的值中已包含空格，则将显示空格，直到用户编辑该值。

<textField id="trimField"
           caption="Trimmed field"
           trim="false"/>

TextField 始终返回 null 而不是输入的空字符串。因此，启用 trim 属性后，任何只包含空格的字符串都将转换为 null。

htmlName

文本输入在 HTML 中以 input 组件展示，htmlName 用于设置 input 的 name 属性值。

转换

大小写转换

TextField 支持自动大小写转换。caseConversion 属性包含下列取值：

UPPER - 转换为大写。
LOWER - 转换为小写。
NONE - 不转换（默认值）。用这个选项来支持在输入法连续输入（比如，在输入中文、日文、韩文的时候）。

数据类型转换

如果用户输入了一个无法通过数据类型解析的值，则会显示默认的转换错误消息。

下面是一个数据类型是 Integer 的 TextField：

<textField id="integerField"
           datatype="int"
           caption="Integer field"/>

如果用户输入的字符不能解析为整数，应用程序将显示默认的错误消息。

默认的错误消息可以按照错误消息转换章节介绍的方法在项目中进行全局定义。

可以在界面 XML 描述中声明式的定义自己的类型转换错误消息，使用 conversionErrorMessage 属性，示例：

<textField id="textField"
           conversionErrorMessage="This field can work only with Integers"
           datatype="int"
           caption="Integer field"/>

或者在界面控制器中通过编程的方式创建：

@Autowired
private TextField<Integer> textField;

@Subscribe
protected void onInit(InitEvent initEvent) {
    textField.setConversionErrorMessage("This field can work only with Integers");
}

验证

如需验证 TextField 组件的值，可以在内部的 validators 元素使用 validator。

TextField 可以使用下列预定义的 validators：

下面例子中，我们演示 textValidField 如何使用 NegativeValidator：

<textField id="textValidField"
           datatype="int">
    <validators>
        <negative/>
    </validators>
</textField>

样式

可以在界面 XML 或者控制器中使用 stylename 属性为 TextField 组件设置预定义样式：

<textField stylename="borderless"
           caption="Borderless field"/>

@Autowired
private TextField<String> styledField;

@Subscribe
protected void onInit(InitEvent initEvent) {
    styledField.setStyleName("align-center");
}

align-center - 使文本在文本框中居中显示。
align-right - 使文本在文本框中居右显示。
borderless - 删除文本框的边框和背景。
inline-icon - 使图标显示在文本框里面。

方法

使用 setCursorPosition() 方法可使控件获得焦点并将光标位置设置为指定索引位置，索引位置从 0 开始。

事件和处理器

如需使用 Jmix Studio 生成处理器的桩代码，需要在界面 XML 描述或者 Jmix UI 层级结构面板选中该组件，然后用 Jmix UI 组件面板的 Handlers 标签页生成。

或者可以使用界面控制器顶部面板的 Generate Handler 按钮。

ContextHelpIconClickEvent

参阅 ContextHelpIconClickEvent。

EnterPressEvent

参阅 EnterPressEvent。

格式化器

为组件添加 formatter 实例。

下面示例中，我们演示为 customerField 文本框使用 formatter：

@Install(to = "customerField", subject = "formatter")
protected String customerFieldFormatter(String value) {
    return value.toUpperCase();
}

如需以编程的方式添加 formatter，使用组件的 addFormatter() 方法。

TextChangeEvent

TextChangeEvent 当用户在组件内输入一些内容时发送。事件会在输入时异步发送，防止阻塞用户输入。

@Autowired
private Label<String> shortTextLabel;
@Autowired
private TextField<String> shortTextField;

@Subscribe("shortTextField")
public void onShortTextFieldTextChange(TextInputField.TextChangeEvent event) {
    int length = event.getText().length();
    shortTextLabel.setValue(length + " of " + shortTextField.getMaxLength());
}

如需以编程的方式注册事件处理器，使用组件的 addTextChangeListener() 方法。

TextChangeEventMode 定义文本的变化被发送到服务器并触发服务端事件的方式。有 3 种预定义的事件模式：

LAZY（默认）- 文件输入暂停时触发事件。暂停时间可以通过 setInputEventTimeout() 修改。
TIMEOUT - 一定时间超时后触发事件。可以使用 setInputEventTimeout() 设置超时时长。
EAGER - 对于文本内容的每次更改，都会立即触发事件，通常是由按键触发。
BLUR - 文本控件失去焦点时，发送事件。

textChangeTimeout 属性可以修改当 TextChangeEventMode 是 LAZY 或 TIMEOUT 时，事件与应用程序沟通的频率。

编程式用法，调用组件的 setTextChangeEventMode() 方法。

@Autowired
private TextField<String> shortTextField;

@Subscribe
protected void onInit(InitEvent initEvent) {
    shortTextField.setTextChangeEventMode(TextInputField.TextChangeEventMode.LAZY);
}

Validator

为组件添加 validator 实例。如果值验证失败，validator 必须抛出 ValidationException 异常。

如果预定义的验证器不能满足要求，可以添加自定义的验证器实例：

@Install(to = "zipField", subject = "validator")
protected void zipFieldValidator(Integer value) {
    if (value != null && String.valueOf(value).length() != 6)
        throw new ValidationException("Zip must be of 6 digits length");
}

ValueChangeEvent

参阅 ValueChangeEvent。

TextField XML 属性

可以使用 Studio 界面设计器的 Jmix UI 组件面板查看和编辑组件的属性。

align - buffered - caseConversion - caption - captionAsHtml - colspan - contextHelpText - contextHelpTextHtmlEnabled - conversionErrorMessage - css - dataContainer - dataType - description - descriptionAsHtml - editable - enable - box.expandRatio - height - htmlSanitizerEnabled - htmlName - icon - id - inputPrompt - maxLength - property - required - requiredMessage - responsive - rowspan - stylename - tabIndex - textChangeEventMode - textChangeTimeout - trim - visible - width

TextField XML 元素

formatter - validators

本页是否有帮助?

感谢您的反馈

出问题啦~