x-next 1.10.0 → 1.10.1

package/AI_USAGE.md

@@ -1,9 +1,9 @@
 <!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/manifest.js. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.10.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.10.1**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（精选示例、映射、版本与公开类型声明）：`c176a3e6388bb70f3e2b34f65c43da412a3a9166c20d276ddfbda3576370c40d`。
+来源指纹（精选示例、映射、版本与公开类型声明）：`c37fbf755e64965a7c5f31201af1884cbf1bf81fedb0a8210ed326b16e14709c`。
 
 本手册覆盖 27 个常用组件与服务；包内还有更多导出可用，只是未在此逐个展开。按业务需要选择即可，不必全部使用。
 
@@ -217,6 +217,8 @@ function changed(value: string | number | boolean, _event: Event) {
 
 `change(value)` 返回新值，`clear(event)` 返回 `Event`；单选清空通常为 `''`，多选为 `[]`，已选禁用项可能保留。`v-model:popup-visible` 控制弹层，`option` / `empty` / `header` / `footer` 等插槽见组件文档。
 
+有值且可清空时，右侧 × 与箭头共用位置，点击 × 不切换面板。`v-model:input-value` 控制搜索输入；远程搜索设置 `filterOption=false`，用 `@search` 请求数据并由业务取消旧请求。对象值用 `valueKey` 标识，`fallbackOption` 处理暂时缺失的候选项。默认触发器 ref 类型为 `SelectInstance`，提供 `focus()` / `blur()`；自定义 `trigger` 插槽将 `onKeydown` 绑定到自己的可聚焦节点。
+
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';

package/CHANGELOG.md

@@ -2,7 +2,19 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [未发布]
+## [1.10.1] - 2026-10-06
+
+### 修复
+
+- Button `loadingFill` 的覆盖层样式改为匹配实际结构，加载图标在按钮内居中，不再与内容挤占宽度；保留原尺寸与圆角，加载期间视觉隐藏文字及前后缀，结束后恢复，并补充可交互文档示例和编译样式回归测试。
+- Select 的清空与展开图标共用末尾位置，可清空时始终显示 ×；清空保留面板状态并恢复焦点，不隐藏 Form 反馈。
+- Select 统一拦截禁用 / 加载中的选择和删除，清理过期搜索任务；修复动态字段映射、缺失多选值保留、同键对象兜底更新、异步选项默认激活和分组虚拟化；插槽选项与虚拟配置并用时保留普通列表。
+- 多选选项复选框统一由选项处理点击，不再参与外层 Form 注册或 Tab 顺序；原生输入属性落到真实输入，输入法 Backspace 不误删标签。
+- Select 按实际已选值保留最新远程标签，缺失标签仍可清空且保留禁用项；清理卸载的虚拟行引用，加载期间不引用隐藏活动选项，并补齐 Trigger 滚动关闭配置类型。
+
+### 新增
+
+- Select 公开 `focus()` / `blur()`、明确 `focus` / `blur` 事件，自定义 trigger 提供 `onKeydown`；展开时支持 Home / End 定位首末启用项，补齐 Props 类型与对象值、远程搜索、自定义触发器及图标的可交互文档示例。
 
 ## [1.10.0] - 2026-10-05
 

package/dist/components/_components/select-view/select-view.d.ts

@@ -40,6 +40,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         type: BooleanConstructor;
         default: boolean;
     };
+    clearable: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
     allowCreate: {
         type: BooleanConstructor;
         default: boolean;
@@ -114,6 +118,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         type: BooleanConstructor;
         default: boolean;
     };
