界面和界面片段（Fragments） - 根界面 - 《CUBA 框架开发者手册 Version 7.2》

3.5.1.6. 根界面

3.5.1.6. 根界面

根界面是一个通用 UI 界面，直接展示在 web 浏览器的标签页中。有两种类型的这种界面：登录界面和主界面。其它的组件中，任何根界面都可以包含 WorkArea 组件，这样使得可以在内部的标签页中打开其它的应用程序界面。如果根界面不包含 WorkArea，应用程序界面只能以 DIALOG 模式打开。

登录界面

登录界面是在用户登录之前展示的界面。可以通过扩展框架提供的登录界面或者创建全新的登录界面对该界面进行自定义。

如果要扩展已有的界面，在 Studio 界面创建向导中使用 Login screen 模板。Studio 会帮助创建一个扩展了标准登录界面的界面。该界面会替代标准的登录界面，因为它在 @UiController 注解中使用了相同的 login 标识符。

如果想从头创建一个新的界面，可以使用 Blank screen 模板。一个极简的登录界面源码差不多是这样：

my-login-screen.xml

<window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd"
        caption="Login"
        messagesPack="com.company.sample.web">
    <layout>
        <label value="Hello World"/>
        <button id="loginBtn" caption="Login"/>
    </layout>
</window>

MyLoginScreen.java

package com.company.sample.web;
import com.haulmont.cuba.gui.Route;
import com.haulmont.cuba.gui.components.Button;
import com.haulmont.cuba.gui.screen.*;
import com.haulmont.cuba.security.auth.LoginPasswordCredentials;
import com.haulmont.cuba.web.App;
@UiController("myLogin")
@UiDescriptor("my-login-screen.xml")
@Route(path = "login", root = true)
public class MyLoginScreen extends Screen {
    @Subscribe("loginBtn")
    private void onLoginBtnClick(Button.ClickEvent event) {
        App.getInstance().getConnection().login(
                new LoginPasswordCredentials("admin", "admin"));
    }
}

为了使用这个界面替代系统默认的界面，需要在 web-app.properties 文件中将 cuba.web.loginScreenId 配置项设置为该界面的 id。

cuba.web.loginScreenId = myLogin

当然，也可以直接将新界面的 id 设置为 login，就不需要修改这个配置了。

主界面

主界面是用户登录之后看到的应用程序的根界面。默认情况下，框架使用带侧边菜单的主界面。

Studio 有一些创建自定义主界面的模板，这些模板都使用相同的 MainScreen 类作为控制器的基类。

Main screen with side menu 创建标准主界面的扩展，并使用 main id。带有侧边菜单的主界面，默认可以使用左下角的 Collapse 按钮展开或者收起侧边菜单。

可以使用 SCSS 变量自定义侧边菜单的行为（在创建了主题扩展或者自定义主题后，可以用可视化编辑器修改这些变量。）：
- $cuba-sidemenu-layout-collapse-enabled 启用或禁用侧边菜单收起模式。默认为 true。
- $cuba-sidemenu-layout-collapsed-width 指定收起后侧边菜单的宽度。
- $cuba-sidemenu-layout-expanded-width 指定展开后侧边菜单的宽度。
- $cuba-sidemenu-layout-collapse-animation-time 指定侧边菜单展开收起的动画时间。
  
  当 $cuba-sidemenu-layout-collapse-enabled 变量设置为 false 时，会隐藏 Collapse 按钮，侧边菜单呈展开状态。

Main screen with responsive side menu 创建一个类似的界面，但是侧边菜单是响应式的，能在窄的显示环境中自动收起。该界面会带有自己生成的 id，因此，必须在 web-app.properties 里面进行注册：
```
cuba.web.mainScreenId = respSideMenuMainScreen
```
Main screen with top menu 创建一个带有顶部菜单栏的界面，并且能在左侧显示文件夹面板。该界面会带有自己生成的 id，因此，必须在 web-app.properties 里面进行注册：
```
cuba.web.mainScreenId = topMenuMainScreen
```

除了标准 UI 组件之外，下面这些特殊的组件也可以用在主界面：

SideMenu - 应用程序菜单，以垂直树的形势展示。
AppMenu – 应用程序菜单栏。
AppWorkArea – 工作区，如果需要以 THIS_TAB、NEW_TAB 和 NEW_WINDOW 模式打开界面，则需要该组件。
FoldersPane – 应用程序和搜索文件夹的面板。
UserIndicator – 显示当前用户的控件，也包括选择替代用户的功能。

使用 setUserNameFormatter() 方法可以设置不同于 User 实例名称的用户名称展示：
```
userIndicator.setUserNameFormatter(value -> value.getName() + " - [" + value.getEmail() + "]");
```
NewWindowButton – 在单独的浏览器标签页打开新主界面的按钮。

UserActionsButton – 如果用户会话没有认证，显示登录界面的链接。否则，显示一个菜单：用户设置界面的链接和登出操作。

可以在主界面控制器装载 LoginHandler 或 LogoutHandler 以实现自定义逻辑：

@Install(to = "userActionsButton", subject = "loginHandler")
private void loginHandler(UserActionsButton.LoginHandlerContext ctx) {
    // do custom logic
}
@Install(to = "userActionsButton", subject = "logoutHandler")
private void logoutHandler(UserActionsButton.LogoutHandlerContext ctx) {
    // do custom logic
}

LogoutButton – 应用程序登出按钮。
TimeZoneIndicator – 显示当前用户时区的标签。
FtsField – 全文搜索控件。

下列应用程序属性可能影响主界面：

cuba.web.appWindowMode – 设置主窗口的默认模式：标签页式的还是单独界面式（TABBED 或 SINGLE）。用户可以使用 UserActionsButton 提供的 Settings - 设置 界面进行修改。
cuba.web.maxTabCount – 当主界面在标签页式时，使用该属性设置用户能打开的标签页最多个数。默认值为 7。
cuba.web.foldersPaneEnabled - 为使用 Main screen with top menu 模板创建的界面启用显示文件夹面板。
cuba.web.defaultScreenId - 设置主窗口自动打开的默认界面。
cuba.web.defaultScreenCanBeClosed - 定义用户是否可以关闭默认界面。
cuba.web.useDeviceWidthForViewport - 处理 viewport 宽度。如果需要使用设备的宽度作为 viewport 宽度，设置为 true。cuba.web.pageInitialScale 属性也可以参考设置。