### 可配置首页文档及开发指引

可配置首页是一个能让用户在线上进行灵活变更的首页，它可以在配置正确的布局、模块后展示它们，提供了更为低成本的维护方式。

## 配置详解

具体的配置字段及注释请见 _/views/vent/deviceManager/configurationTable/types.ts_

## 目录结构

_/configurable_

--_xxx.vue_ 各个首页的具体文件，每个首页需要一个文件来承载它们的子模块，放置特殊的装饰以及实现特定的功能。例如 dustBD 即为保德煤矿专用的粉尘首页。

--_mock.ts_ 提供一些模拟数据

--_configurable.data.ts_ 该文件及类似命名的文件用来提供测试用的首页具体配置，测试通过后可以依据此配置上线。

--_configurable.api.ts_ 获取数据的 api 都在这里维护。

--_/hooks_ 包含了可供各个首页、子模块核心组件复用的 setup 内容，包括初始化配置、初始化选项等。

--_/components_

----_/detail_ 包含了各个细分模块的具体组件，例如列表、表格、告示板、画廊、时间线等等组件，它们根据自己的 prop 实现自己的内容。

----_/enhanced_ 包含了新版子模块的各样组件，例如底部特化、边缘特化等，子模块内由上述的细分模块组成。

----_/original_ 包含了原版子模块的组件，例如底部特化、边缘特化等，子模块内由上述的细分模块组成。

----_/preset_ 包含了预设类细分模块的具体组件，预设类指的是较为复杂，难以可配置化的组件，通常仅需提供数据，即首页配置内指向的数据。

----_ModuleXXX.vue_ 各个子模块的具体组件，子模块通常负责边框、Header、Content的布局，样式在这里维护。特殊情况下更为底层的实现也可以在这里。

----_content.vue_ 内容组件，核心组件之一，这个组件负责将首页配置转换为可以供细分模块使用的 prop，并且引用所有细分模块，负责它们的布局。

----_header.vue_ 头部组件，核心组件之一，这个组件负责将首页配置的 Header 项实现为下拉框，并向外提供了获取所选内容的方法，供其他与 content 类同的组件使用。

## 开发人员开发流程

从开发一个新的首页开始，需要的步骤可能如下：

1、新建 xxx.vue 作为该首页的具体文件，引入 hooks 里的初始化方法，并对配置进行初始化，初始化数据与页面类型编码即 pageType。

2、根据页面类型编码向项目的数据字典里添加新项，code 在配置表处定义（目前为 configurable_homepage），字典内容为上述的 pageType。

3、参照已有的首页文件，将需要支持的子模块类型加入其中，添加必要的装饰并提供子模块需要的 prop。

4、新建 configurable.data.ts 或类同的文件，根据先前的文件配置，写出一份适用于本首页的配置来。

5、测试完毕后提交代码、打包项目，部署后在线上的首页配置页面将写好的配置以JSON写入即可。

如果需要开发新的细分模块，那么基本流程如下，更详细的内容见另一章节：

1、在配置类型声明处添加子项，可参考 chart、table、list、board 项的结构。

2、开发细分模块，将其放置在 _/components/detail_ 下。

3、根据细分模块的 prop，在 content.vue 下参考已有实现将新的细分模块标识添加进处理结构中，添加能把配置转换为 prop 的逻辑，同时添加该细分模块至相关布局代码中。

4、测试修改并提交。

如果是子模块，那么参考 ModuleEnhanced.vue 即可。

## 运维及字典相关配置

1、配置可配置首页配置页面，组件名：_vent/deviceManager/configurationTable/index_，参考菜单：_/configurable/table_，参考页面位置：设置-首页管理。

2、配置可配置首页依赖的字典，进入字典配置页面，添加 configurable_homepage 字典项，参考名称：可配置首页。

3、在 2 中添加的字典里添加子项，添加的子项具体名称需要和相关同事确认，参考字典：vent(通风首页)、gas(瓦斯首页)、dust(粉尘首页)、vent_realtime(通风首页-实时数据版)等。

4、配置可配置首页，组件名：_vent/home/configurable/xxx_(需要和开发同事确认)，参考菜单：将需要替换的首页菜单配给可配置首页。

5、进入可配置首页配置页面，点击导入，将开发同事给的配置导入即可，后续调整可以点击帮助按钮查看配置细则，更为复杂的配置建议交与开发同事。

