组件 XML 属性

align

定义组件与父容器的相对位置。可能值:

  • TOP_RIGHT

  • TOP_LEFT

  • TOP_CENTER

  • MIDDLE_RIGHT

  • MIDDLE_LEFT

  • MIDDLE_CENTER

  • BOTTOM_RIGHT

  • BOTTOM_LEFT

  • BOTTOM_CENTER

box.expandRatio

vboxhbox 容器中,组件放置在预定义的栏位中。box.expandRatio 属性指定每个栏位的延展比率。比率必须大于等于 0。

<hbox width="500px" expand="button1" spacing="true">
    <button id="button1" box.expandRatio="1"/>
    <button id="button2" width="100%" box.expandRatio="3"/>
    <button id="button3" width="100%" box.expandRatio="2"/>
</hbox>

如果我们为一个组件设置 box.expandRatio=1,并且它的 heightwidth 是 100%(依据布局样式),该组件会被延展至使用组件放置方向的所有可用空间。

默认情况下,所有放置组件的栏位有相等的宽度或高度(即,box.expandRatio = 1)。如果至少有一个组件的该属性设置成别的值,则会忽略所有的隐式值,只考虑设置了的显式值。

也可参阅 expand 属性。

buffered

设置缓存模式。默认模式为非缓存模式(即 false 值)。

在缓存模式下,在调用 commit() 之前,对组件的修改都保存在内部的缓存中。此时如果调用 discard(),会将内部缓存恢复至与数据源一致的值。

在非缓存模式下,读写操作会直接对数据源进行操作。该模式下,commit()discard() 不会起作用。

caption

设置组件标题。

属性值可以是文本或者消息包中的键值。如果是键值,需要以 msg:// 作为前缀。

设置键值有两种方法:

  • 截短键值 - 仅在当前界面的包内搜索消息:

    caption="msg://infoField.caption"
  • 全路径键值:

    caption="msg://com.company.sample.gui.screen/infoField.caption"

captionAsHtml

定义是否启用组件 caption 的 HTML。如果设置 true,标题使用 HTML 在浏览器渲染,开发者需要保证使用无害的 HTML。如果设置 false,标题以纯文本渲染。

可能值:- truefalse。默认为 false

captionProperty

定义组件显示的实体属性的名称。captionProperty 只能用数据容器中的实体(例如,EntityComboBox 组件 optionsContainer 属性定义的数据容器)。

如果 captionProperty 没定义,组件会显示实例名称。

colspan

设置组件应占用的网格列(grid columns),默认为 1。

这个属性可以给任何直接位于 GridLayout 容器中的组件定义列宽。

contextHelpText

设置内容提示文字。设置后,会给组件添加一个特殊的 ? 图标。如果组件有外部的标题,即,设置了 caption 或者 icon 属性,那么这个内容提示的图标会显示在标题旁边,否则会显示在这个控件本身的旁边。当用户光标悬停到内容提示的 ? 图标时,会显示内容提示。

contextHelpTextHtmlEnabled

是否启用 HTML 格式的 内容提示文字

css

为 UI 组件提供声明式的方式来设置 CSS 属性。这个属性可以与 stylename 属性一起使用,示例:

XML 定义:
<cssLayout css="display: grid; grid-gap: 10px; grid-template-columns: 33% 33% 33%"
           stylename="demo"
           width="100%"
           height="100%">
    <label value="A" css="grid-column: 1 / 3; grid-row: 1"/>
    <label value="B" css="grid-column: 3; grid-row: 1 / 3;"/>
    <label value="C" css="grid-column: 1; grid-row: 2;"/>
    <label value="D" css="grid-column: 2; grid-row: 2;"/>
</cssLayout>
附加 CSS:
  .demo > .v-label {
    display: block;
    background-color: #444;
    color: #fff;
    border-radius: 5px;
    padding: 20px;
    font-size: 150%;
  }

dataContainer

在界面的 XML 描述中的 data 部分定义一个数据容器。

当设置 dataContainer 属性为 实体实例容器 的时候,property 属性也需要同时设置。

dataLoader

为界面 XML 描述的 data 部分定义的数据容器设置一个数据加载器。

datatype

为组件的内容设置一个 数据类型。可能值:

  • boolean

  • byteArray

  • date

  • dateTime

  • decimal

  • double

  • int

  • localDate

  • localDateTime

  • localTime

  • long

  • offsetDateTime

  • offsetTime

  • string

  • time

  • uuid

description

当用户光标悬停或者点击一个组件的区域的时候,在弹出框显示组件的描述信息。

descriptionAsHtml

定义是否在组件的描述中启用 HTML。如果设置为 true,描述在浏览器中使用 HTML 做渲染,开发者需要保证使用无害的 HTML。如果设置为 false,内容将会按照普通文本显示。

可能值:- truefalse。默认为 false

editable

设置组件的内容是否可编辑(不要跟 enable 混淆)。

可能值:- truefalse。默认为 true

安全子系统也会影响绑定至数据组件的编辑能力。如果安全子系统示意这个组件不能编辑,那么 editable 属性的值会被忽略。

enable

定义组件的启用/禁用状态。

如果一个组件被禁用,那么这个组件将不能操作。禁用一个容器会禁用容器内的所有组件。可能值:truefalse。默认所有组件都是启用的。

expand

定义容器内的组件是否可以按照组件放置的方向延展占用位置至所有可用的空间。

对于垂直布局的容器,这个属性会设置组件的高度为 100%;对于水平布局的容器,则是 100% 宽度。还有,重新设置容器的大小也会影响到自动延展的组件。

