前端元素标记工具：一键终结代码难寻、调试低效与模块耦合的开发困局

wenps
588 阅读7分钟

🌟 Element Tag Marker

📖 简介

大家好！欢迎来到 Element Tag Marker 项目。
我是这个插件的作者，非常高兴能为大家介绍这个能提升效率的小工具。\

🔗 GitHub 地址：github.com/wenps/eleme…

🚀 欢迎点 🌟 Star！

🛠️ 为什么需要 Element Tag Marker？

在日常的前端开发中，你是不是遇到过这些问题：

  • 找不到代码：项目文件很多，结构复杂，明明功能行为可以看到，但代码位置却无从下手。
  • 调试困难：想修复 Bug 或追踪某个功能模块，却要在海量代码中来回翻找，很浪费时间。
  • 模块耦合混乱：多个模块或者不同环境的代码混杂在一起，容易发生误操作，维护难度非常高。

这些问题困扰着不少开发者，也是我开发 Element Tag Marker 的原因。

🌟 它能帮你做什么？

Element Tag Marker 是一个为前端项目元素自动添加标记的工具，通过这些标记，你可以快速定位代码、区分功能模块，以及解决复杂项目中的调试和维护问题。

  • 支持框架：兼容 Vue2、Vue3 和 React
  • 支持构建工具：可无缝集成 Webpack 和 Vite

功能特色：

  1. 多种标记类型：

    • 🗂️ path：基于文件路径生成标记，直观显示代码来源。
    • 🔑 hash：自动生成唯一标识，稳定可靠，避免重复。
    • ✨ function：支持自定义逻辑生成标记，满足灵活需求。

  2. 自定义规则：

    • 通过配置包含或排除文件路径，精准控制标记范围。
    • 支持将标记写入源文件，便于长期追踪和维护。

  3. 缓存优化：

    • 内置缓存机制，文件未更改时直接复用标记，开发体验流畅又高效。

🎯 为什么你需要它？

如果你希望提升开发效率，减少调试和维护的时间浪费，那么 Element Tag Marker 就是为你量身定制的解法。

想象一下这些场景：

  1. 快速定位问题：
    项目代码一多，找代码就会变得极为困难。有了标记，可以通过工具将具体元素的标记值反查到代码文件，一秒定位目标代码，不再为翻找代码浪费时间。

  2. 清晰的模块维护：
    通过给特定模块添加标签，不仅可以标记它的来源，还能告知其他开发人员它适配了哪些环境，例如 "开发模式逻辑" 或 "生产环境核心逻辑"。
    当代码耦合问题出现时，一眼就能看出模块职责来源，方便快速解耦，减少误操作。

  3. 加速调试流程：
    在多人协作的大型项目中，模块调试往往很耗时。有了精准的标记，调试工具输出的数据可以快速关联到具体代码文件和位置，显著提升调试效率，让每次修复问题更快更精准。

📚 示例

Vue2 Vite 示例

vue2Vite.gif

当前示例配置了 hash 标识，标签的默认值便是当前代码所处文件名生产的hash，可以看到页面的元素已经被打上我们希望的标签了

Vue3 Vite 示例

vue2Webpack.gif

当前示例配置了 function 标识，自定义函数实现如下：

tagFunction: (path, _tag, option) => {
    return [['hash', option.hashFunction(path)], ['path', path]]
}

因此 路径标识和hash标识同时存在

React Webpack 示例

reactWebpack.gif

当前示例配置了 hash 标识，标签的默认值便是当前代码所处文件名生产的hash

Vue2 Webpack 示例

vue3Vite.gif

当前示例配置了 path 标识，标签的默认值便是当前代码所处文件的具体路径

🌟 功能

  • 支持框架 😎：兼容 Vue2/3 和 React。
  • 构建工具支持 🔧：适配 Webpack 和 Vite。
  • 可自定义标签生成 🏷️：
    • 支持基于哈希算法或自定义函数生成标签，生成标签时支持传入路径参数以及自定义参数。
    • 支持自定义标签生成规则，允许通过配置包含或排除特定路径及标签。
  • 项目标签区分 ✨：为标签添加工程化的独立前缀。
  • 灵活的文件处理 📂：支持将标记值写入原始文件，便于后续跟踪。

📦 安装

分别通过 npm 安装 Webpack 或 Vite 插件：

Webpack 插件安装

通过 npm 安装：

npm install webpack-element-tag-marker-plugin --save-dev

或使用 Yarn：

yarn add webpack-element-tag-marker-plugin --dev

Vite 插件安装

通过 npm 安装：

npm install vite-element-tag-marker-plugin --save-dev

或使用 Yarn：

yarn add vite-element-tag-marker-plugin --dev

🔢 参数配置

