This skill provides guidance for using the hr-vue-next component library via UMD. It should be used when building HR-related web pages that require employee selectors, organization selectors, position selectors, and other HR-specific components. The skill covers UMD integration, component usage, and best practices for Vue 3 + TDesign + HR-Vue-Next development.
Scanned 9/8/2026
Install to Claude Code
Skills Directorynpx -y skills add infometa/workbuddyskills --skill hr-vue-next --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Hr Vue Next?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/infometa-hr-vue-next)More formats (shields.io, HTML) on the badges page.
---
name: hr-vue-next
description: This skill provides guidance for using the hr-vue-next component library via UMD. It should be used when building HR-related web pages that require employee selectors, organization selectors, position selectors, and other HR-specific components. The skill covers UMD integration, component usage, and best practices for Vue 3 + TDesign + HR-Vue-Next development.
---
# 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 中引入依赖（顺序严格）：
```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>` | 员工选择器 | [详情](assets/hr-staff-selector.md) |
| HrUnitSelector | `<hr-unit-selector>` | 组织选择器 | [详情](assets/hr-unit-selector.md) |
| HrPostSelector | `<hr-post-selector>` | 岗位选择器 | [详情](assets/hr-post-selector.md) |
| HrDictSelector | `<hr-dict-selector>` | 基础字典选择器 | [详情](assets/hr-dict-selector.md) |
| HrContractCompanySelector | `<hr-contract-company-selector>` | 合同公司选择器 | [详情](assets/hr-contract-company-selector.md) |
| HrAreaSelector | `<hr-area-selector>` | 工作地选择器 | [详情](assets/hr-area-selector.md) |
| HrCitySelector | `<hr-city-selector>` | 省市选择器 | [详情](assets/hr-city-selector.md) |
| HrManageSubjectSelector | `<hr-manage-subject-selector>` | 管理主体选择器 | [详情](assets/hr-manage-subject-selector.md) |
| HrOfficeBuildingSelector | `<hr-office-building-selector>` | 办公大厦选择器 | [详情](assets/hr-office-building-selector.md) |
| HrPositionCascader | `<hr-position-cascader>` | 职位级联选择器 | [详情](assets/hr-position-cascader.md) |
| HrPositionLevel | `<hr-position-level>` | 职级选择器 | [详情](assets/hr-position-level.md) |
| HrStaffSubtypeSelector | `<hr-staff-subtype-selector>` | 员工子类型选择器 | [详情](assets/hr-staff-subtype-selector.md) |
### 通用组件 (8 个)
| 组件 | 标签 | 说明 | 文档 |
|------|------|------|------|
| HrAvatar | `<hr-avatar>` | 头像组件 | [详情](assets/hr-avatar.md) |
| HrLangSwitch | `<hr-lang-switch>` | 语言切换 | [详情](assets/hr-lang-switch.md) |
| HrWecom | `<hr-wecom>` | 企微组件 | [详情](assets/hr-wecom.md) |
| HrPrivacySwitch | `<hr-privacy-switch>` | 隐私开关 | [详情](assets/hr-privacy-switch.md) |
| HrCountdownButton | `<hr-countdown-button>` | 倒计时按钮 | [详情](assets/hr-countdown-button.md) |
| HrTextOverflow | `<hr-text-overflow>` | 文本溢出 | [详情](assets/hr-text-overflow.md) |
| HrPageFooter | `<hr-page-footer>` | 页脚组件 | [详情](assets/hr-page-footer.md) |
| HrPageHeader | `<hr-page-header>` | 页头组件 | [详情](assets/hr-page-header.md) |
**查阅详细组件 API**：根据需要读取 `assets/` 目录下对应的组件文档。
## 常用组件示例
### 员工选择器
```html
<!-- 单选 -->
<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 |
### 组织选择器
```html
<!-- 单选 -->
<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-组
### 岗位选择器
```html
<hr-post-selector
v-model="selectedPost"
placeholder="请选择岗位"
:unit-id="100"
:filter-enable-flag="true"
></hr-post-selector>
```
### 字典选择器
```html
<hr-dict-selector
v-model="selectedDict"
dict-type="staff_type"
placeholder="请选择员工类型"
></hr-dict-selector>
```
### 头像组件
```html
<!-- 基础用法 -->
<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 |
### 页头组件
```html
<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 中定义数据：
```javascript
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 | 搜索时触发 | 输入值 |
### 页脚组件
```html
<!-- 基础用法 -->
<hr-page-footer />
<!-- 自定义部门和联系人 -->
<hr-page-footer
department="人力资源平台部"
username="cxyxhhuang(黄鑫杰)"
/>
```
**页脚组件属性：**
| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| department | 业务部门 | String | — |
| username | 联系人名称 | String | 小T(连线HR) |
## 组件实例方法
使用 `ref` 获取组件实例，调用内置方法：
```javascript
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` 下配置全局变量，默认使用生产环境：
```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:端口号`
### 跨域问题
请求远程数据时出现跨域错误：直接访问跨域链接进行登录，登录后返回页面刷新即可。
## 多语言配置（可选）
```html
<!-- 引入 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>
```
切换语言：
```javascript
localStorage.setItem('hr-sys-def-lang', 'en'); // 或 'zh-CN'
location.reload();
```
## 常见错误
### 引入顺序错误
```html
<!-- ❌ 错误：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>
```
### 注册顺序错误
```javascript
// ❌ 错误：未注册 TDesign
app.use(window.HrVueNext).mount('#app');
// ✅ 正确：先注册 TDesign
app.use(TDesign).use(window.HrVueNext).mount('#app');
```
### 初始值设置无效
```javascript
// ❌ 错误：直接修改 v-model
selectedStaff.value = '12345';
// ✅ 正确：使用 setSelected 方法
selectorRef.value.setSelected({
staffId: '12345',
staffName: '张三',
unitName: '技术部'
});
```
## 参考资源
- **组件总览**：[assets/hr-vue-next-components-index.md](assets/hr-vue-next-components-index.md)
- **UMD 文件**：`assets/hr-vue-next.min.js` 和 `assets/hr-vue-next.min.css`
- **各组件详细文档**：`assets/hr-*.md`
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
