如何从零构建PopClip扩展：完整开发指南

PopClip扩展开发是提升 macOS 文本处理效率的实用技能。本文将从文件架构到功能实现，带你系统掌握扩展开发的核心知识，即使是新手也能快速上手创建自己的第一个扩展。

一、核心组件解析

1.1 目录结构设计

一个规范的PopClip扩展包含以下核心目录和文件：

MyExtension.popclipext/
├── Config.yaml         # 扩展配置文件
├── Resources/          # 本地化资源
│   ├── en.lproj/
│   │   └── Localizable.strings
│   └── zh.lproj/
├── Icons/              # 图标资源
│   ├── icon.png
│   └── [e-mail]
├── Source/             # 源代码文件
│   ├── main.js
│   └── helper.sh
├── Dependencies/       # 第三方依赖
│   └── axios.js
└── README.md           # 扩展说明文档

🔧 关键说明：扩展必须以 .popclipext 为后缀，目录结构需严格遵循上述规范以确保兼容性。

1.2 配置文件核心作用

Config.yaml 是扩展的灵魂文件，负责定义扩展的所有行为。它包含：

• 基础信息：名称、版本、描述
• 界面配置：图标、菜单标题
• 行为定义：触发条件、执行动作
• 权限声明：网络访问、文件系统访问

💡 开发提示：所有路径均使用相对引用，如 ./Source/main.js，避免绝对路径导致的移植问题。

二、实战配置指南

2.1 基础配置模板

以下是一个完整的基础配置示例：

name: "TextFormatter"
version: "1.0"
description: "格式化选中文本的实用工具"
icon: "./Icons/icon.png"
actions:
  - title: "转为大写"
    icon: "./Icons/uppercase.png"
    script: "./Source/uppercase.js"
    trigger:
      text: ".*"  # 匹配任意文本
  - title: "转为小写"
    icon: "./Icons/lowercase.png"
    script: "./Source/lowercase.js"
    trigger:
      text: ".*"

🔧 参数说明：trigger.text 支持正则表达式，.* 表示匹配任意文本内容。

2.2 多动作配置进阶

通过配置多个动作实现功能扩展：

actions:
  - title: "复制为Markdown链接"
    script: "./Source/markdown-link.js"
    requirements:
      - type: "url"  # 仅当选中URL时显示
  - title: "翻译选中内容"
    script: "./Source/translate.js"
    requirements:
      - type: "text"  # 仅当选中纯文本时显示
    options:
      - title: "目标语言"
        type: "select"
        key: "targetLang"
        values: ["en", "zh", "ja"]

图：Emoji扩展通过多动作配置实现不同表情转换功能

三、功能扩展技巧

3.1 动态图标切换实现

通过脚本控制不同状态下的图标显示：

// Source/dynamic-icon.js
if (popclip.input.text.length > 10) {
  popclip.setIcon("./Icons/long-text.png");
} else {
  popclip.setIcon("./Icons/short-text.png");
}

💡 实现原理：利用 PopClip 提供的 JavaScript API 动态修改图标路径。

3.2 扩展调试技巧

1. 日志输出：使用 console.log() 在系统控制台查看调试信息
2. 错误捕获：

try {
  // 业务逻辑
} catch (e) {
  popclip.showNotification("错误: " + e.message);
}

3. 配置验证：使用 popclip validate 命令检查配置文件语法

图：CodeCase扩展调试过程中的实时效果预览

四、扩展发布 checklist

发布前请确保完成以下检查：

1. ✅ 所有图标尺寸符合规范（建议256x256px）
2. ✅ 配置文件通过语法验证
3. ✅ 本地测试覆盖各种触发场景
4. ✅ 包含完整的README说明文档
5. ✅ 第三方依赖已正确打包
6. ✅ 权限声明准确无误
7. ✅ 扩展名称无重名冲突

通过以上步骤，你已经掌握了PopClip扩展开发的核心技能。现在可以开始创建自己的扩展，提升日常文本处理效率了！