iRightMenu Pro 插件开发

欢迎使用 iRightMenu Pro 插件开发文档。本指南将帮助你使用 Lua 创建自定义的 Finder 右键菜单扩展。

快速入门

5 分钟创建你的第一个插件！

1. 创建插件目录

插件安装位置在 App Group 容器中：

~/Library/Group Containers/group.net.ymlab.iRightMenu.pro/Plugins/

使用反向域名格式创建新目录：

mkdir -p ~/Library/Group\ Containers/group.net.ymlab.iRightMenu.pro/Plugins/com.yourname.myplugin
cd ~/Library/Group\ Containers/group.net.ymlab.iRightMenu.pro/Plugins/com.yourname.myplugin

2. 创建 plugin.json

{
  "id": "com.yourname.myplugin",
  "name": "我的第一个插件",
  "version": "1.0.0",
  "author": "你的名字",
  "description": "一个简单的 Hello World 插件",
  "main": "main.lua",
  "menus": [
    {
      "id": "hello",
      "title": "打个招呼",
      "enabled": true,
      "showOnFiles": true,
      "showOnFolders": true
    }
  ]
}

3. 创建 main.lua

-- 创建插件类
local MyPlugin = Plugin:extend()

-- 初始化：注册菜单处理函数
function MyPlugin:init()
    self:registerHandler("hello", self.sayHello)
end

-- 菜单动作处理函数
function MyPlugin:sayHello(context)
    local files = context.selectedFiles
    local count = #files

    app.notification.show(
        "你好！",
        "你选中了 " .. count .. " 个项目"
    )
end

-- 导出插件类（引擎自动实例化）
return MyPlugin

4. 重新加载插件

在 iRightMenu Pro 中，前往 偏好设置 > 插件，点击 重新加载。

或者重启 Finder：

killall Finder

5. 测试插件

在 Finder 中右键点击任意文件，你应该能在 iRightMenu 子菜单中看到”打个招呼”选项。

文档目录

文档	说明
开发指南	完整开发教程
API 参考	完整 API 文档
示例插件	插件模板

插件结构

com.yourname.myplugin/
├── plugin.json          # 插件清单（必需）
├── main.lua             # 主脚本（必需）
├── icon.png             # 插件图标（可选，建议 64x64）
├── settings.json        # 运行时设置存储（自动生成）
├── locales/             # 国际化文件（可选）
│   ├── en.json
│   └── zh-Hans.json
└── resources/           # 其他资源（可选）

核心概念

插件生命周期

加载：Finder 启动或插件重新加载时加载插件
初始化：调用 init() 注册菜单处理函数
执行：用户点击菜单项时调用处理函数
卸载：Finder 退出或插件重新加载时卸载

菜单匹配规则

控制菜单何时显示：

{
  "menus": [{
    "id": "process_images",
    "title": "处理图片",
    "showOnFiles": true,
    "showOnFolders": false,
    "fileMatchType": "extension",
    "fileMatchPatterns": ["jpg", "png", "gif"],
    "minFiles": 1,
    "maxFiles": 100
  }]
}

API 命名空间

所有 API 通过全局命名空间 app 访问：

app.log - 日志
app.dialog - 对话框和表单
app.file - 文件操作
app.path - 路径工具
app.shell - Shell 命令
app.notification - 系统通知
app.settings - 插件设置
更多…

获取帮助

查看 API 参考获取详细文档
参考示例插件学习常见模式
查看插件日志：~/Library/Group Containers/group.net.ymlab.iRightMenu.pro/Logs/

许可

你创建的插件归你所有。插件 API 由 iRightMenu Pro 提供。