# tooltip (w-tooltip)

- **Import**: `WTooltip` from `win-design-next`
- **Tag**: `<w-tooltip>`
- **说明**: Tooltip 文字提示
- **分类**: feedback
- **Skill 版本**: V1.1.0
- **适配组件库**: win-design-next 1.2.2
- **API 来源**: `docs/zh-CN/component/tooltip.md`

## API

## API

### 属性

| 名称                      | 说明                                                                                                             | 类型                                                                                                                                                                        | 默认值            |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| append-to                 | tooltip 内容挂载到哪个元素                                                                                       | ^[CSSSelector] / ^[HTMLElement]                                                                                                                                             | —                 |
| effect                    | Tooltip 主题，内置主题：`dark` / `light`                                                                         | ^[enum]`'dark' \| 'light'`                                                                                                                                                  | dark              |
| content                   | 显示内容，可被 `slot#content` 覆盖                                                                               | ^[string]                                                                                                                                                                   | ''                |
| raw-content               | 是否将 `content` 作为 HTML 字符串处理                                                                            | ^[boolean]                                                                                                                                                                  | false             |
| placement                 | Tooltip 的出现位置                                                                                               | ^[enum]`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | bottom            |
| fallback-placements       | Tooltip 可能的备用位置列表（参考 [popper.js](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements)） | ^[array]`Placement[]`                                                                                                                                                       | —                 |
| visible / v-model:visible | Tooltip 是否可见                                                                                                 | ^[boolean]                                                                                                                                                                  | —                 |
| disabled                  | 是否禁用 Tooltip                                                                                                 | ^[boolean]                                                                                                                                                                  | —                 |
| offset                    | Tooltip 的偏移量                                                                                                 | ^[number]                                                                                                                                                                   | 12                |
| transition                | 动画名称                                                                                                         | ^[string]                                                                                                                                                                   | —                 |
| popper-options            | [popper.js](https://popper.js.org/docs/v2/) 参数                                                                 | ^[object]参考 [popper.js](https://popper.js.org/docs/v2/) 文档                                                                                                              | {}                |
| arrow-offset              | 控制 tooltip 箭头相对 popper 的偏移（padding）                                                                   | ^[number]                                                                                                                                                                   | 5                 |
| show-after                | 显示延迟（毫秒），受控模式下无效                                                                                 | ^[number]                                                                                                                                                                   | 0                 |
| show-arrow                | tooltip 内容是否显示箭头                                                                                         | ^[boolean]                                                                                                                                                                  | true              |
| hide-after                | 隐藏延迟（毫秒），受控模式下无效                                                                                 | ^[number]                                                                                                                                                                   | 200               |
| auto-close                | 自动隐藏的超时时间（毫秒），受控模式下无效                                                                       | ^[number]                                                                                                                                                                   | 0                 |
| popper-class              | Tooltip 弹出层的自定义类名                                                                                       | ^[string]                                                                                                                                                                   | —                 |
| popper-style              | Tooltip 弹出层的自定义样式                                                                                       | ^[string] / ^[object]                                                                                                                                                       | —                 |
| enterable                 | 鼠标是否可进入 tooltip                                                                                           | ^[boolean]                                                                                                                                                                  | true              |
| teleported                | tooltip 内容是否 teleport；若为 `true`，将传送到 `append-to` 指定的位置                                          | ^[boolean]                                                                                                                                                                  | true              |
| trigger                   | Tooltip 的触发方式（显示），受控模式下无效                                                                       | ^[enum]`'hover' \| 'click' \| 'focus' \| 'contextmenu'` / ^[array]`Array`                                                                                                   | hover             |
| virtual-triggering        | 是否启用虚拟触发                                                                                                 | ^[boolean]                                                                                                                                                                  | —                 |
| virtual-ref               | tooltip 所依附的参考元素（虚拟触发用）                                                                           | ^[HTMLElement]                                                                                                                                                              | —                 |
| trigger-keys              | 鼠标点击聚焦触发元素后，可定义一组键盘码通过键盘控制 tooltip 显示（受控模式下无效）                              | ^[Array]                                                                                                                                                                    | ['Enter','Space'] |
| persistent                | tooltip 不可见且 `persistent` 为 `false` 时，tooltip 将被销毁                                                    | ^[boolean]                                                                                                                                                                  | —                 |
| aria-label ^(a11y)        | 同 `aria-label`                                                                                                  | ^[string]                                                                                                                                                                   | —                 |
| focus-on-target           | hover 触发时，是否聚焦触发元素（提升可访问性）                                                                   | ^[boolean]                                                                                                                                                                  | false             |

### 事件

| 名称        | 说明                                 | 类型                                 |
| ----------- | ------------------------------------ | ------------------------------------ |
| before-show | Tooltip 显示前触发，参数为触发事件。 | ^[Function]`(event?: Event) => void` |
| show        | Tooltip 显示时触发，参数为触发事件。 | ^[Function]`(event?: Event) => void` |
| before-hide | Tooltip 隐藏前触发，参数为触发事件。 | ^[Function]`(event?: Event) => void` |
| hide        | Tooltip 隐藏时触发，参数为触发事件。 | ^[Function]`(event?: Event) => void` |

### 插槽

| 名称    | 说明                                      |
| ------- | ----------------------------------------- |
| default | Tooltip 的触发/参考元素，只接受单一根元素 |
| content | 自定义内容                                |

### 暴露

| 名称                 | 说明                                              | 类型                                              |
| -------------------- | ------------------------------------------------- | ------------------------------------------------- |
| popperRef            | `w-popper` 组件实例                               | ^[object]`Ref`                                    |
| contentRef           | `w-tooltip-content` 组件实例                      | ^[object]`Ref`                                    |
| isFocusInsideContent | 判断当前焦点事件是否发生在 `w-tooltip-content` 内 | ^[Function]`() => boolean \| undefined`           |
| updatePopper         | 更新 `w-popper` 组件实例                          | ^[Function]`() => void`                           |
| onOpen               | 暴露 `onOpen`，用于管理 `w-tooltip` 打开状态      | ^[Function]`(event?: Event \| undefined) => void` |
| onClose              | 暴露 `onClose`，用于管理 `w-tooltip` 关闭状态     | ^[Function]`(event?: Event \| undefined) => void` |
| hide                 | 暴露 `hide` 方法                                  | ^[Function]`(event?: Event \| undefined) => void` |
