可视化组件库 - 组件的 XML 属性 - 《CUBA 框架开发者手册 Version 7.0》

3.5.2.6. 组件的 XML 属性

3.5.2.6. 组件的 XML 属性

align - 对齐: 定义组件跟父容器的相对位置，可选值有：

-
TOP_RIGHT

-
TOP_LEFT

-
TOP_CENTER

-
MIDDLE_RIGHT

-
MIDDLE_LEFT

-
MIDDLE_CENTER

-
BOTTOM_RIGHT

-
BOTTOM_LEFT

-
BOTTOM_CENTER

box.expandRatio - 箱式占比率

设置放置在 vbox 或者 hbox 内组件的延伸比率，也可参考 expand 属性。比率值需大于等于 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>

caption - 标题

设置组件的标题

这个属性的值可以是一段文本，或者消息包里的一个消息键名。如果是用的消息键名，那么这个值需要以 msg:// 前缀开头。

有两种方式设置键名：

-
短键名 – 这种情况下，只在当前界面的消息包中搜索这个键名：

caption="msg://infoFieldCaption"

-
包含包名的长键名：

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

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

可选值 − true 、 false。默认值 false。

captionProperty - 属性名称: 定义组件显示的实体属性的名称。captionProperty 只能用在关联了数据源的实体（比如，LookupField 组件的关联 optionsDatasource 数据源的属性）。

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

colspan - 占列数目: 设置组件应占用的网格（grid columns）列数，默认是 1

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

contextHelpText - 内容提示文字

设置内容提示文字，如果设置了，那么一个特别的 ? 图标会添加在组件里。如果组件有外部的标题，比如设置了 caption 或者 icon 属性，那么这个内容提示的图标会显示在标题旁边，否则会显示在这个控件本身的旁边：

在 web 客户端当用户光标悬浮到内容提示的 ? 图标时，会显示内容提示。

<textField id="textField"
           contextHelpText="msg://contextHelp"/>

contextHelpTextHtmlEnabled - 是否启用 HTML 格式内容提示

定义内容提示是否可以通过 HTML 格式显示。

<textField id="textField"
           description="Description"
           contextHelpText="<p><h1>Lorem ipsum dolor</h1> sit amet, <b>consectetur</b> adipiscing elit.</p><p>Donec a lobortis nisl.</p>"
           contextHelpTextHtmlEnabled="true"/>

可选值： true 、 false.

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 部分定义一个数据容器。

datasource - 数据源: 在 XML 描述的 dsContext 段定义一个数据源。

当给实现了 DatasourceComponent 接口的组件设置 datasource 属性的时候，property 属性也需要同时设置。

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

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

可选值 − true 、false。默认值 false。

editable - 是否可编辑: 标明这个组件的内容是否可编辑（不要跟 enable 混淆）

可选值： true 、 false。默认值 true。

是否能编辑绑定数据的组件（继承了 DatasourceComponent 或者 ListComponent）的内容也收到 security subsystem 的影响。如果安全子系统示意这个组件不能编辑，那么 editable 属性的值会被忽略。

enable - 是否启用: 定义组件的启用/禁用状态。

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

expand - 延展: 定义容器内的组件是否可以按照组件放置的方向延展占用位置至所有可用的空间。对于垂直布局的容器，这个属性会设置组件的高度（height）到 100%；对于水平布局的容器，则是 100%宽度（width）。还有，重新设置容器的大小也会影响到自动延展的组件。参考 box.expandRatio。

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

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

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

icon - 图标

设置组件的图标

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

icon="icons/create.png"

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

icon="CREATE_ACTION"

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

icon="msg://addIcon"

在用了 Halo 主题（或者继承了这个主题）的 web 客户端，可以用 Font Awesome 来替代图标文件。在 icon 属性中定义所需要的图标名称，名称可以从 com.vaadin.server.FontAwesome 类的常量中找到，然后用 font-icon: 前缀来设置，比如：