参阅 box.expandRatio

height

设置组件的高度。可以用像素(pixels)或者父容器的高度的百分比。例如,100px100%50。如果数字没有单位,默认是用像素。

按照 % 来设置值表示组件会占用父容器可用空间的相应比例的高度。

当设置成 AUTO 或者 -1px 的时候,组件的高度会使用默认值。对于容器来说,默认的高度是由内容定义的:也就是所有内部组件的高度之和。

htmlSanitizerEnabled

定义是否开启组件内容的 HTML 清理(captiondescriptioncontextHelpText 属性)。如果 htmlSanitizerEnabled 设置为 true,且开启 HTML 功能的属性(captionAsHtmldescriptionAsHtmlcontextHelpTextHtmlEnabled)也设置为 true,此时,captiondescriptioncontextHelpText 属性的内容会被清理。

htmlSanitizerEnabled 会覆盖全局的 jmix.ui.component.htmlSanitizerEnabled 配置。

icon

设置组件图标。

这个属性的值需要指定相对于 主题 文件夹的一个图标路径:

icon="icons/create.png"

或者 图标集 里面的图标名称:

icon="CREATE_ACTION"

如果希望根据用户的语言显示不同的图标,可以在消息包里面配置图标的路径,然后在 icon 属性指定这个消息的键名,示例:

icon="msg://addIcon"

可以用 Font Awesome 的字体元素来替代图标文件。在 icon 属性中定义所需要的图标名称,名称可以从 com.vaadin.server.FontAwesome 类的常量中找到,然后用 font-icon: 前缀来设置,示例:

icon="font-icon:BOOK"

参阅 Icons 章节了解使用图标的更多细节。

id

设置组件的标识符。

推荐使用 Java 标识符的规则和驼峰命名法来给组件创建标识符,例如:userGridfilterPanel。任何组件都可以使用 id 属性,需要保证在一个界面中的组件标识符是唯一的。

inputPrompt

定义示例文本或者问题,提示用户如何做或者如何输入内容。

<comboBox id="iconComboBox"
          inputPrompt="Select a file type"/>
input prompt

该属性用在 TextFieldComboBox 中。

由于 ComboBox 有固定的选项列表,可以用 请选择…​ 这样的提示。对于文本输入组件来说,提示信息通常以用户动作开头:请输入搜索;以需要输入的名词结尾,例如,请输入城市名搜索地址 等。

metaClass

如果没有声明式的定义 dataContainer 属性,则用 metaClass 定义表格的列类型。在 XML 中定义 metaClass 属性与设置 DataGridGroupTableTableTreeDataGridTreeTable 为空表格的效果一样,因此需要在界面控制器用编程的方式设置表格内容。

optionsContainer

设置一个数据容器的名称,这个容器包含一个选项列表。组件展示实体的 实例名称

captionProperty 属性可以与 optionsContainer 同时使用。

optionsEnum

设置一个含有选项列表的 枚举 类名称。

property

设置实体属性的名称,这个属性会在这个组件用来编辑和显示。

property 属性总是和 dataContainer 属性一起使用。

required

表示是这个组件必须有值。

可能值:- truefalse。默认为 false

可以和 requiredMessage 属性一起使用。

requiredIndicatorVisible

设置是否为组件显示一个指示符,表名该组件是必需的。

可能值:- truefalse。默认为 false

requiredMessage

required 一起使用。这个属性设置一个消息,当组件没有值的时候会弹出这个消息提示。

该属性可以设置消息或者消息包的键值,示例:

requiredMessage="msg://infoTextField.requiredMessage"

responsive

设置组件是否可以根据可用的空间的大小自动适应。可以通过 样式 来定制自适应的方式。

可能值:- truefalse。默认为 false

rowspan

设置组件占据的网格行数,默认是 1。

这个属性可以给直接位于 GridLayout 容器内的任何组件使用。

stylename

为组件定义样式名。参阅 See 主题 了解详情。

halo 主题中,有一些为组件预定义的 CSS 类名称:

  • huge - 设置组件大小为默认值的 160%

  • large - 设置组件大小为默认值的 120%

  • small - 设置组件大小为默认值的 85%

  • tiny - 设置组件大小为默认值的 75%

tabIndex

定义组件是否可以获得焦点,同时也可以设置组件在界面上所有可获得焦点组件内部的顺序值。

可以使用正负整数:

  • 负值 表示组件可以获得焦点,但是不能被顺序的键盘导航访问到;

  • 0 表示组件可以获得焦点,也可以被顺序的键盘访问访问到;但是它的访问顺序是由它在界面中的相对位置来定;

  • 正值 表示组件可以获得焦点,也可以被顺序的键盘导航访问到;它被访问的相对顺序是通过这个属性的值来定义的:按照 tabIndex 升序来访问。如果几个组件有相同的 tabIndex 值,它们的相对访问顺序由它们在界面的相对位置来确定。

visible

设置组件是否可见。可能值:- truefalse

如果容器被设置成不可见,那么里面的所有组件也不可见。默认所有组件都是可见。

width

定义组件的宽度。

可以用像素(pixels)或者父容器的宽度的百分比。比如 100px100%50。如果数字没有单位,默认是用像素。按照 % 来设置值表示组件会占用父容器可用空间的相应比例的宽度。

当设置成 AUTO 或者 -1px 的时候,组件的宽度会使用默认值。对于容器来说,默认的宽度是由内容定义的,也就是所有内部组件的宽度之和。