@blueking/bk-user-selector 0.0.39-beta.3 → 0.1.0

package/README.md

@@ -2,26 +2,39 @@
 
 [![npm version](https://badge.fury.io/js/%40blueking%2Fbk-user-selector.svg)](https://badge.fury.io/js/%40blueking%2Fbk-user-selector)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Vue2](https://img.shields.io/badge/Vue-2.x-brightgreen.svg)](https://vuejs.org/)
+[![Vue3](https://img.shields.io/badge/Vue-3.x-brightgreen.svg)](https://vuejs.org/)
 
 蓝鲸多租户人员选择器（BkUserSelector）是一个用于在蓝鲸系统中选择用户的组件，支持单选和多选模式，具备搜索、跨租户查询等功能。
 
-## 特性
+## ✨ 特性
 
-- 支持 Vue2 和 Vue3 双版本
-- 支持单选和多选模式
-- 支持用户搜索功能
-- 支持跨租户显示
-- 支持拖拽排序（多选模式）
-- 支持快速选择当前用户
-- 支持用户组显示
+| 特性              | 说明                                 |
+| ----------------- | ------------------------------------ |
+| 🎯 **双版本支持** | 同时支持 Vue2 和 Vue3                |
+| 🔄 **单选/多选**  | 灵活切换单选和多选模式               |
+| 🔍 **智能搜索**   | 支持用户名、登录名、全名等多字段搜索 |
+| 🏢 **跨租户**     | 支持多租户场景下的用户选择和显示     |
+| 🎨 **可拖拽**     | 多选模式下支持拖拽排序               |
+| ⚡ **快捷操作**   | 支持快速选择当前用户（"我"）         |
+| 👥 **用户组**     | 支持用户组/角色分组显示              |
+| ✏️ **自定义输入** | 支持创建自定义用户和自由粘贴         |
+| 🎭 **自定义渲染** | 支持自定义标签和列表项渲染           |
 
-## 安装
+## 📦 安装
 
 ```bash
+# npm
 npm install @blueking/bk-user-selector
+
+# yarn
+yarn add @blueking/bk-user-selector
+
+# pnpm
+pnpm add @blueking/bk-user-selector
 ```
 
-## 使用方法
+## 🚀 快速开始
 
 ### 在 Vue3 中使用
 
@@ -49,6 +62,8 @@ export default {
 };
 ```
 
+## 📖 使用示例
+
 ### 基本用法
 
 ```vue
@@ -59,7 +74,6 @@ export default {
     :api-base-url="apiBaseUrl"
     :tenant-id="tenantId"
     :current-user-id="currentUserId"
-    :exact-search-key="exactSearchKey"
     @change="handleUserChange"
   />
 
@@ -69,11 +83,8 @@ export default {
     :api-base-url="apiBaseUrl"
     :tenant-id="tenantId"
     :current-user-id="currentUserId"
-    :exact-search-key="exactSearchKey"
     :multiple="true"
     :draggable="true"
-    :user-group="userGroup"
-    :user-group-name="userGroupName"
     @change="handleUsersChange"
   />
 </template>
@@ -81,124 +92,339 @@ export default {
 <script setup>
   import { ref } from 'vue';
 
-  // API 基础路径
   const apiBaseUrl = ref('https://api.example.com');
-  // 租户 ID
   const tenantId = ref('default');
-  // 当前用户ID
   const currentUserId = ref('admin');
-  // 精确查找key
-  const exactSearchKey = ref('bk_username');
+
   // 单选选中值
   const selectedUser = ref('');
   // 多选选中值
   const selectedUsers = ref([]);
-  // 用户组, hidden 为 true 时，不会展示在下拉列表里，但回显时会展示
+
+  const handleUserChange = user => {
+    console.log('Selected user:', user);
+  };
+
+  const handleUsersChange = users => {
+    console.log('Selected users:', users);
+  };
+</script>
+```
+
+### 用户组/角色模式
+
+当需要在下拉列表中展示用户组（如角色、部门等）时：
+
+```vue
+<template>
+  <BkUserSelector
+    v-model="selectedUsers"
+    :api-base-url="apiBaseUrl"
+    :tenant-id="tenantId"
+    :multiple="true"
+    :user-group="userGroup"
+    :user-group-name="userGroupName"
+    @change="handleChange"
+  />
+</template>
+
+<script setup>
+  import { ref } from 'vue';
+
+  const apiBaseUrl = ref('https://api.example.com');
+  const tenantId = ref('default');
+  const selectedUsers = ref([]);
+
+  // 用户组配置
   const userGroup = ref([
     {
       id: '1',
       name: '运维人员',
-      hidden: true,
+      hidden: true, // hidden 为 true 时，不会展示在下拉列表里，但回显时会展示
     },
     {
       id: '2',
       name: '产品人员',
     },
   ]);
-  // 用户组名称
   const userGroupName = ref('角色');
 
-  // 处理单选模式下的值变化
-  const handleUserChange = user => {
-    console.log('Selected user:', user);
+  const handleChange = users => {
+    console.log('Selected:', users);
   };
+</script>
+```
 
-  // 处理多选模式下的值变化
-  const handleUsersChange = users => {
-    console.log('Selected users:', users);
+### 自定义渲染
+
+支持自定义标签和列表项的渲染：
+
+```vue
+<template>
+  <BkUserSelector
+    v-model="selectedUsers"
+    :api-base-url="apiBaseUrl"
+    :tenant-id="tenantId"
+    :multiple="true"
+    :render-tag="renderTag"
+    :render-list-item="renderListItem"
+  />
+</template>
+
+<script setup>
+  import { ref, h } from 'vue';
+
+  const apiBaseUrl = ref('https://api.example.com');
+  const tenantId = ref('default');
+  const selectedUsers = ref([]);
+
+  // 自定义标签渲染
+  const renderTag = (createElement, userInfo) => {
+    return createElement('span', { class: 'custom-tag' }, [
+      createElement('img', { src: userInfo.logo, class: 'avatar' }),
+      userInfo.display_name,
+    ]);
+  };
+
+  // 自定义列表项渲染
+  const renderListItem = (createElement, userInfo) => {
+    return createElement('div', { class: 'custom-item' }, [
+      createElement('img', { src: userInfo.logo, class: 'avatar' }),
+      createElement('div', { class: 'info' }, [
+        createElement('span', { class: 'name' }, userInfo.display_name),
+        createElement('span', { class: 'username' }, `@${userInfo.username}`),
+      ]),
+    ]);
+  };
+</script>
+```
+
+### 自定义输入
+
+当 API 无法覆盖所有用户时，允许用户自定义输入：
+
+```vue
+<template>
+  <BkUserSelector
+    v-model="selectedUsers"
+    :api-base-url="apiBaseUrl"
+    :tenant-id="tenantId"
+    :multiple="true"
+    :allow-create="true"
+    :free-paste="true"
+    placeholder="输入用户名，按 Enter 确认"
+    @change="handleChange"
+  />
+</template>
+
+<script setup>
+  import { ref } from 'vue';
+
+  const apiBaseUrl = ref('https://api.example.com');
+  const tenantId = ref('default');
+  const selectedUsers = ref([]);
+
+  const handleChange = users => {
+    // 自定义输入的用户 id 为输入的文本
+    console.log('Selected:', users);
   };
 </script>
 ```
 
-## API
-
-### 属性
-
-| 参数                  | 说明                                                                    | 类型                           | 默认值             |
-| --------------------- | ----------------------------------------------------------------------- | ------------------------------ | ------------------ |
-| modelValue / v-model  | 绑定值，单选为字符串，多选为数组                                        | String / Array                 | '' / []            |
-| apiBaseUrl            | API 基础 URL                                                            | String                         | ''                 |
-| tenantId              | 租户 ID                                                                 | String                         | ''                 |
-| label                 | 文本标签                                                                | String                         | 人员选择           |
-| placeholder           | 占位文本                                                                | String                         | 请输入人员名称搜索 |
-| multiple              | 是否多选                                                                | Boolean                        | false              |
-| draggable             | 是否可拖拽（仅多选模式有效）                                            | Boolean                        | false              |
-| exactSearchKey        | 精确查找key,可选值为 bk_username、login_name、full_name, 多个以逗号分隔 | String                         | bk_username        |
-| currentUserId         | 当前用户ID（用于快速选择"我"）                                          | String                         | ''                 |
-| userGroup             | 用户组列表，用于在下拉列表中显示用户组                                  | Array                          | []                 |
-| userGroupName         | 用户组名称，用于在下拉列表中显示用户组名称                              | String                         | 用户群组           |
-| emptyText             | 无匹配人员时的提示文本                                                  | String                         | 无匹配人员         |
-| disabled              | 是否禁用                                                                | Boolean                        | false              |
-| renderTag             | 渲染标签                                                                | Function(h, userInfo) => VNode | -                  |
-| renderListItem        | 渲染列表项                                                              | Function(h, userInfo) => VNode | -                  |
-| excludeUserIds        | 排除的用户ID列表                                                        | Array                          | []                 |
-| enableMultiTenantMode | 是否启用多租户模式，关闭后则使用原有用户管理接口查询                    | Boolean                        | true               |
-| allowCreate           | 是否允许自定义用户输入，按 Enter 确认                                   | Boolean                        | false              |
-| freePaste             | 是否允许粘贴任意文本                                                    | Boolean                        | false              |
-
-### 事件
-
-| 事件名称          | 说明                 | 回调参数         |
-| ----------------- | -------------------- | ---------------- |
-| update:modelValue | 绑定值变化时触发     | 变化后的值       |
-| change            | 选中值变化时触发     | 变化后的用户信息 |
-| focus             | 输入框获得焦点时触发 | -                |
-| blur              | 输入框失去焦点时触发 | -                |
-
-## 功能说明
+### 排除指定用户
+
+从下拉列表中排除特定用户：
+
+```vue
+<template>
+  <BkUserSelector
+    v-model="selectedUser"
+    :api-base-url="apiBaseUrl"
+    :tenant-id="tenantId"
+    :exclude-user-ids="excludeUserIds"
+  />
+</template>
+
+<script setup>
+  import { ref } from 'vue';
+
+  const apiBaseUrl = ref('https://api.example.com');
+  const tenantId = ref('default');
+  const selectedUser = ref('');
+
+  // 排除这些用户，不会出现在搜索结果中
+  const excludeUserIds = ref(['user1', 'user2', 'user3']);
+</script>
+```
+
+## 📋 API 文档
+
+### Props 属性
+
+| 参数                  | 说明                              | 类型                                             | 默认值                 | 必填 |
+| --------------------- | --------------------------------- | ------------------------------------------------ | ---------------------- | ---- |
+| modelValue / v-model  | 绑定值，单选为字符串，多选为数组  | `string` / `string[]`                            | `''` / `[]`            | 是   |
+| apiBaseUrl            | API 基础 URL                      | `string`                                         | `''`                   | 是   |
+| tenantId              | 租户 ID                           | `string`                                         | `''`                   | 是   |
+| label                 | 文本标签                          | `string`                                         | `'人员选择'`           | 否   |
+| placeholder           | 占位文本                          | `string`                                         | `'请输入人员名称搜索'` | 否   |
+| multiple              | 是否多选                          | `boolean`                                        | `false`                | 否   |
+| draggable             | 是否可拖拽排序（仅多选模式有效）  | `boolean`                                        | `false`                | 否   |
+| exactSearchKey        | 精确查找 key                      | `'bk_username'` / `'login_name'` / `'full_name'` | `'bk_username'`        | 否   |
+| currentUserId         | 当前用户 ID（用于快速选择"我"）   | `string`                                         | `''`                   | 否   |
+| userGroup             | 用户组列表                        | `UserGroupItem[]`                                | `[]`                   | 否   |
+| userGroupName         | 用户组分类名称                    | `string`                                         | `'用户群组'`           | 否   |
+| emptyText             | 无匹配人员时的提示文本            | `string`                                         | `'无匹配人员'`         | 否   |
+| disabled              | 是否禁用                          | `boolean`                                        | `false`                | 否   |
+| renderTag             | 自定义标签渲染函数                | `(h, userInfo) => VNode`                         | -                      | 否   |
+| renderListItem        | 自定义列表项渲染函数              | `(h, userInfo) => VNode`                         | -                      | 否   |
+| excludeUserIds        | 排除的用户 ID 列表                | `string[]`                                       | `[]`                   | 否   |
+| enableMultiTenantMode | 是否启用多租户模式                | `boolean`                                        | `true`                 | 否   |
+| allowCreate           | 是否允许自定义输入，按 Enter 确认 | `boolean`                                        | `false`                | 否   |
+| freePaste             | 是否允许粘贴任意文本              | `boolean`                                        | `false`                | 否   |
+| maxCount              | 最大可选数量（0 表示不限制）      | `number`                                         | `0`                    | 否   |
+
+#### exactSearchKey 说明
+
+支持多个字段组合搜索，以逗号分隔：
+
+| 值                      | 说明                   |
+| ----------------------- | ---------------------- |
+| `bk_username`           | 按蓝鲸用户名搜索       |
+| `login_name`            | 按登录名搜索           |
+| `full_name`             | 按全名搜索             |
+| `bk_username,full_name` | 同时按用户名和全名搜索 |
+
+### Events 事件
+
+| 事件名称          | 说明                 | 回调参数                             |
+| ----------------- | -------------------- | ------------------------------------ |
+| update:modelValue | 绑定值变化时触发     | `(value: string \| string[])`        |
+| change            | 选中值变化时触发     | `(userInfo: UserInfo \| UserInfo[])` |
+| focus             | 输入框获得焦点时触发 | `(event: FocusEvent)`                |
+| blur              | 输入框失去焦点时触发 | `(event: FocusEvent)`                |
+
+### 类型定义
+
+```typescript
+// 用户信息
+interface UserInfo {
+  id: string; // 用户 ID
+  username: string; // 用户名
+  display_name: string; // 显示名称
+  logo?: string; // 头像 URL
+  tenant_id?: string; // 租户 ID
+  // ... 其他字段
+}
+
+// 用户组项
+interface UserGroupItem {
+  id: string; // 用户组 ID
+  name: string; // 用户组名称
+  hidden?: boolean; // 是否隐藏（不在下拉列表显示，但会在回显时展示）
+}
+
+// 自定义渲染函数
+type RenderFunction = (
+  h: CreateElement, // Vue createElement 函数
+  userInfo: UserInfo, // 用户信息
+) => VNode;
+```
+
+## 💡 功能说明
 
 ### 快速选择"我"
 
-当设置了`currentUserId`属性后，组件会在输入框右侧显示一个"我"的标签。点击该标签可以快速选择当前用户，无需手动搜索。
+当设置了 `currentUserId` 属性后，组件会在输入框右侧显示一个"我"的标签：
 
-- 在单选模式下，点击"我"会直接选中当前用户
-- 在多选模式下，点击"我"会将当前用户添加到已选列表中（如果尚未选择）
-- 当当前用户已被选中时，"我"标签会显示为灰色且不可点击
+- **单选模式**：点击"我"直接选中当前用户
+- **多选模式**：点击"我"将当前用户添加到已选列表
+- **状态反馈**：当前用户已被选中时，"我"标签显示为灰色且不可点击
 
 ### 用户组显示
 
-当设置了`userGroup`属性后，组件会在下拉列表中显示用户组信息。用户组数据格式如下：
+当设置了 `userGroup` 属性后：
+
+- 用户组会显示在下拉列表的独立分组中（默认名称为"用户群组"）
+- 用户组数据优先展示在列表顶部
+- 聚焦时会自动展示下拉框
+- 设置 `hidden: true` 的用户组不会在下拉列表中显示，但选中后会正常回显
+
+### 多租户模式
+
+通过 `enableMultiTenantMode` 控制：
+
+- **开启（默认）**：使用多租户用户管理接口查询，支持跨租户显示
+- **关闭**：使用原有用户管理接口查询
+
+### 拖拽排序
+
+在多选模式下启用 `draggable`：
+
+- 支持拖拽调整已选用户的顺序
+- 拖拽时会有视觉反馈
+- 拖拽完成后会触发 `change` 事件
+
+## ⚠️ 注意事项
+
+1. **API 配置**：使用前必须正确配置 `apiBaseUrl` 和 `tenantId`
+2. **CSS 引入**：记得引入对应版本的样式文件
+3. **v-model 类型**：
+   - 单选模式：`v-model` 应为 `string` 类型
+   - 多选模式：`v-model` 应为 `string[]` 类型
+4. **跨租户显示**：跨租户用户会在名称旁显示租户标识
+5. **自定义输入**：启用 `allowCreate` 后，用户输入的内容会作为 `id` 值
+
+## ❓ FAQ
+
+### Q: 组件没有样式怎么办？
+
+A: 请确保引入了对应版本的 CSS 文件：
 
 ```javascript
-const userGroup = [
-  {
-    id: '1',
-    name: '运维人员',
-  },
-  {
-    id: '2',
-    name: '产品人员',
-  },
-];
+// Vue3
+import '@blueking/bk-user-selector/vue3/vue3.css';
+
+// Vue2
+import '@blueking/bk-user-selector/vue2/vue2.css';
 ```
 
-- 用户组会显示在下拉列表的"用户群组"分组中
-- 用户组数据会展示在最前面
-- 有用户组信息，focus 时就会展示下拉框
+### Q: 如何禁止选择某些用户？
+
+A: 使用 `excludeUserIds` 属性传入需要排除的用户 ID 数组。
 
-## 开发
+### Q: 如何获取完整的用户信息？
+
+A: 通过 `change` 事件获取，它会返回完整的用户信息对象，而不仅仅是 ID。
+
+### Q: 多选模式下如何限制选择数量？
+
+A: 目前组件暂不支持直接限制，可以通过 `change` 事件监听并在超出数量时给出提示。
+
+### Q: 搜索没有结果怎么办？
+
+A: 检查以下几点：
+
+1. `apiBaseUrl` 和 `tenantId` 是否正确配置
+2. 网络请求是否正常
+3. 搜索关键词是否匹配 `exactSearchKey` 配置的字段
+
+## 🛠️ 开发
 
 ```bash
 # 安装依赖
-npm install
+pnpm install
 
 # 开发模式
-npm run dev
+pnpm run dev
 
 # 构建
-npm run build
+pnpm run build
+
+# 类型检查
+pnpm run type-check
 ```
 
-## 许可证
+## 📄 许可证
 
-MIT
+[MIT](./LICENSE) © 蓝鲸智云

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/bk-user-selector",
-  "version": "0.0.39-beta.3",
+  "version": "0.1.0",
   "description": "蓝鲸用户选择器",
   "license": "MIT",
   "author": "Tencent BlueKing",
@@ -10,7 +10,7 @@
     "build": "tsx ./scripts/vite.build.ts",
     "dts": "vue-tsc --project tsconfig.dts.json",
     "prettier": "prettier ./src ./scripts ./playground --write",
-    "visualize": "vite-bundle-visualizer -c scripts/vite.vusualizer.ts"
+    "visualize": "vite-bundle-visualizer -c scripts/vite.visualizer.ts"
   },
   "exports": {
     ".": {

package/typings/api/user.d.ts

@@ -7,33 +7,45 @@ import type { FormattedUser, Tenant, User } from '../types';
  */
 export declare const getTenants: (apiBaseUrl: string, tenantId: string) => Promise<Tenant[]>;
 /**
- * 模糊搜索用户
- * @param apiBaseUrl - API基础URL
- * @param tenantId - 租户ID
- * @param keyword - 搜索关键词
- * @returns 用户列表Promise
+ * 搜索用户参数
  */
-export declare const searchUsers: (params: {
+export interface SearchUsersParams {
+    /** API 基础 URL */
     apiBaseUrl: string;
+    /** 是否启用多租户模式 */
     enableMultiTenantMode?: boolean;
+    /** 搜索关键词 */
     keyword: string;
+    /** 租户 ID */
     tenantId: string;
-}) => Promise<User[]>;
+}
 /**
- * 批量精准查找用户
- * @param apiBaseUrl - API基础URL
- * @param tenantId - 租户ID
- * @param users - 用户名列表
- * @param exactSearchKey - 精确查找key
- * @returns 查找到的用户列表Promise
+ * 模糊搜索用户
+ * @param params - 搜索参数
+ * @returns 用户列表Promise
  */
-export declare const lookupUsers: (params: {
+export declare const searchUsers: (params: SearchUsersParams) => Promise<User[]>;
+/**
+ * 批量查找用户参数
+ */
+export interface LookupUsersParams {
+    /** API 基础 URL */
     apiBaseUrl: string;
+    /** 是否启用多租户模式 */
     enableMultiTenantMode?: boolean;
+    /** 精确查找字段 */
     exactSearchKey: string;
+    /** 租户 ID */
     tenantId: string;
+    /** 用户名列表 */
     usersList: string[];
-}) => Promise<User[]>;
+}
+/**
+ * 批量精准查找用户
+ * @param params - 查找参数
+ * @returns 查找到的用户列表Promise
+ */
+export declare const lookupUsers: (params: LookupUsersParams) => Promise<User[]>;
 /**
  * 将API返回的用户数据格式化为组件所需格式
  * @param users - API返回的用户列表
@@ -41,15 +53,24 @@ export declare const lookupUsers: (params: {
  */
 export declare const formatUsers: (users: User[], enableMultiTenantMode?: boolean) => FormattedUser[];
 /**
- * 获取用户列表 兼容旧版本的人员选择器
- * @param url 请求的 URL
- * @param params 请求参数
- * @returns 用户列表
+ * 获取用户列表参数（兼容旧版本）
  */
-export declare const getUserList: (url: string, params: {
+export interface GetUserListParams {
+    /** 应用代码 */
     appCode?: string;
+    /** 搜索关键词 */
     keyword?: string;
+    /** 页码 */
     page?: number;
+    /** 分页大小 */
     pageSize?: number;
+    /** 用户 ID 列表 */
     userIds?: string[];
-}) => Promise<User[]>;
+}
+/**
+ * 获取用户列表（兼容旧版本的人员选择器）
+ * @param url - 请求的 URL
+ * @param params - 请求参数
+ * @returns 用户列表
+ */
+export declare const getUserList: (url: string, params: GetUserListParams) => Promise<User[]>;

package/typings/components/me-tag.vue.d.ts

@@ -1,39 +1,18 @@
-declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
-    /**
-     * 当前用户ID
-     */
-    currentUserId: {
-        type: StringConstructor;
-        default: string;
-    };
-    /**
-     * 是否禁用
-     */
-    isDisabled: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    click: (...args: any[]) => void;
-}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
-    /**
-     * 当前用户ID
-     */
-    currentUserId: {
-        type: StringConstructor;
-        default: string;
-    };
-    /**
-     * 是否禁用
-     */
-    isDisabled: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>> & Readonly<{
-    onClick?: ((...args: any[]) => any) | undefined;
+/**
+ * 组件属性
+ */
+interface MeTagProps {
+    /** 当前用户ID */
+    currentUserId?: string;
+    /** 是否禁用 */
+    isDisabled?: boolean;
+}
+declare const _default: import("vue").DefineComponent<MeTagProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    click: () => any;
+}, string, import("vue").PublicProps, Readonly<MeTagProps> & Readonly<{
+    onClick?: (() => any) | undefined;
 }>, {
     currentUserId: string;
     isDisabled: boolean;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;