3.5.7.2 自定义母版

母版是什么

在业务系统中，母版是一种全局通用的组件，用于包裹每个页面的元素。这个概念类似于 PPT 中的母版，它定义了页面的整体结构、样式和布局，使得系统具有一致的外观和风格。

特点：

1. 全局通用：母版是全局性的，适用于系统中的每个页面，确保一致性的用户体验。

2. 包裹元素：母版包裹每个页面的元素，定义了整体的结构和布局。

3. 外观一致性：通过统一的母版设计，系统达到外观和风格的一致性。

与 PPT 母版的类比：

在母版的概念上，与 PPT 中的母版类似，都是用于定义整体结构和样式，确保每个页面都具有一致的外观。

默认母版范围:

作用场景

在系统中，我们提供了多个纬度的母版，包括全局、应用和页面纬度。这样的设计允许根据不同的业务场景选择合适的母版纬度，以满足不同层次的定制需求。

母版纬度：

1. 全局母版：

   • 覆盖系统中所有页面，确保全局的一致性和统一的用户体验。
   • 定义全局性的结构、样式和布局。

2. 应用母版：

   • 适用于特定应用或模块，定制化程度介于全局和页面之间。
   • 允许在不同应用间实现一定的差异化。

3. 页面母版：

   • 面向具体页面，提供最大的定制化空间。
   • 允许在不同页面中定义不同的结构和样式。

选择纬度：

• 业务场景决定：根据具体的业务场景和需求选择合适的母版纬度。
• 定制化需求：如果需要全局一致性，选择全局母版；如果在应用层面有特定需求，选择应用母版；如果需要最大的灵活性和定制化，选择页面母版。

参数说明：

在系统中，使用 registerMask 注册母版时，需要提供两个参数。第一个参数是母版的 XML，第二个参数用于控制母版的注册行为，包括 module、moduleName、model 和 actionName。

1. 母版 XML（第一个参数）：

   • 提供母版的 XML 描述，定义了母版的结构和样式。

2. 控制参数（第二个参数）：

   • module：指定模块的名称。
   • moduleName：指定模块的显示名称。
   • model：指定母版所属的模型。
   • actionName：指定母版的操作名称，可以是字符串或字符串数组。

全局母版

可以使用 registerMask 注册母版。当第二个参数为 {} 时，即代表注册全局母版。

示例工程目录

以下是需关注的工程目录示例，并确保导入导出依赖正确：

示例代码

以下是一个示例代码：

import { registerMask } from '@kunlun/dependencies';

/**
 * mask: 在做系统时，我们通常会把外层的布局(菜单、顶部导航)等抽出公共组件，公共组件会抽离全局通用。类似ppt母版的概念即为Mask
 * registerMask 第二个入参为{}即注册了全局得母版
 *
 * 和默认母版相比移除右上角消息、语言切换、用户
 * `<block>
 *     <widget widget="notification" />
 *     <widget widget="divider" />
 *     <widget widget="language" />
 *     <widget widget="divider" />
 *     <widget widget="user" />
 * </block>`
 */
const registerGlobalMask = () => {
    registerMask(`
    <mask>
        <multi-tabs />
        <header>
            <widget widget="app-switcher" />
        </header>
        <container>
            <sidebar>
                <widget widget="nav-menu" height="100%" />
            </sidebar>
            <content>
                <breadcrumb />
                <block width="100%">
                    <widget width="100%" widget="main-view" />
                </block>
            </content>
        </container>
    </mask>`, {});
}

registerGlobalMask();

复制这段代码执行下registerGlobalMask()试试看吧

效果

右上角消息、语言切换、用户被移除。

应用母版

在系统中，可以使用 registerMask 注册母版。当第二个参数为 {moduleName: 'resource'} 时，即注册了 resource（资源）应用的母版。

示例工程目录

以下是需关注的工程目录示例，更新导出./moduleMask：

示例代码

以下是一个示例代码：

/**
 * registerMask 第二个入参为{moduleName: 'resource'}即注册了resource(资源)应用的母版
 *
 * resource来源: 通常是浏览器url上的module
 *
 * 和默认模版相比拿掉了菜单
 * `<sidebar>
 *    <widget widget="nav-menu" height="100%" />
 *  </sidebar>`
 * */
const registerModuleMask = () => {
    registerMask(`<mask>
    <multi-tabs />
    <header>
        <widget widget="app-switcher" />
        <block>
            <widget widget="notification" />
            <widget widget="divider" />
            <widget widget="language" />
            <widget widget="divider" />
            <widget widget="user" />
        </block>
    </header>
    <container>
        <content>
            <breadcrumb />
            <block width="100%">
                <widget width="100%" widget="main-view" />
            </block>
        </content>
    </container>
</mask>`, { moduleName: 'resource'})
}

registerModuleMask();

在这个示例中，通过将第二个参数设置为 {moduleName: 'resource'}，实现了注册 resource 应用的母版。该母版包含了特定于 resource 应用的全局结构和布局，并在示例中去掉了菜单部分。

