5. Studio 功能 - 5.4. 通用 UI - 《Studio 用户指南 version 7.0》

5.4. 通用 UI

5.4. 通用 UI

Studio 提供了许多有助于在应用程序中使用通用 UI 的功能。

在项目树中，可以看到 Generic UI 的以下元素：

Web Menu 打开主菜单的图形编辑界面。
Main Message Pack 部分包含主菜单项和通用 UI 元素的消息。
Screens 部分显示已有的应用程序界面。
Themes 用于管理应用程序的可视化展现。

5.4.1. 创建和移除界面

要创建新的 Generic UI 界面，请在项目树中选择 Generic UI，然后在右键菜单中选择 New > Screen。如果要为实体创建 CRUD 界面，请在项目树中选择此实体或其中一个视图，然后在右键菜单中点击 New > Screen ：

Studio 将显示可用模板的列表。该列表分为两部分：Screen Templates 和 Legacy Screen Templates。前者包含框架版本 7 以上可用于新界面 API 的模板，而后者包含也可用于版本 6 的界面模板。

如果为在项目树中选中的实体或视图创建界面，则 Entity 和 Entity view 字段会自动填充：

Advanced 部分允许修改自动生成的界面描述和控制器名称以及界面 ID。当某个实体有多个界面时，这很有用。

单击 Finish 时，将创建并打开界面 XML 描述和 Java 控制器文件。对于没有使用 UiDescriptor 和/或 @UiController 注解的旧版界面，其界面描述被注册在 web-screens.xml 文件中。

移除界面文件时，使用 Safe delete 选项查找并清理对这个界面的引用：

对界面的一些引用会被自动删除，比如在 web-menu.xml 和 web-screens.xml 文件中对界面的引用。如果存在对界面的引用，将会弹出一个对话框显示这些引用。点击对话框上的 View Usages 按钮, 可在 Find 工具窗口中查看这些引用，这时可以根据情况点击 Cancel 或 Do Refactor 按钮：

5.4.2. 使用界面描述

界面描述编辑器底部包含两个选项卡：Text 和 Designer。在 Text 选项卡上，可以直接编辑 XML，而 Designer 选项卡包含一个界面布局的可视化编辑器。

可以使用代码编辑器边栏上的标记从界面描述切换到相应的界面控制器，或者在项目树中选择界面描述，然后单击右键菜单中的 Go to controller。

Studio 会检查界面布局是否存在错误和不一致，并且检查内部和外部引用。出现下列情况，会用警告或高亮显示 XML 元素的方式进行提醒：

由于 XML 错误，无法组装界面布局。
组件属性路径和名称与应用程序数据模型不对应。
组件大小冲突： width 、 height 和 expand 属性值的冲突。
dataContainer 和 dataLoader 属性没有引用任何现有的数据容器或数据加载器。
form 中的字段没有显式定义 property XML 属性：此时，id 将被隐式地用作 property。
form 元素语义错误：字段重复或位于 column 元素之外。
gridLayout 中的列数与指定的数字不匹配。
在扩展界面中出现重复的元素属性，比如父界面和扩展界面中同时定义了完全一样的属性时。
扩展界面中的元素的命名与父界面中不同，或者放置位置不正确。
messagesPack 属性指定的值不是一个有效的包，这个包要至少包含一个 messages_xx.properties 文件。
过时的 XSD 引用。
id 值在界面内不是唯一的。

可以在 Settings 窗口中配置检查器（CUBA > Settings > Editor > Inspections）。

Studio 也能加速界面组件的开发。使用 Alt+Insert (Cmd+N) 快捷键打开特定 UI 和数据组件的相关功能。比如，需要在 Form 组件添加一个新字段，可以将光标移动到 form 元素内然后按照下面的方式之一添加字段：

按下 Alt+Insert (Cmd+N)，选择 Add field，然后选择属性和字段标签，

输入 field 然后按下 TAB 键，然后选择属性和字段标签。

Designer 选项卡显示可视化设计器，允许以 WYSIWYG 方式开发界面布局和设置 UI 组件属性。

设计界面工作区分为四个面板：

Canvas 是工作区，可以在其中按所需的布局排列组件。可以使用控制工具调整组件的大小和对齐：

水平扩展，
垂直扩展，
垂直/水平对齐组件。

Palette 面板显示可用的界面组件集合：

容器；
组件；
数据组件：容器和加载器;
非可视化组件：操作、对话框模式设置、计时器。

要将组件添加到布局，请将其从组件面板(palette)拖放到画布或组件树(hierarchy)面板上。