## 配置详解

我们从一张最常用的通风可配置首页 vent182.vue 开始，这个页面的绝大多数配置都是很好的例子。同时，这份文档只针对与目录结构章节提到的标准内容，对于任何基于此分发的版本不做讨论。

这是一个常用模块的样子![alt text](image.png)，这个模块在页面中存在若干个组成整体页面，页面则类似![alt text](image-1.png)；一个模块通常包括以下几部分内容：

1、模块的外边框

2、模块的标题

3、模块的设备选择框

4、模块的主体

5、模块的背景

让我们逐一介绍，比对配置和代码！

### 模块的外边框

模块外边框在配置中对应值为![alt text](image-2.png)；在代码中的应用实例为![alt text](image-3.png)

目前模块外边框通常是在页面中自己定义的，因为多数页面的外边框是既定的且不同页面有不同边框，所以配置中所提供的外边框配置项仅有少部分页面进行了实际应用，如果需要修改外边框样式，建议直接修改页面中导入的边框。

一个外边框组件负责根据配置渲染模块边框（有短边框，长边框，异形框等），同时边框内设备选择器和主体部分可能需要额外的客制化样式，你可以在这里处理。你可以用 _/src/views/vent/home/configurable/components/ModuleCommon.vue_ 做参考，它们的结构类似：

```vue
<template>
  <Transition>
    <BorderComponent>
      <Title>标题在此</Title>
      <Header>设备选择器，可以使用已有的hooks编写逻辑，也可以用标准的Header组件与Content交互</Header>
      <Content>主体，只建议使用标准的Header组件</Content>
    </BorderComponent>
  </Transition>
</template>
<script>
  // extract config and data form props
</script>
```

### 模块标题

略

### 模块设备选择框

模块设备选择框是模块中非常重要的部分，它负责展示设备列表，并允许用户选择设备。负责将选择到的数据向外传递，页面传递过来的数据和配置里的模拟数据通常都在这里处理。你可以参考 _/src/views/vent/home/configurable/components/header.vue_ 文件，简要地来说它的工作流程如下：

1、根据Props传入的页面数据进行初始化

2、根据Props传入的配置将数据进行处理

3、渲染内容并提交事件，将选中的设备提交

其中，数据处理时，如果配置上提供了模拟数据（mock）那么模拟数据会优先使用，然后走数据处理逻辑，会根据配置是否需要显示设备选择器进行进一步处理，现假设传入数据为`{ a: 123, b: [1,2,3] }`：

1、如果需要设备选择器，则会根据`Config.deviceType`、`Config.moduleData.header`筛选上述数据，然后将设备数组初始化并默认选择第一个设备，假设配置了`Config.deviceType = 'b'`，那么最终设备数据为`[1,2,3]`，首个设备数据为`1`。组件将把`1`提交出去交给主体。

2、如果不要设备选择器，则会把上述数据转化为一个设备，那么最终设备数据为`[{ a: 123, b: [1,2,3] }]`，首个设备数据为`{ a: 123, b: [1,2,3] }`。组件将把前面的数据提交给主体。

### 模块主体

