@blueking/bk-user-selector 0.0.1-beta.2 → 0.0.2-9.beta.1

package/README.md

@@ -1 +1,199 @@
-### 人员选择器
+# 蓝鲸多租户人员选择器组件
+
+[![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)
+
+蓝鲸多租户人员选择器（BkUserSelector）是一个用于在蓝鲸系统中选择用户的组件，支持单选和多选模式，具备搜索、跨租户查询等功能。
+
+## 特性
+
+- 支持 Vue2 和 Vue3 双版本
+- 支持单选和多选模式
+- 支持用户搜索功能
+- 支持跨租户显示
+- 支持拖拽排序（多选模式）
+- 支持快速选择当前用户
+- 支持用户组显示
+
+## 安装
+
+```bash
+npm install @blueking/bk-user-selector
+```
+
+## 使用方法
+
+### 在 Vue3 中使用
+
+```javascript
+import BkUserSelector from '@blueking/bk-user-selector';
+import '@blueking/bk-user-selector/vue3/vue3.css';
+
+export default {
+  components: {
+    BkUserSelector,
+  },
+};
+```
+
+### 在 Vue2 中使用
+
+```javascript
+import BkUserSelector from '@blueking/bk-user-selector/vue2';
+import '@blueking/bk-user-selector/vue2/vue2.css';
+
+export default {
+  components: {
+    BkUserSelector,
+  },
+};
+```
+
+### 基本用法
+
+```vue
+<template>
+  <!-- 单选模式 -->
+  <BkUserSelector
+    v-model="selectedUser"
+    :api-base-url="apiBaseUrl"
+    :tenant-id="tenantId"
+    :current-user-id="currentUserId"
+    :exact-search-key="exactSearchKey"
+    @change="handleUserChange"
+  />
+
+  <!-- 多选模式 -->
+  <BkUserSelector
+    v-model="selectedUsers"
+    :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>
+
+<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 userGroup = ref([
+    {
+      id: '1',
+      name: '运维人员',
+      hidden: true,
+    },
+    {
+      id: '2',
+      name: '产品人员',
+    },
+  ]);
+  // 用户组名称
+  const userGroupName = ref('角色');
+
+  // 处理单选模式下的值变化
+  const handleUserChange = user => {
+    console.log('Selected user:', user);
+  };
+
+  // 处理多选模式下的值变化
+  const handleUsersChange = users => {
+    console.log('Selected users:', 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                          | []                 |
+
+### 事件
+
+| 事件名称          | 说明             | 回调参数         |
+| ----------------- | ---------------- | ---------------- |
+| update:modelValue | 绑定值变化时触发 | 变化后的值       |
+| change            | 选中值变化时触发 | 变化后的用户信息 |
+
+## 功能说明
+
+### 快速选择"我"
+
+当设置了`currentUserId`属性后，组件会在输入框右侧显示一个"我"的标签。点击该标签可以快速选择当前用户，无需手动搜索。
+
+- 在单选模式下，点击"我"会直接选中当前用户
+- 在多选模式下，点击"我"会将当前用户添加到已选列表中（如果尚未选择）
+- 当当前用户已被选中时，"我"标签会显示为灰色且不可点击
+
+### 用户组显示
+
+当设置了`userGroup`属性后，组件会在下拉列表中显示用户组信息。用户组数据格式如下：
+
+```javascript
+const userGroup = [
+  {
+    id: '1',
+    name: '运维人员',
+  },
+  {
+    id: '2',
+    name: '产品人员',
+  },
+];
+```
+
+- 用户组会显示在下拉列表的"用户群组"分组中
+- 用户组数据会展示在最前面
+- 有用户组信息，focus 时就会展示下拉框
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式
+npm run dev
+
+# 构建
+npm run build
+```
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/bk-user-selector",
-  "version": "0.0.1-beta.2",
+  "version": "0.0.29.beta.1",
   "description": "蓝鲸用户选择器",
   "license": "MIT",
   "author": "Tencent BlueKing",
@@ -61,13 +61,9 @@
     "sortablejs": "^1.15.6"
   },
   "peerDependencies": {
-    "@blueking/bkui-library": "^0.0.0-beta.4",
-    "vue": "^3"
+    "@blueking/bkui-library": "^0.0.0-beta.4"
   },
   "engines": {
     "node": ">=18.16.0"
-  },
-  "devDependencies": {
-    "vite": "^6.2.2"
   }
 }

package/typings/api/user.d.ts