Hierarchy 面板显示添加到布局的组件树。可以使用拖放重新排列树的元素，因为有时这比在画布(Canvas)上执行相同操作更方便。可以使用右键菜单来删除、复制、剪切或粘贴组件树中的元素。
Properties 面板显示可视化组件的属性。

5.4.3. 使用界面控制器

本节介绍 Studio 为界面控制器提供的功能。

利用源码编辑器的边栏图标可以快速切换到相应的 XML 描述文件、定位到注入组件的 XML 定义以及其它导航功能。

依赖注入

依赖注入是在界面控制器代码中获取对可视化组件和 API 端点(api endpoint)的引用的主要方式。当然，也可以编写所需类型的字段并手动进行注解。但是 Studio 提供了一个专用的窗口，这个窗口允许从列表中选择一个对象并自动创建合适的字段。按下 Alt+Insert（Cmd+N）键，在弹出的 Generate 菜单中选择 Inject…，就会打开这个窗口：

以下对象可以被注入到控制器中：

界面 XML 描述中定义的可视化组件和数据组件，
界面 API 接口，
基础设施接口，
中间层服务，
配置接口。

事件处理

通过创建事件处理程序，可以在界面生命周期的各个点执行代码并对用户操作做出响应。处理程序是一个用 @Subscribe 注解的控制器方法，使用事件作为输入参数。按下 Alt+Insert（Cmd+N）键，在弹出的 Generate 菜单中选择 Subscribe to Event，就可以在 Studio 中创建此类方法：

每个事件在窗口右侧都提供了描述，这个描述是从事件的 Javadoc 中提取的。

打开的窗口中提供以下事件：

表示界面生命周期的控制器事件。
可对按钮点击、表格选择、操作等做出响应的组件事件。
表示此界面的外部框架的生命周期的框架事件(Frame Events)。
允许对数据上下文更改做出响应，并在数据提交之前和之后执行代码的数据上下文事件。
允许接收有关数据容器和实体状态更改通知的数据容器事件。

委托

使用委托，可以为各种界面机制提供代码来代替其标准实现。例如，可以提供自己的函数来提交数据或选择表格行的图标。

委托是具有特定签名的控制器方法，并使用 @Install 进行注解。按下 Alt+Insert（Cmd+N）键，在弹出的 Generate 菜单中选择 Install Delegate，就可以在 Studio 中创建此类方法：

每个事件都在窗口右边提供了描述，该描述是从框架的 Javadocs 中提取的。

5.4.4. 使用应用程序菜单

菜单设计器允许定义应用程序主菜单并将其存储在 web-menu.xml 配置文件中。Structure 选项卡显示图形设计器，可以在 Text 选项卡上编辑菜单的 XML 代码。

菜单可以以两种模式创建：

在 Single mode 中，菜单仅包含当前项目的 web-menu.xml 文件中的菜单项。在这种情况下，需要创建所有菜单项，必要时还需要将应用程序组件中的菜单项也定义进来，这种方式有点麻烦，但好处是可以完全控制菜单结构。
在 Composite mode 中，菜单除了包含当前项目的 web-menu.xml 中的菜单项，还包含所有应用程序组件的菜单配置文件中的菜单项。这种模式可以很方便地包含所有继承的菜单项，可以在菜单结构的任何位置插入当前项目需要的菜单项。继承的菜单项不能被修改。

此外，在 Text 选项卡上，可以为菜单项定义 insertBefore 或 insertAfter 属性。这两个属性定义了当前菜单项的插入位置。在 Composite 模式下，这两个属性有助于将当前项目菜单项与继承的应用程序组件菜单项组合在一起。

例如，如果要将当前项目的菜单结构放在 Administration 菜单项的左侧，可以为当前项目的菜单树的根菜单项设置属性 insertBefore="administration"。

菜单配置文件列表通过 cuba.menuConfig 应用程序属性定义，选择菜单模式时会更新此属性。

要添加菜单项，选择已有的菜单项（或配置文件以创建顶级菜单），然后单击。菜单项编辑窗口会在模式窗口中打开。

可以创建以下类型的菜单项：

Screen - 界面

用于打开应用程序界面的菜单项。

应该为 Screen 项指定以下属性：

Screen - 这个菜单项打开的界面的非唯一 ID。
Id - 为菜单项指定任意唯一 ID。
Open type - 定义界面打开的方式，可以在新的选项卡打开，或者以模态窗的方式打开（NEW_TAB 或 DIALOG）。默认使用 NEW_TAB。
Shortcut - 用于打开界面的快捷键。可选的组合键（ALT、CTRL、SHIFT）用“-”分隔，例如 ALT-C。
Style name - 定义菜单项的样式名称。有关详细信息，请参阅主题。