@blueking/bk-user-selector 0.1.5 → 0.1.7

package/README.md

@@ -18,10 +18,12 @@
 | 🎨 **可拖拽**     | 多选模式下支持拖拽排序               |
 | ⚡ **快捷操作**   | 支持快速选择当前用户（"我"）         |
 | 👥 **用户组**     | 支持用户组/角色分组显示              |
+| 🕘 **最近选择**   | 支持在下拉右侧展示最近选择人员       |
 | ✏️ **自定义输入** | 支持创建自定义用户和自由粘贴         |
 | 🎭 **自定义渲染** | 支持自定义标签和列表项渲染           |
 | 📝 **多行输入**   | 支持 textarea 模式，完整展示所有标签 |
 | ⌨️ **键盘导航**   | 支持上下键切换选项、Enter 快速选中   |
+| 🎯 **焦点控制**   | 支持自动聚焦和手动 focus/blur 方法   |
 
 ## 📦 安装
 
@@ -157,6 +159,29 @@ export default {
 </script>
 ```
 
+### 最近选择
+
+业务只需传入最近选择用户 ID，组件会自动补全并展示在下拉右侧：
+
+```vue
+<template>
+  <BkUserSelector
+    v-model="selectedUsers"
+    :api-base-url="apiBaseUrl"
+    :multiple="true"
+    :recent-user-ids="recentUserIds"
+  />
+</template>
+
+<script setup>
+  import { ref } from 'vue';
+
+  const apiBaseUrl = ref('https://api.example.com');
+  const selectedUsers = ref([]);
+  const recentUserIds = ref(['admin', 'operator']);
+</script>
+```
+
 ### 自定义渲染
 
 支持自定义标签和列表项的渲染：
@@ -294,33 +319,35 @@ export default {
 
 ### Props 属性
 
-| 参数                  | 说明                              | 类型                                             | 默认值                 | 必填 |
-| --------------------- | --------------------------------- | ------------------------------------------------ | ---------------------- | ---- |
-| modelValue / v-model  | 绑定值，单选为字符串，多选为数组  | `string` / `string[]`                            | `''` / `[]`            | 是   |
-| apiBaseUrl            | API 基础 URL                      | `string`                                         | `''`                   | 是   |
-| tenantId              | 租户 ID                           | `string`                                         | `'default'`            | 否   |
-| hasAvatar             | 是否显示头像                      | `boolean`                                        | `false`                | 否   |
-| avatarBaseUrl         | 头像基础 URL                      | `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`                    | 否   |
-| type                  | 输入框类型                        | `'input'` / `'textarea'`                         | `'input'`              | 否   |
-| rows                  | 默认行数（仅 textarea 模式生效）  | `number`                                         | `4`                    | 否   |
-| resize                | 是否允许拖拽调整高度（仅 textarea 模式生效） | `boolean`                              | `true`                 | 否   |
+| 参数                  | 说明                                               | 类型                                             | 默认值                 | 必填 |
+| --------------------- | -------------------------------------------------- | ------------------------------------------------ | ---------------------- | ---- |
+| modelValue / v-model  | 绑定值，单选为字符串，多选为数组                   | `string` / `string[]`                            | `''` / `[]`            | 是   |
+| apiBaseUrl            | API 基础 URL                                       | `string`                                         | `''`                   | 是   |
+| tenantId              | 租户 ID                                            | `string`                                         | `'default'`            | 否   |
+| hasAvatar             | 是否显示头像                                       | `boolean`                                        | `false`                | 否   |
+| avatarBaseUrl         | 头像基础 URL                                       | `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[]`                                       | `[]`                   | 否   |
+| recentUserIds         | 最近选择用户 ID 列表，传入后在下拉右侧展示最近选择 | `string[]`                                       | `[]`                   | 否   |
+| enableMultiTenantMode | 是否启用多租户模式                                 | `boolean`                                        | `true`                 | 否   |
+| allowCreate           | 是否允许自定义输入，按 Enter 确认                  | `boolean`                                        | `false`                | 否   |
+| freePaste             | 是否允许粘贴任意文本                               | `boolean`                                        | `false`                | 否   |
+| maxCount              | 最大可选数量（0 表示不限制）                       | `number`                                         | `0`                    | 否   |
+| type                  | 输入框类型                                         | `'input'` / `'textarea'`                         | `'input'`              | 否   |
+| rows                  | 默认行数（仅 textarea 模式生效）                   | `number`                                         | `4`                    | 否   |
+| resize                | 是否允许拖拽调整高度（仅 textarea 模式生效）       | `boolean`                                        | `true`                 | 否   |
+| autoFocus             | 是否自动聚焦                                       | `boolean`                                        | `false`                | 否   |
 
 #### exactSearchKey 说明
 
@@ -335,12 +362,42 @@ export default {
 
 ### Events 事件
 
-| 事件名称          | 说明                 | 回调参数                             |
-| ----------------- | -------------------- | ------------------------------------ |
-| update:modelValue | 绑定值变化时触发     | `(value: string \| string[])`        |
-| change            | 选中值变化时触发     | `(userInfo: UserInfo \| UserInfo[])` |
-| focus             | 输入框获得焦点时触发 | `(event: FocusEvent)`                |
-| blur              | 输入框失去焦点时触发 | `(event: FocusEvent)`                |
+| 事件名称          | 说明                                                                               | 回调参数                             |
+| ----------------- | ---------------------------------------------------------------------------------- | ------------------------------------ |
+| update:modelValue | 绑定值变化时触发                                                                   | `(value: string \| string[])`        |
+| change            | 选中值变化时触发                                                                   | `(userInfo: UserInfo \| UserInfo[])` |
+| focus             | 输入框获得焦点时触发                                                               | -                                    |
+| blur              | 输入框失去焦点时触发                                                               | -                                    |
+| error             | 任意接口请求失败时触发（包含 401、网络错误等），业务可在此弹 Message、上报 Sentry  | `(error: ApiError)`                  |
+| unauthorized      | 登录态失效（HTTP 401）时触发，同时也会触发 `error`，业务可在此跳转登录或刷新 token | `(error: ApiError)`                  |
+
+### Methods 方法
+
+通过模板 ref 调用组件方法：
+
+| 方法名 | 说明       | 参数 |
+| ------ | ---------- | ---- |
+| focus  | 使组件聚焦 | -    |
+| blur   | 使组件失焦 | -    |
+
+```vue
+<template>
+  <BkUserSelector
+    ref="selectorRef"
+    v-model="value"
+    :api-base-url="apiBaseUrl"
+  />
+  <button @click="selectorRef?.focus()">聚焦</button>
+  <button @click="selectorRef?.blur()">失焦</button>
+</template>
+
+<script setup>
+  import { ref } from 'vue';
+  const selectorRef = ref(null);
+  const value = ref('');
+  const apiBaseUrl = 'https://api.example.com';
+</script>
+```
 
 ### 类型定义
 
@@ -367,8 +424,56 @@ type RenderFunction = (
   h: CreateElement, // Vue createElement 函数
   userInfo: UserInfo, // 用户信息
 ) => VNode;
+
+// 接口错误
+interface ApiError {
+  scene: string; // 业务场景，如 '搜索用户'、'批量查找用户'
+  cause: unknown; // 原始错误对象
+  status?: number; // HTTP 状态码（网络错误时为 undefined）
+  isUnauthorized: boolean; // 是否为登录态失效（HTTP 401）
+}
 ```
 
+## 🛡️ 错误处理
+
+组件遵循「不强依赖 UI 反馈」的设计原则，接口失败时**不会自动弹 Message**，而是通过事件向业务侧暴露错误，由业务自行决定弹消息、上报监控或静默处理。
+
+```vue
+<template>
+  <BkUserSelector
+    v-model="selectedUser"
+    :api-base-url="apiBaseUrl"
+    :tenant-id="tenantId"
+    @error="handleApiError"
+    @unauthorized="handleUnauthorized"
+  />
+</template>
+
+<script setup lang="ts">
+  import { Message } from 'bkui-vue';
+
+  import type { ApiError } from '@blueking/bk-user-selector';
+
+  const handleApiError = (err: ApiError) => {
+    // 401 不需要重复弹 Message，由 unauthorized 单独处理
+    if (err.isUnauthorized) return;
+    Message({ theme: 'error', message: `${err.scene}失败，请稍后重试` });
+    // 也可以上报 Sentry / 蓝鲸监控
+    // sentry.captureException(err.cause, { extra: { scene: err.scene, status: err.status } });
+  };
+
+  const handleUnauthorized = (err: ApiError) => {
+    location.href = `/login?next=${encodeURIComponent(location.href)}`;
+  };
+</script>
+```
+
+行为说明：
+
+- 失败统一构造 `ApiError`，已通过 `console.error` 打印兜底日志
+- 401 会同时触发 `unauthorized` 和 `error` 事件，便于业务统一收口或独立处理
+- 业务回调如果抛错不会影响组件正常流程
+
 ## 💡 功能说明
 
 ### 快速选择"我"
@@ -437,6 +542,7 @@ type RenderFunction = (
    - 多选模式：`v-model` 应为 `string[]` 类型
 4. **跨租户显示**：跨租户用户会在名称旁显示租户标识
 5. **自定义输入**：启用 `allowCreate` 后，用户输入的内容会作为 `id` 值
+6. **批量粘贴限制**：单次粘贴最多处理 `100` 个用户标识，超出部分会被截断；批量精准查询按后端限制分批执行（每批最多 `100` 个）
 
 ## ❓ FAQ
 
@@ -462,7 +568,11 @@ A: 通过 `change` 事件获取，它会返回完整的用户信息对象，而
 
 ### Q: 多选模式下如何限制选择数量？
 
-A: 目前组件暂不支持直接限制，可以通过 `change` 事件监听并在超出数量时给出提示。
+A: 使用 `maxCount` 属性设置最大可选数量，`0` 表示不限制。
+
+### Q: 一次粘贴很多用户，为什么没有全部添加？
+
+A: 出于性能与安全保护，批量粘贴单次最多处理 `100` 个用户标识，超出部分会被截断；组件会按后端限制分批查询（每批最多 `100` 个）。如需导入更多用户，请分批粘贴。
 
 ### Q: 搜索没有结果怎么办？
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/bk-user-selector",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "蓝鲸用户选择器",
   "license": "MIT",
   "author": "Tencent BlueKing",
@@ -10,7 +10,10 @@
     "build": "vite-node ./scripts/vite.build.ts",
     "dts": "vue-tsc --project tsconfig.dts.json",
     "prettier": "prettier ./src ./scripts ./playground --write",
-    "visualize": "vite-bundle-visualizer -c scripts/vite.visualizer.ts"
+    "visualize": "vite-bundle-visualizer -c scripts/vite.visualizer.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "exports": {
     ".": {
@@ -61,4 +64,4 @@
     "lodash": "^4.17.23",
     "sortablejs": "^1.15.6"
   }
-}
+}

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