@@ -0,0 +1,55 @@
+import { type User, type Tenant, type FormattedUser } from '../types';
+/**
+ * 获取本租户所有数据来源的租户信息
+ * @param apiBaseUrl - API基础URL
+ * @param tenantId - 租户ID
+ * @returns 租户列表Promise
+ */
+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: {
+    apiBaseUrl: string;
+    tenantId: string;
+    keyword: string;
+    enableMultiTenantMode?: boolean;
+}) => Promise<User[]>;
+/**
+ * 批量精准查找用户
+ * @param apiBaseUrl - API基础URL
+ * @param tenantId - 租户ID
+ * @param users - 用户名列表
+ * @param exactSearchKey - 精确查找key
+ * @returns 查找到的用户列表Promise
+ */
+export declare const lookupUsers: (params: {
+    apiBaseUrl: string;
+    tenantId: string;
+    exactSearchKey: string;
+    usersList: string[];
+    enableMultiTenantMode?: boolean;
+}) => Promise<User[]>;
+/**
+ * 将API返回的用户数据格式化为组件所需格式
+ * @param users - API返回的用户列表
+ * @returns 格式化后的用户列表
+ */
+export declare const formatUsers: (users: User[]) => FormattedUser[];
+/**
+ * 获取用户列表 兼容旧版本的人员选择器
+ * @param url 请求的 URL
+ * @param params 请求参数
+ * @returns 用户列表
+ */
+export declare const getUserList: (url: string, params: {
+    userIds?: string[];
+    keyword?: string;
+    pageSize?: number;
+    page?: number;
+    appCode?: string;
+}) => Promise<User[]>;

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

