address-book-shell

基于vue2和element-ui开发的地址本组件

目录

[TOC]

快速开始

安装

# 使用 npm
npm install address-book-shell --save

# 使用 yarn
yarn add address-book-shell

注册组件

import microserviceRequest from '@/utils/microService/microService-request.js'
import AddressBookShell from 'address-book-shell'
import 'address-book-shell/src/theme/element-ui-theme/element-ui-common.scss'

// 注册地址本组件
Vue.use(AddressBookShell, {
  // 微服务请求方法（必传）
  microserviceRequest: microserviceRequest,
})

基本使用

<template>
  <div>
    <el-button @click="addressListVisible = true">打开地址本</el-button>
    
    <address-book-shell
      :visible.sync="addressListVisible"
      :selected="selected"
      :close-on-click-modal="false"
      @submitted="submitAddress"
      @close="closeAddress"
      :loginUserinfo="loginUserinfo"
      :append-to-body="true"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      addressListVisible: false,
      selected: [], // 默认选中的人员
      loginUserinfo: {
        // CAS单点登录返回的用户信息
        dept: "xxx",
        deptId: "xx",
        email: "xxxx",
        headImage: "xxxx",
        hrId: "xxxx",
        loginName: "xxxx",
        phone: "12345678999",
        post: "xxx",
        telNo: "123456789",
        type: 0,
        userName: "xx"
      }
    }
  },
  methods: {
    submitAddress(personData, typeList, data) {
      console.log('人员数据:', personData)
      console.log('结构数据:', typeList)
      console.log('原始数据:', data)
    },
    closeAddress() {
      // 你的逻辑
    }
  }
}
</script>

组件属性

注意:地址本组件继承了element-ui库Dialog组件的全部属性，即Dialog属性全部适用本组件。

loginUserinfo

CAS单点登录返回的用户信息，必传，否则地址本将无法正常使用。

数据结构：

| 字段名 | 说明 | 类型 | | :--- | :--- | :--- | | dept | 部门名称 | String | | deptId | 部门ID | String | | email | 邮箱地址 | String | | headImage | 头像地址 | String | | hrId | 人员ID | String | | loginName | 登录名 | String | | phone | 手机号码 | String | | post | 职位 | String | | telNo | 固定电话 | String | | type | 用户类型 | Number | | userName | 用户名 | String |

使用示例：

<address-book-shell
  :loginUserinfo="loginUserinfo"
/>

selected

默认勾选的人员数据，通过该属性可以将需要默认勾选的数据传入地址本。

数据结构：

| 字段名 | 说明 | 类型 | 是否必填 | | :--- | :--- | :--- | :--- | | avatar | 头像地址 | String | 是 | | aduser | OA账号 | String | 是 | | hrId | 人员/部门/岗位ID | String | 是 | | name | 中文名称 | String | 是 | | fdOrgType | 数据类型 | String | 是 | | detailedPerson | 人员详情（用于鼠标经过岗位或部门时提示） | String | 否 |

fdOrgType取值说明：

• '2'：部门
• '4'：岗位
• '8'：人员

使用示例：

// 默认勾选的人员数据
selected: [
  {
    avatar: 'xxx', // 头像地址
    aduser: 'xxxxx', // OA账号
    hrId: 'xxxxxxxxx', // 例如 100001111
    name: 'xxx', // 中文名称
    fdOrgType: '8' // 数据类型：人员
  },
  {
    avatar: 'xxxxxxxxxxxxx',
    hrId: 'xxx',
    aduser: 'xxx',
    name: 'xxxxxxxx',
    fdOrgType: '4', // 数据类型：岗位
    detailedPerson: 'xxxxxxxxxxxx' // 人员详情
  }
]

<address-book-shell
  :selected="selected"
/>

注意：以上列出的属性为必须属性，如添加了其他非必须属性，点击确定时也会原封不动暴露出去。

selectDisabled

