optimize: 优化文档

diboot-docs/.vuepress/config.js

@@ -94,7 +94,8 @@ module.exports = {
                         ['/guide/diboot-devtools/开始使用', '开始使用'],
                         ['/guide/diboot-devtools/数据表管理', '数据表管理'],
                         ['/guide/diboot-devtools/后端代码生成与更新', '后端代码生成与更新'],
-                        ['/guide/diboot-devtools/前端功能生成', '前端功能生成']
+                        ['/guide/diboot-devtools/前端功能生成', '前端功能生成'],
+                        ['/guide/diboot-devtools/面板-前端组件灵活之道', '面板-前端组件灵活之道']
                     ]
                 }
             ],

diboot-docs/guide/diboot-devtools/面板-前端组件灵活之道.md

@@ -0,0 +1,212 @@
+# 面板-前端组件灵活之道
+
+::: tip
+在前端开发过程中，我们往往会面临很多组件复用的场景，在组件开发完成后，我们或嵌套、或布局、或弹窗等方式对已有组件进行使用。
+
+现在我们将为支持我们的付费用户、订阅用户等提供了与上述问题相关的解决方案，即本文将要介绍的面板。
+:::
+
+## 面板介绍
+
+* 面板可以理解为常规意义上的前端组件，一个面板在配置完成后，生成的也往往是一个代码文件，这个文件不会直接在页面展示出来，如果需要显示出来，需要在页面设计器中进行引用后，方可通过对应方式显示出来。
+
+* 我们对于面板提供了专有的面板设计器，来对面板进行系列配置和代码生成等功能。
+
+* 我们在面板和页面中内置了面板容器基础组件，可以嵌套使用面板，完成在面板和页面中对面板进行的引用与集成工作。
+
+* 我们在面板和页面中内置了自定义按钮及弹窗基础组件，并可在弹窗中选择已有面板，完成在面板中和页面中对按钮的自定义以及面板的引用与集成工作。
+
+* 我们在面板中添加了对于系列基础组件事件函数的自定义功能，满足我们更多的个性化需求。
+
+* 我们在面板中添加了对面板整体的入参设置与事件列表展示等功能，满足了我们的面板作为一个业务组件方面，与其他组件或面板进行对接时的数据交互（主要包含参数传递与事件通知）等的功能需求。
+
+* 我们在面板中增加了对面板参数自定义的功能，以此来协调面板中多个面板间的数据交互工作。
+
+* 可在一个页面运行同一面板的多个实例，高复用、低耦合。
+
+## 使用指南
+
+### 创建第一个面板
+
+1. 面板在diboot-devtools中以单独页面呈现，可点击如下图标处进入面板设计器页面。
+![面板页面导航菜单](/panel_images/nav_menu.png)
+2. 将左侧**标题行**组件拖拽到中间预览区内，更改右侧属性中的标题项为**Hello, World!**
+3. 填写顶部的面板名称与面板编码，面板名称为面板说明，面板编码为面板文件名，也是当前面板生成后的组件名。
+4. 选择所在目录，如果不选择，默认为**src/views/panel**目录下。
+5. 点击顶部的按钮，即可开始生成当前面板所对应的组件文件。
+
+### 使用第一个面板
+
+1. 打开前端页面生成器。
+2. 选择一个指定的表来进行前端页面生成。
+3. 在列表页的操作区组件中，添加自定义按钮。
+4. 配置按钮的类型为模态框，并配置完成弹窗标题等信息。
+5. 模态框内的面板配置处，选择刚刚创建的面板。
+
+完成上述配置后，即可在页面中开始使用新建的面板了。
+
+
+![创建第一个面板](/panel_images/创建第一个面板.gif)
+
+## 常用组件说明
+
+我们目前提供了系列的功能组件，我们将这些组件简单分为业务组件与基础组件。利用这些组件，我们可以构建出一个又一个可应用于生产的面板实例。
+
+### 树列表
+
+该组件主要适用于需要展示左树右列表的业务场景，将两个具有关联关系的业务对象关联起来，实现数据展示上的联动。
+1. 展示其中被关联对象的树状结构。
+2. 展示其中列表数据对象的列表展示。
+3. 当树状结构被更改时，列表数据随之改变。
+
+配置说明：
+1. **树结构实体配置**：这里展示当前系统中所有可构建为树结构的数据对象列表（具有parent_id字段并设置n-1关联自身），这里选择的数据对象将生成其对应的树结构数据结构以及左侧树结构展示相关代码。
+2. **树结构显示字段配置**：即树结构在当前面板所生成的前端页面中所展示出来的树状结构中显示出来的信息所对应的字段，比如name、title等。
+3. **列表实体配置**：在此需要显示为的列表的业务数据对象。这里只有关联了上述树结构业务对象的才可以被选中，在配置好**树结构实体配置**后，也将会自动选择一个默认的符合条件的列表实体配置到这里。
+4. **列表复选框设置**：针对列表的一项配置，开启后将会在列表中显示复选框。
+5. **搜索项配置**：默认开启，开启后将会在列表上方显示相关的搜索栏。此处搜索栏选项也可以在下方进行配置。
+
+提示：
+1. 应用该功能，至少需要两个及以上的业务数据对象。
+2. 至少需要有一个业务数据对象是具有parent_id字段，并设置了关联自身id的关联关系。
+3. 至少需要有一个业务数据对象是关联了上述2所述的业务数据对象。
+4. 需要先生成与之相关的业务数据对象的后端接口代码。
+
+### 树结构
+
+该组件主要适用于需要处理的树状结构数据的业务场景中，将可以做到：
+1. 为后端项目中添加可读取所配置业务数据的树状结构数据相关代码。
+2. 生成具有所配置的业务数据所对应的业务树状结构展示。
+3. 前端所生成的业务数据树列表展示可自定义改变当前节点事件的自定义处理函数。
+
+配置说明：
+1. **树结构实体配置**：选择需要用作当前树结构展示的业务数据对象（这里只可在具有parent_id字段并设置了n-1关联自身的数据对象列表中进行选择）。
+2. **树结构显示字段配置**：当选择了上述实体配置后，这里将会提供该实体配置中相关字段列表供选择，此处设置的字段，将在展示出树结构时，提取该字段值展示在树节点上。
+3. **组件事件处理**：树结构内置了更改当前节点后的事件自定义处理，可编辑当前节点发生改变后的相关处理流程。
+
+提示：
+1. 使用该功能，至少需要一个业务数据对象是具有parent_id字段，并设置了关联自身id的关联关系。
+2. 需要先生成与之相关的业务数据对象的后端接口代码。
+
+### 通用列表
+
+该组件主要适用于通用展示数据列表的业务场景中。
+
+配置说明：
+1. **列表实体配置**：选择需要用作当前列表展示的业务数据对象
+2. **列表复选框设置**：如果启用该配置，当前列表将展示复选框，可勾选当前列表数据项。
+3. **搜索项配置**：默认开启，开启后，可配置搜索项列表，当前列表将拥有分页数据搜索功能。
+4. **列表项配置**：配置当前列表展示数据项列表及顺序。
+
+提示：
+1. 使用该功能前，需要先生成与之相关的业务数据对象的后端接口代码。
+
+### 间隔行
+
+该组件主要用于提供面板中竖向间隔的功能。
+
+### 标题行
+
+该组件可向面吧中添加标题栏，可通过调整组件属性中的系列属性，从而更改标题的系列性质。
+
+### 操作栏
+
+该组件可向面板中添加操作按钮，并可自定义操作按钮的点击事件处理函数，也可配置按钮进行弹窗打开已有面板等操作。
+
+配置说明：
+1. **行设置**：目前可设置该操作栏的按钮对齐方式。
+2. **自定义按钮**：可设置该操作栏中的按钮列表，并设置每个按钮的系列参数和行为等。
+
+### 布局器
+
+该组件可利用前端框架中的布局组件，来对一列进行24等分的栅格布局。
+
+配置说明：
+1. **自动排列**：开启该配置后，当下方新增列时，将会自动对24进行等分，均等地设置到每个列的配置中。
+2. **列配置**：可添加删除列，配置每列所占宽度等。
+
+### 面板容器
+
+面板容器可在当前面板中引入已有的面板容器，让已有的面板能够参与到后续的面板建设中来。
+
+配置说明：
+1. **面板选择**：选择一个已有的面板，选择好面板后，预览区将会自动预览展示所选的面板信息。
+2. **当前面板编码**：此处会在上述面板选择完成后，自动以所选面板编码填充，生成代码中作为引用面板处的ref属性使用。
+3. **入参配置**：如果所选的已有面板在之前的配置中，配置了入参参数，这里需根据需要进行入参参数的绑定。
+    1. **选择绑定参数**：将会从当前面板已有的其他组件中获取参数，如果没有参数列表可选，可在**通用属性**中**面板data参数配置**中配置对应的data参数。
+    2. **参数有值时显示**：将会对入参进行v-if绑定，当该入参有值时才显示当前面板。
+    3. **转String格式**：将会对当前绑定的入参参数进行转String操作，用以保持参数类型一致。
+4. **组件事件处理**：如果所选的已有面板在之前的配置中，具有对外发送的事件，这里将可以对这些事件列表进行事件处理函数自定义相关的配置。
+
+提示：
+1. 当在当前面板中引入多个相同面板时，需手动更改各相同面板的编码不同，以免生成的代码在运行时冲突。
+2. 入参配置需留意引入的面板的入参是否为必填。
+
+## 常用技巧
+
+### 面板的多个实例
+
+1. 同一个面板在同一页面中，可以被引用多次，这里在生成的代码中也是以组件引用这种形式呈现的。
+2. 以下使用布局的一个案例来演示面板的多个实例。
+
+![面板的多个实例](/panel_images/面板多实例.gif)
+
+### 面板的层层嵌套
+
+在面板设计器中，我们可以通过面板容器组件，来实现已有面板的引入，这样便能够将面板层层嵌套来进行配置，也就可以从各个层面来逐步构建我们更加完善的面板库了。
+
+![面板层层嵌套](/panel_images/面板层层嵌套.gif)
+
+### 面板弹窗弹出
+
+在面板设计器中，可以通过**操作栏**组件，来实现对已有面板的弹窗引入，其实也算作面板的层层嵌套。
+
+![弹窗打开面板](/panel_images/弹窗打开面板.gif)
+
+弹窗打开面板示例：
+
+![弹窗打开面板结果示例](/panel_images/弹窗打开面板结果示例.gif)
+
+### 面板入参设置
+
+当面板作为一个独立的组件使用时，我们往往需要配置这个组件的入参参数，那么我们可以在一个面板配置完成后，在**通用属性**中配置其**面板入参props**。
+
+在配置完成**面板入参props**后，我们便可以在上述**面板容器**组件中，指定面板容器的入参参数所对应的当前面板或页面中的参数。
+
+配置项说明：
+* 必填项：如果设为必填项，则在引入该面板的地方，必须设置该必填项参数。
+* 参数变化检测：如果启用该配置，则会对该参数生成对应的watch方法，那么当前面板中该入参发生变化后，将会执行此watch方法中的相关代码。
+* 初始化时检测：将会对该参数设置immediate配置为true。
+
+![面板入参设置](/panel_images/面板入参设置.gif)
+
+### 面板参数设置
+
+当面板中的多个组件之间需要相互传递数据时，可能需要一些在此面板空间下的参数来对各组件之间的数据进行传递，以便于实现当前面板下的各组件数据的协同工作。
+
+面板参数设置，可以配置**通用属性**中的**面板data参数配置**项中进行配置，这里配置的面板参数列表，都将生成当前面板组件文件的data属性中。
+
+面板参数配置项说明：
+* 参数变化时检测：启用该配置后，则会对当前参数生成对应的watch方法。当前参数发生变化后，将会执行此watch方法中的相关代码。
+
+![面板参数设置](/panel_images/面板参数设置.gif)
+
+### 面板发送事件设置
+
+面板对外发送的事件有一下几方面的来源：
+1. 使用组件自身发出的事件：引入的左侧组件列表中的组件默认的事件列表。
+2. 在各种自定义方法中使用this.$emit(eventName, params)这种方案发出的事件，将作为当前面板容器对外发出的事件。
+
+![面板发送事件设置](/panel_images/面板发送事件设置.gif)
+
+### 基础组件事件处理函数自定义
+
+如果当前面板中对应组件有上述发出事件列表，那么将可以在当前组件中自定义对应事件的处理函数。
+
+![基础组件事件处理函数自定义](/panel_images/基础组件事件处理函数自定义.gif)
+
+### 面板的事件处理函数自定义
+
+如果当前面板中对应组件有上述发出事件列表，那么将可以在当前组件中自定义对应事件的处理函数。
+
+![面板的事件处理函数自定义](/panel_images/面板的事件处理函数自定义.gif)