# Tool-tip 文档


```javascript
import ToolTip from 'dt-ui/lib/tool-tip'
import 'dt-ui/lib/theme/tool-tip.css'
// 注册组件使用
Vue.use(ToolTip.component)
// 注册指令使用
Vue.use(ToolTip.directive)
// 工具函数调用
Vue.prototype.$tip = ToolTip.tip
```


## 作为指令来使用

最方便的方式就是作为组件的指令来使用，默认的指令名称为 `v-tip`。如果想用其他名称可以在 `Vue.use` 进行配置。

```javascript
Vue.use(ToolTip.directive, { directiveName: 'otherName' })
```

如果只是作为过长文案提示，可以直接绑定一个需要显示文案信息来使用：

```html
<span v-tip="msg">{{ msg }}</span>
```

指标的修饰符：

```html
<span v-tip.top.dark.click="msg">{{ msg }}</span>
```
`click`： 点击触发，默认由 hover 触发

`dark`：使用黑色主题，默认为 `light`

`top right bottom left`： 可用于限制组件显示方向

支持绑定一个配置对象进行更配置：

```html
<button v-tip.right="options">
  指令使用-绑定一个对象
</button>
```

对应的 `options` 详细配置说明可以参考参数说明

```javascript
const options = {
  title: '这里是标题',
  content: '显示内容',
  theme: 'dark',
  //  tip 的容器，在不设置的情况下，tip 会自动在参考元素的父级元素上面查找合适的容器
  container: document.body,
  customComponent: h => h('span', '自定义渲染'),
  placementQueue: ['top', 'buttom'],
  duration: 400,
  transition: true
  ...
}
```

<iframe width="100%" height="300" src="//jsfiddle.net/nlush/m46yn8gj/6/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0">
</iframe>

指令的实现是基于工具函数实现的。


## 作为工具函数来使用

ToolTip 有提供一个工具函数，可直接调用 `tip` 工具函数进行内容的展示：

```
Vue.prototype.$tip = ToolTip.tip
```

自定义组件 `custom.vue`
```html
<template>
  <div>
    <span>{{ msg }}</span>
    <button @click="handler">确认</button>
  </div>
</template>

<script>
export default {
  props: {
    msg: String,
    handler: Function
  },

  created () {
    this.$emit('created')
  }
}
</script>
```


```javascript
import Custom from 'components/custom.vue'
const tipInstance = this.$tip({
  target: this.$el, // tool-tip 的参考元素
  width: 400,
  content: '提示显示内容',
  customProps: {
    msg: '自定义渲染内容',
    handler () {
      console.log('click)
    }
  },
  // 用于监听自定义组件的 emit 事件
  customListeners: {
    created () {
      console.log('created)
    }
  }
  customComponent: Custom
  ...
})

// 隐藏 tip
tipInstance.hiddenTip()
```

作为工具函数调用时会返回一个 tip 的组件实例，可直接调用组件的方法进行控制操作。

<iframe width="100%" height="600"
  src="//jsfiddle.net/nlush/as42975v/1/embedded/result,html,js,css"
  allowfullscreen="allowfullscreen" frameborder="0">
</iframe>


## 作为组件来使用

一般很少会直接使用组件，工具函数是基于组件实现的。


```javascript
Vue.use(ToolTip.component, { name: 'dt-tip' })
```
默认使用 `dt-tip` 作为组件的名字


```html
<dt-tip theme="dark"
  :content="content"
  :target="target">
  <span :style="{ color: '#42b983' }">
    这里是 slot 内容
  </span>
</dt-tip>

<button
  @mouseenter="showTip"
  @mouseleave="hiddenTip">
  组件调用
</button>
```

```javascript
export default {
  data () {
    return {
      content: '这里是内容',
      target: null
    }
  },

  methods: {
    showTip ({ target }) {
      this.target = target
    },

    hiddenTip () {
      this.target = null
    }
  }
}
```

组件内部有 watch `target` 属性，如果 `target` 有变化则会触发 tip 位置更新

<iframe width="100%" height="600"
  src="//jsfiddle.net/nlush/svhsh7dp/1/embedded/result,html,js,css"
  allowfullscreen="allowfullscreen" frameborder="0">
</iframe>


## 配置参数

| 属性   | 说明 | 默认 |
| ---   | ---- | --- |
| title | `String` 内容标题 | `''` |
| content| `String` 显示的内容 | `''` |
| theme| `String` 主题色调 `light dark` | `'light'` |
| customComponent | `[String, Function, Object]` <br>工具函数与指令调用时，可以通过 render 函数或者传入的自定义组件自定义显示内容, 组件使用时推荐用 slot 大法| `''` |
| customProps | `Object` 工具函数调用 customComponent 时附加到自定义组件 props 上面的属性 | `{}` |
| customListeners | `Object` 用监听 customComponent 自定义组件内部 emit 的事件 <br> 注意：这里使用了 vue 2.4 新加 v-on 新语法 <br> 小于 2.4 的版本的 vue 不支词特性，若有需要处理自定义组件的的事件可以通过 customProps 传入处理函数实现| `{}` |
| target | `Element Objcet` tip 绑定的目标元素，taget 元素更新时会触发 tip 会自动移动新的目标元素上面 | `null` |
| container | `Element Objcet` tip 父级容器，未设置容器是 tip 会自动从 `target` 元素的父级容器中挑选出一个合适的节点作为 tip 的容器 | `null` |
| placementQueue | `Array` 用于限制 tip 出现的方向 | ` ['top', 'right', 'bottom', 'left']` |
| duration | `Number` tip 窗口多久后自动消失 | `1200` |
| arrowsSize | `Number` 提示用的小箭头大小 | `8` |
| width | `[String, Number]` 组件的宽度 | `300px` |
| height | `[String, Number]` 内容的高度 | `auto`|
| zIndex | `Number` tip 的 z-index | `9999` |
| customClass | `String` 组件自定义 class 的类名 | `''` |
| transition | `Boolean` 是否为组件添加 transfrom 过渡 | `false` |

`customComponent` 可以是一个组件也可以是一个 render 函数，如果是一个组件 `customProps` 对应的就是组件的 `props` 参数。

`placementQueue` 用于限制 tip 的显示方向与各个方向的优先级。

例如 `placementQueue` 设置为 `['top', 'right']` tip 会优先尝试在 top 与 right 方向上显示 tip。

如果 top 与 right 方向上都可显示 tip 优先在 top 方向上显示。

如果 top 与 bottom 上都不足以容纳 tip 则会在 tip 会自动选择一个可容纳 tip 方向展示。


## 组件方法

| 方法  | 说明 | 参数 |
| ---  | ---  | --- |
| showTip() | 显示 tip | 无 |
| hiddenTip(immedia) | 隐藏 tip | `immedia` 是否立即隐藏 tip |
| updateTip()  | 显示更新 tip 位置 |  无 |