x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/dropdown-api.md

@@ -0,0 +1,529 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Dropdown 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Dropdown API
+
+公开声明：`dist/components/dropdown/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| popupVisible | 弹出框是否可见 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 默认是否可见，非受控模式 | undefined &#124; false &#124; true | 否 | false |
+| trigger | 触发方式 | undefined &#124; "click" &#124; "hover" &#124; "focus" &#124; "contextMenu" &#124; ("click" &#124; "hover" &#124; "focus" &#124; "contextMenu")[] | 否 | "click" |
+| position | 弹出位置 | undefined &#124; "top" &#124; "bottom" &#124; "tl" &#124; "tr" &#124; "bl" &#124; "br" | 否 | "bottom" |
+| popupContainer | 弹出层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| popupMaxHeight | 弹出层最大高度 | undefined &#124; number &#124; false &#124; true | 否 | true |
+| loading | 是否为加载中状态 | undefined &#124; false &#124; true | 否 | false |
+| isEmpty | 是否为空状态 | undefined &#124; false &#124; true | 否 | false |
+| bottomOffset | 触发到达底部的偏移量 | undefined &#124; number | 否 | 0 |
+| alignPoint | 弹出层是否跟随鼠标位置，常用于右键菜单 | undefined &#124; false &#124; true | 否 | false |
+| hideOnSelect | 选择后是否隐藏弹出层 | undefined &#124; false &#124; true | 否 | true |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:popupVisible | 弹出层显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+| popupVisibleChange | 弹出层显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+| select | 选中菜单项时触发 | undefined &#124; (value: string &#124; number &#124; Record<string, any> &#124; undefined, ev: Event) => any |
+| scroll | 下拉菜单滚动时触发 | undefined &#124; (ev: Event) => any |
+| reachBottom | 下拉菜单滚动到底部时触发 | undefined &#124; (ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 触发元素 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| content | 下拉菜单内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| empty | 空状态内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| footer | 下拉菜单底部 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type DropdownPosition = 'top' | 'tl' | 'tr' | 'bottom' | 'bl' | 'br';
+
+interface DropDownProps {
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    trigger?: TriggerEvent | TriggerEvent[];
+    position?: DropdownPosition;
+    popupContainer?: string | HTMLElement;
+    popupMaxHeight?: boolean | number;
+    loading?: boolean;
+    isEmpty?: boolean;
+    bottomOffset?: number;
+    alignPoint?: boolean;
+    hideOnSelect?: boolean;
+}
+
+interface DOption {
+    value: string | number;
+    disabled?: boolean;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DGroup {
+    isGroup: true;
+    options: DropdownOption[];
+    title?: string;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DSubmenu extends DOption {
+    isSubmenu: true;
+    render: Slot;
+    children: DropdownOption[];
+    trigger?: TriggerEvent;
+    position?: TriggerPosition;
+    footer?: Slot;
+}
+
+type DropdownOption = DOption | DGroup | DSubmenu;
+
+interface DropdownContext {
+    popupMaxHeight: boolean | number;
+    onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
+}
+
+interface DropdownMenuItem {
+    element: Ref<HTMLElement | undefined>;
+    disabled: Readonly<Ref<boolean>>;
+}
+
+interface DropdownMenuContext {
+    activeItem: Ref<DropdownMenuItem | undefined>;
+    registerItem: (item: DropdownMenuItem) => () => void;
+    setActiveItem: (item: DropdownMenuItem) => void;
+}
+
+interface DropdownPanelRef {
+    focus: (edge?: 'first' | 'last') => boolean;
+}
+```
+
+
+## DropdownButton API
+
+公开声明：`dist/components/dropdown/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| popupVisible | 弹出框是否可见 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 默认是否可见，非受控模式 | undefined &#124; false &#124; true | 否 | false |
+| trigger | 触发方式 | undefined &#124; "click" &#124; "hover" &#124; "focus" &#124; "contextMenu" &#124; ("click" &#124; "hover" &#124; "focus" &#124; "contextMenu")[] | 否 | "click" |
+| position | 弹出位置 | undefined &#124; "top" &#124; "bottom" &#124; "tl" &#124; "tr" &#124; "bl" &#124; "br" | 否 | "br" |
+| popupContainer | 弹出层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| type | 按钮类型 | undefined &#124; "default" &#124; "primary" &#124; "dashed" &#124; "outline" &#124; "text" | 否 | "default" |
+| size | 按钮尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" &#124; "huge" | 否 | "medium" |
+| buttonProps | 左侧主按钮属性 | undefined &#124; { disabled?: boolean; block?: boolean; loading?: boolean; loadingFill?: boolean; debounce?: number; shape?: ButtonShape; link?: boolean; type?: ButtonTypes; htmlType?: ButtonHtmlType; status?: ButtonStatus; plain?: boolean; size?: ButtonSize; border?: boolean; narrow?: boolean; } | 否 | 未声明 |
+| hideOnSelect | 选择后是否隐藏弹出层 | undefined &#124; false &#124; true | 否 | true |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:popupVisible | 弹出层显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+| popupVisibleChange | 弹出层显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+| click | 点击左侧主按钮时触发 | undefined &#124; (ev: MouseEvent) => any |
+| select | 选中菜单项时触发 | undefined &#124; (value: string &#124; number &#124; Record<string, any> &#124; undefined, ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 左侧主按钮内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| icon | 右侧下拉按钮图标，参数为 popupVisible | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| content | 下拉菜单内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type DropdownPosition = 'top' | 'tl' | 'tr' | 'bottom' | 'bl' | 'br';
+
+interface DropDownProps {
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    trigger?: TriggerEvent | TriggerEvent[];
+    position?: DropdownPosition;
+    popupContainer?: string | HTMLElement;
+    popupMaxHeight?: boolean | number;
+    loading?: boolean;
+    isEmpty?: boolean;
+    bottomOffset?: number;
+    alignPoint?: boolean;
+    hideOnSelect?: boolean;
+}
+
+interface DOption {
+    value: string | number;
+    disabled?: boolean;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DGroup {
+    isGroup: true;
+    options: DropdownOption[];
+    title?: string;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DSubmenu extends DOption {
+    isSubmenu: true;
+    render: Slot;
+    children: DropdownOption[];
+    trigger?: TriggerEvent;
+    position?: TriggerPosition;
+    footer?: Slot;
+}
+
+type DropdownOption = DOption | DGroup | DSubmenu;
+
+interface DropdownContext {
+    popupMaxHeight: boolean | number;
+    onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
+}
+
+interface DropdownMenuItem {
+    element: Ref<HTMLElement | undefined>;
+    disabled: Readonly<Ref<boolean>>;
+}
+
+interface DropdownMenuContext {
+    activeItem: Ref<DropdownMenuItem | undefined>;
+    registerItem: (item: DropdownMenuItem) => () => void;
+    setActiveItem: (item: DropdownMenuItem) => void;
+}
+
+interface DropdownPanelRef {
+    focus: (edge?: 'first' | 'last') => boolean;
+}
+```
+
+
+## DropdownGroup API
+
+公开声明：`dist/components/dropdown/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| title | 分组标题 | undefined &#124; string | 否 | 未声明 |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| title | 分组标题 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| default | 分组内选项 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type DropdownPosition = 'top' | 'tl' | 'tr' | 'bottom' | 'bl' | 'br';
+
+interface DropDownProps {
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    trigger?: TriggerEvent | TriggerEvent[];
+    position?: DropdownPosition;
+    popupContainer?: string | HTMLElement;
+    popupMaxHeight?: boolean | number;
+    loading?: boolean;
+    isEmpty?: boolean;
+    bottomOffset?: number;
+    alignPoint?: boolean;
+    hideOnSelect?: boolean;
+}
+
+interface DOption {
+    value: string | number;
+    disabled?: boolean;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DGroup {
+    isGroup: true;
+    options: DropdownOption[];
+    title?: string;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DSubmenu extends DOption {
+    isSubmenu: true;
+    render: Slot;
+    children: DropdownOption[];
+    trigger?: TriggerEvent;
+    position?: TriggerPosition;
+    footer?: Slot;
+}
+
+type DropdownOption = DOption | DGroup | DSubmenu;
+
+interface DropdownContext {
+    popupMaxHeight: boolean | number;
+    onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
+}
+
+interface DropdownMenuItem {
+    element: Ref<HTMLElement | undefined>;
+    disabled: Readonly<Ref<boolean>>;
+}
+
+interface DropdownMenuContext {
+    activeItem: Ref<DropdownMenuItem | undefined>;
+    registerItem: (item: DropdownMenuItem) => () => void;
+    setActiveItem: (item: DropdownMenuItem) => void;
+}
+
+interface DropdownPanelRef {
+    focus: (edge?: 'first' | 'last') => boolean;
+}
+```
+
+
+## DropdownOption API
+
+公开声明：`dist/components/dropdown/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| value | 选项值，不传时使用文本内容 | undefined &#124; string &#124; number &#124; { [x: string]: any; } | 否 | 未声明 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| active | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| uninjectContext | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| click | 点击或键盘激活选项时触发 | undefined &#124; (ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 选项内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| icon | 选项图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| suffix | 选项后缀 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type DropdownPosition = 'top' | 'tl' | 'tr' | 'bottom' | 'bl' | 'br';
+
+interface DropDownProps {
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    trigger?: TriggerEvent | TriggerEvent[];
+    position?: DropdownPosition;
+    popupContainer?: string | HTMLElement;
+    popupMaxHeight?: boolean | number;
+    loading?: boolean;
+    isEmpty?: boolean;
+    bottomOffset?: number;
+    alignPoint?: boolean;
+    hideOnSelect?: boolean;
+}
+
+interface DOption {
+    value: string | number;
+    disabled?: boolean;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DGroup {
+    isGroup: true;
+    options: DropdownOption[];
+    title?: string;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DSubmenu extends DOption {
+    isSubmenu: true;
+    render: Slot;
+    children: DropdownOption[];
+    trigger?: TriggerEvent;
+    position?: TriggerPosition;
+    footer?: Slot;
+}
+
+type DropdownOption = DOption | DGroup | DSubmenu;
+
+interface DropdownContext {
+    popupMaxHeight: boolean | number;
+    onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
+}
+
+interface DropdownMenuItem {
+    element: Ref<HTMLElement | undefined>;
+    disabled: Readonly<Ref<boolean>>;
+}
+
+interface DropdownMenuContext {
+    activeItem: Ref<DropdownMenuItem | undefined>;
+    registerItem: (item: DropdownMenuItem) => () => void;
+    setActiveItem: (item: DropdownMenuItem) => void;
+}
+
+interface DropdownPanelRef {
+    focus: (edge?: 'first' | 'last') => boolean;
+}
+```
+
+
+## DropdownSubmenu API
+
+公开声明：`dist/components/dropdown/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| value | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 未声明 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| trigger | 触发方式 | undefined &#124; "click" &#124; "hover" &#124; ("click" &#124; "hover")[] | 否 | "click" |
+| position | 弹出位置 | undefined &#124; "lt" &#124; "rt" | 否 | "rt" |
+| popupVisible | 弹出层是否可见 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 默认是否可见 | undefined &#124; false &#124; true | 否 | false |
+| optionProps | 传给内部 DropdownOption 的属性 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:popupVisible | 子菜单显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+| popupVisibleChange | 子菜单显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 子菜单触发项内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| icon | 子菜单图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| suffix | 子菜单后缀 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| content | 子菜单内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| footer | 子菜单底部 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type DropdownPosition = 'top' | 'tl' | 'tr' | 'bottom' | 'bl' | 'br';
+
+interface DropDownProps {
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    trigger?: TriggerEvent | TriggerEvent[];
+    position?: DropdownPosition;
+    popupContainer?: string | HTMLElement;
+    popupMaxHeight?: boolean | number;
+    loading?: boolean;
+    isEmpty?: boolean;
+    bottomOffset?: number;
+    alignPoint?: boolean;
+    hideOnSelect?: boolean;
+}
+
+interface DOption {
+    value: string | number;
+    disabled?: boolean;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DGroup {
+    isGroup: true;
+    options: DropdownOption[];
+    title?: string;
+    _props?: Record<string, any>;
+    _slots?: Slots;
+}
+
+interface DSubmenu extends DOption {
+    isSubmenu: true;
+    render: Slot;
+    children: DropdownOption[];
+    trigger?: TriggerEvent;
+    position?: TriggerPosition;
+    footer?: Slot;
+}
+
+type DropdownOption = DOption | DGroup | DSubmenu;
+
+interface DropdownContext {
+    popupMaxHeight: boolean | number;
+    onOptionClick: (value: string | number | Record<string, unknown> | undefined, ev: Event) => void;
+}
+
+interface DropdownMenuItem {
+    element: Ref<HTMLElement | undefined>;
+    disabled: Readonly<Ref<boolean>>;
+}
+
+interface DropdownMenuContext {
+    activeItem: Ref<DropdownMenuItem | undefined>;
+    registerItem: (item: DropdownMenuItem) => () => void;
+    setActiveItem: (item: DropdownMenuItem) => void;
+}
+
+interface DropdownPanelRef {
+    focus: (edge?: 'first' | 'last') => boolean;
+}
+```
+
+
+返回 [Dropdown 用法](./dropdown.md)。