从零到一，用 Vue 3 + Vite 打造你的第一个 uTools 插件

文章目录

摘要
1. 引言：为什么选择为 uTools 开发插件？
2. 技术选型：Vue 3 + Vite
3. uTools 插件核心概念解析

3.1. `plugin.json`：插件的“身份证”
3.2. `preload.js`：连接前端与 uTools 的桥梁

4. 项目结构搭建
5. 核心功能实现

5.1. 前端界面 (`App.vue`)
5.2. 核心命名引擎 (`services.js`)

6. 开发与调试
7. 总结

摘要

本文将通过一个实战项目——规范命名助手，带你从零开始，一步步学习如何使用现代前端技术栈（Vue 3 + Vite）为 uTools 平台开发一款实用、美观且功能强大的插件。你将学到 uTools 插件的核心概念、项目搭建、功能实现、与 uTools API 的交互，以及最终的打包发布流程。

关键词：uTools, 插件开发, Vue 3, Vite, JavaScript, 前端实战

1. 引言：为什么选择为 uTools 开发插件？

uTools 是一个极客范的生产力工具集，它通过插件化的方式，将各种常用工具（如翻译、截图、计算器等）聚合在一起，极大地提升了我们的工作效率。为 uTools 开发插件，不仅能解决自己工作流中的痛点，还能将自己的创意分享给广大的 uTools 用户，非常有成就感。

本文将以我开发的“规范命名助手”为例，详细讲解 uTools 插件的开发全过程。这个插件旨在解决程序员日常开发中的一大“难题”——命名。它能根据中文含义，智能生成符合多种编程语言规范的变量、函数、类名等。

2. 技术选型：Vue 3 + Vite

为什么选择 Vue 3 和 Vite 作为我们的技术栈？

Vite：提供了闪电般的冷启动和极速的热模块更新（HMR），这对于需要频繁调试的插件开发来说，体验极佳。
Vue 3：其 Composition API 使得代码逻辑组织更加清晰，响应式系统也更加高效，非常适合构建复杂的交互界面。

这套组合不仅开发体验好，而且打包后的体积小、性能高，非常适合 uTools 这种轻量级的插件平台。

3. uTools 插件核心概念解析

在开始编码之前，我们必须理解 uTools 插件的两个核心文件：plugin.json 和 preload.js。

3.1. `plugin.json`：插件的“身份证”

这个文件是插件的清单文件，用于向 uTools 声明插件的基本信息、功能、入口等。我们的“规范命名助手”的配置如下：

{
  "main": "index.html",
  "preload": "preload/services.js",
  "logo": "logo.png",
  "development": {
    "main": "http://localhost:5173"
  },
  "features": [
    {
      "code": "naming",
      "explain": "规范命名助手 - 智能生成符合编程规范的变量、函数、类名",
      "cmds": [
        "命名",
        "规范命名",
        "naming"
      ]
    }
  ]
}

main: 插件主界面的入口文件，这里指向 Vite 打包生成的 index.html。
preload: 预加载脚本，这是插件的“后端”，负责处理核心逻辑和与 uTools API 的交互。
development.main: 开发模式下的入口，指向 Vite 的开发服务器地址。
features: 定义插件的功能。每个功能有一个唯一的 code，一个 explain（解释），以及一组 cmds（命令）。用户通过这些命令来唤起你的插件。

3.2. `preload.js`：连接前端与 uTools 的桥梁

preload.js 运行在 Node.js 环境中，拥有完整的 Node.js API 权限，并且可以访问 uTools 提供的所有 API。它通过 window 对象向前端页面（运行在浏览器环境中）暴露方法和数据。

在我们的项目中，preload/services.js 就是这个角色。它定义了 NamingEngine 类，负责所有命名的计算和 AI 调用逻辑，并将其挂载到 window.services 上，供 App.vue 调用。

// preload/services.js

class NamingEngine {
  // ... 命名转换、AI调用等核心逻辑
}

window.services = {
  namingEngine: new NamingEngine(),
  getNamingSuggestions: async (desc, type, lang) => {
    return window.services.namingEngine.generateAISuggestions(desc, type, lang);
  },
  // ... 其他暴露给前端的方法
};

4. 项目结构搭建

一个清晰的项目结构是高效开发的基础。我们的项目结构如下：

standardized-naming-assistant/
├── public/                  # uTools 插件的静态资源
│   ├── plugin.json          # 插件配置
│   ├── preload/             # 预加载脚本目录
│   │   └── services.js      # 核心命名服务
│   └── logo.png             # 插件图标
├── src/                     # Vue 应用源码
│   ├── App.vue              # 主应用组件
│   ├── main.js              # Vue 应用入口
│   └── main.css             # 全局样式
├── package.json             # 项目配置
└── vite.config.js           # Vite 配置

5. 核心功能实现

5.1. 前端界面 (`App.vue`)

前端使用 Vue 3 的 Composition API 来组织代码，使得状态管理和逻辑复用变得非常简单。

响应式数据：使用 ref 来定义所有需要动态更新的数据，如输入框内容、建议列表、加载状态等。
用户交互：通过 @click、@input 等事件监听用户的操作，并调用相应的方法。
与 preload 通信：直接通过 window.services 对象调用在 preload.js 中暴露的方法，获取命名建议。

<script setup>
import { ref } from 'vue';

const namingRequirement = ref('');
const suggestions = ref([]);
const loading = ref(false);

const getNamingSuggestions = async () => {
  if (!namingRequirement.value.trim()) return;
  loading.value = true;
  try {
    // 直接调用 preload 中暴露的方法
    const newSuggestions = await window.services.getNamingSuggestions(
      namingRequirement.value,
      selectedType.value,
      selectedLanguage.value
    );
    suggestions.value = newSuggestions;
  } finally {
    loading.value = false;
  }
};
</script>

<template>
  <!-- ... 模板代码 ... -->
  <input v-model="namingRequirement" @input="getNamingSuggestions" />
  <!-- ... 显示建议列表 ... -->
</template>

5.2. 核心命名引擎 (`services.js`)

这是插件的大脑。它不仅实现了多种命名风格（如 camelCase, PascalCase, snake_case）的转换算法，还集成了 uTools 的 AI 能力，提供更智能的命名建议。

命名风格转换：使用正则表达式和字符串操作实现各种 case 之间的转换。
调用 uTools AI：通过 utools.ai.ask 方法，将用户的命名需求发送给 AI，并解析返回的结果。
失败回退：当 AI 调用失败或返回结果不理想时，优雅地回退到本地的、基于规则的命名生成逻辑，保证插件的可用性。

// preload/services.js

class NamingEngine {
  convertCase(text, style) { /* ... */ }

  async generateAISuggestions(description, type, language) {
    try {
      // 检查 uTools AI 是否可用
      if (!window.utools || !window.utools.ai) {
        return this.generateLocalSuggestions(description, type, language);
      }
      const prompt = this.buildAIPrompt(description, type, language);
      const response = await window.utools.ai({ messages: [{ role: 'user', content: prompt }] });
      // ... 解析和处理 AI 响应 ...
    } catch (error) {
      // ... 错误处理和回退逻辑 ...
    }
  }
}