组件 XML 属性

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

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

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

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

也可参阅 expand 属性。

设置缓存模式。默认模式为非缓存模式（即 false 值）。

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

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

设置组件标题。

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

设置键值有两种方法：

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

可能值：- true、false。默认为 false。

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

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

设置组件应占用的网格列（grid columns），默认为 1。

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

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

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

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

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

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

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

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

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

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

可能值：- true、false。默认为 false。

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

可能值：- true、false。默认为 true。

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

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

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

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

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

参阅 box.expandRatio。

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

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

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

定义是否开启组件内容的 HTML 清理（caption、description、contextHelpText 属性）。如果 htmlSanitizerEnabled 设置为 true，且开启 HTML 功能的属性（captionAsHtml、descriptionAsHtml、contextHelpTextHtmlEnabled）也设置为 true，此时，caption，description 和 contextHelpText 属性的内容会被清理。

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

设置组件图标。

如需通过 Jmix Studio 设置 icon 值，可以在 Component Inspector 中选择 icon 属性，然后打开 选择图标 对话框进行设置。

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

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

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

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

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

设置组件的标识符。

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

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

该属性用在 TextField、ComboBox 中。

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

定义外部边界和容器内容之间的距离。可以有两种类型的值：

默认不启用边距。

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

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

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

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

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

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

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

可能值：- true、false。默认为 false。

可以和 requiredMessage 属性一起使用。

如果 容器 中至少有一个组件的 required 属性设置为 true，并且 requiredIndicatorVisible="true"，则会在容器的右上角显示“必需”的图标。

可能值：- true、false。默认为 false。

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

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

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

可能值：- true、false。默认为 false。

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

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

设置容器中组件之间的空白。

可能值：- true、false。默认为 false。

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

在 halo 主题中，有一些为组件预定义的 CSS 类名称：

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

可以使用正负整数：

设置组件是否可见。可能值：- true、false。

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

定义组件的宽度。

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

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