@alanwang-merit/meritdata-platform-skill-package 1.0.8 → 1.0.10

package/skills/meritdata-platform-ui-components/references/catalog/15_/344/272/224/345/211/215/347/253/257/350/265/204/344/272/247-5.1UI/347/273/204/344/273/266/345/272/223-/344/270/212/345/215/212.md

@@ -0,0 +1,514 @@
+---
+name: 前端 UI 组件库（上半）
+source-file: 公共资产清单
+source-section: 5.1.1 - 5.1.7 前端 UI 组件库（CloudDialog / UserSelect / UserSelectMulti / DeptSelect / RoleSelect / ImportButton / MenuAuth）
+keywords: [CloudDialog, UserSelect, UserSelectMulti, DeptSelect, RoleSelect, ImportButton, MenuAuth, Vue组件, 对话框, 用户选择, 部门选择, 角色选择, 导入按钮, 菜单权限]
+use-cases: [用户选择, 部门选择, 角色选择, 对话框, 导入数据, 菜单权限控制]
+related: [16, 12, 17]
+---
+
+# 前端 UI 组件库（上半）
+
+> **原文章节**：`公共资产清单 → 5.1 UI 组件库（5.1.1–5.1.7）`
+> **行号范围**：L2298–L2780
+
+## 🎯 一句话
+涵盖 cloud-module-base 提供的 7 个基础 UI 组件：CloudDialog（对话框）、UserSelect/UserSelectMulti（用户选择）、DeptSelect（部门选择）、RoleSelect（角色选择）、ImportButton（导入按钮）、MenuAuth（菜单权限）。
+
+## 📋 接口/方法清单
+
+### 5.1 UI组件库
+
+#### 全局安装方式
+
+```javascript
+// cloud-module-base 全局安装
+import base from 'cloud-module-base';
+Vue.use(base);
+
+// cloud-module-bpm 全局安装
+import bpm from 'cloud-module-bpm';
+Vue.use(bpm);
+```
+
+---
+
+#### cloud-module-base 公共组件
+
+##### 5.1.1 通用对话框组件 (CloudDialog)
+
+**文件路径**: `cloud-module/cloud-module-base/packages/cloud-dialog/cloud-dialog.vue`
+
+**功能说明**: 平台通用对话框组件，支持标题定制、密级标签提示、异步关闭控制等特性。
+
+**导入方式**:
+```javascript
+import cloudDialog from 'cloud-module-base/packages/cloud-dialog';
+Vue.component(cloudDialog.name, cloudDialog);
+```
+
+**Props 属性**:
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| visible | Boolean | null | 控制对话框显示/隐藏，支持 .sync 或 v-model 双向绑定 |
+| title | String | '' | 对话框主标题文本 |
+| tip | String/null | null | 强制指定的密级标签提示 |
+| beforeClose | Function | null | 自定义关闭前钩子，用于异步关闭控制 |
+| showSecretLabel | Boolean | true | 是否显示密级标签区域 |
+
+**Events 事件**:
+- `open` - 对话框打开时触发
+- `close` - 对话框关闭时触发
+- `opened` - 对话框打开动画完成时触发
+- `closed` - 对话框关闭动画完成时触发
+
+**Slots 插槽**:
+- `title` - 自定义标题区域
+- `secretTip` - 密级标签插槽
+- `default` - 对话框内容区
+- `footer` - 对话框底部
+
+**实际使用示例**:
+```vue
+<!-- 来源: cloud-system-bpm/src/pages/procdesigner/view/ConfigDialog.vue -->
+<cloud-dialog
+  :title="titleconfig"
+  :visible.sync="dialogVisible"
+  width="600px"
+  top="8vh"
+  :before-close="handleClose"
+  @open="onOpen"
+  :close-on-click-modal="false"
+  append-to-body
+>
+  <div>对话框内容区域</div>
+  <template #footer>
+    <el-button @click="dialogVisible = false">取消</el-button>
+    <el-button type="primary" @click="handleConfirm">确定</el-button>
+  </template>
+</cloud-dialog>
+```
+
+**常用Props**:
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| visible.sync | Boolean | 控制对话框显示/隐藏 |
+| title | String | 对话框标题 |
+| width | String | 宽度，如 "600px", "800px", "1030px" |
+| top | String | 距顶部距离，如 "8vh", "2vh" |
+| before-close | Function | 关闭前回调，可用于异步关闭控制 |
+| close-on-click-modal | Boolean | 点击遮罩是否关闭 |
+| append-to-body | Boolean | 是否插入到body |
+
+---
+
+##### 5.1.2 用户选择组件 (UserSelect)
+
+**文件路径**: `cloud-module/cloud-module-base/packages/user-select/UserSelect.vue`
+
+**功能说明**: 人员选择对话框组件，支持组织机构、角色，工作组等多种选人模式。
+
+**导入方式**:
+```javascript
+import userSelect from 'cloud-module-base/packages/user-select';
+Vue.component(userSelect.name, userSelect);
+```
+
+**Props 属性**:
+| 属性名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| dialogVisible | Boolean | true | 控制对话框显示/隐藏 |
+| options | Object | false | 配置选项 |
+| showSecretLabel | Boolean | false | 是否显示密级标签 |
+
+**options 配置项**:
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| title | String | 'base.user_select.title' | 对话框标题 |
+| selectType | String | 'org' | 选人模式：org/role/workgroup/category |
+| orgUrl | String | '/cloud-system-manage/api/ou/org/tree' | 组织机构树接口 |
+| listUserByOrgIdUrl | String | '/cloud-system-manage/api/ou/emp/listEmp' | 人员列表接口 |
+| selectedUsers | Array | [] | 已选择的人员ID或编码集合 |
+| filterSwitch | Boolean | false | 是否过滤已选人员 |
+| userIds | Array | [] | 需要过滤的已选人员列表 |
+| isShowNoUser | Boolean | true | 是否过滤没有账户的人员 |
+
+**Events 事件**:
+- `dialog-save` - 确认选择时触发，返回选中的人员数据
+- `dialog-close` - 关闭对话框时触发
+
+**实际使用示例**:
+```vue
+<!-- 来源: cloud-system-bpm/src/pages/procdesigner/view/ConfigDialog.vue -->
+<!-- 人员选择弹窗 -->
+<user-select
+  :showSecretLabel="true"
+  :dialogVisible="dialogVisibleUser"
+  :options="optionsUser"
+  @dialog-close="dialogClose"
+  @dialog-save="dialogSaveUser"
+/>
+```
+
+```javascript
+// 对话框数据
+dialogVisibleUser: false,
+optionsUser: {
+  selectedUsers: []
+},
+
+// 打开人员选择对话框
+changePeop () {
+  this.dialogVisibleUser = true;
+  this.optionsUser.selectedUsers = this.formData.userConfigIds 
+    ? this.formData.userConfigIds.split(',') : [];
+},
+
+// 保存选择的人员
+dialogSaveUser (selectedUser) {
+  selectedUser = selectedUser || [];
+  let selectCodes = '';
+  let selectNames = '';
+  if (selectedUser.length > 0) {
+    let userName = [];
+    let userCode = [];
+    selectedUser.forEach(item => {
+      userName.push(item.name);
+      userCode.push(item.code);
+    });
+    selectNames = userName.join(',');
+    selectCodes = userCode.join(',');
+  }
+  this.formData.userConfigNames = selectNames;
+  this.formData.userConfigIds = selectCodes;
+  this.dialogVisibleUser = false;
+}
+```
+
+---
+
+##### 5.1.3 多用户选择组件 (UserSelectMulti)
+
+**文件路径**: `cloud-module/cloud-module-base/packages/user-select-multi/UserSelect.vue`
+
+**功能说明**: 增强版多用户选择组件，支持组织、角色，工作组、职务等多种维度选择。
+
+**导入方式**:
+```javascript
+import userSelectMulti from 'cloud-module-base/packages/user-select-multi';
+Vue.component(userSelectMulti.name, userSelectMulti);
+```
+
+**Props 属性**:
+| 属性名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| dialogVisible | Boolean | true | 控制对话框显示/隐藏 |
+| options | Object | false | 配置选项 |
+| showSecretLabel | Boolean | false | 是否显示密级标签 |
+
+**options 配置项**:
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| title | String | - | 对话框标题 |
+| selectType | String | 'all' | 选人模式：org/role/workgroup/category/duty/all |
+| selectedUsers | Array | [] | 已选择的人员 |
+| limit | Number | null | 选择人数限制 |
+| radioFlag | Boolean | false | 是否单选模式 |
+| threeMemberApply | Boolean | false | 是否三员申请模式 |
+
+**Events 事件**:
+- `dialog-save` - 确认选择时触发
+- `dialog-close` - 关闭对话框时触发
+
+**实际使用示例**:
+```vue
+<!-- 来源: cloud-system-schedule/src/pages/monitor/view/messageSubscribe.vue -->
+<!-- 人员选择器 -->
+<user-select-multi
+  :showSecretLabel="true"
+  :dialogVisible="editDialogVisible"
+  :options="options"
+  @dialog-close="editDialogClose"
+  @dialog-save="editDialogSave"
+/>
+```
+
+```javascript
+// 数据
+editDialogVisible: false,
+options: {
+  title: "人员选择",
+  selectedUsers: [],
+  secirtFlag: false
+},
+
+// 事件处理
+editDialogSave (selectedUsers) {
+  // selectedUsers 为选中的人员数组
+  console.log('选中人员', selectedUsers);
+  this.editDialogVisible = false;
+},
+editDialogClose () {
+  this.editDialogVisible = false;
+}
+```
+
+---
+
+##### 5.1.4 部门选择组件 (DeptSelect)
+
+**文件路径**: `cloud-module/cloud-module-base/packages/dept-select/dept-select.vue`
+
+**功能说明**: 部门机构树选择对话框组件。
+
+**导入方式**:
+```javascript
+import deptSelect from 'cloud-module-base/packages/dept-select';
+Vue.component(deptSelect.name, deptSelect);
+```
+
+**Props 属性**:
+| 属性名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| dialogVisible | Boolean | true | 控制对话框显示/隐藏 |
+| options | Object | false | 配置选项 |
+| showSecretLabel | Boolean | false | 是否显示密级标签 |
+
+**options 配置项**:
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| title | String | 'base.dept_select.title' | 对话框标题 |
+| treeUrl | String | '/api/ou/org/orgDeptTree' | 部门树接口 |
+| checkedIds | Array | [] | 默认选中的部门ID列表 |
+
+**Events 事件**:
+- `dialog-save` - 确认选择时触发，返回选中的部门节点数据
+- `dialog-close` - 关闭对话框时触发
+
+**实际使用示例**:
+```vue
+<!-- 来源: cloud-system-bpm/src/pages/procdesigner/view/ConfigDialog.vue -->
+<!-- 部门选择弹窗 -->
+<dept-select
+  :showSecretLabel="true"
+  :dialogVisible="dialogVisibleDept"
+  :options="optionsDept"
+  @dialog-close="dialogClose"
+  @dialog-save="dialogSaveDept"
+/>
+```
+
+```javascript
+// 数据
+dialogVisibleDept: false,
+optionsDept: {
+  checkedIds: []
+},
+
+// 打开部门选择对话框
+changeDep () {
+  this.dialogVisibleDept = true;
+  this.optionsDept.checkedIds = this.formData.deptConfigIds 
+    ? this.formData.deptConfigIds.split(',') : [];
+},
+
+// 保存选择的部门
+dialogSaveDept (selectedDept) {
+  selectedDept = selectedDept || [];
+  let selectCodes = '';
+  let selectNames = '';
+  if (selectedDept.length > 0) {
+    let deptName = [];
+    let deptCode = [];
+    selectedDept.forEach(item => {
+      deptName.push(item.name);
+      deptCode.push(item.code);
+    });
+    selectCodes = deptCode.join(',');
+    selectNames = deptName.join(',');
+  }
+  this.formData.deptConfigNames = selectNames;
+  this.formData.deptConfigIds = selectCodes;
+  this.dialogVisibleDept = false;
+}
+```
+
+---
+
+##### 5.1.5 角色选择组件 (RoleSelect)
+
+**文件路径**: `cloud-module/cloud-module-base/packages/role-select/role-select.vue`
+
+**功能说明**: 角色树选择对话框组件。
+
+**导入方式**:
+```javascript
+import roleSelect from 'cloud-module-base/packages/role-select';
+Vue.component(roleSelect.name, roleSelect);
+```
+
+**Props 属性**:
+| 属性名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| dialogVisible | Boolean | true | 控制对话框显示/隐藏 |
+| options | Object | false | 配置选项 |
+| showSecretLabel | Boolean | false | 是否显示密级标签 |
+
+**options 配置项**:
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| title | String | 'base.role_select.title' | 对话框标题 |
+| treeUrl | String | '/api/ou/org/orgRoleTree' | 角色树接口 |
+| checkedIds | Array | [] | 默认选中的角色ID列表 |
+
+**Events 事件**:
+- `dialog-save` - 确认选择时触发
+- `dialog-close` - 关闭对话框时触发
+
+**实际使用示例**:
+```vue
+<!-- 来源: cloud-system-manage/src/pages/us/workbench/view/workbench-base.vue -->
+<role-select
+  :dialogVisible="dialogVisibleRole"
+  :options="optionsRoles"
+  @dialog-close="dialogClose"
+  @dialog-save="dialogSaveRole"
+/>
+```
+
+```javascript
+// 数据
+dialogVisibleRole: false,
+optionsRoles: {
+  checkedIds: []
+},
+
+// 事件处理
+dialogSaveRole (selectedRoles) {
+  // selectedRoles 为选中的角色数组
+  console.log('选中角色', selectedRoles);
+  this.dialogVisibleRole = false;
+},
+dialogClose () {
+  this.dialogVisibleRole = false;
+}
+```
+
+---
+
+##### 5.1.6 导入按钮组件 (ImportButton)
+
+**文件路径**: `cloud-module/cloud-module-base/packages/import-button/import-button.vue`
+
+**功能说明**: 数据导入按钮组件，支持下载模板、上传文件、导入验证等功能。
+
+**导入方式**:
+```javascript
+import importButton from 'cloud-module-base/packages/import-button';
+Vue.component(importButton.name, importButton);
+```
+
+**Props 属性**:
+| 属性名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| options | Object | true | 导入配置选项 |
+| isDisAble | Boolean | true | 是否禁用按钮 |
+
+**options 配置项**:
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| applicationName | String | 应用名称 |
+| configId | String | 导入配置ID |
+| text | String | 按钮文本，默认'导入' |
+| rootOrgCode | String | 根组织编码 |
+| rootOrgId | String | 根组织ID |
+| rootDLevelCode | String | 密级编码 |
+
+**Events 事件**:
+- `requestGridData` - 导入完成或取消时触发，用于刷新列表
+
+**实际使用示例**:
+```vue
+<!-- 来源: cloud-system-manage/src/pages/ou/emp/view/Grid.vue -->
+<cloud-import-button
+  buttonCode="emp_import"
+  :disabled_custom="canShowImport"
+  :options="importOpts"
+  class="marL8"
+  @requestGridData="requestGridData"
+/>
+```
+
+```javascript
+// 导入配置
+importOpts: {
+  applicationName: 'cloud-system-manage',
+  configId: 'emp_import_config',
+  rootOrgCode: 'YRD',
+  rootOrgId: 'org-root-id',
+  rootDLevelCode: '3'
+},
+
+// 刷新列表
+requestGridData () {
+  this.queryGridData(); // 重新查询列表数据
+}
+
+// 控制按钮是否禁用
+canShowImport () {
+  // 根据权限或其他业务逻辑判断
+  return false; // false=启用, true=禁用
+}
+```
+
+---
+
+##### 5.1.7 菜单权限认证组件 (MenuAuth)
+
+**文件路径**: `cloud-module/cloud-module-base/packages/authenticate/menu-auth.vue`
+
+**功能说明**: 页面权限控制组件，用于控制用户是否有页面访问权限。
+
+**导入方式**:
+```javascript
+import MenuAuth from 'cloud-module-base/packages/authenticate/menu-auth';
+Vue.component(MenuAuth.name, MenuAuth);
+```
+
+**使用示例**:
+```vue
+<menu-auth>
+  <div>需要权限才能显示的内容</div>
+</menu-auth>
+```
+
+**实际使用示例**:
+```vue
+<!-- 来源: cloud-system-manage/src/pages/webapi/app/Index.vue -->
+<!-- 包裹整个页面布局，根据菜单权限控制访问 -->
+<menu-auth>
+  <el-container class="el-root-container">
+    <el-header height="50px">
+      <v-header />
+    </el-header>
+    <el-container class="el-main-container">
+      <el-aside>
+        <v-tree />
+      </el-aside>
+      <v-grid />
+    </el-container>
+  </el-container>
+</menu-auth>
+```
+
+## 💡 使用建议
+
+1. **全局注册 vs 局部注册**：通用组件（CloudDialog / UserSelect / DeptSelect）在 `main.js` 中 `Vue.component` 全局注册；页面专属组件用 `components` 局部注册。
+2. **密级标签**：所有对话框类组件默认 `showSecretLabel: true`，涉密业务必须保留。
+3. **多选用户组件优先**：`UserSelectMulti` 支持 `org/role/workgroup/category/duty/all` 多维度选人，复杂场景优先选它。
+
+## 🔗 相关章节
+
+- `16_五前端资产-5.1UI组件库-下半.md`（ResourceCodeAuth / ThreeMemberAuth / TableHeadSearch / VerifiyPassword / CommonHeader）
+- `12_四业务组件-4.1工作流BpmEngine.md`（BPM 流程触发）
+- `17_附录-统计汇总-Maven依赖-注意事项.md`（Maven 依赖与组件开发注意事项）