urlQueryParameters

urlQueryParameters facet 用来声明式地将视图状态绑定至 URL。支持在不同的视图之间导航或者刷新浏览器网页时保留视图状态。

如果整个视图状态来自数据库（例如，实体详情视图），URL 路由中的实体 id 已经足够用来恢复视图状态。但是如果某些视图组件包含了非数据库信息，那么需要将这些信息编码至 URL 中，以便重新初始化该视图时能恢复数据。

实体列表的分页和过滤就是一个很好的例子。当刷新浏览器网页或者从详情视图返回时，我们希望保留分页和过滤参数。

将视图状态在 URL 中编码也能提供一个深度链接（deep link），表达视图展示的内容。

基本用法

如需将分页和过滤参数绑定至 URL，定义 urlQueryParameters 并使用内部元素将已有的组件与它们的 id 关联。下面的示例演示了 urlQueryParameters facet 与 genericFilter 和 simplePagination 使用：

<facets>
    <urlQueryParameters id="urlQueryParameters">
        <pagination component="pagination"/>
        <genericFilter component="genericFilter"/>
    </urlQueryParameters>
</facets>
<layout expand="usersTable">
    <genericFilter id="genericFilter"
                   dataLoader="usersDl">
        <properties include=".*"/>
    </genericFilter>
    <hbox id="buttonsPanel" classNames="buttons-panel">
        <!-- ... -->
        <simplePagination id="pagination" dataLoader="usersDl"/>
    </hbox>

结果是，当使用 active 属性对 User 实体进行过滤并选择第二页时，URL 将变成类似这样：

http://localhost:8080/users?genericFilterCondition=property%3Aactive_equal_true&maxResults=50&firstResult=100

在 Jmix Studio 可以使用 Jmix UI 组件属性面板查看和编辑 facet 属性。

支持的组件

pagination

pagination 内部元素支持将 urlQueryParameters facet 与 simplePagination 简单分页器组件连接。

pagination 元素的属性：

component - 所连接分页组件的 id。
firstResultParam -（可选）表示当前页开始的 URL 查询参数。
maxResultsParam -（可选）表示页面数据大小的 URL 查询参数。

propertyFilter

pagination 内部元素支持将 urlQueryParameters facet 与 propertyFilter 属性过滤器组件连接。

propertyFilter 元素的属性：

component - 所连接 propertyFilter 组件的 id。
param -（可选）表示过滤器值的 URL 查询参数。

genericFilter

pagination 内部元素支持将 urlQueryParameters facet 与 genericFilter 组件连接。

genericFilter 元素的属性：

component - 所连接 genericFilter 组件的 id。
conditionParam -（可选）表示过滤器条件的 URL 查询参数。
configurationParam -（可选）表示所选过滤器配置的 URL 查询参数。

dataGridFilter

dataGridFilter 元素支持将表头过滤器的状态与 URL 绑定。

以下示例中，所有列都可过滤，并将其过滤器状态绑定到 URL：

<urlQueryParameters>
    <dataGridFilter component="usersDataGrid"/>
</urlQueryParameters>
<dataGrid id="usersDataGrid"
          width="100%"
          minHeight="20em"
          dataContainer="usersDc">
    <columns filterable="true">
        <column property="username"/>
        <column property="firstName"/>
        <column property="lastName"/>
        <column property="email"/>
        <column property="active"/>
    </columns>
</dataGrid>

当用户应用或清除表头过滤器时，URL 会更新。打开 URL 或刷新页面会恢复每个过滤器的操作和值。

dataGridFilter 元素的属性：

component - 需要绑定表头过滤器和 URL 的 dataGrid 组件的标识符。
param - （可选）表示已应用表头过滤器的查询参数名称。默认情况下，是组件标识符后跟 Filter，例如 customersDataGridFilter。

groupDataGridFilter

Jmix 3.1+

groupDataGridFilter 嵌套元素支持将 groupDataGrid 表头过滤器的状态与 URL 绑定。该元素由分组表格扩展组件提供，因此需要使用为 groupDataGrid 声明的 groupg 命名空间。

以下示例中，所有列都可过滤，并将其过滤器状态绑定到 URL：

<urlQueryParameters>
    <groupg:groupDataGridFilter component="customersDataGrid"/>
