infometa HR-Vue-Next UMD 组件库使用指南
概述
@tencent/hr-vue-next 是腾讯内部人力资源平台专用的 Vue 3.x 桌面端组件库，包含 20 个企业级组件（12 个人事组件 + 8 个通用组件）。
适用场景：
- 无构建工具的项目（直接在 HTML 中引入）
- 快速原型开发
- 传统 Web 项目集成
技术栈： Vue 3.x + TDesign 设计规范
快速开始
组件方式引入
npm install @tencent/hr-vue-next
UMD 引入模板
如果是html使用，按以下顺序在 HTML 中引入依赖（顺序严格）：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>页面标题</title>
<!-- 1. 引入 Vue 3 (CDN) -->
<script src="https://unpkg.com/vue@3.5.27/dist/vue.global.js"></script>
<!-- 2. 引入 TDesign Vue Next CSS (CDN) -->
<link rel="stylesheet" href="https://unpkg.com/tdesign-vue-next@1.18.0/dist/tdesign.min.css">
<!-- 3. 引入 TDesign Vue Next JS (CDN) -->
<script src="https://unpkg.com/tdesign-vue-next@1.18.0/dist/tdesign.min.js"></script>
<!-- 4. HR-Vue-Next CSS (CDN) -->
<link rel="stylesheet" href="https://cdn.m.tencent.com/hr-web/hr-vue-next.min.css">
<!-- 5. HR-Vue-Next JS (CDN) -->
<script src="https://cdn.m.tencent.com/hr-web/hr-vue-next.min.js"></script>
</head>
<body>
<div id="app">
<!-- 页面内容 -->
</div>
<script>
const { createApp, ref, reactive } = Vue;
// 设置环境变量（必需），默认使用生产环境
window.SDC_BUILD_ENV = 'prd'; // 可选: test, uat, prd
createApp({
setup() {
// 响应式数据和方法
return {};
}
})
.use(TDesign) // 先注册 TDesign
.use(window.HrVueNext) // 再注册 HR-Vue-Next
.mount('#app');
</script>
</body>
</html>
引入检查清单
- ✅ Vue 3 CDN 已引入
- ✅ TDesign CSS 和 JS 已引入（CDN）
- ✅ HR-Vue-Next CSS 和 JS 已引入（CDN
https://cdn.m.tencent.com/hr-web/） - ✅ 引入顺序：Vue → TDesign → HR-Vue-Next
- ✅ 注册顺序：
.use(TDesign).use(HrVueNext) - ✅ 环境变量：
window.SDC_BUILD_ENV已设置（默认prd）
组件列表
人事组件 (12 个)
| 组件 | 标签 | 说明 | 文档 |
|---|---|---|---|
| HrStaffSelector | <hr-staff-selector> |
员工选择器 | 详情 |
| HrUnitSelector | <hr-unit-selector> |
组织选择器 | 详情 |
| HrPostSelector | <hr-post-selector> |
岗位选择器 | 详情 |
| HrDictSelector | <hr-dict-selector> |
基础字典选择器 | 详情 |
| HrContractCompanySelector | <hr-contract-company-selector> |
合同公司选择器 | 详情 |
| HrAreaSelector | <hr-area-selector> |
工作地选择器 | 详情 |
| HrCitySelector | <hr-city-selector> |
省市选择器 | 详情 |
| HrManageSubjectSelector | <hr-manage-subject-selector> |
管理主体选择器 | 详情 |
| HrOfficeBuildingSelector | <hr-office-building-selector> |
办公大厦选择器 | 详情 |
| HrPositionCascader | <hr-position-cascader> |
职位级联选择器 | 详情 |
| HrPositionLevel | <hr-position-level> |
职级选择器 | 详情 |
| HrStaffSubtypeSelector | <hr-staff-subtype-selector> |
员工子类型选择器 | 详情 |
通用组件 (8 个)
| 组件 | 标签 | 说明 | 文档 |
|---|---|---|---|
| HrAvatar | <hr-avatar> |
头像组件 | 详情 |
| HrLangSwitch | <hr-lang-switch> |
语言切换 | 详情 |
| HrWecom | <hr-wecom> |
企微组件 | 详情 |
| HrPrivacySwitch | <hr-privacy-switch> |
隐私开关 | 详情 |
| HrCountdownButton | <hr-countdown-button> |
倒计时按钮 | 详情 |
| HrTextOverflow | <hr-text-overflow> |
文本溢出 | 详情 |
| HrPageFooter | <hr-page-footer> |
页脚组件 | 详情 |
| HrPageHeader | <hr-page-header> |
页头组件 | 详情 |
查阅详细组件 API：根据需要读取 assets/ 目录下对应的组件文档。
常用组件示例
员工选择器
<!-- 单选 -->
<hr-staff-selector
v-model="selectedStaff"
placeholder="请选择员工"
show-full-tag
@change="handleChange"
></hr-staff-selector>
<!-- 多选 -->
<hr-staff-selector
v-model="selectedStaffs"
multiple
:include-dimission="true"
:include-on-boarding="true"
></hr-staff-selector>
<!-- 限制组织范围 -->
<hr-staff-selector
v-model="selectedStaff"
:range="{ unitId: 100, isContainSubStaff: true }"
></hr-staff-selector>
range 限制选项范围配置：
| 参数 | 说明 | 类型 |
|---|---|---|
| unitId | 组织Id，仅选择该组织下的子级员工 | Number/Array |
| contractCompanyIdList | 合同公司Id集合 | Array |
| isContainSubStaff | 是否包含子级员工 | Boolean |
| staffTypeIdList | 员工类型Id集合 | Array |
组织选择器
<!-- 单选 -->
<hr-unit-selector
v-model="selectedUnit"
placeholder="请选择组织"
@change="handleChange"
></hr-unit-selector>
<!-- 多选 -->
<hr-unit-selector
v-model="selectedUnits"
:multiple="true"
></hr-unit-selector>
<!-- 限制组织级别（仅公司、BG、线） -->
<hr-unit-selector
v-model="selectedUnit"
:include-unit-sort-ids="[0, 6, 8]"
:is-limit-unit-expand="true"
></hr-unit-selector>
组织级别说明： 0-公司, 6-BG, 8-线, 1-部门, 7-中心, 2-组
岗位选择器
<hr-post-selector
v-model="selectedPost"
placeholder="请选择岗位"
:unit-id="100"
:filter-enable-flag="true"
></hr-post-selector>
字典选择器
<hr-dict-selector
v-model="selectedDict"
dict-type="staff_type"
placeholder="请选择员工类型"
></hr-dict-selector>
头像组件
<!-- 基础用法 -->
<hr-avatar username="cxyxhhuang(黄鑫杰)"></hr-avatar>
<!-- 附加文本 -->
<hr-avatar
username="cxyxhhuang(黄鑫杰)"
extra-text="人力资源平台部"
></hr-avatar>
<!-- 指定尺寸 -->
<hr-avatar
username="cxyxhhuang(黄鑫杰)"
avatar-size="large"
></hr-avatar>
头像组件属性：
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| username | 用户名称 | String | — | — |
| extraText | 补充文本 | String | — | — |
| avatarSize | 头像尺寸 | String | small/medium/large | medium |
| avatarOnly | 是否只显示头像 | Boolean | — | false |
页头组件
<hr-page-header
:menu-list="menuList"
:active-menu="activeMenu"
logo-name="HR系统名称"
show-search
show-langswitch
:avatar-props="{ username: 'cxyxhhuang(黄鑫杰)' }"
@menu-item-click="handleMenuClick"
/>
在 setup 中定义数据：
setup() {
const activeMenu = ref('1')
const menuList = ref([
{ key: '1', text: '首页', link: '/' },
{ key: '2', text: '员工管理', link: '/staff' },
{ key: '3', text: '组织管理', link: '/organization' }
])
const handleMenuClick = (item) => {
console.log('点击菜单:', item)
}
return { activeMenu, menuList, handleMenuClick }
}
页头组件属性：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| logoSrc | Logo 图片链接 | String/Slot | — |
| logoName | Logo 名称 | String/Slot | — |
| menuList | 菜单列表 | Array | [] |
| activeMenu | 当前激活菜单项的 key | String/Number | — |
| navitationList | 导航列表（支持子菜单） | Array | [] |
| operationList | 用户信息下拉列表 | Array | [] |
| showSearch | 是否显示搜索 | Boolean | false |
| showLangswitch | 是否显示语言切换 | Boolean | false |
| avatarProps | 头像组件 props | Object | — |
menuList 菜单项结构：
| 参数 | 说明 | 类型 |
|---|---|---|
| key | 菜单唯一标识，用于激活状态匹配 | String/Number |
| text | 菜单名称 | String |
| link | 跳转链接 | String |
| target | 链接跳转方式 | String (_blank/_self) |
| onClick | 自定义点击方法 | Function |
页头组件事件：
| 事件名称 | 说明 | 回调参数 |
|---|---|---|
| menuItemClick | 点击菜单时触发 | 当前菜单 item |
| navigationClick | 点击导航时触发 | 当前导航 item |
| operationClick | 点击用户下拉菜单时触发 | 当前下拉菜单 item |
| onSearch | 搜索时触发 | 输入值 |
页脚组件
<!-- 基础用法 -->
<hr-page-footer />
<!-- 自定义部门和联系人 -->
<hr-page-footer
department="人力资源平台部"
username="cxyxhhuang(黄鑫杰)"
/>
页脚组件属性：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| department | 业务部门 | String | — |
| username | 联系人名称 | String | 小T(连线HR) |
组件实例方法
使用 ref 获取组件实例，调用内置方法：
setup() {
const selectorRef = ref(null);
// 设置初始值（推荐方式）
const setInitial = () => {
selectorRef.value?.setSelected({
staffId: '12345',
staffName: '张三',
unitName: '技术部'
});
};
// 清空选择
const clear = () => {
selectorRef.value?.clearSelected();
};
return { selectorRef, setInitial, clear };
}
注意：不要直接修改 v-model 值来设置初始选中项，使用 setSelected 方法。
环境配置
环境变量配置
需要在项目 public/index.html 下配置全局变量，默认使用生产环境：
<!-- 打包 test 环境 -->
<!-- window.SDC_BUILD_ENV = 'test'; -->
<!-- 打包 uat 环境 -->
<!-- window.SDC_BUILD_ENV = 'uat'; -->
<!-- 打包生产环境（默认） -->
window.SDC_BUILD_ENV = 'prd';
| 环境值 | 说明 |
|---|---|
test |
测试环境 |
uat |
预发布环境 |
prd |
生产环境（默认） |
Hosts 配置（本地开发必需）
在系统 hosts 文件中添加：
127.0.0.1 test.woa.com
文件位置：
- Windows:
C:\Windows\System32\drivers\etc\hosts - Mac/Linux:
/etc/hosts
访问地址
本地开发通过域名访问：http://test.woa.com:端口号
跨域问题
请求远程数据时出现跨域错误：直接访问跨域链接进行登录，登录后返回页面刷新即可。
多语言配置（可选）
<!-- 引入 Vue I18n -->
<script src="https://unpkg.com/vue-i18n@9/dist/vue-i18n.global.js"></script>
<script>
const { createI18n } = VueI18n;
const i18n = createI18n({
legacy: false,
locale: localStorage.getItem('hr-sys-def-lang') || 'zh-CN',
fallbackLocale: 'zh-CN',
messages: {
en: { /* 英文翻译 */ },
'zh-CN': { /* 中文翻译 */ }
}
});
// 挂载到 window
window.__i18n = i18n;
createApp({...})
.use(i18n)
.use(TDesign)
.use(window.HrVueNext)
.mount('#app');
</script>
切换语言：
localStorage.setItem('hr-sys-def-lang', 'en'); // 或 'zh-CN'
location.reload();
常见错误
引入顺序错误
<!-- ❌ 错误：HR-Vue-Next 在 TDesign 之前 -->
<script src="./hr-vue-next.min.js"></script>
<script src="https://unpkg.com/tdesign-vue-next/dist/tdesign.min.js"></script>
<!-- ✅ 正确：TDesign 在 HR-Vue-Next 之前 -->
<script src="https://unpkg.com/tdesign-vue-next/dist/tdesign.min.js"></script>
<script src="https://cdn.m.tencent.com/hr-web/hr-vue-next.min.js"></script>
注册顺序错误
// ❌ 错误：未注册 TDesign
app.use(window.HrVueNext).mount('#app');
// ✅ 正确：先注册 TDesign
app.use(TDesign).use(window.HrVueNext).mount('#app');
初始值设置无效
// ❌ 错误：直接修改 v-model
selectedStaff.value = '12345';
// ✅ 正确：使用 setSelected 方法
selectorRef.value.setSelected({
staffId: '12345',
staffName: '张三',
unitName: '技术部'
});
参考资源
- 组件总览：assets/hr-vue-next-components-index.md
- UMD 文件：
assets/hr-vue-next.min.js和assets/hr-vue-next.min.css - 各组件详细文档：
assets/hr-*.md