项目作者: kinglisky

项目描述 :
基于 Vue 的简单 tooltip 工具
高级语言: JavaScript
项目地址: git://github.com/kinglisky/vtip.git
创建时间: 2017-07-06T02:10:48Z
项目社区:https://github.com/kinglisky/vtip

开源协议:MIT License

关键词:
"tooltip" "vue"

下载


Vtip 文档

项目地址:https://github.com/kinglisky/vtip

文档地址: https://kinglisky.github.io/vtip

开始使用

安装:

npm i vtip -S

使用:

  1. import Vtip from 'vtip'
  2. import 'vtip/lib/index.min.css'
  3. // 注册指令使用
  4. Vue.use(Vtip.directive)
  5. // 工具函数调用
  6. Vue.prototype.$tip = Vtip.tip

指令使用

推荐的使用方式为注册指令来使用,默认的指令名称为 v-tip。如果想用其他名称可以在 Vue.use 进行配置。

  1. Vue.use(Vtip.directive, { directiveName: 'otherName' })

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

  1. <span v-tip="msg">{{ msg }}</span>

在线栗子 🌰 :

指标的修饰符:

  1. <span v-tip.top.dark.click="msg">{{ msg }}</span>

click: 点击触发,默认由 hover 触发

dark:使用黑色主题,默认为 light

top right bottom left: 可用于设置 tip 优先显示方向

transition: 是否为 tip 设置 tranfrom 过渡效果

如果还想进一步自定义 tip 显示,v-tip 指令支持绑定一个配置对象进行更配置:

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

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

  1. const options = {
  2. title: '这里是标题',
  3. content: '显示内容',
  4. theme: 'dark',
  5. // tip 的容器,在不设置的情况下,tip 会自动在参考元素的父级元素上面查找合适的容器,但推荐手动设置一个 tip 对象容器
  6. container: document.body,
  7. customProps: { msg: '自定义渲染' },
  8. // 这里通过 customComponent 定义了一个自定义组件
  9. customComponent: Vue.extend({
  10. props: ['msg'],
  11. render (h) {
  12. return h('span', this.msg)
  13. }
  14. }),
  15. placements: ['top', 'buttom'],
  16. duration: 400,
  17. transition: true
  18. ...
  19. }

可以看下面的栗子 🌰 :

一般情况下指令都能满足 tip 的显示需要,但有时可能需要通过工具函数的形式来调用 tip 显示,这时就可以使用 Vtip 提供的 tip 工具函数了,v-tip 的指令是基于 tip 函数实现的。

工具函数

Vtip 有提供一个工具函数,可直接调用 tip 工具函数进行内容的展示:

  1. Vue.prototype.$tip = Vtip.tip

自定义组件 custom.vue

  1. <template>
  2. <div>
  3. <span>{{ msg }}</span>
  4. <button @click="handler">确认</button>
  5. </div>
  6. </template>
  7. <script>
  8. export default {
  9. props: {
  10. msg: String,
  11. handler: Function
  12. },
  13. created () {
  14. this.$emit('created')
  15. }
  16. }
  17. </script>
  1. import Custom from 'components/custom.vue'
  2. const tipInstance = this.$tip({
  3. target: this.$el, // tip 的参考元素
  4. width: 400,
  5. content: '提示显示内容',
  6. // customProps 传递 customComponent 组件的需要的 props
  7. customProps: {
  8. msg: '自定义渲染内容',
  9. handler () {
  10. console.log('click')
  11. }
  12. },
  13. // 用于监听自定义组件的 emit 事件
  14. customListeners: {
  15. created () {
  16. console.log('created')
  17. }
  18. }
  19. customComponent: Custom
  20. ...
  21. })
  22. // 隐藏 tip
  23. tipInstance.hiddenTip()
  24. tipInstance.updateTip()
  25. ...

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

在线栗子 🌰 :

配置参数

属性 说明 默认
title String 内容标题 ''
content String 显示的内容 ''
theme String 主题色调 light dark 'light'
customComponent [String, Function, Object]
工具函数与指令调用时,可以通过 customComponent 传递自定义组件来渲染自定义内容
''
customProps Object 附加到 customComponent 自定义组件 props 上面的值 {}
customListeners Object 用监听 customComponent 自定义组件内部 emit 的事件
注意:这里使用了 vue 2.4 新加 v-on 新语法, 小于 2.4 的版本的 vue 不支持此特性,若有需要处理自定义组件的事件可以通过 customProps 传入处理函数实现
{}
target Element Objcet tip 绑定的目标元素 null
container Element Objcet tip 父级容器,未设置容器是 tip 会自动从 target 元素的父级容器中挑选出一个合适的节点作为 tip 的容器
推荐为 tip 手动指定一个显示容器
-
placements Array 用于设置 tip 显示的优先级 ['top', 'right', 'bottom', 'left']
duration Number tip 窗口多久后自动消失 400
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

customComponent 用于往 tip 中塞一些自定义的组件,内部实现实际上使用 <component> 组件:

  1. <component :is="customComponent" v-bind="customProps" v-on="customListeners"></component>

所以 customComponent 的值与 <component> 组件的 is 属性相同。

customProps

customProps 其实就是附加给自定义组件 customComponent 上的 props 参数,有时候可以将处理函数以 props 的形式传入便于处理自定义组件内部的事件。

customListeners

customListeners 基于 Vue 2.4 引入 v-on 新语法实现,v-on 直接可直接绑定一个事件对象如:{ mousedown: doThis, mouseup: doThat } 。通过传入的 customListeners 可以方便的处理自定义组件内部的 emit 出的事件。当 Vue 版本小于 2.4 不支持此语法时,我们可以通过 customComponent 传处理函数实现事件处理。

placements

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

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

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

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

container

container tip 的容器对象,不设置时组件会在参考元素的父级寻找合适的节点作为容器,平时使用的还是推荐手动设置一个容器

组件方法

方法 说明 参数
showTip() 显示 tip -
hiddenTip(immedia) 隐藏 tip immedia 是否立即隐藏 tip
updateTip() 显示更新 tip 位置 -
destroy() 销毁 tip 实例,一般不需要调用 -

组件还有一些其他方法,一般使用不到,具体可以到源码看看。

附:组件内部有监听 customComponent 自定义组件 emit 出的 hidden-tip 事件与 update-tip 事件,对应触发 hiddenTipupdateTip 方法。