是否禁用默认选中数据的操作。如果设置为true，通过selected传入的默认选中数据将被置灰，不允许在地址本中取消选中。

使用示例：

<address-book-shell
  selectDisabled
/>

showOnlyNewPersonnel

是否只展示新增的人员列表。

取值说明：

• 0：默认值，取selectDisabled的值
• 1：展示全部人员，包括selected传进来的人员
• 2：只显示新增人员，不包括selected传进来的人员

使用示例：

<address-book-shell
  :showOnlyNewPersonnel="2"
/>

onlyOriginalData

是否只返回原始勾选数据。

取值说明：

• false（默认）：点击确定按钮时会调用接口，将岗位和部门转化为人员数据，并通过submitted方法返回
• true：直接返回原始勾选数据，不调用接口，可减少地址本的反应时间

注意：如果没有配置该属性，且勾选的只有人员数据，点击确定按钮时也不会调用接口，而是直接将人员数据返回。

使用示例：

<address-book-shell
  onlyOriginalData
/>

typeList

自定义模糊搜索下拉选项内容，用于控制模糊搜索的权限范围。

默认值：['全部', '部门', '岗位', '人员']

使用示例：

// 仅开启人员搜索权限
typeList: ['人员']

<address-book-shell
  :typeList="typeList"
/>

onlyMailList

是否只展示通讯录模块。

说明：地址本默认会根据用户身份自动加载对应模块，内部员工默认加载通讯录和合作方好友模块。如果内部员工只想加载通讯录模块，可以设置该属性。

使用示例：

<address-book-shell
  onlyMailList
/>

tabs

自定义地址本加载的模块。

说明：与onlyMailList一样都是用来控制地址本加载模块的。如果想自定义加载的模块，可手动配置tabs参数来实现。如果不传或传空数组，将根据用户身份动态显示合适的模块。

默认值：[]

使用示例：

// 加载通讯录和合作方好友模块
tabs: ['通讯录', '合作方好友']

<address-book-shell
  :tabs="tabs"
/>

radio

是否开启单选模式。

说明：如果开启了单选模式，selected传入的数据又不止一个的话，地址本只会获取第一项数据，其他数据将被抛弃。

使用示例：

<address-book-shell
  radio
/>

title

地址本组件的标题。

默认值：'地址本'

使用示例：

<address-book-shell
  title="测试地址本"
/>

width

地址本弹层的宽度。

默认值：'800px'

使用示例：

<address-book-shell
  width="800px"
/>

customClass

自定义地址本的class类名，用于定制样式。

默认值：'address-modal'

使用示例：

<address-book-shell
  customClass="demo-address"
/>

noAddRecent

是否不需要添加最近联系人。设置该属性后，点击确定按钮不会将已选人员写入最近联系人。

使用示例：

<address-book-shell
  noAddRecent
/>

hiddenRecently

是否隐藏最近联系人模块。设置该属性后，地址本上将不再显示最近联系人模块。

使用示例：

<address-book-shell
  hiddenRecently
/>

footButton

自定义左下角功能按钮。

可选值：

• 'check'：查看当前名单（只有选择了部门或岗位才会显示，仅选择了人员不会显示）
• 'collect'：收藏当前名单（未开发完成）
• 'change'：本次变动名单（只有selected有值才会显示）

默认值：['check']

使用示例：

<address-book-shell
  :footButton="['check']"
/>

top

自定义地址本组件的margin-top值。

默认值：'7vh'

使用示例：

<address-book-shell
  top="7vh"
/>

robotsList

机器人数据，用于显示机器人模块。不传或传空数组时，不会显示机器人模块。

数据结构：

| 字段名 | 说明 | 类型 | | :--- | :--- | :--- | | add_im_group | 是否添加到IM群 | Number | | bottom_title | 底部按钮标题 | String | | chat_desc | 聊天描述 | String | | chat_tips | 聊天提示 | String | | ctime | 创建时间 | String | | hr_id | 机器人ID | String | | jump_url | 跳转链接 | String | | login_name | 登录名 | String | | status | 状态 | Number | | user_desc | 机器人描述 | String | | user_detail | 机器人详情 | String | | user_id | 用户ID | String | | user_image | 机器人头像 | String | | user_name | 机器人名称 | String |

