路由 API - CUBA 框架开发者手册

路由注册

要为一个界面注册路由，需要在界面控制器添加 @Route 注解，示例：

@Route("my-screen")
public class MyScreen extends Screen {
}

该注解有三个参数：

path（或 value）是路由本身的值；
parentPrefix 用来做路由压缩（squashing）（参阅以下）。

root 是一个布尔值属性，用来确定一个路由是否是为根界面定义的（比如登录界面或者主界面）。默认值为 false。

如果您创建了一个根界面，实用了非默认 login 的其他路径并且做成了可以不需要登录而通过链接直接访问的界面，您需要为匿名用户启用该界面。否则，当用户输入 URL，比如 /app/#your_root_screen，他们会被重定向到 /app/#login 界面。

在 web-app.properties 文件设置 cuba.web.allowAnonymousAccess = true
为匿名用户启用该界面：启动应用程序，打开 Administration > Roles，然后创建一个新角色并分配该界面的访问权限。然后为 anonymous 用户分配该角色。

如果需要为旧界面定义路由，可以在screens.xml文件中为界面元素添加 route 属性（routeParentPrefix 可选，即对应 parentPrefix 参数；rootRoute 对应 root 参数），示例：

<screen id="myScreen" template="..." route="my-screen" />

路由压缩

此功能目的是为了在打开多个带有相同部分路由的界面时保持 URL 干净易读。举例说明：

对 Order 实体，假设有浏览和编辑界面：

@Route("orders")
public class OrderBrowser extends StandardLookup<Order> {
}

@Route("orders/edit")
public class OrderEditor extends StandardEditor<Order> {
}

在打开浏览界面之后马上打开编辑界面，就能用上 URL 压缩，此时，URL 压缩用来避免 URL 中重复的 orders 路由部分。需要在编辑界面的 @Route 注解中用 parentPrefix 参数指定路由的重复部分：

@Route("orders")
public class OrderBrowser extends StandardLookup<Order> {
}

@Route(value = "orders/edit", parentPrefix = "orders")
public class OrderEditor extends StandardEditor<Order> {
}

现在，当跟浏览界面在同一标签页打开编辑界面时，地址将像这样：app/#main/0/orders/edit?id=…

UI 状态与 URL 的映射

使用 UrlRouting bean 可以根据当前界面和一些参数来更改当前应用程序的 URL。其包含如下方法：

pushState() – 更改地址并添加新的浏览器历史记录；
replaceState() – 替换地址但不添加新的浏览器历史记录；
getState() – 将当前状态作为 NavigationState 对象返回。

pushState()/replaceState() 方法接受当前界面控制器和一组参数（map 形式，可选）为输入参数。

使用 UrlRouting 的示例，请参阅后面部分。

导航过滤

导航过滤器可以用来阻止切换到某些路由。

导航过滤器是实现了 NavigationFilter 接口的 Spring bean。可以使用 @Order 注解来配置所有导航过滤器的调用顺序。常量 NavigationFilter.HIGHEST_PLATFORM_PRECEDENCE 和 NavigationFilter.LOWEST_PLATFORM_PRECEDENCE 用来定义框架中的过滤器优先级范围。

NavigationFilter 接口有 allowed() 方法，可以使用两个输入参数：当前导航状态 fromState 和请求的导航状态 toState。此方法返回 AccessCheckResult 实例并检查是否允许从当前导航状态切换到请求导航状态。

CubaLoginScreenFilter 是一个导航过滤器的例子。设计用来在用户已经登录的情况下，检查当前会话是否已授权能拒绝导航至登录界面：

@Component
@Order(NavigationFilter.LOWEST_PLATFORM_PRECEDENCE)
public class CubaLoginScreenFilter implements NavigationFilter {
    @Inject
    protected Messages messages;

    @Override
    public AccessCheckResult allowed(NavigationState fromState, NavigationState toState) {
        if (!"login".equals(toState.getRoot())) {
            return AccessCheckResult.allowed();
        }
        boolean authenticated = App.getInstance().getConnection().isAuthenticated();
        return authenticated
                ? AccessCheckResult.rejected(messages.getMainMessage("navigation.unableToGoToLogin"))
                : AccessCheckResult.allowed();
    }
}

3.5.13.2. 路由 API