从零到一：Wox Python插件开发实战指南

柯轶芊

689人浏览 · 2026-02-21 03:08:59

柯轶芊 · 2026-02-21 03:08:59 发布

从零到一：Wox Python插件开发实战指南

【免费下载链接】Wox A cross-platform launcher that simply works 项目地址: https://gitcode.com/gh_mirrors/wo/Wox

Wox是一款跨平台启动器（A cross-platform launcher that simply works），通过插件扩展可以实现各种实用功能。本文将带你从零开始构建一个Wox Python插件，掌握插件开发的核心流程与最佳实践。

1. 环境准备：快速搭建开发环境

首先需要准备基础开发环境：

Python 3.8+（推荐3.10版本）
Wox主程序（从官方仓库获取：git clone https://gitcode.com/gh_mirrors/wo/Wox）
代码编辑器（VS Code或PyCharm）

Wox Python插件开发依赖官方提供的SDK，位于项目目录 wox.plugin.python/，包含完整的插件API定义和类型提示。

2. 插件结构：理解核心组成部分

一个标准的Wox Python插件包含以下核心文件：

your_plugin/
├── plugin.json       # 插件元数据（名称、作者、触发关键词等）
├── main.py           # 主逻辑实现
└── icon.png          # 插件图标

元数据文件plugin.json是插件的"身份证"，定义了插件的基本信息和行为。示例结构：

{
  "ID": "your_unique_plugin_id",
  "Name": "实用工具插件",
  "Description": "一个演示用的Wox Python插件",
  "Author": "Your Name",
  "Version": "1.0.0",
  "Language": "python",
  "Website": "",
  "Trigger": "ut ",  // 触发关键词，用户输入"ut "时激活插件
  "IcoPath": "icon.png"
}

3. 开发实战：构建你的第一个插件

3.1 创建基础框架

在Wox的插件目录（通常位于~/.config/Wox/Plugins/）创建插件文件夹
创建plugin.json文件，配置插件元数据
创建main.py文件，实现核心逻辑

3.2 实现查询处理逻辑

Wox插件的核心是处理用户查询并返回结果。以下是一个简单的示例，实现一个计算功能：

from wox_plugin import WoxPlugin, Result

class UtilityPlugin(WoxPlugin):
    def query(self, query):
        results = []
        try:
            # 尝试计算数学表达式
            result = eval(query)
            results.append(Result(
                Title=f"计算结果: {result}",
                SubTitle=f"表达式: {query}",
                IcoPath="icon.png",
                JsonRPCAction={
                    "method": "copy_to_clipboard",
                    "parameters": [str(result)],
                    "dontHideAfterAction": False
                }
            ))
        except:
            results.append(Result(
                Title="请输入有效的数学表达式",
                SubTitle="例如: 2+2*3",
                IcoPath="icon.png"
            ))
        return results
    
    def copy_to_clipboard(self, text):
        import pyperclip
        pyperclip.copy(text)
        return None

if __name__ == "__main__":
    UtilityPlugin()

3.3 调试与测试

将插件文件夹复制到Wox的插件目录，然后：

重启Wox
输入触发关键词（如示例中的"ut "）
输入查询内容测试功能

Wox提供了调试日志功能，可在设置中开启，日志文件位于 wox.core/util/log.go 定义的路径下。

4. 高级功能：提升插件体验

4.1 添加设置界面

通过Wox的设置API，可以为插件添加配置界面。在plugin.json中添加：

"Settings": [
  {
    "Name": "decimal_places",
    "Type": "TextBox",
    "DefaultValue": "2",
    "Description": "计算结果保留小数位数"
  }
]

在代码中获取设置值：

decimal_places = self.get_setting("decimal_places", 2)

4.2 结果预览与交互

利用Wox的预览功能，可以为结果添加富文本预览：

Result(
    Title="计算结果",
    SubTitle=f"{query} = {result}",
    IcoPath="icon.png",
    PreviewType="text",
    PreviewContent=f"# 计算结果\n\n{query} = **{result}**"
)

图1：Wox启动器展示应用程序搜索结果，插件可无缝集成到类似界面中