@@ -0,0 +1,39 @@
+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;
+}>, {
+    currentUserId: string;
+    isDisabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/typings/components/multiple-selector.vue.d.ts

@@ -0,0 +1,33 @@
+import { FormattedUser, MultipleSelectorProps } from '../types';
+declare const _default: import("vue").DefineComponent<MultipleSelectorProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:selectedUsers": (...args: any[]) => void;
+    "add-user": (...args: any[]) => void;
+    "remove-user": (...args: any[]) => void;
+}, string, import("vue").PublicProps, Readonly<MultipleSelectorProps> & Readonly<{
+    "onUpdate:selectedUsers"?: ((...args: any[]) => any) | undefined;
+    "onAdd-user"?: ((...args: any[]) => any) | undefined;
+    "onRemove-user"?: ((...args: any[]) => any) | undefined;
+}>, {
+    tenantId: string;
+    apiBaseUrl: string;
+    exactSearchKey: string;
+    currentUserId: string;
+    tenants: Record<string, string>;
+    userGroup: {
+        id: string;
+        name: string;
+        hidden
+        /**
+         * 多选模式用户选择器组件
+         */
+        ?: boolean;
+    }[];
+    userGroupName: string;
+    emptyText: string;
+    draggable: boolean;
+    modelValue: string[];
+    selectedUsers: FormattedUser[];
+    placeholder: string;
+    excludeUserIds: string[];
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/typings/components/selection-popover.vue.d.ts

@@ -0,0 +1,205 @@
+/**
+ * 用户选择器下拉菜单组件
+ */
+import { createVNode, VNode } from 'vue';
+import { FormattedUser } from '../types';
+declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /**
+     * 是否显示下拉菜单
+     */
+    isShow: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * 容器宽度
+     */
+    containerWidth: {
+        type: (StringConstructor | NumberConstructor)[];
+        default: string;
+    };
+    /**
+     * popover crossAxis 偏移量
+     */
+    crossAxisOffset: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /**
+     * 是否加载中
+     */
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * 搜索结果选项
+     */
+    options: {
+        type: () => FormattedUser[];
+        default: () => never[];
+    };
+    /**
+     * 搜索关键词
+     */
+    searchQuery: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 当前租户ID
+     */
+    tenantId: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 租户信息映射
+     */
+    tenants: {
+        type: () => Record<string, string>;
+        default: () => {};
+    };
+    /**
+     * 用户组
+     */
+    userGroup: {
+        type: () => {
+            id: string;
+            name: string;
+            hidden?: boolean;
+        }[];
+        default: () => never[];
+    };
+    /**
+     * 用户组名称
+     */
+    userGroupName: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 无匹配人员时的提示文本
+     */
+    emptyText: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 渲染列表项
+     */
+    renderListItem: {
+        type: () => (h: typeof createVNode, item: FormattedUser) => VNode;
+    };
+}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "select-user": (...args: any[]) => void;
+    "click-outside": (...args: any[]) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /**
+     * 是否显示下拉菜单
+     */
+    isShow: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * 容器宽度
+     */
+    containerWidth: {
+        type: (StringConstructor | NumberConstructor)[];
+        default: string;
+    };
+    /**
+     * popover crossAxis 偏移量
+     */
+    crossAxisOffset: {
+        type: NumberConstructor;
+        default: number;
+    };
+    /**
+     * 是否加载中
+     */
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * 搜索结果选项
+     */
+    options: {
+        type: () => FormattedUser[];
+        default: () => never[];
+    };
+    /**
+     * 搜索关键词
+     */
+    searchQuery: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 当前租户ID
+     */
+    tenantId: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 租户信息映射
+     */
+    tenants: {
+        type: () => Record<string, string>;
+        default: () => {};
+    };
+    /**
+     * 用户组
+     */
+    userGroup: {
+        type: () => {
+            id: string;
+            name: string;
+            hidden?: boolean;
+        }[];
+        default: () => never[];
+    };
+    /**
+     * 用户组名称
+     */
+    userGroupName: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 无匹配人员时的提示文本
+     */
+    emptyText: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 渲染列表项
+     */
+    renderListItem: {
+        type: () => (h: typeof createVNode, item: FormattedUser) => VNode;
+    };
+}>> & Readonly<{
+    "onSelect-user"?: ((...args: any[]) => any) | undefined;
+    "onClick-outside"?: ((...args: any[]) => any) | undefined;
+}>, {
+    tenantId: string;
+    tenants: Record<string, string>;
+    isShow: boolean;
+    containerWidth: string | number;
+    crossAxisOffset: number;
+    loading: boolean;
+    options: FormattedUser[];
+    searchQuery: string;
+    userGroup: {
+        id: string;
+        name: string;
+        hidden?: boolean;
+    }[];
+    userGroupName: string;
+    emptyText: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/typings/components/single-selector.vue.d.ts

@@ -0,0 +1,28 @@
+import { SingleSelectorProps } from '../types';
+declare const _default: import("vue").DefineComponent<SingleSelectorProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    change: (...args: any[]) => void;
+    "update:modelValue": (...args: any[]) => void;
+}, string, import("vue").PublicProps, Readonly<SingleSelectorProps> & Readonly<{
+    onChange?: ((...args: any[]) => any) | undefined;
+    "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
+}>, {
+    tenantId: string;
+    apiBaseUrl: string;
+    exactSearchKey: string;
+    currentUserId: string;
+    userGroup: {
+        id: string;
+        name: string;
+        hidden
+        /**
+         * 单选模式用户选择器组件
+         */
+        ?: boolean;
+    }[];
+    userGroupName: string;
+    emptyText: string;
+    modelValue: string;
+    placeholder: string;
+    excludeUserIds: string[];
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/typings/components/user-render.d.ts

@@ -0,0 +1,37 @@
+import type { FormattedUser } from '../types';
+declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    user: {
+        type: () => FormattedUser;
+        required: true;
+    };
+    tenantId: {
+        type: StringConstructor;
+        required: true;
+    };
+    tenants: {
+        type: () => Record<string, string>;
+        required: true;
+    };
+    render: {
+        type: FunctionConstructor;
+        required: false;
+    };
+}>, () => any, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    user: {
+        type: () => FormattedUser;
+        required: true;
+    };
+    tenantId: {
+        type: StringConstructor;
+        required: true;
+    };
+    tenants: {
+        type: () => Record<string, string>;
+        required: true;
+    };
+    render: {
+        type: FunctionConstructor;
+        required: false;
+    };
+}>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/typings/components/user-selector.vue.d.ts

@@ -0,0 +1,33 @@
+import { UserSelectorProps } from '../types';
+declare const _default: import("vue").DefineComponent<UserSelectorProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    change: (...args: any[]) => void;
+    "update:modelValue": (...args: any[]) => void;
+}, string, import("vue").PublicProps, Readonly<UserSelectorProps> & Readonly<{
+    onChange?: ((...args: any[]) => any) | undefined;
+    "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
+}>, {
+    tenantId: string;
+    apiBaseUrl: string;
+    enableMultiTenantMode: boolean;
+    exactSearchKey: string;
+    currentUserId: string;
+    disabled: boolean;
+    userGroup: {
+        id: string;
+        name: string;
+        hidden
+        /**
+         * 蓝鲸用户选择器组件
+         * @module components/UserSelector
+         */
+        ?: boolean;
+    }[];
+    userGroupName: string;
+    emptyText: string;
+    draggable: boolean;
+    modelValue: string | string[];
+    placeholder: string;
+    excludeUserIds: string[];
+    multiple: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;