@blueking/bk-user-selector 0.0.1-beta.2 → 0.0.3

package/README.md

@@ -1 +1,149 @@
-### 人员选择器
+# 蓝鲸用户选择器组件
+
+蓝鲸用户选择器（BkUserSelector）是一个用于在蓝鲸系统中选择用户的组件，支持单选和多选模式，具备搜索、跨租户查询等功能。
+
+## 特性
+
+- 支持单选和多选模式
+- 支持用户搜索功能
+- 支持跨租户显示
+- 支持拖拽排序（多选模式）
+- 支持快速选择当前用户
+
+## 安装
+
+```bash
+npm install @blueking/bk-user-selector
+```
+
+## 使用方法
+
+### 在 Vue3 中使用
+
+```javascript
+// 全局注册
+import { createApp } from 'vue';
+import BkUserSelector from '@blueking/bk-user-selector';
+import '@blueking/bk-user-selector/vue3/vue3.css';
+
+const app = createApp(App);
+app.use(BkUserSelector);
+app.mount('#app');
+
+// 或者局部注册
+import { UserSelector } from '@blueking/bk-user-selector';
+
+export default {
+  components: {
+    BkUserSelector: UserSelector,
+  },
+};
+```
+
+### 在 Vue2 中使用
+
+```javascript
+import BkUserSelector from '@blueking/bk-user-selector/vue2';
+import '@blueking/bk-user-selector/vue2/vue2.css';
+```
+
+### 基本用法
+
+```vue
+<template>
+  <!-- 单选模式 -->
+  <BkUserSelector
+    v-model="selectedUser"
+    :api-base-url="apiBaseUrl"
+    :tenant-id="tenantId"
+    :current-user-id="currentUserId"
+    @change="handleUserChange"
+  />
+
+  <!-- 多选模式 -->
+  <BkUserSelector
+    v-model="selectedUsers"
+    :api-base-url="apiBaseUrl"
+    :tenant-id="tenantId"
+    :current-user-id="currentUserId"
+    :multiple="true"
+    :draggable="true"
+    @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'); 
+  // 单选选中值
+  const selectedUser = ref('');
+  // 多选选中值
+  const selectedUsers = ref([]);
+
+  // 处理单选模式下的值变化
+  const handleUserChange = user => {
+    console.log('Selected user:', user);
+  };
+
+  // 处理多选模式下的值变化
+  const handleUsersChange = users => {
+    console.log('Selected users:', users);
+  };
+</script>
+```
+
+## API
+
+### 属性
+
+| 参数                 | 说明                             | 类型           | 默认值               |
+| -------------------- | -------------------------------- | -------------- | -------------------- |
+| modelValue / v-model | 绑定值，单选为字符串，多选为数组 | String / Array | '' / []              |
+| label                | 文本标签                         | String         | '人员选择'           |
+| required             | 是否必填                         | Boolean        | false                |
+| placeholder          | 占位文本                         | String         | '请输入人员名称搜索' |
+| multiple             | 是否多选                         | Boolean        | false                |
+| draggable            | 是否可拖拽（仅多选模式有效）     | Boolean        | false                |
+| apiBaseUrl           | API 基础 URL                     | String         | ''                   |
+| tenantId             | 租户 ID                          | String         | ''                   |
+| currentUserId        | 当前用户ID（用于快速选择"我"）   | String         | ''                   |
+
+### 事件
+
+| 事件名称          | 说明             | 回调参数         |
+| ----------------- | ---------------- | ---------------- |
+| update:modelValue | 绑定值变化时触发 | 变化后的值       |
+| change            | 选中值变化时触发 | 变化后的用户信息 |
+
+## 功能说明
+
+### 快速选择"我"
+
+当设置了`currentUserId`属性后，组件会在输入框右侧显示一个"我"的标签。点击该标签可以快速选择当前用户，无需手动搜索。
+
+- 在单选模式下，点击"我"会直接选中当前用户
+- 在多选模式下，点击"我"会将当前用户添加到已选列表中（如果尚未选择）
+- 当当前用户已被选中时，"我"标签会显示为灰色且不可点击
+
+## 开发
+
+```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.3",
   "description": "蓝鲸用户选择器",
   "license": "MIT",
   "author": "Tencent BlueKing",

package/typings/api/user.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 用户选择器相关API
+ * @module api/user
+ */
+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: (apiBaseUrl?: string, tenantId?: string, keyword?: string) => Promise<User[]>;
+/**
+ * 批量精准查找用户
+ * @param apiBaseUrl - API基础URL
+ * @param tenantId - 租户ID
+ * @param users - 用户名列表
+ * @returns 查找到的用户列表Promise
+ */
+export declare const lookupUsers: (apiBaseUrl?: string, tenantId?: string, users?: string[]) => Promise<User[]>;
+/**
+ * 将API返回的用户数据格式化为组件所需格式
+ * @param users - API返回的用户列表
+ * @returns 格式化后的用户列表
+ */
+export declare const formatUsers: (users: User[]) => FormattedUser[];

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

@@ -0,0 +1,134 @@
+import { FormattedUser } from '../types';
+declare const _default: import("vue").DefineComponent<{
+    /**
+     * 绑定值
+     */
+    modelValue: {
+        type: ArrayConstructor;
+        default: () => never[];
+    };
+    /**
+     * 占位文本
+     */
+    placeholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 是否可拖拽
+     */
+    draggable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * API 基础 URL
+     */
+    apiBaseUrl: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 租户 ID
+     */
+    tenantId: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 已选用户
+     */
+    selectedUsers: {
+        type: () => FormattedUser[];
+        default: () => never[];
+    };
+    /**
+     * 租户信息映射
+     */
+    tenants: {
+        type: () => Record<string, string>;
+        default: () => {};
+    };
+    /**
+     * 当前用户ID
+     */
+    currentUserId: {
+        type: StringConstructor;
+        default: string;
+    };
+}, {}, unknown, {}, {}, 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<import("vue").ExtractPropTypes<{
+    /**
+     * 绑定值
+     */
+    modelValue: {
+        type: ArrayConstructor;
+        default: () => never[];
+    };
+    /**
+     * 占位文本
+     */
+    placeholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 是否可拖拽
+     */
+    draggable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * API 基础 URL
+     */
+    apiBaseUrl: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 租户 ID
+     */
+    tenantId: {
+        type: StringConstructor;
+        default: string;
+    };
+    /**
+     * 已选用户
+     */
+    selectedUsers: {
+        type: () => FormattedUser[];
+        default: () => never[];
+    };
+    /**
+     * 租户信息映射
+     */
+    tenants: {
+        type: () => Record<string, string>;
+        default: () => {};
+    };
+    /**
+     * 当前用户ID
+     */
+    currentUserId: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & {
+    "onUpdate:selectedUsers"?: ((...args: any[]) => any) | undefined;
+    "onAdd-user"?: ((...args: any[]) => any) | undefined;
+    "onRemove-user"?: ((...args: any[]) => any) | undefined;
+}, {
+    tenants: Record<string, string>;
+    draggable: boolean;
+    modelValue: unknown[];
+    placeholder: string;
+    apiBaseUrl: string;
+    tenantId: string;
+    selectedUsers: FormattedUser[];
+    currentUserId: string;
+}, {}>;
+export default _default;

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

@@ -0,0 +1,18 @@
+import { SingleSelectorProps } from '../types';
+declare const _default: import("vue").DefineComponent<__VLS_TypePropsToOption<SingleSelectorProps>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    change: (...args: any[]) => void;
+    "update:modelValue": (...args: any[]) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToOption<SingleSelectorProps>>> & {
+    onChange?: ((...args: any[]) => any) | undefined;
+    "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
+}, {}, {}>;
+export default _default;
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToOption<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};

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

@@ -0,0 +1,50 @@
+import { UserSelectorProps } from '../types';
+declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToOption<UserSelectorProps>, {
+    apiBaseUrl: string;
+    tenantId: string;
+    placeholder: string;
+    modelValue: string;
+    draggable: boolean;
+    multiple: boolean;
+    currentUserId: string;
+}>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    change: (...args: any[]) => void;
+    "update:modelValue": (...args: any[]) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<UserSelectorProps>, {
+    apiBaseUrl: string;
+    tenantId: string;
+    placeholder: string;
+    modelValue: string;
+    draggable: boolean;
+    multiple: boolean;
+    currentUserId: string;
+}>>> & {
+    onChange?: ((...args: any[]) => any) | undefined;
+    "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
+}, {
+    draggable: boolean;
+    modelValue: string | string[];
+    placeholder: string;
+    apiBaseUrl: string;
+    tenantId: string;
+    currentUserId: string;
+    multiple: boolean;
+}, {}>;
+export default _default;
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_PrettifyLocal<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToOption<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

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

@@ -0,0 +1,68 @@
+import { FormattedUser } from '../types';
+declare const _default: import("vue").DefineComponent<__VLS_TypePropsToOption<{
+    /**
+     * 用户信息
+     */
+    user: FormattedUser;
+    /**
+     * 租户数据映射
+     */
+    tenants: Record<string, string>;
+    /**
+     * 当前租户ID
+     */
+    currentTenantId?: string;
+    /**
+     * 是否可拖拽
+     */
+    draggable?: boolean;
+    /**
+     * 是否激活状态
+     */
+    active?: boolean;
+    /**
+     * 是否显示租户信息
+     */
+    showTenant?: boolean;
+}>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    click: (...args: any[]) => void;
+    close: (...args: any[]) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToOption<{
+    /**
+     * 用户信息
+     */
+    user: FormattedUser;
+    /**
+     * 租户数据映射
+     */
+    tenants: Record<string, string>;
+    /**
+     * 当前租户ID
+     */
+    currentTenantId?: string;
+    /**
+     * 是否可拖拽
+     */
+    draggable?: boolean;
+    /**
+     * 是否激活状态
+     */
+    active?: boolean;
+    /**
+     * 是否显示租户信息
+     */
+    showTenant?: boolean;
+}>>> & {
+    onClick?: ((...args: any[]) => any) | undefined;
+    onClose?: ((...args: any[]) => any) | undefined;
+}, {}, {}>;
+export default _default;
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToOption<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};

package/typings/hooks/useTenantData.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 租户数据处理 Hook
+ * @module hooks/useTenantData
+ */
+import { type Ref } from 'vue';
+/**
+ * 使用租户数据的Hook
+ * @param apiBaseUrl - API基础URL
+ * @param tenantId - 租户ID
+ * @returns 租户数据和加载状态
+ */
+export declare const useTenantData: (apiBaseUrl: string, tenantId: string) => {
+    tenants: Ref<Record<string, string>>;
+    loading: Ref<boolean>;
+    fetchTenants: () => Promise<void>;
+};

package/typings/hooks/useUserSearch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 用户搜索 Hook
+ * @module hooks/useUserSearch
+ */
+import { type Ref } from 'vue';
+import { type FormattedUser } from '../types';
+/**
+ * 使用用户搜索的Hook
+ * @param apiBaseUrl - API基础URL
+ * @param tenantId - 租户ID
+ * @returns 用户搜索相关状态和方法
+ */
+export declare const useUserSearch: (apiBaseUrl: string, tenantId: string) => {
+    searchResults: Ref<FormattedUser[]>;
+    loading: Ref<boolean>;
+    searchQuery: Ref<string>;
+    performSearch: (keyword: string) => Promise<void>;
+    handleSearchInput: (value: string) => void;
+    clearSearch: () => void;
+};

package/typings/hooks/useUserSelection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 用户选择 Hook
+ * @module hooks/useUserSelection
+ */
+import { type Ref } from 'vue';
+import { type FormattedUser } from '../types';
+/**
+ * 使用用户选择的Hook
+ * @param apiBaseUrl - API基础URL
+ * @param tenantId - 租户ID
+ * @param initialSelectedUsers - 初始选中的用户ID
+ * @param multiple - 是否多选
+ * @returns 用户选择相关状态和方法
+ */
+export declare const useUserSelection: (apiBaseUrl: string, tenantId: string, initialSelectedUsers?: string | string[], multiple?: boolean) => {
+    selectedUsers: Ref<FormattedUser[]>;
+    selectedUserIds: import("vue").ComputedRef<string | string[]>;
+    loading: Ref<boolean>;
+    addUser: (user: FormattedUser) => void;
+    removeUser: (user: FormattedUser) => void;
+    removeUserAtIndex: (index: number) => void;
+    clearSelection: () => void;
+};

package/typings/types/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 用户对象接口
+ */
+export interface User {
+    /**
+     * 用户名
+     */
+    bk_username: string;
+    /**
+     * 数据源类型
+     */
+    data_source_type: string;
+    /**
+     * 显示名称
+     */
+    display_name: string;
+    /**
+     * 全名
+     */
+    full_name: string;
+    /**
+     * 登录名
+     */
+    login_name: string;
+    /**
+     * 所属租户ID
+     */
+    owner_tenant_id: string;
+}
+/**
+ * 格式化后的用户信息
+ */
+export interface FormattedUser {
+    /**
+     * 用户ID
+     */
+    id: string;
+    /**
+     * 用户名称
+     */
+    name: string;
+    /**
+     * 租户ID
+     */
+    tenantId?: string;
+}
+/**
+ * 租户信息
+ */
+export interface Tenant {
+    /**
+     * 租户ID
+     */
+    id: string;
+    /**
+     * 租户名称
+     */
+    name: string;
+}
+/**
+ * 用户选择器属性
+ */
+export interface UserSelectorProps {
+    /**
+     * 接口基础URL
+     */
+    apiBaseUrl: string;
+    /**
+     * 租户ID
+     */
+    tenantId: string;
+    /**
+     * 占位文字
+     */
+    placeholder?: string;
+    /**
+     * 默认选中的用户(单选时为字符串，多选时为数组)
+     */
+    modelValue?: string | string[];
+    /**
+     * 是否支持拖拽排序
+     */
+    draggable?: boolean;
+    /**
+     * 是否多选
+     */
+    multiple?: boolean;
+    /**
+     * 本人ID
+     */
+    currentUserId?: string;
+}
+/**
+ * 单选模式属性
+ */
+export interface SingleSelectorProps {
+    /**
+     * 选中的用户ID
+     */
+    modelValue?: string;
+    /**
+     * 占位文字
+     */
+    placeholder?: string;
+    /**
+     * 接口基础URL
+     */
+    apiBaseUrl?: string;
+    /**
+     * 租户ID
+     */
+    tenantId?: string;
+    /**
+     * 租户信息映射
+     */
+    tenants: Record<string, string>;
+    /**
+     * 本人ID
+     */
+    currentUserId?: string;
+}

package/typings/utils/common.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 通用工具函数
+ * @module utils/common
+ */
+import { type FormattedUser } from '../types';
+/**
+ * 防抖函数
+ * @param fn - 需要防抖的函数
+ * @param delay - 延迟时间（毫秒）
+ * @returns 防抖后的函数
+ */
+export declare const debounce: <T extends (...args: any[]) => any>(fn: T, delay: number) => (...args: Parameters<T>) => void;
+/**
+ * 计算标签容器可见数量
+ * @param container - 容器元素
+ * @param items - 项目元素列表
+ * @param containerWidth - 容器宽度
+ * @returns 可见项目数量
+ */
+export declare const calculateVisibleTags: (container: HTMLElement, items: HTMLElement[] | NodeListOf<Element>, containerWidth: number) => number;
+/**
+ * 转换用户数组为Map结构，方便快速查找
+ * @param users - 用户列表
+ * @returns 用户Map对象
+ */
+export declare const userArrayToMap: (users: FormattedUser[]) => Map<string, FormattedUser>;
+/**
+ * 判断两个数组是否有值的变化
+ * @param arr1 - 数组1
+ * @param arr2 - 数组2
+ * @returns 是否有变化
+ */
+export declare const hasArrayChanged: (arr1?: any[], arr2?: any[]) => boolean;

package/typings/vue2.d.ts

@@ -1,2 +1,16 @@
-declare const _default: any;
+import BkUserSelector from './components/user-selector.vue';
+declare const _default: {
+    beforeDestroy(): void;
+    created(): void;
+    data(): {
+        app: null;
+        unWatchStack: never[];
+    };
+    mounted(): void;
+    name: string;
+    props: any;
+    render(createElement: any): any;
+};
 export default _default;
+export { BkUserSelector };
+export * from './types';