icon="font-icon:BOOK"

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

id - 组件标识符: 设置组件的标识符。

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

inputPrompt - 输入提示

定义当组件的值是 null 的时候在这个组件显示的文字。

<suggestionField inputPrompt="Let's search something!"/>

这个属性只能在 TextField 、LookupField 、 LookupPickerField 、 SearchPickerField 、 SuggestionPickerField 这些组件中使用，并且只支持 web 客户端。

margin - 边距: 定义组件的外边框和容器内容之间的留白。

可以有两种形式的值设置：

-
margin="true" − 给所有方向都加了边距。

-
margin="true,false,true,false" − 只给上下两边加了边距（值格式是：“上，右，下，左”）。

默认情况下没有边距设置。

nullName - null 名称

选择 nullName 属性定义的名称相当于设置组件的值为 null。换言之，nullName 就是组件 null 选项的显示名称。

这个属性可以在 LookupField 、 LookupPickerField 和 SearchPickerField 组件使用。

在 XML 描述内设置这个属性的值：

<lookupField datasource="orderDs"
             property="customer"
             nullName="(none)"
             optionsDatasource="customersDs" width="200px"/>

在控制器中设置这个属性的值：

<lookupField id="customerLookupField" optionsDatasource="customersDs"
             width="200px" datasource="orderDs" property="customer"/>

customerLookupField.setNullOption("<null>");

openType - 界面打开类型: 定义一个界面要以什么方式打开。对应 WindowManager.OpenType 枚举类型的值： NEW_TAB 、 THIS_TAB 、 NEW_WINDOW 、 DIALOG 。默认是THIS_TAB.

optionsContainer - 选项容器: 设置一个数据容器的名称，这个容器包含一个选项列表。

captionProperty 属性可以跟 optionsContainer 一起使用。

optionsDatasource - 选项数据源: 设置包含一个选项列表的数据源。

captionProperty 属性可以跟 optionsDatasource 一起使用。

optionsEnum - 选项枚举类型: 设置一个含有选项列表的枚举类名称，一个枚举值就是一个选项。

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

property 属性总是和数据源属性一起使用。

required - 必须有值: 表示是这个字段必须要有值。

可选值： true 、 false。默认是 false。

可以和 requiredMessage 属性一起使用。

requiredMessage - 必须有值提醒: 总是跟 required 一起使用。这个属性设置一个消息，当组件没有值的时候会弹出这个消息提示。

这个属性也可以用消息包的键名，比如： requiredMessage="msg://infoTextField.requiredMessage"

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

可选值：true 、 false。默认值 false。

rowspan - 占用行数: 设置组件占据的网格行数（grid lines），默认是 1。

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

settingsEnabled - 设置开启: 定义用户是否可以保存/恢复对组件的设置。只有组件有 id，才能保存组件的设置。

可选值：true 、 false。默认值 true。

spacing - 留白: 设置容器内组件之间是否留白。

可选值：true 、 false。默认值 false。

stylename - 样式名称: 定义组件的 CSS 类名称，更多细节，参考主题。

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

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

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

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

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

tabCaptionsAsHtml - 标签名称是否 HTML 格式: 定义标签的标题是否可以用 HTML。如果设置成 true，标题在浏览器里会以 HTML 的方式渲染，开发者需要保证没有使用有害的 HTML。如果设置成 false，内容会按照纯文本来渲染。

可选值：true 、 false。默认值 false。

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

可以使用正负整数：

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

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

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

tabsVisible - 标签可见: 设置在标签页面板中是否显示标签选择部分。

可选值：true 、 false。默认值 true。

textSelectionEnabled - 文本选择启用: 定义在表格单元格中是否能选择文本。

可选值：true 、 false。默认值 false。

visible - 组件是否可见: 设置组件是否可见。

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

可选值：true 、 false。默认值 true。

width - 组件宽度: 定义组件的宽度

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

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

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