From 7db060b7fb7f0da5e93bae7d76b65f6d87ce1fac Mon Sep 17 00:00:00 2001 From: wzc520pyfm <1528857653@qq.com> Date: Tue, 23 Jul 2024 11:04:23 +0800 Subject: [PATCH] docs(components): [menu] use new display tag (#15385) * docs(components): [menu] use new display tag * docs(components): [menu] delete deprecated attr of sub-menu --- docs/en-US/component/menu.md | 214 +++++++++++------- .../components/menu/src/menu-item-group.ts | 3 + packages/components/menu/src/menu-item.ts | 9 + packages/components/menu/src/menu.ts | 60 +++++ packages/components/menu/src/sub-menu.ts | 33 +++ 5 files changed, 238 insertions(+), 81 deletions(-) diff --git a/docs/en-US/component/menu.md b/docs/en-US/component/menu.md index c6d3d29643..579811ed9f 100644 --- a/docs/en-US/component/menu.md +++ b/docs/en-US/component/menu.md @@ -61,105 +61,157 @@ menu/popper-offset ::: -## Menu Attributes +## Menu API -| Name | Description | Type | Accepted Values | Default | -| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | -------- | -| mode | menu display mode | string | horizontal / vertical | vertical | -| collapse | whether the menu is collapsed (available only in vertical mode) | boolean | — | false | -| ellipsis | whether the menu is ellipsis (available only in horizontal mode) | boolean | — | true | -| ellipsis-icon ^(2.4.4) | custom ellipsis icon (available only in horizontal mode and ellipsis is true) | `string \| Component` | — | — | -| popper-offset ^(2.4.4) | offset of the popper (effective for all submenus) | number | — | 6 | -| background-color | background color of Menu (hex format) (deprecated, use `--bg-color` instead) | string | — | #ffffff | -| text-color | text color of Menu (hex format) (deprecated, use `--text-color` instead) | string | — | #303133 | -| active-text-color | text color of currently active menu item (hex format) (deprecated, use `--active-color` instead) | string | — | #409eff | -| default-active | index of active menu on page load | string | — | — | -| default-openeds | array that contains indexes of currently active sub-menus | Array | — | — | -| unique-opened | whether only one sub-menu can be active | boolean | — | false | -| menu-trigger | how sub-menus are triggered, only works when `mode` is 'horizontal' | string | hover / click | hover | -| router | whether `vue-router` mode is activated. If true, index will be used as 'path' to activate the route action. Use with `default-active` to set the active item on load. | boolean | — | false | -| collapse-transition | whether to enable the collapse transition | boolean | — | true | -| popper-effect ^(2.2.26) | Tooltip theme, built-in theme: `dark` / `light` when menu is collapsed | string | dark / light | dark | -| close-on-click-outside ^(2.4.4) | optional, whether menu is collapsed when clicking outside | `boolean` | — | false | -| popper-class ^(2.5.0) | custom class name for all popup menus | string | — | — | -| show-timeout ^(2.5.0) | Control timeout for all menus before showing | `number` | — | 300 | -| hide-timeout ^(2.5.0) | Control timeout for all menus before hiding | `number` | — | 300 | +### Menu Attributes -## Menu Methods +| Name | Description | Type | Default | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -------- | +| mode | menu display mode | ^[enum]`'horizontal' \| 'vertical'` | vertical | +| collapse | whether the menu is collapsed (available only in vertical mode) | ^[boolean] | false | +| ellipsis | whether the menu is ellipsis (available only in horizontal mode) | ^[boolean] | true | +| ellipsis-icon ^(2.4.4) | custom ellipsis icon (available only in horizontal mode and ellipsis is true) | ^[string] / ^[Component] | — | +| popper-offset ^(2.4.4) | offset of the popper (effective for all submenus) | ^[number] | 6 | +| background-color ^(deprecated) | background color of Menu (hex format) (deprecated, use `--bg-color` instead) | ^[string] | #ffffff | +| text-color ^(deprecated) | text color of Menu (hex format) (deprecated, use `--text-color` instead) | ^[string] | #303133 | +| active-text-color ^(deprecated) | text color of currently active menu item (hex format) (deprecated, use `--active-color` instead) | ^[string] | #409eff | +| default-active | index of active menu on page load | ^[string] | '' | +| default-openeds | array that contains indexes of currently active sub-menus | ^[object]`string[]` | [] | +| unique-opened | whether only one sub-menu can be active | ^[boolean] | false | +| menu-trigger | how sub-menus are triggered, only works when `mode` is 'horizontal' | ^[enum]`'hover' \| 'click'` | hover | +| router | whether `vue-router` mode is activated. If true, index will be used as 'path' to activate the route action. Use with `default-active` to set the active item on load. | ^[boolean] | false | +| collapse-transition | whether to enable the collapse transition | ^[boolean] | true | +| popper-effect ^(2.2.26) | Tooltip theme, built-in theme: `dark` / `light` when menu is collapsed | ^[enum]`'dark' \| 'light'` | dark | +| close-on-click-outside ^(2.4.4) | optional, whether menu is collapsed when clicking outside | ^[boolean] | false | +| popper-class ^(2.5.0) | custom class name for all popup menus | ^[string] | — | +| show-timeout ^(2.5.0) | control timeout for all menus before showing | ^[number] | 300 | +| hide-timeout ^(2.5.0) | control timeout for all menus before hiding | ^[number] | 300 | -| Methods Name | Description | Parameters | -| ------------ | ------------------------- | ------------------------------------- | -| open | Open a specific sub-menu | index: index of the sub-menu to open | -| close | Close a specific sub-menu | index: index of the sub-menu to close | +### Menu Events -## Menu Events +| Name | Description | Type | +| ------ | ----------------------------------------- | ---------------------------- | +| select | callback function when menu is activated | ^[Function]`MenuSelectEvent` | +| open | callback function when sub-menu expands | ^[Function]`MenuOpenEvent` | +| close | callback function when sub-menu collapses | ^[Function]`MenuCloseEvent` | -| Name | Description | Parameters | -| ------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| select | callback function when menu is activated | index: index of activated menu, indexPath: index path of activated menu, item: the selected menu item, routeResult: result returned by `vue-router` if `router` is enabled | -| open | callback function when sub-menu expands | index: index of expanded sub-menu, indexPath: index path of expanded sub-menu | -| close | callback function when sub-menu collapses | index: index of collapsed sub-menu, indexPath: index path of collapsed sub-menu | +### Menu Slots -## Menu Slots +| Name | Description | Subtags | +| ------- | ------------------------- | ------------------------------------- | +| default | customize default content | SubMenu / Menu-Item / Menu-Item-Group | -| Name | Description | Subtags | -| ---- | ------------------------- | ------------------------------------- | -| — | customize default content | SubMenu / Menu-Item / Menu-Item-Group | +### Menu Exposes -## SubMenu Attributes +| Name | Description | Type | +| ------------ | ---------------------------------------------------------------------- | ------------------------------------ | +| open | open a specific sub-menu, the param is index of the sub-menu to open | ^[Function]`(index: string) => void` | +| close | close a specific sub-menu, the param is index of the sub-menu to close | ^[Function]`(index: string) => void` | -| Name | Description | Type | Accepted Values | Default | -| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------- | ----------------------------------------------- | -| index | unique identification | string | — | — | -| popper-class | custom class name for the popup menu | string | — | — | -| show-timeout | timeout before showing a sub-menu(inherit `show-timeout` of the menu by default.) | number | — | — | -| hide-timeout | timeout before hiding a sub-menu(inherit `hide-timeout` of the menu by default.) | number | — | — | -| disabled | whether the sub-menu is disabled | boolean | — | false | -| popper-append-to-body ^(deprecated) | whether to append the popup menu to body. If the positioning of the menu is wrong, you can try setting this prop | boolean | — | level one SubMenu: true / other SubMenus: false | -| teleported | whether popup menu is teleported to the body | boolean | — | level one SubMenu: true / other SubMenus: false | -| popper-offset | offset of the popper (overrides the `popper` of menu) | number | — | — | -| expand-close-icon | Icon when menu are expanded and submenu are closed, `expand-close-icon` and `expand-open-icon` need to be passed together to take effect | `string \| Component` | — | — | -| expand-open-icon | Icon when menu are expanded and submenu are opened, `expand-open-icon` and `expand-close-icon` need to be passed together to take effect | `string \| Component` | — | — | -| collapse-close-icon | Icon when menu are collapsed and submenu are closed, `collapse-close-icon` and `collapse-open-icon` need to be passed together to take effect | `string \| Component` | — | — | -| collapse-open-icon | Icon when menu are collapsed and submenu are opened, `collapse-open-icon` and `collapse-close-icon` need to be passed together to take effect | `string \| Component` | — | — | +## SubMenu API -## SubMenu Slots +### SubMenu Attributes -| Name | Description | Subtags | -| ----- | ------------------------- | ------------------------------------- | -| — | customize default content | SubMenu / Menu-Item / Menu-Item-Group | -| title | customize title content | — | +| Name | Description | Type | Default | +| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | --------- | +| index ^(required) | unique identification | ^[string] | — | +| popper-class | custom class name for the popup menu | ^[string] | — | +| show-timeout | timeout before showing a sub-menu(inherit `show-timeout` of the menu by default.) | ^[number] | — | +| hide-timeout | timeout before hiding a sub-menu(inherit `hide-timeout` of the menu by default.) | ^[number] | — | +| disabled | whether the sub-menu is disabled | ^[boolean] | false | +| teleported | whether popup menu is teleported to the body, the default is true for the level one SubMenu, false for other SubMenus | ^[boolean] | undefined | +| popper-offset | offset of the popper (overrides the `popper` of menu) | ^[number] | — | +| expand-close-icon | Icon when menu are expanded and submenu are closed, `expand-close-icon` and `expand-open-icon` need to be passed together to take effect | ^[string] / ^[Component] | — | +| expand-open-icon | Icon when menu are expanded and submenu are opened, `expand-open-icon` and `expand-close-icon` need to be passed together to take effect | ^[string] / ^[Component] | — | +| collapse-close-icon | Icon when menu are collapsed and submenu are closed, `collapse-close-icon` and `collapse-open-icon` need to be passed together to take effect | ^[string] / ^[Component] | — | +| collapse-open-icon | Icon when menu are collapsed and submenu are opened, `collapse-open-icon` and `collapse-close-icon` need to be passed together to take effect | ^[string] / ^[Component] | — | -## Menu-Item Attributes +### SubMenu Slots -| Name | Description | Type | Accepted Values | Default | -| -------- | --------------------- | ----------- | --------------- | ------- | -| index | unique identification | string/null | — | null | -| route | Vue Router object | object | — | — | -| disabled | whether disabled | boolean | — | false | +| Name | Description | Subtags | +| ------- | ------------------------- | ------------------------------------- | +| default | customize default content | SubMenu / Menu-Item / Menu-Item-Group | +| title | customize title content | — | -## Menu-Item Events +## Menu-Item API -| Name | Description | Parameters | -| ----- | ------------------------------------------- | ---------------------- | -| click | callback function when menu-item is clicked | el: menu-item instance | +### Menu-Item Attributes -## Menu-Item Slots +| Name | Description | Type | Default | +| -------- | --------------------- | ------------------- | ------- | +| index | unique identification | ^[string] / ^[null] | null | +| route | Vue Router object | ^[object] | — | +| disabled | whether disabled | ^[boolean] | false | -| Name | Description | -| ----- | ------------------------- | -| — | customize default content | -| title | customize title content | +### Menu-Item Events -## Menu-Item-Group Attributes +| Name | Description | Type | +| ----- | ---------------------------------------------------------------------------- | ----------------------------------------------- | +| click | callback function when menu-item is clicked, the param is menu-item instance | ^[Function]`(item: MenuItemRegistered) => void` | -| Name | Description | Type | Accepted Values | Default | -| ----- | ----------- | ------ | --------------- | ------- | -| title | group title | string | — | — | +### Menu-Item Slots -## Menu-Item-Group Slots +| Name | Description | +| ------- | ------------------------- | +| default | customize default content | +| title | customize title content | -| Name | Description | Subtags | -| ----- | ------------------------- | --------- | -| — | customize default content | Menu-Item | -| title | customize group title | — | +## Menu-Item-Group API + +### Menu-Item-Group Attributes + +| Name | Description | Type | Default | +| ----- | ----------- | --------- | ------- | +| title | group title | ^[string] | — | + +### Menu-Item-Group Slots + +| Name | Description | Subtags | +| ------- | ------------------------- | --------- | +| default | customize default content | Menu-Item | +| title | customize group title | — | + +## Type Declarations + +
+ Show declarations + +```ts +/** + * @param index index of activated menu + * @param indexPath index path of activated menu + * @param item the selected menu item + * @param routerResult result returned by `vue-router` if `router` is enabled + */ +type MenuSelectEvent = ( + index: string, + indexPath: string[], + item: MenuItemClicked, + routerResult?: Promise +) => void + +/** + * @param index index of expanded sub-menu + * @param indexPath index path of expanded sub-menu + */ +type MenuOpenEvent = (index: string, indexPath: string[]) => void + +/** + * @param index index of collapsed sub-menu + * @param indexPath index path of collapsed sub-menu + */ +type MenuCloseEvent = (index: string, indexPath: string[]) => void + +interface MenuItemRegistered { + index: string + indexPath: string[] + active: boolean +} + +interface MenuItemClicked { + index: string + indexPath: string[] + route?: RouteLocationRaw +} +``` +
diff --git a/packages/components/menu/src/menu-item-group.ts b/packages/components/menu/src/menu-item-group.ts index 5ee3474bc4..defeca23ca 100644 --- a/packages/components/menu/src/menu-item-group.ts +++ b/packages/components/menu/src/menu-item-group.ts @@ -1,6 +1,9 @@ import type { ExtractPropTypes } from 'vue' export const menuItemGroupProps = { + /** + * @description group title + */ title: String, } as const export type MenuItemGroupProps = ExtractPropTypes diff --git a/packages/components/menu/src/menu-item.ts b/packages/components/menu/src/menu-item.ts index fa5c66b764..672561a554 100644 --- a/packages/components/menu/src/menu-item.ts +++ b/packages/components/menu/src/menu-item.ts @@ -5,13 +5,22 @@ import type { RouteLocationRaw } from 'vue-router' import type { MenuItemRegistered } from './types' export const menuItemProps = buildProps({ + /** + * @description unique identification + */ index: { type: definePropType([String, null]), default: null, }, + /** + * @description Vue Router object + */ route: { type: definePropType([String, Object]), }, + /** + * @description whether disabled + */ disabled: Boolean, } as const) export type MenuItemProps = ExtractPropTypes diff --git a/packages/components/menu/src/menu.ts b/packages/components/menu/src/menu.ts index bf66e31721..9623f5e194 100644 --- a/packages/components/menu/src/menu.ts +++ b/packages/components/menu/src/menu.ts @@ -45,57 +45,117 @@ import type { import type { UseResizeObserverReturn } from '@vueuse/core' export const menuProps = buildProps({ + /** + * @description menu display mode + */ mode: { type: String, values: ['horizontal', 'vertical'], default: 'vertical', }, + /** + * @description index of active menu on page load + */ defaultActive: { type: String, default: '', }, + /** + * @description array that contains indexes of currently active sub-menus + */ defaultOpeneds: { type: definePropType(Array), default: () => mutable([] as const), }, + /** + * @description whether only one sub-menu can be active + */ uniqueOpened: Boolean, + /** + * @description whether `vue-router` mode is activated. If true, index will be used as 'path' to activate the route action. Use with `default-active` to set the active item on load. + */ router: Boolean, + /** + * @description how sub-menus are triggered, only works when `mode` is 'horizontal' + */ menuTrigger: { type: String, values: ['hover', 'click'], default: 'hover', }, + /** + * @description whether the menu is collapsed (available only in vertical mode) + */ collapse: Boolean, + /** + * @description background color of Menu (hex format) (deprecated, use `--bg-color` instead) + * @deprecated use `--bg-color` instead + */ backgroundColor: String, + /** + * @description text color of Menu (hex format) (deprecated, use `--text-color` instead) + * @deprecated use `--text-color` instead + */ textColor: String, + /** + * @description text color of currently active menu item (hex format) (deprecated, use `--active-color` instead) + * @deprecated use `--active-color` instead + */ activeTextColor: String, + /** + * @description optional, whether menu is collapsed when clicking outside + */ closeOnClickOutside: Boolean, + /** + * @description whether to enable the collapse transition + */ collapseTransition: { type: Boolean, default: true, }, + /** + * @description whether the menu is ellipsis (available only in horizontal mode) + */ ellipsis: { type: Boolean, default: true, }, + /** + * @description offset of the popper (effective for all submenus) + */ popperOffset: { type: Number, default: 6, }, + /** + * @description custom ellipsis icon (available only in horizontal mode and ellipsis is true) + */ ellipsisIcon: { type: iconPropType, default: () => More, }, + /** + * @description Tooltip theme, built-in theme: `dark` / `light` when menu is collapsed + */ popperEffect: { type: String, values: ['dark', 'light'], default: 'dark', }, + /** + * @description custom class name for all popup menus + */ popperClass: String, + /** + * @description control timeout for all menus before showing + */ showTimeout: { type: Number, default: 300, }, + /** + * @description control timeout for all menus before hiding + */ hideTimeout: { type: Number, default: 300, diff --git a/packages/components/menu/src/sub-menu.ts b/packages/components/menu/src/sub-menu.ts index 9888f6f20c..7461976d04 100644 --- a/packages/components/menu/src/sub-menu.ts +++ b/packages/components/menu/src/sub-menu.ts @@ -34,28 +34,61 @@ import type { ExtractPropTypes, VNodeArrayChildren } from 'vue' import type { MenuProvider, SubMenuProvider } from './types' export const subMenuProps = buildProps({ + /** + * @description unique identification + */ index: { type: String, required: true, }, + /** + * @description timeout before showing a sub-menu(inherit `show-timeout` of the menu by default.) + */ showTimeout: Number, + /** + * @description timeout before hiding a sub-menu(inherit `hide-timeout` of the menu by default.) + */ hideTimeout: Number, + /** + * @description custom class name for the popup menu + */ popperClass: String, + /** + * @description whether the sub-menu is disabled + */ disabled: Boolean, + /** + * @description whether popup menu is teleported to the body + */ teleported: { type: Boolean, default: undefined, }, + /** + * @description offset of the popper (overrides the `popper` of menu) + */ popperOffset: Number, + /** + * @description Icon when menu are expanded and submenu are closed, `expand-close-icon` and `expand-open-icon` need to be passed together to take effect + */ expandCloseIcon: { type: iconPropType, }, + /** + * @description Icon when menu are expanded and submenu are opened, `expand-open-icon` and `expand-close-icon` need to be passed together to take effect + */ expandOpenIcon: { type: iconPropType, }, + /** + * @description Icon when menu are collapsed and submenu are closed, `collapse-close-icon` and `collapse-open-icon` need to be passed together to take effect + */ collapseCloseIcon: { type: iconPropType, }, + /** + * @description Icon when menu are collapsed and submenu are opened, `collapse-open-icon` and `collapse-close-icon` need to be passed together to take effect + */ collapseOpenIcon: { type: iconPropType, },