twinColumn 双列

twinColumn 支持用户在候选列和已选列之间移动条目。

XML 元素

twinColumn

Java 类

TwinColumn

基本用法

在线示例

该组件中的两列并排放置。左列包含用户可以选择的条目。右列显示当前已选定的条目。用户可以选择一个或多个条目，然后点击按钮在两列中移动条目进行选择或移除。

在 XML 中使用 twinColumn 创建双列组件，设置 itemsContainer 属性为一个 集合容器。容器内的条目将展示在列中。

下面的示例展示双列的基本用法：

<data readOnly="true">
    <instance id="productDc"
              class="io.jmix.uisamples.entity.Product"
              fetchPlan="_local">
    </instance>
    <collection id="productTagsDc"
                class="io.jmix.uisamples.entity.ProductTag"
                fetchPlan="_local">
        <loader id="productTagsDl" readOnly="true">
            <query>
                <![CDATA[select e from ProductTag e order by e.name]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
    <twinColumn id="twinColumn" label="Tags" itemsColumnLabel="Available tags"
                selectedItemsColumnLabel="Selected tags" itemsContainer="productTagsDc"
                dataContainer="productDc" property="tags"/>

数据感知的 twinColumn

在线示例

数据绑定是指将组件与 数据容器 进行关联。可视化组件或相应数据容器中的更改可以触发彼此的更新。有关详细信息，请参阅 使用数据组件。

如需创建关联数据的 twinColumn，请使用 dataContainer 和 property 属性。itemsContainer 属性用于创建选项列表。

XML
<data readOnly="true">
    <instance id="productDc"
              class="io.jmix.uisamples.entity.Product"
              fetchPlan="_local">
    </instance>
    <collection id="productTagsDc"
                class="io.jmix.uisamples.entity.ProductTag"
                fetchPlan="_local">
        <loader id="productTagsDl" readOnly="true">
            <query>
                <![CDATA[select e from ProductTag e order by e.name]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
    <twinColumn id="twinColumn" label="Tags" itemsColumnLabel="Available tags"
                selectedItemsColumnLabel="Selected tags" itemsContainer="productTagsDc"
                dataContainer="productDc" property="tags"/>
Java
@ViewComponent
protected InstanceContainer<Product> productDc;
@ViewComponent
protected Span spanValue;

@Autowired
protected Metadata metadata;

@Subscribe
protected void onInit(InitEvent event) {
    Product product = metadata.create(Product.class);
    productDc.setItem(product);
}

@Subscribe("twinColumn")
protected void onTwinColumnValueChange(ComponentValueChangeEvent<TwinColumn<Product>, Product> event) {
    if (productDc.getItem().getTags() == null) {
        return;
    }

    spanValue.setText(getSelectedTagsInstanceName());
}

protected String getSelectedTagsInstanceName() {
    return productDc.getItem().getTags()
            .stream()
            .map(ProductTag::getInstanceName)
            .collect(Collectors.joining(", "));
}

多选

在线示例

twinColumn 组件默认是多选模式，用户可以选择并移动多个条目。还可以支持移动所有条目，需要设置 selectAllButtonsVisible 属性：

@ViewComponent
protected TwinColumn<String> twinColumn;
@Subscribe("selectAllButtonsCheckbox")
public void onSelectAllButtonsCheckboxValueChange(ComponentValueChangeEvent<JmixCheckbox, Boolean> event) {
    twinColumn.setSelectAllButtonsVisible(event.getValue());
}

列标签

在线示例

如需设置列标签，请使用 itemsColumnLabel 和 selectedItemsColumnLabel 属性：

<twinColumn id="twinColumn" label="Shopping list" itemsColumnLabel="Need to buy"
            selectedItemsColumnLabel="Purchased"/>

条目顺序

在线示例

默认情况下，条目在移动之后不会保留原来的顺序。条目每次移到另一列时，会自动添加到列的底部。可以通过设置 reorderable = "true" 属性保留原始顺序。

@ViewComponent
protected TwinColumn<String> twinColumn;
@Subscribe("reorderableCheckbox")
public void onReorderableCheckboxValueChange(ComponentValueChangeEvent<JmixCheckbox, Boolean> event) {
    twinColumn.setReorderable(event.getValue());
}

自定义选项

在线示例

可以使用列表、键值对 Map 或枚举填充 twinColumn。

XML
<twinColumn id="twinColumnWithList"
            label="Items List"/>
<twinColumn id="twinColumnWithMap"
            label="Items Map"/>
<twinColumn id="twinColumnWithEnum"
            label="Items Enum"/>
Java
@ViewComponent
protected TwinColumn<Integer> twinColumnWithList;
@ViewComponent
protected TwinColumn<Integer> twinColumnWithMap;
@ViewComponent
protected TwinColumn<CustomerGrade> twinColumnWithEnum;

@Subscribe
protected void onInit(InitEvent event) {
    twinColumnWithList.setItems(getItemsList());
    ComponentUtils.setItemsMap(twinColumnWithMap, getItemsMap());
    twinColumnWithEnum.setItems(CustomerGrade.class);
}

protected List<Integer> getItemsList() {
    return List.of(2, 4, 5, 7);
}

protected Map<Integer, String> getItemsMap() {
    Map<Integer, String> itemsMap = new LinkedHashMap<>();
    itemsMap.put(2, "Two");
    itemsMap.put(4, "Four");
    itemsMap.put(5, "Five");
    itemsMap.put(7, "Seven");
    return itemsMap;
}

样式版本

在线示例

使用 themeNames 属性配置一个或多个样式。

样式 描述 支持的主题

no-border

不显示组件的边框

Aura, Lumo

no-row-border

不显示行分隔符

Lumo

checkmarks

用对钩表示选择的条目，而非修改背景色。

Lumo

no-spaces-between-actions

不显示操作按钮之间的空隙

Aura, Lumo

XML 属性

下面是 twinColumn 的特殊属性：

名称 描述 默认值

itemsColumnLabel

设置选项列的标签。参考 列标签。

—

itemsContainer

设置选项的数据容器。参考基本用法。

—

reorderable

用户是否可以调整组件中选项的顺序。参考 条目顺序。

—

selectAllButtonsVisible

是否显示全选和全部清除的按钮。参考 多选。

—

selectedItemsColumnLabel

设置已选项列的标签。参考 列标签。

—

下面是 twinColumn 支持的其他通用属性：

id - alignSelf - ariaLabel - ariaLabelledBy - classNames - colspan - css - dataContainer - enabled - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - property - readOnly - required - requiredMessage - themeNames - visible - width

事件和处理器

下面是 twinColumn 的特殊事件和处理器：

名称 描述

validator

验证组件值。

下面是 twinColumn 支持的其他通用事件：

AttachEvent - ComponentValueChangeEvent - DetachEvent

XML 内部元素

一个 twinColumn 可以包含 validator 作为其内部元素。