模块主体部分是模块中最重要的部分，它负责实现主体子模块布局，展示设备数据，展示背景。处理 ![alt text](###模块设备选择框) 传递过来的数据。你可以参考 _/src/views/vent/home/configurable/components/content.vue_ 文件，简要地来说它的工作流程如下：

1、处理传入的主体配置即`Config.moduleData`和设备数据，将数据转化为主体子模块需要的格式

2、渲染主体布局、背景以及子模块，这两张图片是很好的例子![alt text](image-4.png)、![alt text](image-5.png)

3、根据`<template>`的判断，显示指定的子模型并传递数据

### 模块的子模块

模块的子模块是显示信息的最小组件，开发者需要在这个级别的组件里接收从![alt text](###模块主体)传递过来的数据，并根据数据渲染内容。你可以参考 _/src/views/vent/home/configurable/components/detail/MiniBoard.vue_ 文件，简要地来说它的工作流程如下：

1、根据传入的数据渲染主体文本、图表等内容

2、根据样式文件，针对不同的`Props.type`渲染不同的样式

子模块的工作非常简单，也很容易理解。但是简单意味着支持的复杂度不高，它们分为几个大类，但都只能胜任简单的展示任务，如果需要复杂的展示任务，那么你需要看看`Preset`！预设类组件可以自定义实现并实现复用，你可以参考 _/src/views/vent/home/configurable/components/preset/QHCurve.vue_ 文件，这是一个根据数据渲染风量风压曲线图的组件。要使用这些`Preset`，首先要确认所用的![alt text](###模块主体)中是否注册了该组件，你需要导入并注册该组件。然后在配置中把配置项写入`Config.moduleData.preset`下并在`Config.moduleData.layout`下使用注册名称排版。图片说明参考![alt text](image-6.png)、![alt text](image-7.png)

### 常见问题

#### 为什么我配置写好了却没有数据展示在上面呢？

A：阅读上面的文档后检查一下，是不是没有正确地配置。具体的检查步骤参考：

- 检查`Config.deviceType`是否需要配置，仅在需要设备选择器的时候配置该项!
- 检查`Config.moduleData.header`配置是否正确，在需要设备选择器时，确保`readForm`指向了可读数组!
- 检查`Config.moduleData.mock`是否配置，即使是空对象也会被认为是存在模拟数据，请确保模拟数据的正确性!
- 检查控制台是否存在可配置首页下的报错，如有报错应当立即处理，否则会影响后续模块读取数据！

#### 为什么我配置好了，数据也有但是数据没有正确地展示出来呢？

A：通常是因为配置项没有正确地配置，请仔细检查配置项，尤其是类似与`{ ..., readForm: 'outer', items: [{ ..., readForm: 'outer.inner' }] }`的错误配置，内层的配置重复读取了`outer`导致了错误，正确的配置应该让内外层的`readForm`拼接起来后指向所要的数据。

#### 我不会配置模拟数据，总是达不到想要的效果怎么办？

A：模拟数据即`Config.moduleData.mock`，它绝大多数情况下是一个对象，如果不需要设备选择器，那么可配置首页将直接把模拟数据传给子模块。但如果需要设备选择器那么需要配合`Config.deviceType`来使用并确保其指向数组，例如写成`{ ..., mock: { [Config.deviceType]: [ ... ] } }`

#### 如果项目部署后访问首页（可配置首页）没有出现任何内容怎么办？

A：可能是由于以下的原因之一

- 没有正确地配置菜单及其权限，请检查设置-菜单配置
- 没有正确地配置子应用的模型导致出现了类似 _/micro-vent-3dModal/404_ 的链接，请检查设置-菜单配置-模型设置
- 没有正确地添加配置项导致页面无内容，应在获取配置导入信息后于设置-首页配置导入

#### 首页正常显示其内容，但是点击左下角呼出菜单后，点击Home图标却跳转到了其他页面怎么办？

A：这是因为项目配置不正确导致的，参考设置-项目设置-编辑功能编辑首页为可配置首页路径并保存。

#### 首页能够显示其内容，但是各个模块位置不齐、出现不想要的滚动条或者矿方想要更宽/更窄/更高等需求怎么办？

A：根据需求自行调整模块`Config.showStyle`定义的宽高位置即可。需要注意定位（即`Config.showStyle.position`）里的`Top`和`Left`是按照总标题下至最底部，最左侧至最右侧为框计算的绝对值，不会计算模块的相互关系。

#### 首页能够显示内容且位置、样式正确，但是某项指标的数据不对、不需要某项指标、需要添加某项指标怎么办？

A：修改某项指标大致可以按照如下流程处理，图片资料参考![alt text](image-8.png)、![alt text](image-9.png)

- 在首页使用控制台（F12）查看数据来源，通常是与 `/homedata` 相似的接口
- 进入首页配置页面找到需要修改的模块，点击配置
- 在控制台确认某项指标需要显示的数据的正确读取路径并更新至配置里

#### 需要开发一个全新的页面，但是不知道如何下手怎么办？

A：首先确认新页面的各个模块有没有可复用模块，通常在 _/assets/images/home-container/configurable_ 下可以通过图片的命名方式和样子来作初步确认，如果没有需要按需开发同时建议将图片资源按已有的命名规则加入。涉及复杂逻辑且没有可复用组件的建议直接使用![alt text](###模块子模块)中提到的`Preset`组件。