这样的设计使得可以根据不同应用注册不同的母版，以满足应用层面的定制需求。

效果

页面母版

在系统中，可以使用 registerMask 注册母版。当第二个参数为 {moduleName: 'resource', model: 'resource.ResourceRegionProxyModel'} 时，即注册了 resource（资源）应用和 这个应用下ResourceRegionProxyModel（地区）模型的母版。

示例工程目录

以下是需关注的工程目录示例，更新导出./viewMask：

示例代码

以下是一个示例代码：

/**
 * registerMask 第二个入参为{moduleName: 'resource', model: 'resource.ResourceRegionProxyModel'}即注册了resource(资源)和resource.ResourceRegionProxyModel(地区)模型的母版
 *
 * resource来源: 通常是浏览器url上的module
 * model来源:  通常是浏览器url上的model
 *
 * 拿掉菜单
 * `<sidebar>
 *    <widget widget="nav-menu" height="100%" />
 *  </sidebar>`
 *
 *  拿掉appFounder
 *  `<widget widget="app-switcher" />`
 * */
const registerViewMask = () => {
  registerMask(`<mask>
    <multi-tabs />
    <header>
        <block>
            <widget widget="notification" />
            <widget widget="divider" />
            <widget widget="language" />
            <widget widget="divider" />
            <widget widget="user" />
        </block>
    </header>
    <container>
        <content>
            <breadcrumb />
            <block width="100%">
                <widget width="100%" widget="main-view" />
            </block>
        </content>
    </container>
</mask>`, { moduleName: 'resource', model: 'resource.ResourceRegionProxyModel'})
}
registerViewMask();

在这个示例中，通过将第二个参数设置为 {moduleName: 'resource', model: 'resource.ResourceRegionProxyModel'}，实现了注册 Resource 应用和 ResourceRegionProxyModel 模型的母版。该母版包含了特定于这两个条件的全局结构和布局，并在示例中去掉了菜单和应用切换部分。

效果

这样的设计使得可以根据不同应用和模型注册不同的母版，以满足不同层次的定制需求

扩展母版

在系统中，除了平台内置的母版组件和布局外，开发者还可以自由地添加自定义的组件和布局，以决定应用的个性化。以下是一些示例代码和说明：

注册母版组件

在这个示例中，我们注册了一个名为 custom-mask-widget 的自定义组件，并使用 CustomMaskWidget 类初始化了该组件。

示例工程目录

以下是需关注的工程目录示例，更新导出./widget：

示例代码

以下是代码示例和相应的组件实现：

1. 注册自定义组件：

import { SPI, MaskWidget } from '@kunlun/dependencies'
import CustomMaskWidgetVue from './MaskWidget.vue'

@SPI.ClassFactory(MaskWidget.Token({ widget: 'custom-mask-widget' }))
export class CustomMaskWidget extends MaskWidget {
  public initialize(props) {
    super.initialize(props);
    this.setComponent(CustomMaskWidgetVue);
    return this;
  }
}

在这段代码中，我们使用 @SPI.ClassFactory 注解来创建 CustomMaskWidget 类，并使用 MaskWidget.Token 注入组件的标识。通过 setComponent 方法，我们将组件与 CustomMaskWidgetVue 相关联。

2. 自定义组件实现（MaskWidget.vue）：

  <template>
    <div class="mask-widget-wrapper">
      <h1>Mask组件</h1>
    </div>
  </template>

  <script lang="ts">
    import { defineComponent } from 'vue'

    export default defineComponent({
      inheritAttrs: false,
      name: 'CustomMaskWidgetVue'
    })
  </script>

  <style lang="scss">
    .mask-widget-wrapper {
      display: flex;
      align-items: center;
      background-color: var(--oio-disable-color);
      h1 {
        color: red;
      }
    }
  </style>

在 MaskWidget.vue 文件中，我们定义了 CustomMaskWidgetVue 组件的模板、逻辑和样式。这个组件简单地展示了一个包含标题的容器。

通过这个示例，我们展示了如何使用 SPI 和 Vue 来注册和实现自定义组件，以满足系统中的个性化需求

自定义母版

在这个示例中，我们注册了一个全局母版，并将自定义组件 custom-mask-widget 与母版结合。

示例工程目录

以下是需关注的工程目录示例，新导出了./globalMask：

示例代码

以下是代码示例：

const registerGlobalMask = () => {
  registerMask(`
    <mask>
        <multi-tabs />
        <header>
            <widget widget="language" />
+            <widget widget="custom-mask-widget" />
        </header>
        <container>
            <sidebar>
                <widget widget="nav-menu" height="100%" />
            </sidebar>
            <content>
                <breadcrumb />
                <block width="100%">
                    <widget width="100%" widget="main-view" />
                </block>
            </content>
        </container>
    </mask>`, {});
}

registerGlobalMask();

在这段代码中，我们使用 registerMask 注册了一个全局母版，其中包含了多个内置组件和布局元素。通过 的方式，我们将自定义组件 custom-mask-widget 添加到了母版的头部（header）中

效果