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. 允许未签名插件

自己写的插件没有官方签名，默认加载不了。到 设置 → 高级，勾选「允许安装未签名的插件」，会弹一次安全警告，确认后插件立刻重新加载，不用重启 App。

这个开关跟 macOS 的「允许任何来源」是一个意思：默认只认已签名的，要不要放开由你决定。开发完想恢复默认，取消勾选即可，已加载的未签名插件会随之停用。

开关的位置和风险说明见设置 → 高级。

5. 重新加载插件

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

或者重启 Finder：

killall Finder

6. 测试插件

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

文档目录

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

插件结构

com.yourname.myplugin/
├── plugin.json          # 插件清单（必需）
├── main.lua             # 主脚本（必需）
├── icon.png             # 插件图标（可选，建议 64x64）
├── CHANGELOG.md         # 本次版本的更新日志（可选，插件商店会展示给用户）
├── CHANGELOG.en.md      # 更新日志英文版（可选）
├── locales/             # 国际化文件（可选）
│   ├── en.json
│   └── zh-Hans.json
├── resources/           # 其他资源（可选）
└── plugin.sig           # 签名（发布时由工具生成，不要手写）

插件目录是只读的随包内容。 升级插件时整个目录会被替换掉，写在这里的东西会丢；改动随包分发的文件还会让签名校验失败。要落盘的数据（缓存、数据库、状态）一律写到 app.context.dataDirectory()——那是插件自己的可写目录，升级不受影响，卸载时随插件一并清除。用户设置用 app.settings，它已经存在那里。

核心概念

插件生命周期

加载：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 提供。