使用示例：

// 机器人数据
robotsList: [
  {
    add_im_group: 1,
    bottom_title: "去咨询",
    chat_desc: "",
    chat_tips: "",
    ctime: "20230608102803",
    hr_id: "R00001",
    jump_url: "xxx",
    login_name: "iwenida",
    status: 1,
    user_desc: '智能知识助手，随时解答您的业务问题', 
    user_detail: "xxx",
    user_id: "",
    user_image: "xxx",
    user_name: "爱问i答"
  }
]

<address-book-shell
  :robotsList="robotsList"
/>

searchStatus

控制模糊搜索的权限范围。

取值说明：

• '1'：搜索全部
• '2'：仅内部
• '3'：仅合作方

默认值：长江e家默认'1'，web默认'2'

使用示例：

<address-book-shell
  searchStatus="1"
/>

defaultActiveMenu

自定义初始化时菜单默认选中项，值为部门ID（deptId）。

示例值：'C1'、'D794'

使用示例：

<address-book-shell
  defaultActiveMenu="C1"
/>

enableChangeConfirmation

是否开启人员变动超过5人时的弹窗提示功能。

说明：配置了该属性后，当人员变动超过5人时，点击确定按钮会弹出提示。但只有当地址本打开时已选人员列表selected有值时，才会显示该提示。

使用示例：

<address-book-shell
  enableChangeConfirmation
/>

queryCannotChooseLeader

配置是否不允许选择行政及党务领导。

取值说明：

• '0'或不配置：默认有权限勾选领导
• '1'：禁止勾选领导
• 'query'：通过接口查询权限

使用示例：

<!-- 通过接口查询是否有勾选行政及党务领导权限 -->
<address-book-shell
  queryCannotChooseLeader="query"
/>

属性总览

