x-next 1.13.0 → 1.15.0

package/AI_USAGE/components/tree-select-api.md

@@ -0,0 +1,498 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# TreeSelect 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## TreeSelect API
+
+公开声明：`dist/components/tree-select/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值，勾选 / 多选为数组 | undefined &#124; string &#124; number &#124; TreeSelectLabelValue &#124; TreeSelectValue[] | 否 | undefined |
+| defaultValue | 默认值（非受控） | undefined &#124; string &#124; number &#124; TreeSelectLabelValue &#124; TreeSelectValue[] | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| multiple | 是否多选 | undefined &#124; false &#124; true | 否 | false |
+| treeCheckable | 是否开启勾选模式，值始终为数组 | undefined &#124; false &#124; true | 否 | false |
+| treeCheckStrictly | 勾选模式是否取消父子联动 | undefined &#124; false &#124; true | 否 | false |
+| checkedStrategy | 勾选回填策略 | undefined &#124; "all" &#124; "parent" &#124; "child" | 否 | "parent" |
+| data | 树数据 | undefined &#124; TreeSelectNodeData[] | 否 | [] |
+| fieldNames | 自定义节点字段名 | undefined &#124; { [x: string]: string &#124; undefined; key?: string &#124; undefined; title?: string &#124; undefined; children?: string &#124; undefined; disabled?: string &#124; undefined; checkable?: string &#124; undefined; disableCheckbox?: string &#124; undefined; selectable?: string &#124; undefined; isLeaf?: string &#124; undefined; icon?: string &#124; undefined; } | 否 | 未声明 |
+| labelInValue | 值是否包含标题 | undefined &#124; false &#124; true | 否 | false |
+| selectable | 节点可选规则，支持 'leaf' 或方法 | undefined &#124; false &#124; true &#124; "leaf" &#124; (node: TreeSelectNodeData, info: { isLeaf: boolean; level: number; }) => boolean | 否 | true |
+| allowSearch | 是否允许搜索 | undefined &#124; false &#124; true &#124; { retainInputValue?: boolean; } | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| allowClear | 是否允许清空 | undefined &#124; false &#124; true | 否 | false |
+| filterTreeNode | 过滤节点方法，false 关闭过滤 | undefined &#124; false &#124; true &#124; (inputValue: string, node: TreeSelectNodeData) => boolean | 否 | true |
+| searchDelay | search 事件触发延迟 | undefined &#124; number | 否 | 500 |
+| inputValue | 搜索输入值（v-model） | undefined &#124; string | 否 | 未声明 |
+| defaultInputValue | 默认搜索输入值 | undefined &#124; string | 否 | "" |
+| size | 尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| placeholder | 占位提示 | undefined &#124; string | 否 | 未声明 |
+| loading | 是否加载中 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| error | 是否错误状态 | undefined &#124; false &#124; true | 否 | false |
+| bordered | 是否显示边框 | undefined &#124; false &#124; true | 否 | true |
+| maxTagCount | 最多展示标签数，0 不限制 | undefined &#124; number | 否 | 0 |
+| tagNowrap | 标签是否不换行 | undefined &#124; false &#124; true | 否 | false |
+| popupVisible | 面板显示状态（v-model） | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 面板默认显示状态 | undefined &#124; false &#124; true | 否 | false |
+| unmountOnClose | 关闭时销毁面板 | undefined &#124; false &#124; true | 否 | false |
+| popupContainer | 弹出层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| triggerProps | 触发器配置 | undefined &#124; TriggerProps | 否 | 未声明 |
+| defaultExpandAll | 默认展开全部节点 | undefined &#124; false &#124; true | 否 | false |
+| expandedKeys | 展开节点（v-model） | undefined &#124; TreeSelectKey[] | 否 | undefined |
+| defaultExpandedKeys | 默认展开节点 | undefined &#124; TreeSelectKey[] | 否 | [] |
+| autoExpandParent | 是否自动展开父节点 | undefined &#124; false &#124; true | 否 | true |
+| showLine | 是否显示连接线 | undefined &#124; false &#124; true | 否 | false |
+| blockNode | 节点占据整行 | undefined &#124; false &#124; true | 否 | false |
+| virtualListProps | 虚拟列表配置，传入即开启 | undefined &#124; VirtualListProps | 否 | 未声明 |
+| scrollbar | 是否开启滚动条或滚动条配置 | undefined &#124; false &#124; true &#124; ScrollbarProps | 否 | true |
+| maxHeight | 下拉列表最大高度 | undefined &#124; string &#124; number | 否 | 未声明 |
+| loadMore | 异步加载子节点 | undefined &#124; (node: TreeSelectNodeData) => Promise<void> | 否 | 未声明 |
+| fallbackOption | 自定义缺失值显示，false 丢弃 | undefined &#124; false &#124; true &#124; (value: TreeSelectKey) => TreeSelectNodeData | 否 | true |
+| formatLabel | 格式化显示内容 | undefined &#124; (data: TreeSelectNodeData) => string | 否 | 未声明 |
+| showHeaderOnEmpty | 空态是否显示页头 | undefined &#124; false &#124; true | 否 | false |
+| showFooterOnEmpty | 空态是否显示页脚 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: TreeSelectValue &#124; TreeSelectValue[] &#124; undefined) => any |
+| update:inputValue | 搜索输入更新时触发 | undefined &#124; (inputValue: string) => any |
+| update:popupVisible | 面板显隐更新时触发 | undefined &#124; (visible: boolean) => any |
+| update:expandedKeys | 展开节点更新时触发 | undefined &#124; (keys: TreeSelectKey[]) => any |
+| change | 值变化时触发 | undefined &#124; (value: TreeSelectValue &#124; TreeSelectValue[] &#124; undefined, info: Record<string, unknown>) => any |
+| inputValueChange | 搜索输入变化时触发 | undefined &#124; (inputValue: string) => any |
+| search | 用户搜索时触发（searchDelay 后） | undefined &#124; (inputValue: string) => any |
+| popupVisibleChange | 面板显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+| clear | 点击清空按钮时触发 | undefined &#124; (ev: Event) => any |
+| remove | 关闭多选标签时触发 | undefined &#124; (removed: TreeSelectValue &#124; undefined) => any |
+| expand | 展开状态变化时触发 | undefined &#124; (keys: TreeSelectKey[], info: Record<string, unknown>) => any |
+| dropdownScroll | 下拉滚动时触发 | undefined &#124; (ev: Event) => any |
+| nodeClick | 点击（勾选）节点时触发 | undefined &#124; (value: TreeSelectValue, info: Record<string, unknown>) => any |
+| focus | 默认触发器聚焦 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 默认触发器失焦 | undefined &#124; (ev: FocusEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| title | 自定义节点标题；参数 { node, value, title, level, checked, halfChecked, selected, expanded, disabled, isLeaf } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| node-icon | 节点前缀图标；参数 { node } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| switcher-icon | 展开 / 收起图标；参数 { node, expanded, loading } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| label | 选择框显示内容；参数 { data }，data 为 { value, label, raw } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| header | 下拉页头 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| footer | 下拉页脚 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| empty | 空状态内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| prefix | 选择框前缀元素 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| arrow-icon | 箭头图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| loading-icon | 加载中图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| search-icon | 搜索图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| trigger | 自定义触发元素；参数 { popupVisible, disabled, treeId, activeDescendant, onKeydown } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | 公开声明未细化（用法和实现已显式暴露） |
+| blur | 公开声明未细化（用法和实现已显式暴露） |
+| expandAll | 公开声明未细化（用法和实现已显式暴露） |
+| checkAll | 公开声明未细化（用法和实现已显式暴露） |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type TreeSelectKey = string | number;
+
+interface TreeSelectNodeData {
+    /**
+     * @zh 节点键值，全局唯一；不传时按节点路径自动生成
+     * @en Node key, unique in the whole tree; generated from the node path when omitted
+     */
+    key?: TreeSelectKey;
+    /**
+     * @zh 节点标题
+     * @en Node title
+     */
+    title?: string;
+    /**
+     * @zh 子节点
+     * @en Child nodes
+     */
+    children?: TreeSelectNodeData[];
+    /**
+     * @zh 是否禁用，禁用节点不可选中、不可勾选、不参与父子联动
+     * @en Whether disabled. Disabled nodes cannot be selected or checked and are excluded from cascade
+     */
+    disabled?: boolean;
+    /**
+     * @zh 是否可勾选，仅 `treeCheckable` 时生效
+     * @en Whether checkable, only works with `treeCheckable`
+     */
+    checkable?: boolean;
+    /**
+     * @zh 是否禁用复选框，仍可被父节点联动勾选
+     * @en Whether the checkbox is disabled. The node can still be toggled by its parent
+     */
+    disableCheckbox?: boolean;
+    /**
+     * @zh 是否可选中
+     * @en Whether selectable
+     */
+    selectable?: boolean;
+    /**
+     * @zh 是否为叶子节点，配合 `loadMore` 判断是否需要异步加载子节点
+     * @en Whether it is a leaf, used with `loadMore` for lazy loading
+     */
+    isLeaf?: boolean;
+    /**
+     * @zh 节点前缀图标
+     * @en Node prefix icon
+     */
+    icon?: RenderFunction;
+    [other: string]: any;
+}
+
+type TreeSelectFieldNames = FieldString<TreeSelectNodeData>;
+
+interface TreeSelectLabelValue {
+    /**
+     * @zh 选中的键值
+     * @en Selected key
+     */
+    value: TreeSelectKey;
+    /**
+     * @zh 选中的标题
+     * @en Selected title
+     */
+    label: string;
+    /**
+     * @zh 节点原始数据
+     * @en Raw node data
+     */
+    raw?: TreeSelectNodeData;
+}
+
+type TreeSelectValue = TreeSelectKey | TreeSelectLabelValue;
+
+type TreeSelectFilterNode = (inputValue: string, node: TreeSelectNodeData) => boolean;
+
+type TreeSelectSelectable = boolean | 'leaf' | ((node: TreeSelectNodeData, info: {
+    isLeaf: boolean;
+    level: number;
+}) => boolean);
+
+interface TreeSelectInstance {
+    /** 聚焦默认触发器 */
+    focus: () => void;
+    /** 失焦默认触发器 */
+    blur: () => void;
+    /** 展开 / 收起全部可展开节点，默认展开 */
+    expandAll: (expanded?: boolean) => void;
+    /** 全选 / 清空勾选，仅勾选模式生效，默认全选 */
+    checkAll: (checked?: boolean) => void;
+}
+
+interface TreeSelectProps {
+    modelValue?: TreeSelectValue | TreeSelectValue[];
+    defaultValue?: TreeSelectValue | TreeSelectValue[];
+    multiple?: boolean;
+    treeCheckable?: boolean;
+    treeCheckStrictly?: boolean;
+    checkedStrategy?: 'all' | 'parent' | 'child';
+    data?: TreeSelectNodeData[];
+    fieldNames?: TreeSelectFieldNames;
+    labelInValue?: boolean;
+    selectable?: TreeSelectSelectable;
+    allowSearch?: boolean | {
+        retainInputValue?: boolean;
+    };
+    allowClear?: boolean;
+    filterTreeNode?: boolean | TreeSelectFilterNode;
+    searchDelay?: number;
+    inputValue?: string;
+    defaultInputValue?: string;
+    size?: Size;
+    placeholder?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    bordered?: boolean;
+    maxTagCount?: number;
+    tagNowrap?: boolean;
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    unmountOnClose?: boolean;
+    popupContainer?: string | HTMLElement;
+    triggerProps?: TriggerProps;
+    defaultExpandAll?: boolean;
+    expandedKeys?: TreeSelectKey[];
+    defaultExpandedKeys?: TreeSelectKey[];
+    autoExpandParent?: boolean;
+    showLine?: boolean;
+    blockNode?: boolean;
+    virtualListProps?: VirtualListProps;
+    scrollbar?: boolean | ScrollbarProps;
+    maxHeight?: number | string;
+    loadMore?: (node: TreeSelectNodeData) => Promise<void>;
+    fallbackOption?: boolean | ((value: TreeSelectKey) => TreeSelectNodeData);
+    formatLabel?: (data: TreeSelectNodeData) => string;
+    showHeaderOnEmpty?: boolean;
+    showFooterOnEmpty?: boolean;
+}
+
+interface TreeSelectNodeInfo {
+    key: string;
+    value: TreeSelectKey;
+    title: string;
+    raw: TreeSelectNodeData;
+    level: number;
+    index: number;
+    parentKey?: string;
+    pathKeys: string[];
+    childrenKeys: string[];
+    siblingIndex: number;
+    siblingCount: number;
+    isLeaf: boolean;
+    disabled: boolean;
+    checkable: boolean;
+    disableCheckbox: boolean;
+    selectable: boolean;
+    loading: boolean;
+}
+
+interface TreeSelectNodeSlotProps {
+    node: TreeSelectNodeData;
+    value: TreeSelectKey;
+    title: string;
+    level: number;
+    checked: boolean;
+    halfChecked: boolean;
+    selected: boolean;
+    expanded: boolean;
+    disabled: boolean;
+    isLeaf: boolean;
+}
+```
+
+
+## TreeSelectDropdown API
+
+公开声明：`dist/components/tree-select/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| id | 见场景用法与类型 | undefined &#124; string | 否 | 未声明 |
+| loading | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| empty | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| virtualList | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| showLine | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| scrollbar | 见场景用法与类型 | undefined &#124; false &#124; true &#124; ScrollbarProps | 否 | true |
+| maxHeight | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 未声明 |
+| onScroll | 见场景用法与类型 | undefined &#124; ((ev: Event) => void) & ((...args: any[]) => any) &#124; ((ev: Event) => void)[] & ((...args: any[]) => any) | 否 | 未声明 |
+| showHeaderOnEmpty | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| showFooterOnEmpty | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| scroll | 见场景用法与类型 | undefined &#124; ((ev: Event) => void) & ((...args: any[]) => any) &#124; ((ev: Event) => void)[] & ((...args: any[]) => any) |
+| keydown | 见场景用法与类型 | undefined &#124; (...args: any[]) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type TreeSelectKey = string | number;
+
+interface TreeSelectNodeData {
+    /**
+     * @zh 节点键值，全局唯一；不传时按节点路径自动生成
+     * @en Node key, unique in the whole tree; generated from the node path when omitted
+     */
+    key?: TreeSelectKey;
+    /**
+     * @zh 节点标题
+     * @en Node title
+     */
+    title?: string;
+    /**
+     * @zh 子节点
+     * @en Child nodes
+     */
+    children?: TreeSelectNodeData[];
+    /**
+     * @zh 是否禁用，禁用节点不可选中、不可勾选、不参与父子联动
+     * @en Whether disabled. Disabled nodes cannot be selected or checked and are excluded from cascade
+     */
+    disabled?: boolean;
+    /**
+     * @zh 是否可勾选，仅 `treeCheckable` 时生效
+     * @en Whether checkable, only works with `treeCheckable`
+     */
+    checkable?: boolean;
+    /**
+     * @zh 是否禁用复选框，仍可被父节点联动勾选
+     * @en Whether the checkbox is disabled. The node can still be toggled by its parent
+     */
+    disableCheckbox?: boolean;
+    /**
+     * @zh 是否可选中
+     * @en Whether selectable
+     */
+    selectable?: boolean;
+    /**
+     * @zh 是否为叶子节点，配合 `loadMore` 判断是否需要异步加载子节点
+     * @en Whether it is a leaf, used with `loadMore` for lazy loading
+     */
+    isLeaf?: boolean;
+    /**
+     * @zh 节点前缀图标
+     * @en Node prefix icon
+     */
+    icon?: RenderFunction;
+    [other: string]: any;
+}
+
+type TreeSelectFieldNames = FieldString<TreeSelectNodeData>;
+
+interface TreeSelectLabelValue {
+    /**
+     * @zh 选中的键值
+     * @en Selected key
+     */
+    value: TreeSelectKey;
+    /**
+     * @zh 选中的标题
+     * @en Selected title
+     */
+    label: string;
+    /**
+     * @zh 节点原始数据
+     * @en Raw node data
+     */
+    raw?: TreeSelectNodeData;
+}
+
+type TreeSelectValue = TreeSelectKey | TreeSelectLabelValue;
+
+type TreeSelectFilterNode = (inputValue: string, node: TreeSelectNodeData) => boolean;
+
+type TreeSelectSelectable = boolean | 'leaf' | ((node: TreeSelectNodeData, info: {
+    isLeaf: boolean;
+    level: number;
+}) => boolean);
+
+interface TreeSelectInstance {
+    /** 聚焦默认触发器 */
+    focus: () => void;
+    /** 失焦默认触发器 */
+    blur: () => void;
+    /** 展开 / 收起全部可展开节点，默认展开 */
+    expandAll: (expanded?: boolean) => void;
+    /** 全选 / 清空勾选，仅勾选模式生效，默认全选 */
+    checkAll: (checked?: boolean) => void;
+}
+
+interface TreeSelectProps {
+    modelValue?: TreeSelectValue | TreeSelectValue[];
+    defaultValue?: TreeSelectValue | TreeSelectValue[];
+    multiple?: boolean;
+    treeCheckable?: boolean;
+    treeCheckStrictly?: boolean;
+    checkedStrategy?: 'all' | 'parent' | 'child';
+    data?: TreeSelectNodeData[];
+    fieldNames?: TreeSelectFieldNames;
+    labelInValue?: boolean;
+    selectable?: TreeSelectSelectable;
+    allowSearch?: boolean | {
+        retainInputValue?: boolean;
+    };
+    allowClear?: boolean;
+    filterTreeNode?: boolean | TreeSelectFilterNode;
+    searchDelay?: number;
+    inputValue?: string;
+    defaultInputValue?: string;
+    size?: Size;
+    placeholder?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    bordered?: boolean;
+    maxTagCount?: number;
+    tagNowrap?: boolean;
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    unmountOnClose?: boolean;
+    popupContainer?: string | HTMLElement;
+    triggerProps?: TriggerProps;
+    defaultExpandAll?: boolean;
+    expandedKeys?: TreeSelectKey[];
+    defaultExpandedKeys?: TreeSelectKey[];
+    autoExpandParent?: boolean;
+    showLine?: boolean;
+    blockNode?: boolean;
+    virtualListProps?: VirtualListProps;
+    scrollbar?: boolean | ScrollbarProps;
+    maxHeight?: number | string;
+    loadMore?: (node: TreeSelectNodeData) => Promise<void>;
+    fallbackOption?: boolean | ((value: TreeSelectKey) => TreeSelectNodeData);
+    formatLabel?: (data: TreeSelectNodeData) => string;
+    showHeaderOnEmpty?: boolean;
+    showFooterOnEmpty?: boolean;
+}
+
+interface TreeSelectNodeInfo {
+    key: string;
+    value: TreeSelectKey;
+    title: string;
+    raw: TreeSelectNodeData;
+    level: number;
+    index: number;
+    parentKey?: string;
+    pathKeys: string[];
+    childrenKeys: string[];
+    siblingIndex: number;
+    siblingCount: number;
+    isLeaf: boolean;
+    disabled: boolean;
+    checkable: boolean;
+    disableCheckbox: boolean;
+    selectable: boolean;
+    loading: boolean;
+}
+
+interface TreeSelectNodeSlotProps {
+    node: TreeSelectNodeData;
+    value: TreeSelectKey;
+    title: string;
+    level: number;
+    checked: boolean;
+    halfChecked: boolean;
+    selected: boolean;
+    expanded: boolean;
+    disabled: boolean;
+    isLeaf: boolean;
+}
+```
+
+
+返回 [TreeSelect 用法](./tree-select.md)。