快速开始

欢迎来到 Spark 插件开发世界！本指南将帮助您快速上手，创建您的第一个 Spark 插件。

前置要求

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: >= 18.0.0
• npm: >= 9.0.0 或 yarn: >= 1.22.0
• Spark Desktop: 最新版本的 Spark 应用（用于本地调试）

安装 Spark CLI

Spark CLI 是创建和管理插件的命令行工具。通过 npm 全局安装：

npm

npm install -g @spark-center/cli

yarn

yarn global add @spark-center/cli

验证安装：

spark --version

创建插件项目

使用 CLI 创建一个新的插件项目：

spark create my-first-plugin

CLI 会引导您选择插件类型：

插件类型选择

UI 插件 - 创建带有用户界面的交互式插件

• 适用于：工具、面板、可视化应用
• 渲染环境：独立的渲染进程
• 通信方式：IPC + Preload Script

System 插件 - 创建后台服务和系统级插件

• 适用于：监听器、后台任务、系统钩子
• 运行环境：主进程
• 能力：完整的 Node.js API + Electron 主进程 API

项目结构

创建完成后，您的项目结构如下：

txt

[UI 插件结构]
my-first-plugin/
├── plugin.json          # 插件配置清单
├── src/
│   ├── main.ts          # 渲染进程入口
│   ├── preload.ts       # 预加载脚本
│   └── App.vue          # Vue 组件（如果使用 Vue）
├── public/              # 静态资源
├── package.json
└── tsconfig.json

txt

[System 插件结构]
my-first-plugin/
├── plugin.json          # 插件配置清单
├── src/
│   └── index.ts         # 主进程入口
├── package.json
└── tsconfig.json

plugin.json 配置详解

plugin.json 是插件的核心配置文件，定义了插件的基本信息和权限：

{
  "name": "my-first-plugin",
  "displayName": "我的第一个插件",
  "version": "1.0.0",
  "description": "这是一个示例插件",
  "type": "ui",
  "author": "Your Name",
  "entry": "dist/main.js",
  "preload": "dist/preload.js",
  "permissions": [
    "clipboard:read",
    "clipboard:write",
    "shell:execute"
  ],
  "icon": "public/icon.png",
  "keywords": ["工具", "效率"],
  "category": "productivity"
}

配置字段说明

字段	类型	必填	说明
name	string	✅	插件唯一标识符（npm 包名）
displayName	string	✅	插件显示名称
version	string	✅	语义化版本号
description	string	❌	插件描述
type	string	✅	插件类型：ui 或 system
entry	string	✅	构建后的入口文件路径
preload	string	❌	预加载脚本路径（UI 插件推荐）
permissions	array	❌	所需权限列表
icon	string	❌	插件图标路径
keywords	array	❌	搜索关键词
category	string	❌	分类标识

本地开发调试

1. 启动开发模式

在插件项目目录下运行：

npm

npm run dev

yarn

yarn dev

这会启动插件的watch模式，自动监听文件变化并重新构建。

2. 在 Spark 中加载插件

方式一：开发模式（推荐）

在 Spark 设置中启用"开发者模式"，然后添加您的本地插件路径：

设置 → 开发者 → 添加本地插件 → 选择项目目录

方式二：本地安装

使用 npm link 将插件链接到 Spark：

# 在插件目录
npm link

# 在 Spark 目录
npm link my-first-plugin

3. 调试工具

• 渲染进程调试：打开插件窗口后，使用 Cmd+Option+I (macOS) 或 Ctrl+Shift+I (Windows/Linux) 打开 DevTools
• 主进程调试：在启动 Spark 时添加 --inspect 标志

开发您的第一个功能

示例：剪贴板历史记录

// src/preload.ts
import { contextBridge, ipcRenderer } from 'electron'

contextBridge.exposeInMainWorld('sparkAPI', {
  getClipboardHistory: () => ipcRenderer.invoke('clipboard:getHistory'),
  copyToClipboard: (text: string) => ipcRenderer.invoke('clipboard:copy', text)
})

// src/main.ts (渲染进程)
const history = await window.sparkAPI.getClipboardHistory()
console.log('剪贴板历史:', history)

// src/index.ts (主进程 - System 插件)
import { ipcMain, clipboard } from 'electron'

const history: string[] = []

ipcMain.handle('clipboard:getHistory', () => {
  return history
})

ipcMain.handle('clipboard:copy', async (_, text: string) => {
  clipboard.writeText(text)
  history.unshift(text)
  if (history.length > 100) history.pop()
  return true
})

构建与发布

构建插件

npm

npm run build

yarn

yarn build

构建产物会输出到 dist/ 目录。

发布到 npm

npm publish

发布后，其他用户可以通过 Spark 插件市场直接安装您的插件。

发布到 Spark 插件市场

1. 访问 Spark 插件市场
2. 点击"提交插件"
3. 填写插件信息并提交审核
4. 审核通过后即可上架

下一步

恭喜您完成了第一个插件的创建！接下来您可以：

• 阅读 插件创建进阶指南 深入了解高级特性
• 查看 API 参考手册 了解完整的 API 文档
• 探索 官方插件示例 学习最佳实践

常见问题

插件加载失败怎么办？

检查以下几点：

1. plugin.json 格式是否正确
2. entry 路径是否指向构建后的文件
3. package.json 中的 name 字段与 plugin.json 中的 name 是否一致
4. 查看 Spark 开发者控制台的错误日志

如何在插件中使用 React/Vue？

UI 插件完全支持前端框架。创建项目时选择对应的模板：

spark create my-react-plugin --template react
spark create my-vue-plugin --template vue

插件可以访问系统资源吗？

可以，但需要在 plugin.json 中声明相应的权限：

• clipboard:read/write - 剪贴板访问
• shell:execute - 执行 shell 命令
• fs:read - 文件系统读取
• fs:write - 文件系统写入
• network:request - 网络请求