3.11.2. 扩展界面

平台支持通过继承现有的界面描述来创建新的界面 XML 描述。

通过在 window 根元素的 extends 属性中指定父描述路径来实现 XML 继承。

XML 界面元素覆盖规则：

• 如果新扩展的界面描述中有某个元素，则将使用以下算法在父描述中搜索相应的元素：

• 如果覆盖的元素是 view，则会通过 name 、 class 和 entity 属性在父描述中搜索相应的元素。

• 如果覆盖的元素是 property，则会通过 name 属性在父描述中搜索相应的元素。

• 在其它情况下，如果覆盖的元素有 id 属性，则会在父描述中搜索具有相同 id 的相应元素。

• 如果搜索成功，则找到的元素被 覆盖。

• 否则，平台将先确定父描述中包含具有提供的路径和名称的元素数量。如果只有一个元素，则它被 覆盖。

• 如果搜索没有产生结果，并且在父描述中没有具有给定路径和名称的元素或者有多个这种元素，则会 添加 新元素。

• 被覆盖或添加的元素的文本将从扩展的新元素中复制。

• 扩展的新元素的所有属性都会复制到被覆盖或添加的元素中。如果属性名称匹配，则从扩展的新元素中获取值。

• 默认情况下，新元素将添加到元素列表的末尾。要将新元素添加到开头或使用任意位置，可以执行以下操作：

• 在继承描述中定义一个额外的命名空间： xmlns:ext="http://schemas.haulmont.com/cuba/window-ext.xsd"。

• 添加带有所需索引的 ext:index 属性到扩展元素，例如：ext:index="0"。

要调试 XML 描述的转换过程，可以通过在 Logback 配置文件中将 com.haulmont.cuba.gui.xml.XmlInheritanceProcessor 记录器指定为 TRACE 级别，从而将结果 XML 输出到服务端日志。

下面是 ExtUser 实体浏览界面的 XML 描述示例：

<window xmlns="http://schemas.haulmont.com/cuba/window.xsd"
      xmlns:ext="http://schemas.haulmont.com/cuba/window-ext.xsd"
      extends="/com/haulmont/cuba/gui/app/security/user/browse/user-browse.xml">
  <layout>
      <groupTable id="usersTable">
          <columns>
              <column id="address" ext:index="2"/>
          </columns>
      </groupTable>
  </layout>
</window>

在此示例中，XML 描述继承自平台的标准 User 实体浏览界面。address 列以 2 为索引被添加到表中，因此它在 login 和 name 列之后显示。

如果在screens.xml中注册一个新界面，新界面使用与父界面相同的标识符，这样新界面就会代替旧界面。

<screen id="sec$User.browse"
      template="com/sample/sales/gui/extuser/extuser-browse.xml"/>
<screen id="sec$User.lookup"
      template="com/sample/sales/gui/extuser/extuser-browse.xml"/>

同样，创建一个编辑界面：

<window xmlns="http://schemas.haulmont.com/cuba/window.xsd"
      xmlns:ext="http://schemas.haulmont.com/cuba/window-ext.xsd"
      extends="/com/haulmont/cuba/gui/app/security/user/edit/user-edit.xml">
  <layout>
      <fieldGroup id="fieldGroup">
          <column id="fieldGroupColumn2">
              <field property="address" ext:index="4"/>
          </column>
      </fieldGroup>
  </layout>
</window>

使用父界面的标识符在 screens.xml 中注册它：

<screen id="sec$User.edit"
      template="com/sample/sales/gui/extuser/extuser-edit.xml"/>

完成上述所有操作后，应用程序将使用带有相应界面的 ExtUser 实体代替平台中标准的 User 实体。

可以通过创建一个继承基本界面控制器的新类来扩展界面控制器。类名在扩展的 XML 描述的根元素的 class 属性中指定；上面描述的继承 XML 的通用规则在这里同样适用。