zk-desktop-ui/docs/components/tooltip.md

ZKTeco UI Components

## Tooltip 文字提示

常用于展示鼠标 hover 时的提示信息。

### 基础用法

在这里我们提供 9 种不同方向的展示方式，可以通过以下完整示例来理解，选择你要的效果。

> demo

 使用`content`属性来决定`hover`时的提示信息。由`placement`属性决定展示效果：`placement`属性值为：`方向-对齐位置`；四个方向：`top`、`left`、`right`、`bottom`；三种对齐位置：`start`, `end`，默认为空。如`placement="left-end"`，则提示信息出现在目标元素的左侧，且提示信息的底部与目标元素的底部对齐。

```html
<div class="box">
  <div class="top">
    <zk-tooltip class="item" effect="dark" content="Top Left 提示文字" placement="top-start">
      <zk-button>上左</zk-button>
    </zk-tooltip>
    <zk-tooltip class="item" effect="dark" content="Top Center 提示文字" placement="top">
      <zk-button>上边</zk-button>
    </zk-tooltip>
    <zk-tooltip class="item" effect="dark" content="Top Right 提示文字" placement="top-end">
      <zk-button>上右</zk-button>
    </zk-tooltip>
  </div>
  <div class="left">
    <zk-tooltip class="item" effect="dark" content="Left Top 提示文字" placement="left-start">
      <zk-button>左上</zk-button>
    </zk-tooltip>
    <zk-tooltip class="item" effect="dark" content="Left Center 提示文字" placement="left">
      <zk-button>左边</zk-button>
    </zk-tooltip>
    <zk-tooltip class="item" effect="dark" content="Left Bottom 提示文字" placement="left-end">
      <zk-button>左下</zk-button>
    </zk-tooltip>
  </div>
  <div class="right">
    <zk-tooltip class="item" effect="dark" content="Right Top 提示文字" placement="right-start">
      <zk-button>右上</zk-button>
    </zk-tooltip>
    <zk-tooltip class="item" effect="dark" content="Right Center 提示文字" placement="right">
      <zk-button>右边</zk-button>
    </zk-tooltip>
    <zk-tooltip class="item" effect="dark" content="Right Bottom 提示文字" placement="right-end">
      <zk-button>右下</zk-button>
    </zk-tooltip>
  </div>
  <div class="bottom">
    <zk-tooltip class="item" effect="dark" content="Bottom Left 提示文字" placement="bottom-start">
      <zk-button>下左</zk-button>
    </zk-tooltip>
    <zk-tooltip class="item" effect="dark" content="Bottom Center 提示文字" placement="bottom">
      <zk-button>下边</zk-button>
    </zk-tooltip>
    <zk-tooltip class="item" effect="dark" content="Bottom Right 提示文字" placement="bottom-end">
      <zk-button>下右</zk-button>
    </zk-tooltip>
  </div>
</div>

<style>
  .box {
    width: 400px;

    .top {
      text-align: center;
    }

    .left {
      float: left;
      width: 60px;
    }

    .right {
      float: right;
      width: 60px;
    }

    .bottom {
      clear: both;
      text-align: center;
    }

    .item {
      margin: 4px;
    }
    
    .left .zk-tooltip__popper,
    .right .zk-tooltip__popper {
      padding: 8px 10px;
    }
  }
</style>
```



### 主题

Tooltip 组件提供了两个不同的主题：`dark`和`light`。


> demo

 通过设置`effect`属性来改变主题，默认为`dark`。
```html
<zk-tooltip content="Top center" placement="top">
  <zk-button>Dark</zk-button>
</zk-tooltip>
<zk-tooltip content="Bottom center" placement="bottom" effect="light">
  <zk-button>Light</zk-button>
</zk-tooltip>
```



### 更多 Content

展示多行文本或者是设置文本内容的格式

> demo

 用具名 slot 分发`content`，替代`tooltip`中的`content`属性。
```html
<zk-tooltip placement="top">
  <div slot="content">多行信息<br/>第二行信息</div>
  <zk-button>Top center</zk-button>
</zk-tooltip>
```



### 高级扩展

除了这些基本设置外，还有一些属性可以让使用者更好的定制自己的效果：

`transition`属性可以定制显隐的动画效果，默认为`fade-in-linear`。

如果需要关闭`tooltip`功能，`disabled`属性可以满足这个需求，它接受一个`Boolean`，设置为`true`即可。

事实上，这是基于 [Vue-popper](https://github.com/ZKTecoFE-component/vue-popper) 的扩展，你可以自定义任意 Vue-popper 中允许定义的字段。

当然，Tooltip 组件实际上十分强大，文末的API文档会做一一说明。

> demo


```html
<template>
  <zk-tooltip :disabled="disabled" content="点击关闭 tooltip 功能" placement="bottom" effect="light">
    <zk-button @click.native="disabled=true">点击关闭 tooltip 功能</zk-button>
  </zk-tooltip>
</template>
```



### Attributes
| 参数               | 说明                                                     | 类型              | 可选值      | 默认值 |
|--------------------|----------------------------------------------------------|-------------------|-------------|--------|
|  effect        |  默认提供的主题  | String            | dark/light | dark  |
|  content        |  显示的内容，也可以通过 `slot#content` 传入 DOM  | String            | — | — |
|  placement        |  Tooltip 的出现位置  | String           |  top/top-start/top-end/bottom/bottom-start/bottom-end/left/left-start/left-end/right/right-start/right-end |  bottom |
|  value(v-model) |  状态是否可见  | Boolean           | — |  false |
|  disabled       |  Tooltip 是否可用  | Boolean           | — |  false |
|  offset        |  出现位置的偏移量  | Number           | — |  0 |
|  transition     |  定义渐变动画      | String             | — | `fade-in-linear` |
|  visible-arrow   |  是否显示 Tooltip 箭头，更多参数可见[Vue-popper](https://github.com/element-component/vue-popper) | Boolean | — | true |
|  options        | [popper.js](https://popper.js.org/documentation.html) 的参数 | Object            | 参考 [popper.js](https://popper.js.org/documentation.html) 文档 | `{ boundariesElement: 'body', gpuAcceleration: false }` |
| openDelay | 延迟出现，单位毫秒 | Number | — | 0 |
| manual | 手动控制模式，设置为 true 后，mouseenter 和 mouseleave 事件将不会生效 | Boolean | — | false |