| 参数 | 说明 | 类型 | 可选值 | 默认值 | | :--- | :--- | :--- | :---: |:---: | | loginUserinfo | cas登录返回的用户信息(必传) | Object | - | {} | | selected | 地址本初始化默认选中的人员数据 | Array | - | [] | | selectDisabled | 是否将selected传入的人员置灰不能再选 | Boolean | - | false | | showOnlyNewPersonnel | 是否只展示新勾选的人员，默认值为0，取selectDisabled的值；值为1，展示全部人员；值为2，只展示新勾选的人员 | Number | 0,1,2 | 0 | | onlyOriginalData | 是否只需要原始勾选的数据(设置为true将勾选的数据直接返回;设置为false则会在submitted回调中返回 【仅人员数据,仅结构数据,勾选的原始数据】三个参数) | Boolean | - | false | | typeList | 用来控制模糊搜索下拉选项内容 | Array | [ '全部','部门' ,'岗位' ,'人员'] | ['全部','部门','岗位','人员'] | | onlyMailList | 是否只展示通讯录模块 | Boolean | - | false | | tabs | 自定义tabs的内容,如果不传或传空数组,将根据身份动态显示合适的模块 | Array | ['通讯录','合作方好友] | [] | | radio | 地址本是否只能单选 | Boolean | - | false | | title | 地址本标题 | String | - | 地址本 | | width | 地址本宽度 | String | - | 800px | | customClass | 地址本自定义类名 | String | - | address-modal | | noAddRecent | 是否不需要添加最近联系人 | Boolean | - | false | | hiddenRecently | 是否隐藏最近联系人模块 | Boolean | - | false | | footButton | 自定义功能按钮(check:查看当前名单;collect: 收藏当前名单;change: 本次变动名单) | Array | ['check','collect','change'] | ['check'] | | top | 地址本 CSS 中的 margin-top 值 | string | - | 7vh | | robotsList | 机器人数据,不传或传[],不会显示机器人模块 | Array | - | [] | | searchStatus | 搜索框权限控制 | String | '1':搜索全部;'2':仅内部;'3':仅合作方 | 长江e家默认'1',web默认'2' | | defaultActiveMenu | 菜单默认选中项 | String | - | | | enableChangeConfirmation | 人员变动超过5人 弹窗提示 | Boolean | - | false | | queryCannotChooseLeader | 配置是否不允许选择行政及党务领导 | String | '0','1','query' | '0' |

组件事件

注意:地址本组件继承了element-ui库Dialog组件的全部事件，即Dialog事件全部适用本组件。

submitted

点击地址本确定按钮的回调事件，根据是否配置onlyOriginalData属性返回不同的值。

回调参数：

• 当未配置onlyOriginalData或设置为false时：
  • person_data：人员数据，包含了部门和岗位中的人员
  • type_list：已选的结构数据，仅包含已选了部门和岗位，不包含人员数据
  • data：默认勾选的所有数据，包含勾选的人员、部门和岗位
• 当设置onlyOriginalData为true时：
  • data：默认勾选的所有数据，包含勾选的人员、部门和岗位

使用示例：

<address-book-shell
  @submitted="submitted"
/>

<script>
export default {
  methods: {
    submitted(personData, typeList, data) {
      console.log('人员数据:', personData)
      console.log('结构数据:', typeList)
      console.log('原始数据:', data)
    }
  }
}
</script>

<address-book-shell
  onlyOriginalData
  @submitted="submitted"
/>

<script>
export default {
  methods: {
    submitted(data) {
      console.log('原始数据:', data)
    }
  }
}
</script>

add

地址本勾选时触发的事件。

回调参数：

• data：新勾选的数据（数组）
• selectList：勾选的全部数据（数组）

使用示例：

<address-book-shell
  @add="add"
/>

<script>
export default {
  methods: {
    add(data, selectList) {
      console.log('新勾选的数据:', data)
      console.log('勾选的全部数据:', selectList)
    }
  }
}
</script>

remove

地址本取消勾选时触发的事件。

回调参数：

• data：取消勾选的数据（数组）
• selectList：勾选的全部数据（数组）

使用示例：

<address-book-shell
  @remove="remove"
/>

<script>
export default {
  methods: {
    remove(data, selectList) {
      console.log('取消勾选的数据:', data)
      console.log('勾选的全部数据:', selectList)
    }
  }
}
</script>

事件总览

组件自定义事件:

| 事件名称 | 说明 | 回调参数 | | :--- | :--- | :-- | | submitted | 点击确定按钮的回调 | [全部人员数据],[仅结构数据],[原始勾选数据] 或 [原始勾选数据]| | add | 新增勾选的回调 | [新增勾选数据],[勾选的全部数据] | | remove | 取消勾选的回调 | [取消勾选数据],[勾选的全部数据] |

内置功能

名单导入

名单导入通过调用接口查询权限开启，开启之后，可通过上传指定格式的excel表单选择人员。

常见问题

Q: 地址本组件无法正常显示怎么办？

A: 请检查以下几点：

1. 是否正确注册了组件并传入了 microserviceRequest 参数
2. 是否传入了 loginUserinfo 属性，且数据结构正确
3. 项目是否已接入CAS单点登录

Q: 选择部门或岗位后，点击确定按钮没有反应？

A: 请检查是否配置了 microserviceRequest 参数，该参数是调用接口将部门和岗位转化为人员数据的必要条件。

Q: 如何只显示通讯录模块？

A: 可以通过设置 onlyMailList 属性来实现：

<address-book-shell
  onlyMailList
/>

Q: 如何禁用默认选中数据的操作？

A: 可以通过设置 selectDisabled 属性来实现：

<address-book-shell
  selectDisabled
/>

Q: 如何开启单选模式？

A: 可以通过设置 radio 属性来实现：

<address-book-shell
  radio
/>