文本字段小组件 (可应用主题)
文本字段小组件是通常在表单中使用的输入元素。通过使用文本字段，可使得用户能够在混搭中键入文本。可使用 Text 属性设置或检索字段内的文本。与“文本区域”小组件不同，“文本字段”限制为单行。除常用的小组件属性外，您还可以使用属性通过以下方式来配置小组件：
• 配置最大字符数并添加计数器。
• 将文本用作数据服务、函数和其他小组件的输入。
• 在未设置值的情况下显示提示文本。
• 添加清除文本按钮。
• 启用只读模式。
• 隐藏敏感信息 (如密码) 的输入。
• 定义掩码模式以确保输入使用特定格式。
 |
“文本字段”小组件可在平台中用作标准小组件，也可用作 web 组件 (可从 Web Component SDK 导入)。
|
当小组件值在运行时更新时，可以使用以下小组件事件执行数据服务或函数：
• EnterKeyPressed - 按下 ENTER 键时触发。
• FocusLost - 单击小组件之外的区域或按下 TAB 键时触发。
使用事件
“文本字段”小组件会触发两个可绑定事件：
• Changed - 添加或移除字符时触发。
• EnterKeyPressed - 用户按 Enter 键时触发。
您可以使用小组件事件来触发小组件内的函数、数据服务或服务。例如，您可以将事件绑定到“验证器”函数，以在键入或按 Enter 键时验证输入。
启用只读模式
您可以启用 ReadOnly 属性，以防止在运行时对文本进行更改。例如，您可以使用此属性防止进行更改，除非启用切换按钮或在混搭中选择复选框。启用只读时，可以选择和复制文本，但不能编辑、剪切或删除当前值。要更改只读文本字段的文本值，请在设计时输入 Text 属性的值。也可以将数据源绑定到属性，以在运行时更改文本值。
设置字符数限制
可通过以下方式之一将文本字段中的输入限制为特定数量的字符：
• 将 MaxNumberOfCharacters 属性设置为任意数值。默认情况下，文本字段最多可支持 100 个字符。
• 使用 Mask 属性定义掩码模式。模式中的特殊字符数用于设置字符限制。
向文本字段添加计数器
要添加计数器以显示文本字段中的字符数，请将 Counter 属性设置为 True。MaxNumberOfCharacters 属性用于设置字符限制，包括空格。下图显示了一个具有可见计数器且最大字符数为 10 的文本字段小组件：
达到字符限制后，计数器颜色会发生更改：
添加“清除文本”按钮
您可以启用 ShowClearText 属性以将文本按钮添加到小组件的输入框中。当输入字段包含值时，该按钮会自动出现在小组件的右侧。这可使得用户快速移除小组件内的任何现有文本。
添加图标
可使用 Icon 属性在文本字段中显示图标。图标会自动显示在小组件的左侧。可从平台提供的 SVG 图标中选择一个图标。有关这些图标的详细信息，请参阅使用 SVG 图标。
配置文本字段输入模式
可使用 Mask 属性指定数字、字母以及字母数字字符的输入模式。定义模式时，系统会在输入框中添加占位符指引线。指引线是指用于指示用户可在文本字段中键入的文本模式的线。除了必要模式外，该属性还可以设置文本字段中的字符数。可使用以下特殊字符创建模式：
• a - 字母
• 9 - 数字
• * - 字母数字
要创建模式，请将特殊字符组合到表示所需输入的字符串中。例如，以下模式表示不同类型的输入：
• 9999 - 四位数
• ***** - 五个字母数字字符
• 99–aa - 一个两位数，后跟一个分隔符破折号和两个字母字符。
下图显示了在运行时包含 4 个 3 位数的 999–999–999–999 数字模式的指引线：
除了数字位数外，模式还可用于设置数字格式。在本示例中，您可以键入任意 12 位数字，如：256120233234。键入时，下划线 (_) 指引线将被数字替换。
指示符指引线根据您在设计时在模式内设置的字符总数进行显示。键入的数字位数少于模式数时，输入将保持未完成状态。您应该使用掩码来定义具有特定字符数的模式，例如电话号码或邮政编码。输入非特定数量的字符 (如货币金额) 时，请避免使用掩码。
| | 您可以使用不同类型的符号 (如句点、破折号、斜杠等) 作为字符之间的分隔符。 |
| | “文本字段”小组件可在平台中用作标准小组件，也可用作 web 组件 (可从 SDK 导入)。 |
下面列出了“文本字段”小组件的属性。
属性名称 | 说明 | 基本类型 | 默认值 | 是否可绑定? (Y/N) | 是否可本地化? (Y/N) | ||
|---|---|---|---|---|---|---|---|
Text | 文本字段中显示的文本。 | STRING | 不可用 | Y | Y | ||
Label | 文本字段的标签中显示的文本。 | STRING | 不可用 | Y | Y | ||
Counter | 计算并显示文本字段中输入的字符数。 | BOOLEAN | False | N | N | ||
MaxNumberOfCharacters | 用于设置文本字段中的最大字符数。 | NUMBER | 100 | Y | N | ||
HintText | 显示用于说明字段中应输入内容的占位符文本。 | STRING | 不适用 | N | Y | ||
Disabled | 使用此属性可以禁用混搭中的小组件。小组件会显示在混搭中，但无法单击。 | BOOLEAN | False | Y | N | ||
ReadOnly | 用于将文本字段设置为只读，从而使得用户无法编辑文本。 | BOOLEAN | False | N | N | ||
Password | 用于隐藏文本字段条目。 | BOOLEAN | False | N | N | ||
ShowClearText | 用于在文本字段中添加“清除”按钮，用户可在单击该按钮后清除运行时字段中的文本。 | BOOLEAN | True | N | N | ||
LabelAlignment | 可用于靠左、靠右或居中对齐标签。 | STRING | 左 | N | N | ||
TextAlignment | 用于在字段左侧或右侧对齐文本。 | STRING | 左 | N | N | ||
Mask | 用于在文本字段中设置预定义字符。在属性配置字段中，"a" 代表字母，"9" 代表数字，"*" 代表字母数字。 | STRING | 不适用 | N | N | ||
TabSequence | 当用户按下 Tab 键时，内容将在其中突出显示的小组件序列。 | NUMBER | 不可用 | N | N | ||
CustomClass | 用于定义要应用于小组件顶层 div 的 CSS 类。可以输入多个类，以空格作为分隔符。 | STRING | 不可用 | Y | N | ||
EnterKeyPressed | 在编辑文本值期间，按下 ENTER 键将触发的事件。
| 不适用 | 不适用 | Y | N | ||
FocusLost | 用户在编辑文本值期间，通过按下 TAB 键或单击小组件之外的区域来更改焦点时将触发的事件。
| 不适用 | 不适用 | Y | N | ||
Changed | 修改此小组件的数据时所触发的事件。 | 不适用 | 不适用 | Y | N | ||
ResetToDefaultValue | 将此小组件的输入重置为其默认值。 | 不适用 | 不适用 | Y | N | ||
Width | 小组件宽度。 | NUMBER | 273 | N | N | ||
Height | 小组件高度。默认情况下将自动计算此值。如果在文本字段中包括标签，则高度会增加。 | NUMBER | 自动大小 | N | N | ||
TooltipField | 设置当您将光标悬停在小组件上时显示的工具提示文本。 | STRING | 不可用 | Y | Y | ||
TooltipIcon | 设置小组件工具提示的图标图像。 可添加图像或指定图像 URL 路径。 | MEDIA ENTITY | 不适用 | N | N | ||
Icon | 用于指定：文本框的显示图标。 | SVG 图标列表 | 不适用 | N | N |
验证小组件数据
除常用属性外，还可使用 MaxLength 和 MinLength 验证属性来验证文本字段小组件内的字符数。
可使用 MaxLengthFailureMessage 和 MinLengthFailureMessage 属性自定义默认失败消息。使用 ${value} 参数在消息中显示最大值和最小值。
有关使用常用验证属性的详细信息，请参阅将验证应用于小组件。
下表列出了 ThingWorx 9.3.4 或更高版本中“验证”面板上提供的验证属性。
属性 | 说明 | 基本类型 | 默认值 | 是否可绑定 (Y/N) | 是否可本地化 (Y/N) |
|---|---|---|---|---|---|
CriteriaMessage | 有关验证条件以及验证失败时显示的消息。 | STRING | 不可用 | Y | Y |
CriteriaMessageDetails | 针对验证条件和失败消息显示的详细信息。 | STRING | 不可用 | Y | Y |
MaxLength | 文本字段值的最大长度。 | STRING | 不可用 | Y | N |
MaxLengthFailureMessage | 当前值超出最大字符长度时显示的消息。 | STRING | ${value} characters is the maximum | Y | Y |
MinLength | 文本字段值的最小长度。 | STRING | 不可用 | Y | N |
MinLengthFailureMessage | 当前值低于最小字符长度时显示的消息。 | STRING | ${value} characters is the minimum | Y | Y |
RequiredMessage | 必需值设置为 true 且未选择任何项时显示的消息。 | STRING | 必需提供值 | Y | Y |
ShowValidationCriteria | 编辑文本字段时显示有关所需输入的提示消息。 | BOOLEAN | False | Y | N |
ShowValidationFailure | 当输入的值验证失败时，显示失败消息。 | BOOLEAN | False | Y | N |
ShowValidationSuccess | 当输入的值验证成功时，显示成功消息。 | BOOLEAN | False | Y | N |
SuccessMessage | 验证成功时显示的消息。 | STRING | 不可用 | Y | Y |
SuccessMessageDetails | 二级消息，显示关于验证成功消息的更多信息。 | STRING | 不可用 | Y | Y |
Validate | 更改小组件值时触发的可绑定事件。将此事件绑定至服务或函数以应用验证模式或表达式。 | 事件 | 不可用 | Y | N |
ValidationCriteriaIcon | 针对关于验证条件的提示消息，设置在其中显示的 SVG 图标。 | IMAGELINK | info | N | N |
ValidationFailureIcon | 设置验证失败时显示在状况消息中的 SVG 图标。 | IMAGELINK | error | N | N |
ValidationOutput | 检索小组件验证的输出。返回值为 Undefined、Valid、Unvalidated 或 Invalid。 | STRING | 不可用 | Y | N |
ValidationState | 用于设置验证状态的可绑定属性。可将此属性设置为 Undefined、Unvalidated、Valid 或 Invalid。 | STRING | Undefined | Y | N |
ValidationSuccessIcon | 选择验证成功时显示在状态消息中的 SVG 图标。 | IMAGELINK | success | N | N |
ValueRequired | 需要选择列表内的其中一项。 | BOOLEAN | False | Y | N |