参数名称类型默认值必填描述
tagTypeenum (hash | path | function)hash✔️标记类型，支持三种类型：hash、path、function。插件会根据标记类型处理标记，生成的值为标签的键值。
tagKeystring'tag'✔️标签的键名，用于在文件/元素属性中标识标签。
excludedPath(string | RegExp)[][]❌需要排除的文件路径或正则表达式。例如：node_modules、dist 等。 默认不排除任何文件路径。
includePath(string | RegExp)[][/src\//]✔️需要包含的文件路径匹配规则，可以为字符串或正则表达式。默认包含 src 目录下的所有文件。注意：webpack 插件包含范围需要注意，不能全量放开，如果要操作node_modules中的文件，需要精确不能操作 vue源码包的 打包文件
includeTagstring[][]❌需要包含的标签列表，留空时表示包含所有标签。
excludedTagstring[][]❌需要排除的标签列表，优先级高于 includeTag。
hashFunction(path: string) => string--❌用于生成标签值的哈希函数，默认以路径字符串生成哈希值。函数接收路径参数并返回哈希值。
toProdbooleanfalse❌是否在生产环境中触发功能。
writeToFilefalse | hash | pathfalse❌是否将标签值写入原文件，仅支持 hash 和 path 类型。当为 hash 或 path 时，插件将值转化为对应标识并写入到原文件中。
tagPrefixstring''❌标签前缀，用于区分不同项目中的标签，仅对 hash 和 path 两种类型生效。
tagFunction(path: string, elementTag: Record<string, any>, option) => {tag: string, tagValue: string} | ([tag: string, value: string][])() => [['', '']]❌标签生成函数，结合自身逻辑生成标签，可以返回一个 {tag, tagValue} 的对象或标签数组。函数接收文件路径、元素标签 AST 节点和完整配置项作为参数。

🛠️ 配置示例

Webpack 配置（Vue2 示例）

const path = require('path');
const { VueLoaderPlugin } = require('vue-loader');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const webpackElementTagMarkerPlugin = require('webpack-element-tag-marker-plugin');

module.exports = {
  entry: './src/main.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  resolve: {
    extensions: ['.js', '.vue'],
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader'
      },
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: 'babel-loader'
      },
      {
        test: /\.css$/,
        use: ['vue-style-loader', 'css-loader']
      }
    ]
  },
  plugins: [
    new VueLoaderPlugin(),
    new HtmlWebpackPlugin({
      template: './public/index.html'
    }),
    new webpackElementTagMarkerPlugin({
      tagKey: 'data-tag',
      tagType: 'hash',
      writeToFile: 'hash',
      includePath: ['/src/'],
      excludedPath: ['/node_modules/', '/dist/'],
      toProd: true,
    })
  ],
  devServer: {
    port: 3000,
    hot: true
  }
};

Vite 配置（Vue3 示例）

import path from 'path'
import { defineConfig } from 'vite'
import createVuePlugin from '@vitejs/plugin-vue'
import viteElementTagMarkerPlugin from 'vite-element-tag-marker-plugin'

const vuePlugin = createVuePlugin({
  include: [/\.vue$/],
  template: {
    compilerOptions: {
      hoistStatic: false,
      cacheHandlers: false
    }
  }
})

export default defineConfig({
  plugins: [vuePlugin, viteElementTagMarkerPlugin({
    tagKey: 'data-tag',
    tagType: 'function',
    tagFunction: (path, _tag, option) => {
      return [['hash', option.hashFunction(path)], ['path', path]]
    },
    writeToFile: 'hash',
    includePath: ['/src/'],
    excludedPath: ['/node_modules/', '/dist/'],
    toProd: true,
  })]
})

⚙️ 机制介绍

  • 解析与处理：这个插件是通过 Babel 对各个前端框架解析后的代码进行处理来实现新增功能的。通过观察编译后的源码，可以在合适的位置添加属性以实现标签功能。这对 Vue2/3 和 React 的 Webpack 和 Vite 产物均适用。

  • 使用 WriteToFile 功能：可以将当前文件的标签写入原文件。通过在项目中搜索标签来找到对应文件（这也是此插件的初衷，为了在大量复制粘贴的代码中快速找到目标文件）。

  • 缓存处理：插件维护了代码映射表，当文件未改变时直接读取缓存，提高开发体验。

📋 注意事项

  • Vue3 开发者提示：在 Vue3 中，开发者优化可能会跳过静态节点编译，而目前插件只处理 JavaScript，因此需要强制编译。

  • React 支持：React 的支持可能还不够完善，因为本人的 React 项目经验较少，遇到问题欢迎提问。

  • 环境判断：Vite 插件在生产模式的判断是 process.env.NODE_ENV === "production"，Webpack 在生产模式的判断是 compiler.options.mode === "production"。需要注意当前项目中的生产模式判断是否与此一致，这将影响 toProd 属性的作用。

🔚结语

Element Tag Marker 就是一个为前端开发量身打造的效率工具。希望它能为你的开发工作助一臂之力！

如果你在使用过程中有任何问题，可以提 Issue，如果有改进建议，欢迎提交 PR，让我们一起把这个工具做得更好！😊✨

avatar
文章
阅读
粉丝