+    clearable: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
     allowCreate: {
         type: BooleanConstructor;
         default: boolean;
@@ -153,6 +161,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
     maxTagCount: number;
     retainInputValue: boolean;
     tagNowrap: boolean;
+    clearable: boolean;
     allowCreate: boolean;
     allowSearch: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

package/dist/components/form-select/Select.d.ts

@@ -297,15 +297,17 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         default: boolean;
     };
 }>, () => VNode, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    'update:modelValue': (value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
+    focus: (ev: FocusEvent) => true;
+    blur: (ev: FocusEvent) => true;
+    'update:modelValue': (value: string | undefined | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
     'update:inputValue': (inputValue: string) => true;
     'update:popupVisible': (visible: boolean) => true;
     /**
      * @zh 值发生改变时触发
      * @en Triggered when the value changes
-     * @param { string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] } value
+     * @param { string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] | undefined } value
      */
-    change: (value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
+    change: (value: string | undefined | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
     /**
      * @zh 输入框的值发生改变时触发
      * @en Triggered when the value of the input changes
@@ -644,11 +646,13 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         default: boolean;
     };
 }>> & Readonly<{
+    onFocus?: ((ev: FocusEvent) => any) | undefined;
     onSearch?: ((inputValue: string) => any) | undefined;
     onClear?: ((ev: Event) => any) | undefined;
     onRemove?: ((removed: string | number | boolean | Record<string, any> | undefined) => any) | undefined;
-    onChange?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => any) | undefined;
-    "onUpdate:modelValue"?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => any) | undefined;
+    onBlur?: ((ev: FocusEvent) => any) | undefined;
+    onChange?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] | undefined) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] | undefined) => any) | undefined;
     "onUpdate:popupVisible"?: ((visible: boolean) => any) | undefined;
     onPopupVisibleChange?: ((visible: boolean) => any) | undefined;
     "onUpdate:inputValue"?: ((inputValue: string) => any) | undefined;
@@ -1292,6 +1296,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             type: BooleanConstructor;
             default: boolean;
         };
+        clearable: {
+            type: BooleanConstructor;
+            default: undefined;
+        };
         allowCreate: {
             type: BooleanConstructor;
             default: boolean;
@@ -1366,6 +1374,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             type: BooleanConstructor;
             default: boolean;
         };
+        clearable: {
+            type: BooleanConstructor;
+            default: undefined;
+        };
         allowCreate: {
             type: BooleanConstructor;
             default: boolean;
@@ -1405,6 +1417,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         maxTagCount: number;
         retainInputValue: boolean;
         tagNowrap: boolean;
+        clearable: boolean;
         allowCreate: boolean;
         allowSearch: boolean;
     }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

package/dist/components/form-select/SelectOptionGroup.vue.d.ts

@@ -13,6 +13,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         modifier: (className: string) => string;
         is: (className: string) => string;
     };
+    component: import('vue').ComputedRef<string>;
 }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
     /**
      * @zh 选项组的标题

package/dist/components/form-select/hooks/use-options.d.ts

@@ -17,7 +17,7 @@ export declare const useOptions: ({ options, extraOptions, inputValue, filterOpt
         key: string;
         index?: number | undefined;
         origin: "slot" | "options" | "extraOptions";
-        value: import('../interface').SelectOptionValue;
+        value: import('..').SelectOptionValue;
         label: string;
         disabled?: boolean | undefined;
         tagProps?: any;

package/dist/components/form-select/hooks/use-select.d.ts

@@ -32,7 +32,7 @@ export declare const useSelect: ({ multiple, options, extraOptions, inputValue,
         key: string;
         index?: number | undefined;
         origin: "slot" | "options" | "extraOptions";
-        value: import('../interface').SelectOptionValue;
+        value: import('..').SelectOptionValue;
         label: string;
         disabled?: boolean | undefined;
         tagProps?: any;

package/dist/components/form-select/index.d.ts

@@ -1,4 +1,4 @@
-export type { SelectProps } from './interface';
+export type { SelectProps, SelectInstance, SelectOptionData, SelectOptionGroup as SelectOptionGroupData, SelectOptionValue, } from './interface';
 export declare const Select: {
     new (...args: any[]): import('vue').CreateComponentPublicInstanceWithMixins<Readonly<import('vue').ExtractPropTypes<{
         multiple: {
@@ -134,11 +134,13 @@ export declare const Select: {
             default: boolean;
         };
     }>> & Readonly<{
+        onFocus?: ((ev: FocusEvent) => any) | undefined;
         onSearch?: ((inputValue: string) => any) | undefined;
         onClear?: ((ev: Event) => any) | undefined;
         onRemove?: ((removed: string | number | boolean | Record<string, any> | undefined) => any) | undefined;
-        onChange?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => any) | undefined;
-        "onUpdate:modelValue"?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => any) | undefined;
+        onBlur?: ((ev: FocusEvent) => any) | undefined;
+        onChange?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] | undefined) => any) | undefined;
+        "onUpdate:modelValue"?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] | undefined) => any) | undefined;
         "onUpdate:popupVisible"?: ((visible: boolean) => any) | undefined;
         onPopupVisibleChange?: ((visible: boolean) => any) | undefined;
         "onUpdate:inputValue"?: ((inputValue: string) => any) | undefined;
@@ -147,10 +149,12 @@ export declare const Select: {
         onDropdownReachBottom?: ((ev: Event) => any) | undefined;
         onExceedLimit?: ((value: string | number | boolean | Record<string, any> | undefined, ev: Event) => any) | undefined;
     }>, () => VNode, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-        'update:modelValue': (value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
+        focus: (ev: FocusEvent) => true;
+        blur: (ev: FocusEvent) => true;
+        'update:modelValue': (value: string | undefined | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
         'update:inputValue': (inputValue: string) => true;
         'update:popupVisible': (visible: boolean) => true;
-        change: (value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
+        change: (value: string | undefined | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
         inputValueChange: (inputValue: string) => true;
         popupVisibleChange: (visible: boolean) => true;
         clear: (ev: Event) => true;
@@ -795,6 +799,10 @@ export declare const Select: {
                 type: BooleanConstructor;
                 default: boolean;
             };
+            clearable: {
+                type: BooleanConstructor;
+                default: undefined;
+            };
             allowCreate: {
                 type: BooleanConstructor;
                 default: boolean;
@@ -869,6 +877,10 @@ export declare const Select: {
                 type: BooleanConstructor;
                 default: boolean;
             };
+            clearable: {
+                type: BooleanConstructor;
+                default: undefined;
+            };
             allowCreate: {
                 type: BooleanConstructor;
                 default: boolean;
@@ -908,6 +920,7 @@ export declare const Select: {
             maxTagCount: number;
             retainInputValue: boolean;
             tagNowrap: boolean;
+            clearable: boolean;
             allowCreate: boolean;
             allowSearch: boolean;
         }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
@@ -1052,11 +1065,13 @@ export declare const Select: {
             default: boolean;
         };
     }>> & Readonly<{
+        onFocus?: ((ev: FocusEvent) => any) | undefined;
         onSearch?: ((inputValue: string) => any) | undefined;
         onClear?: ((ev: Event) => any) | undefined;
         onRemove?: ((removed: string | number | boolean | Record<string, any> | undefined) => any) | undefined;
-        onChange?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => any) | undefined;
-        "onUpdate:modelValue"?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => any) | undefined;
+        onBlur?: ((ev: FocusEvent) => any) | undefined;
+        onChange?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] | undefined) => any) | undefined;
+        "onUpdate:modelValue"?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] | undefined) => any) | undefined;
         "onUpdate:popupVisible"?: ((visible: boolean) => any) | undefined;
         onPopupVisibleChange?: ((visible: boolean) => any) | undefined;
         "onUpdate:inputValue"?: ((inputValue: string) => any) | undefined;
@@ -1232,11 +1247,13 @@ export declare const Select: {
         default: boolean;
     };
 }>> & Readonly<{
+    onFocus?: ((ev: FocusEvent) => any) | undefined;
     onSearch?: ((inputValue: string) => any) | undefined;
     onClear?: ((ev: Event) => any) | undefined;
     onRemove?: ((removed: string | number | boolean | Record<string, any> | undefined) => any) | undefined;
-    onChange?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => any) | undefined;
-    "onUpdate:modelValue"?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => any) | undefined;
+    onBlur?: ((ev: FocusEvent) => any) | undefined;
+    onChange?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] | undefined) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[] | undefined) => any) | undefined;
     "onUpdate:popupVisible"?: ((visible: boolean) => any) | undefined;
     onPopupVisibleChange?: ((visible: boolean) => any) | undefined;
     "onUpdate:inputValue"?: ((inputValue: string) => any) | undefined;
@@ -1245,10 +1262,12 @@ export declare const Select: {
     onDropdownReachBottom?: ((ev: Event) => any) | undefined;
     onExceedLimit?: ((value: string | number | boolean | Record<string, any> | undefined, ev: Event) => any) | undefined;
 }>, () => VNode, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    'update:modelValue': (value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
+    focus: (ev: FocusEvent) => true;
+    blur: (ev: FocusEvent) => true;
+    'update:modelValue': (value: string | undefined | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
     'update:inputValue': (inputValue: string) => true;
     'update:popupVisible': (visible: boolean) => true;
-    change: (value: string | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
+    change: (value: string | undefined | number | boolean | Record<string, any> | (string | number | boolean | Record<string, any>)[]) => true;
     inputValueChange: (inputValue: string) => true;
     popupVisibleChange: (visible: boolean) => true;
     clear: (ev: Event) => true;
@@ -1893,6 +1912,10 @@ export declare const Select: {
             type: BooleanConstructor;
             default: boolean;
         };
+        clearable: {
+            type: BooleanConstructor;
+            default: undefined;
+        };
         allowCreate: {
             type: BooleanConstructor;
             default: boolean;
@@ -1967,6 +1990,10 @@ export declare const Select: {
             type: BooleanConstructor;
             default: boolean;
         };
+        clearable: {
+            type: BooleanConstructor;
+            default: undefined;
+        };
         allowCreate: {
             type: BooleanConstructor;
             default: boolean;
@@ -2006,6 +2033,7 @@ export declare const Select: {
         maxTagCount: number;
         retainInputValue: boolean;
         tagNowrap: boolean;
+        clearable: boolean;
         allowCreate: boolean;
         allowSearch: boolean;
     }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
@@ -3559,6 +3587,7 @@ export declare const SelectOptionGroup: {
             modifier: (className: string) => string;
             is: (className: string) => string;
         };
+        component: import('vue').ComputedRef<string>;
     }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, import('vue').PublicProps, {}, true, {}, {}, import('vue').GlobalComponents, import('vue').GlobalDirectives, string, {}, any, import('vue').ComponentProvideOptions, {
         P: {};
         B: {};
@@ -3577,6 +3606,7 @@ export declare const SelectOptionGroup: {
             modifier: (className: string) => string;
             is: (className: string) => string;
         };
+        component: import('vue').ComputedRef<string>;
     }, {}, {}, {}, {}>;
     __isFragment?: never;
     __isTeleport?: never;
@@ -3592,6 +3622,7 @@ export declare const SelectOptionGroup: {
         modifier: (className: string) => string;
         is: (className: string) => string;
     };
+    component: import('vue').ComputedRef<string>;
 }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, {}, {}, string, {}, import('vue').GlobalComponents, import('vue').GlobalDirectives, string, import('vue').ComponentProvideOptions> & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps & {
     install(app: import('vue').App): void;
 };

package/dist/components/form-select/interface.d.ts

@@ -3,6 +3,11 @@ import { FieldString } from '../../_hooks/_types';
 import { Size } from '../../_utils/constant';
 import { VirtualListProps } from '../virtual-list-v2/interface';
 import { TriggerProps } from '../trigger/interface';
+import { ScrollbarProps } from '../scrollbar-v2';
+export interface SelectInstance {
+    focus: () => void;
+    blur: () => void;
+}
 export interface SelectProps {
     options?: (string | number | boolean | SelectOptionData | SelectOptionGroup)[];
     multiple?: boolean;
@@ -25,6 +30,7 @@ export interface SelectProps {
     bordered?: boolean;
     popupVisible?: boolean;
     defaultPopupVisible?: boolean;
+    defaultActiveFirstOption?: boolean;
     unmountOnClose?: boolean;
     filterOption?: boolean | ((inputValue: string, option: SelectOptionData) => boolean);
     virtualListProps?: VirtualListProps;
@@ -38,6 +44,8 @@ export interface SelectProps {
     fieldNames?: SelectFieldNames;
     showHeaderOnEmpty?: boolean;
     showFooterOnEmpty?: boolean;
+    scrollbar?: boolean | ScrollbarProps;
+    tagNowrap?: boolean;
 }
 export type SelectOptionValue = string | number | boolean | Record<string, unknown>;
 export interface OptionValueWithKey {