From a67b52cccecefd8f352698b58e7cc899a1a5583b Mon Sep 17 00:00:00 2001 From: Xc <124118265@qq.com> Date: Fri, 10 Mar 2023 14:42:46 +0800 Subject: [PATCH] docs(components): [tooltip] (#11850) * docs(components): [tooltip] * Update popconfirm docs with new syntax. * Remove tabindex and manual api * docs(components): [tooltip] * add Exposes * docs(components): [tooltip] * docs(components): [tooltip] * docs(components): [tooltip] * docs(components): [tooltip] * docs(components): [tooltip] * docs(components): [tooltip] * docs(components): [tooltip] * docs(components): [tooltip] * docs(components): [tooltip] * docs(components): [tooltip] --- docs/en-US/component/tooltip.md | 70 ++++++++++++--------- packages/components/popper/src/content.ts | 9 +++ packages/components/tooltip/src/content.ts | 40 +++++++++--- packages/components/tooltip/src/tooltip.ts | 3 + packages/components/tooltip/src/tooltip.vue | 6 +- packages/components/tooltip/src/trigger.ts | 9 +++ packages/hooks/use-delayed-toggle/index.ts | 6 ++ 7 files changed, 105 insertions(+), 38 deletions(-) diff --git a/docs/en-US/component/tooltip.md b/docs/en-US/component/tooltip.md index 8a23314c31..8c634a66f5 100644 --- a/docs/en-US/component/tooltip.md +++ b/docs/en-US/component/tooltip.md @@ -146,37 +146,51 @@ tooltip/animations ::: -## Attributes +## API -| Name | Description | Type | Accepted Values | Default | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| append-to | which element the tooltip CONTENT appends to | `CSSSelector \| HTMLElement` | — | #el-popper-container-[randomValue] | -| effect | Tooltip theme, built-in theme: `dark` / `light` | string | dark / light | dark | -| content | display content, can be overridden by `slot#content` | String | — | — | -| raw-content | whether `content` is treated as HTML string | boolean | — | false | -| placement | position of Tooltip | string | top/top-start/top-end/bottom/bottom-start/bottom-end/left/left-start/left-end/right/right-start/right-end | bottom | -| visible / v-model:visible | visibility of Tooltip | boolean | — | false | -| disabled | whether Tooltip is disabled | boolean | — | false | -| offset | offset of the Tooltip | number | — | 0 | -| transition | animation name | string | — | el-fade-in-linear | -| popper-options | [popper.js](https://popper.js.org/docs/v2/) parameters | Object | refer to [popper.js](https://popper.js.org/docs/v2/) doc | `{modifiers: [{name: 'computeStyles',options: {gpuAcceleration: false}}]}` | -| show-after | delay of appearance, in millisecond | number | — | 0 | -| show-arrow | whether the tooltip content has an arrow | boolean | true / false | true | -| hide-after | delay of disappear, in millisecond | number | — | 200 | -| auto-close | timeout in milliseconds to hide tooltip | number | — | 0 | -| manual | whether to control Tooltip manually. `mouseenter` and `mouseleave` won't have effects if set to `true` | boolean | — | false | -| popper-class | custom class name for Tooltip's popper | string | — | — | -| enterable | whether the mouse can enter the tooltip | Boolean | — | true | -| tabindex | [tabindex](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) of Tooltip | number | — | 0 | -| teleported | whether tooltip content is teleported, if `true` it will be teleported to where `append-to` sets | boolean | true / false | true | -| trigger | How should the tooltip be triggered (to show) | string | hover / click / focus / contextmenu | hover | -| virtual-triggering | Indicates whether virtual triggering is enabled | boolean | — | false | -| virtual-ref | Indicates the reference element to which the tooltip is attached | HTMLElement | — | — | -| trigger-keys | When you click the mouse to focus on the trigger element, you can define a set of keyboard codes to control the display of tooltip through the keyboard | Array | — | `['Enter','Space']` | +### Attributes -## Slots +| Name | Description | Type | Default | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | +| append-to | which element the tooltip CONTENT appends to | ^[CSSSelector] / ^[HTMLElement] | — | +| effect | Tooltip theme, built-in theme: `dark` / `light` | ^[enum]`'dark' \| 'light'` | dark | +| content | display content, can be overridden by `slot#content` | ^[string] | '' | +| raw-content | whether `content` is treated as HTML string | ^[boolean] | false | +| placement | position of Tooltip | ^[enum]`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | bottom | +| visible / v-model:visible | visibility of Tooltip | ^[boolean] | — | +| disabled | whether Tooltip is disabled | ^[boolean] | — | +| offset | offset of the Tooltip | ^[number] | 12 | +| transition | animation name | ^[string] | — | +| popper-options | [popper.js](https://popper.js.org/docs/v2/) parameters | ^[object]refer to [popper.js](https://popper.js.org/docs/v2/) doc | {} | +| show-after | delay of appearance, in millisecond | ^[number] | 0 | +| show-arrow | whether the tooltip content has an arrow | ^[boolean] | true | +| hide-after | delay of disappear, in millisecond | ^[number] | 200 | +| auto-close | timeout in milliseconds to hide tooltip | ^[number] | 0 | +| popper-class | custom class name for Tooltip's popper | ^[string] | — | +| enterable | whether the mouse can enter the tooltip | ^[boolean] | true | +| teleported | whether tooltip content is teleported, if `true` it will be teleported to where `append-to` sets | ^[boolean] | true | +| trigger | How should the tooltip be triggered (to show) | ^[enum]`'hover' \| 'click' \| 'focus' \| 'contextmenu'` | hover | +| virtual-triggering | Indicates whether virtual triggering is enabled | ^[boolean] | — | +| virtual-ref | Indicates the reference element to which the tooltip is attached | ^[HTMLElement] | — | +| trigger-keys | When you click the mouse to focus on the trigger element, you can define a set of keyboard codes to control the display of tooltip through the keyboard | ^[Array] | ['Enter','Space'] | +| persistent | when tooltip inactive and `persistent` is `false` , popconfirm will be destroyed | ^[boolean] | — | +| aria-label^[a11y] | same as `aria-label` | ^[string] | — | + +### Slots | Name | Description | | ------- | -------------------------------------- | -| — | Tooltip triggering & reference element | +| default | Tooltip triggering & reference element | | content | customize content | + +### Exposes + +| Name | Description | Type | +| -------------------- | ----------------------------------------------------------------- | ------------------------------------------------- | +| popperRef | el-popper component instance | ^[objcet]`Ref` | +| contentRef | el-tooltip-content component instance | ^[objcet]`Ref` | +| isFocusInsideContent | validate current focus event is trigger inside el-tooltip-content | ^[Function]`() => boolean \| undefined` | +| updatePopper | update el-popper component instance | ^[Function]`() => void` | +| onOpen | expose onOpen function to mange el-tooltip open state | ^[Function]`(event?: Event \| undefined) => void` | +| onClose | expose onOpen function to mange el-tooltip open state | ^[Function]`(event?: Event \| undefined) => void` | +| hide | expose hide function | ^[Function]`(event?: Event \| undefined) => void` | diff --git a/packages/components/popper/src/content.ts b/packages/components/popper/src/content.ts index 9310aec64d..0bf17776c2 100644 --- a/packages/components/popper/src/content.ts +++ b/packages/components/popper/src/content.ts @@ -30,15 +30,24 @@ export const popperCoreConfigProps = buildProps({ type: Boolean, default: true, }, + /** + * @description offset of the Tooltip + */ offset: { type: Number, default: 12, }, + /** + * @description position of Tooltip + */ placement: { type: String, values: placements, default: 'bottom', }, + /** + * @description [popper.js](https://popper.js.org/docs/v2/) parameters + */ popperOptions: { type: definePropType>(Object), default: () => ({}), diff --git a/packages/components/tooltip/src/content.ts b/packages/components/tooltip/src/content.ts index 3529bf5272..8c86534d7e 100644 --- a/packages/components/tooltip/src/content.ts +++ b/packages/components/tooltip/src/content.ts @@ -1,45 +1,71 @@ import { buildProps, definePropType } from '@element-plus/utils' import { popperContentProps } from '@element-plus/components/popper' import { useDelayedToggleProps } from '@element-plus/hooks' + +import type TooltipContent from './content.vue' import type { ExtractPropTypes } from 'vue' export const useTooltipContentProps = buildProps({ ...useDelayedToggleProps, ...popperContentProps, + /** + * @description which element the tooltip CONTENT appends to + */ appendTo: { type: definePropType([String, Object]), }, + /** + * @description display content, can be overridden by `slot#content` + */ content: { type: String, default: '', }, + /** + * @description whether `content` is treated as HTML string + */ rawContent: { type: Boolean, default: false, }, + /** + * @description when tooltip inactive and `persistent` is `false` , popconfirm will be destroyed + */ persistent: Boolean, + /** + * @description same as `aria-label` + */ ariaLabel: String, // because model toggle prop is generated dynamically // so the typing cannot be evaluated by typescript as type: // [name]: { type: Boolean, default: null } // so we need to declare that again for type checking. + /** + * @description visibility of Tooltip + */ visible: { type: definePropType(Boolean), default: null, }, - transition: { - type: String, - default: '', - }, + /** + * @description animation name + */ + transition: String, + /** + * @description whether tooltip content is teleported, if `true` it will be teleported to where `append-to` sets + */ teleported: { type: Boolean, default: true, }, - disabled: { - type: Boolean, - }, + /** + * @description whether Tooltip is disabled + */ + disabled: Boolean, } as const) export type ElTooltipContentProps = ExtractPropTypes< typeof useTooltipContentProps > + +export type TooltipContentInstance = InstanceType diff --git a/packages/components/tooltip/src/tooltip.ts b/packages/components/tooltip/src/tooltip.ts index 1085db53df..c4b8cc55fa 100644 --- a/packages/components/tooltip/src/tooltip.ts +++ b/packages/components/tooltip/src/tooltip.ts @@ -19,6 +19,9 @@ export const useTooltipProps = buildProps({ ...useTooltipContentProps, ...useTooltipTriggerProps, ...popperArrowProps, + /** + * @description whether the tooltip content has an arrow + */ showArrow: { type: Boolean, default: true, diff --git a/packages/components/tooltip/src/tooltip.vue b/packages/components/tooltip/src/tooltip.vue index c45bcc3dfc..9911e1dc17 100644 --- a/packages/components/tooltip/src/tooltip.vue +++ b/packages/components/tooltip/src/tooltip.vue @@ -70,6 +70,7 @@ import { TOOLTIP_INJECTION_KEY } from './constants' import { tooltipEmits, useTooltipModelToggle, useTooltipProps } from './tooltip' import ElTooltipTrigger from './trigger.vue' import ElTooltipContent from './content.vue' +import type { PopperInstance } from '@element-plus/components/popper' defineOptions({ name: 'ElTooltip', @@ -81,9 +82,8 @@ const emit = defineEmits(tooltipEmits) usePopperContainer() const id = useId() -// TODO any is temporary, replace with `InstanceType | null` later -const popperRef = ref() -// TODO any is temporary, replace with `InstanceType | null` later +const popperRef = ref() +// TODO any is temporary, replace with `TooltipContentInstance` later const contentRef = ref() const updatePopper = () => { diff --git a/packages/components/tooltip/src/trigger.ts b/packages/components/tooltip/src/trigger.ts index 9531a07242..e33bcccf05 100644 --- a/packages/components/tooltip/src/trigger.ts +++ b/packages/components/tooltip/src/trigger.ts @@ -8,11 +8,20 @@ export type TooltipTriggerType = 'hover' | 'focus' | 'click' | 'contextmenu' export const useTooltipTriggerProps = buildProps({ ...popperTriggerProps, + /** + * @description whether Tooltip is disabled + */ disabled: Boolean, + /** + * @description How should the tooltip be triggered (to show) + */ trigger: { type: definePropType>([String, Array]), default: 'hover', }, + /** + * @description When you click the mouse to focus on the trigger element, you can define a set of keyboard codes to control the display of tooltip through the keyboard + */ triggerKeys: { type: definePropType(Array), default: () => [EVENT_CODE.enter, EVENT_CODE.space], diff --git a/packages/hooks/use-delayed-toggle/index.ts b/packages/hooks/use-delayed-toggle/index.ts index 5d736f8063..d1475ede39 100644 --- a/packages/hooks/use-delayed-toggle/index.ts +++ b/packages/hooks/use-delayed-toggle/index.ts @@ -5,10 +5,16 @@ import { useTimeout } from '../use-timeout' import type { ExtractPropTypes, ToRefs } from 'vue' export const useDelayedToggleProps = buildProps({ + /** + * @description delay of appearance, in millisecond + */ showAfter: { type: Number, default: 0, }, + /** + * @description delay of disappear, in millisecond + */ hideAfter: { type: Number, default: 200,