</urlQueryParameters>
<groupg:groupDataGrid id="customersDataGrid"
                      width="100%"
                      minHeight="20em"
                      dataContainer="customersDc">
    <groupg:groupBy>
        <groupg:columnRef key="grade"/>
    </groupg:groupBy>
    <groupg:columns filterable="true">
        <groupg:groupColumn header="Grade"/>
        <groupg:column property="firstName"/>
        <groupg:column property="lastName"/>
        <groupg:column property="email"/>
        <groupg:column property="country"/>
        <groupg:column property="grade"/>
    </groupg:columns>
</groupg:groupDataGrid>

当用户应用或清除表头过滤器时，URL 会更新。打开该 URL 或刷新页面会恢复每个过滤器的操作和值。序列化格式与 dataGridFilter 相同，因此 URL 可以在等效的 dataGrid 和 groupDataGrid 配置之间复用。

groupDataGridFilter 元素的属性：

component - 需要绑定表头过滤器和 URL 的 groupDataGrid 组件的标识符。
param - （可选）用于表示已应用表头过滤器的查询参数名称。默认情况下，是组件标识符后跟 Filter，例如 customersGroupDataGridFilter。

自定义状态绑定

urlQueryParameters facet 还支持在 URL 绑定任何自定义视图状态。

我们看下面的视图示例：

<details id="sampleDetails" summaryText="Some details">
    <textField id="sampleTextField" datatype="string"/>
</details>

假设目标是保留 details 详情面板布局的 opened 状态以及 textField 文本框的值。

我们需要实现一个 binder 对象，并在 urlQueryParameters facet 内注册：

private static final String DETAILS_OPENED_URL_PARAM = "detailsOpened";
private static final String TEXT_URL_PARAM = "text";

@ViewComponent
private UrlQueryParametersFacet urlQueryParameters;

@ViewComponent
private JmixDetails sampleDetails;

@ViewComponent
private TypedTextField<String> sampleTextField;

private class SampleUrlQueryParametersBinder extends AbstractUrlQueryParametersBinder { (1)

    public SampleUrlQueryParametersBinder() { (2)
        sampleDetails.addOpenedChangeListener(event -> {
            boolean opened = event.isOpened();
            QueryParameters qp = new QueryParameters(ImmutableMap.of(DETAILS_OPENED_URL_PARAM,
                    opened ? Collections.singletonList("1") : Collections.emptyList()));
            fireQueryParametersChanged(new UrlQueryParametersFacet.UrlQueryParametersChangeEvent(this, qp));
        });

        sampleTextField.addValueChangeListener(event -> {
            String text = event.getValue();
            QueryParameters qp = new QueryParameters(ImmutableMap.of(TEXT_URL_PARAM,
                    text != null ? Collections.singletonList(text) : Collections.emptyList()));
            fireQueryParametersChanged(new UrlQueryParametersFacet.UrlQueryParametersChangeEvent(this, qp));
        });
    }

    @Override
    public void updateState(QueryParameters queryParameters) { (3)
        List<String> detailsOpenedStrings = queryParameters.getParameters().get(DETAILS_OPENED_URL_PARAM);
        if (detailsOpenedStrings != null) {
            sampleDetails.setOpened("1".equals(detailsOpenedStrings.get(0)));
        }

        List<String> textStrings = queryParameters.getParameters().get(TEXT_URL_PARAM);
        if (textStrings != null && !textStrings.isEmpty()) {
            sampleTextField.setValue(textStrings.get(0));
        }
    }

    @Override
    public Component getComponent() {
        return null;
    }
}

@Subscribe
public void onInit(final InitEvent event) {
    urlQueryParameters.registerBinder(new SampleUrlQueryParametersBinder()); (4)
}

1	- 从 `AbstractUrlQueryParametersBinder` 基类派生 binder 类。
2	- 在 binder 的构造器中，添加组件的监听器，当组件的状态变化时，会调用 `fireQueryParametersChanged()` 方法。
3	- 在 `updateState()` 方法中，更新组件的状态。
4	- 创建一个 binder 实例，并在视图初始化的时候在 `urlQueryParameters` facet 内注册。

urlQueryParameters facet 使用 Vaadin API 的 QueryParameters 类收发查询参数。

本页是否有帮助？

感谢您的反馈

出错啦~