@@ -21,6 +21,10 @@ interface SelectionPopoverProps {
     loading?: boolean;
     /** 搜索结果选项 */
     options?: FormattedUser[];
+    /** 最近选择用户 */
+    recentUsers?: FormattedUser[];
+    /** 最近选择标题 */
+    recentUsersName?: string;
     /** 渲染列表项 */
     renderListItem?: RenderFunction;
     /** 搜索关键词 */
@@ -34,9 +38,9 @@ interface SelectionPopoverProps {
     /** 用户组名称 */
     userGroupName?: string;
 }
-declare var __VLS_22: {};
+declare var __VLS_27: {};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_22) => any;
+    default?: (props: typeof __VLS_27) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<SelectionPopoverProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "click-outside": (event: MouseEvent) => any;
@@ -58,6 +62,8 @@ declare const __VLS_base: import("vue").DefineComponent<SelectionPopoverProps, {
     isShow: boolean;
     loading: boolean;
     options: FormattedUser[];
+    recentUsers: FormattedUser[];
+    recentUsersName: string;
     userGroupName: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

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

@@ -1,17 +1,24 @@
-import { FormattedUser, UserSelectorProps } from '../types';
-declare const __VLS_export: import("vue").DefineComponent<UserSelectorProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+import { ApiError, FormattedUser, UserSelectorProps } from '../types';
+declare const __VLS_export: import("vue").DefineComponent<UserSelectorProps, {
+    focus: () => void;
+    blur: () => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    error: (error: ApiError) => any;
     blur: () => any;
     change: (user: FormattedUser | FormattedUser[] | null) => any;
     focus: () => any;
     dragEnd: (event: Sortable.SortableEvent) => any;
     dragStart: (event: Sortable.SortableEvent) => any;
+    unauthorized: (error: ApiError) => any;
     "update:modelValue": (value: string | string[]) => any;
 }, string, import("vue").PublicProps, Readonly<UserSelectorProps> & Readonly<{
+    onError?: ((error: ApiError) => any) | undefined;
     onBlur?: (() => any) | undefined;
     onChange?: ((user: FormattedUser | FormattedUser[] | null) => any) | undefined;
     onFocus?: (() => any) | undefined;
     onDragEnd?: ((event: Sortable.SortableEvent) => any) | undefined;
     onDragStart?: ((event: Sortable.SortableEvent) => any) | undefined;
+    onUnauthorized?: ((error: ApiError) => any) | undefined;
     "onUpdate:modelValue"?: ((value: string | string[]) => any) | undefined;
 }>, {
     userGroup: import("../types").UserGroupConfig[];
@@ -32,10 +39,15 @@ declare const __VLS_export: import("vue").DefineComponent<UserSelectorProps, {},
     userGroupName: string;
     disabled: boolean;
     draggable: boolean;
+    autoFocus: boolean;
     modelValue: string | string[];
     multiple: boolean;
     rows: number;
+    allowCrossOriginCredentials: boolean;
+    allowedApiOrigins: string[];
+    allowPrivateApiHost: boolean;
     placeholder: string;
+    recentUserIds: string[];
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/typings/hooks/use-api-config.d.ts

@@ -0,0 +1,33 @@
+import { type InjectionKey } from 'vue';
+import type { ApiErrorHandler } from '../types';
+export interface ApiConfig {
+    allowCrossOriginCredentials: boolean;
+    allowedApiOrigins: string[];
+    allowPrivateApiHost: boolean;
+    apiBaseUrl: string;
+    /**
+     * 接口失败回调
+     * 由组件透传或调用方在直接调用 API 函数时传入
+     */
+    onError?: ApiErrorHandler;
+    /**
+     * 登录态失效回调（HTTP 401）
+     * 由组件透传或调用方在直接调用 API 函数时传入
+     */
+    onUnauthorized?: ApiErrorHandler;
+    tenantId: string;
+}
+/**
+ * 可选回调集合，用于向 provideApiConfig 注入回调
+ */
+export interface ApiConfigCallbacks {
+    onError?: ApiErrorHandler;
+    onUnauthorized?: ApiErrorHandler;
+}
+export declare const API_CONFIG_KEY: InjectionKey<ApiConfig>;
+export declare const normalizeAllowedOrigins: (allowedApiOrigins?: string[]) => string[];
+export declare const sanitizeApiBaseUrl: (apiBaseUrl: string, allowedApiOrigins?: string[], allowPrivateApiHost?: boolean) => string;
+export declare const sanitizeTenantId: (tenantId: string) => string;
+export declare const getApiConfig: () => ApiConfig;
+export declare const provideApiConfig: (apiBaseUrl: string, tenantId: string, allowedApiOrigins?: string[], allowPrivateApiHost?: boolean, allowCrossOriginCredentials?: boolean, callbacks?: ApiConfigCallbacks) => void;
+export declare const useApiConfig: (fallbackApiBaseUrl?: string, fallbackTenantId?: string, fallbackAllowedApiOrigins?: string[], fallbackAllowPrivateApiHost?: boolean, fallbackAllowCrossOriginCredentials?: boolean) => ApiConfig;

package/typings/locale/en-us.d.ts

@@ -1,6 +1,7 @@
 declare const _default: {
     我: string;
     请输入人员名称搜索: string;
+    最近选择: string;
     用户群组: string;
     无匹配人员: string;
     虚拟账号: string;

package/typings/locale/zh-cn.d.ts

@@ -1,6 +1,7 @@
 declare const _default: {
     我: string;
     请输入人员名称搜索: string;
+    最近选择: string;
     用户群组: string;
     无匹配人员: string;
     虚拟账号: string;

package/typings/types/index.d.ts

@@ -1,6 +1,35 @@
 import type { createVNode } from 'vue';
 import type { VNode } from 'vue';
 import type { USER_TYPE } from '../constants';
+/**
+ * API 请求错误对象
+ * 组件内部所有接口请求失败时统一构造此对象，向外暴露给业务侧
+ */
+export interface ApiError {
+    /**
+     * 原始错误对象
+     */
+    cause: unknown;
+    /**
+     * 是否为登录态失效（HTTP 401）
+     * 同时会触发 onUnauthorized 回调
+     */
+    isUnauthorized: boolean;
+    /**
+     * 业务场景描述
+     * 例如：'获取租户信息'、'搜索用户'、'批量查找用户'
+     */
+    scene: string;
+    /**
+     * HTTP 状态码（仅在响应已到达时存在；网络错误等情况下为 undefined）
+     */
+    status?: number;
+}
+/**
+ * API 错误回调
+ * 所有接口失败（含 401、网络错误等）都会触发此回调
+ */
+export type ApiErrorHandler = (error: ApiError) => void;
 /**
  * 基础选择器属性
  */
@@ -9,6 +38,18 @@ export interface BaseSelectorProps {
      * 是否允许创建用户
      */
     allowCreate?: boolean;
+    /**
+     * 是否允许跨域请求携带 Cookie
+     */
+    allowCrossOriginCredentials?: boolean;
+    /**
+     * 允许访问的跨域 API 源白名单
+     */
+    allowedApiOrigins?: string[];
+    /**
+     * 是否允许 apiBaseUrl 指向私网或 localhost
+     */
+    allowPrivateApiHost?: boolean;
     /**
      * 接口基础URL
      */
@@ -55,6 +96,10 @@ export interface BaseSelectorProps {
      * 占位文字
      */
     placeholder?: string;
+    /**
+     * 最近选择用户 ID 列表
+     */
+    recentUserIds?: string[];
     /**
      * 渲染列表项
      */
@@ -204,6 +249,11 @@ export interface UserGroupConfig {
  * 用户选择器属性
  */
 export interface UserSelectorProps extends BaseSelectorProps {
+    /**
+     * 是否自动聚焦
+     * @default false
+     */
+    autoFocus?: boolean;
     /**
      * 是否支持拖拽排序
      */

package/typings/utils/logger.d.ts

@@ -1,3 +1,8 @@
+/**
+ * 日志工具
+ * @module utils/logger
+ */
+import type { ApiConfig } from '../hooks/use-api-config';
 /**
  * 日志级别
  */
@@ -38,8 +43,11 @@ export declare const logger: {
 };
 /**
  * API 错误处理
+ * - 打印错误日志（兜底）
+ * - 触发 apiConfig.onError 回调
+ * - 如果是 401，额外触发 apiConfig.onUnauthorized 回调
  */
-export declare const handleApiError: (operation: string, error: unknown) => void;
+export declare const handleApiError: (operation: string, error: unknown, apiConfig?: ApiConfig, status?: number, isUnauthorized?: boolean) => void;
 /**
  * 参数校验警告
  */