Hr Vue Next

---
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`