如何全局将含data-app-tooltip属性的元素转为Vuetify提示组件

需求说明 #

正在将应用从Handlebars + Semantic UI迁移到Vue3 + Vuetify，需实现以下目标：

• 自动将所有带data-app-tooltip属性的元素，用Vuetify的v-tooltip组件按指定结构包裹
• 保留原有的「用户禁用提示」配置逻辑
• 了解Vue模板实例化前的转换方法

原实现参考 #

Semantic UI 提示逻辑（jQuery版） #

$(document).ready(function () {
    // Disable tooltips on user config.
    if(confTooltips){
        // convert  placeholders to actual tooltips
        $("[data-app-tooltip]").each(function(i,el){
            var $el = $(el);
            $el.attr('data-tooltip', $el.attr('data-app-tooltip'));
        });
    }
})

原UI示例 #

<a href="/app/mode/full"
   class="ui mini basic icon item"
   data-app-tooltip="Show the full navigation controls"
>
    <i class="icon angle right"></i>
</a>

期望转换后的Vue结构 #

<v-tooltip text="The number of items imported from this file">
   <template v-slot:activator="{ props }">
        <span v-bind="props">
             {{ item.count }} 
       </span>
     </template>
</v-tooltip>

实现方案 #

方案1：全局自定义指令（运行时处理） #

适合动态渲染的元素（如v-for生成的内容），全局注册后自动处理所有带data-app-tooltip的元素：

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import vuetify from './plugins/vuetify'

// 读取用户配置（示例从localStorage获取，可替换为你的配置源）
const confTooltips = localStorage.getItem('enableTooltips') !== 'false'

const app = createApp(App)

app.directive('app-tooltip', {
  mounted(el) {
    if (!confTooltips) return

    const tooltipText = el.getAttribute('data-app-tooltip')
    if (!tooltipText) return

    // 移除原属性避免重复处理
    el.removeAttribute('data-app-tooltip')

    // 创建v-tooltip组件实例并配置
    const tooltip = document.createElement('v-tooltip')
    tooltip.setAttribute('text', tooltipText)

    // 创建激活元素插槽容器
    const activatorTemplate = document.createElement('template')
    activatorTemplate.setAttribute('v-slot:activator', '{ props }')
    const activatorWrap = document.createElement('span')
    activatorWrap.setAttribute('v-bind', 'props')
    
    // 把原元素移入插槽容器
    activatorWrap.appendChild(el.cloneNode(true))
    activatorTemplate.appendChild(activatorWrap)
    
    // 替换原元素为v-tooltip组件
    el.parentNode.replaceChild(tooltip, el)
    tooltip.appendChild(activatorTemplate)
  }
})

app.use(vuetify).mount('#app')

方案2：模板编译阶段转换（实例化前处理） #

在构建阶段修改模板内容，性能更优，适合静态模板：

1. 编写模板转换函数：

// tooltip-transform.js
export function transformTooltipTemplate(template) {
  // 读取用户配置（构建阶段可通过环境变量或配置文件传入）
  const confTooltips = process.env.VUE_APP_ENABLE_TOOLTIPS !== 'false'
  if (!confTooltips) return template

  // 正则匹配并替换带data-app-tooltip的元素
  return template.replace(
    /<([a-z][a-z0-9-]*)([^>]*)data-app-tooltip="([^"]*)"([^>]*)>([\s\S]*?)<\/\1>/gi,
    (match, tag, attrsBefore, tooltipText, attrsAfter, innerHtml) => `
      <v-tooltip text="${tooltipText}">
        <template v-slot:activator="{ props }">
          <${tag}${attrsBefore}${attrsAfter} v-bind="props">
            ${innerHtml}
          </${tag}>
        </template>
      </v-tooltip>
    `
  )
}

2. 在Vue构建配置中集成（以vue-cli为例）：

// vue.config.js
const { transformTooltipTemplate } = require('./tooltip-transform.js')

module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => {
        options.compilerOptions = {
          ...options.compilerOptions,
          preprocessOptions: {
            html: {
              transform: transformTooltipTemplate
            }
          }
        }
        return options
      })
  }
}

方案对比 #

• 自定义指令：运行时处理，支持动态生成的元素，无需修改构建流程，但每次挂载都会执行逻辑，性能略低
• 编译阶段转换：构建时完成替换，性能最优，适合静态模板，但动态生成的元素需要额外处理

内容的提问来源于stack exchange，提问作者scipilot