3分钟上手PopClip扩展开发：从核心概念到实战配置

PopClip扩展开发是提升 macOS 文本处理效率的利器。本指南将通过"核心概念→实战搭建→深度配置"三阶结构，帮助开发者快速掌握扩展开发全流程，实现从0到1的功能定制。

如何通过核心概念理解PopClip扩展架构

PopClip扩展本质是文本选择触发的微应用，由配置文件定义行为、脚本文件实现逻辑、资源文件提供界面支持。首次接触需理解三个核心要素：

• YAML：一种层级化配置语言，用于定义扩展元数据与行为规则
• 动作触发阈值：文本选择长度、应用上下文等触发扩展的条件
• 沙箱执行环境：限制扩展权限的安全机制，脚本运行需遵循文件系统访问规则

核心文件关系图

PopClip扩展的文件架构遵循"配置驱动-逻辑分离"原则，各组件关系如下：

扩展目录结构树状表

文件/目录	类型	作用	必需性
Config.yaml	文件	定义扩展元数据与行为	✅ 必需
Source/	目录	存放可执行脚本（.sh/.js等）	❗ 视功能而定
Icons/	目录	存放不同尺寸的图标文件	✅ 必需
Tests/	目录	单元测试与调试脚本	❌ 可选

---

如何通过实战搭建第一个功能扩展

环境准备

🔧 前置步骤：

1. 克隆项目仓库：git clone https://gitcode.com/gh_mirrors/po/PopClip-Extensions
2. 进入扩展模板目录：cd PopClip-Extensions/source/TestMinimal.popclipext

基础文件创建

🔧 创建核心文件：

# 创建配置文件
touch Config.yaml
# 创建脚本目录
mkdir Source && touch Source/main.sh
# 创建图标目录
mkdir Icons && cp ../TestIcons.popclipext/rainbow.png Icons/icon.png

基础配置模板

# Config.yaml 基础模板
name: "文本反转器"
icon: Icons/icon.png
description: "将选中文本进行反转处理"
actions:
  - title: "反转文本"
    script: Source/main.sh
    # 错误处理：当脚本执行失败时显示提示
    on_error: "⚠️ 处理失败，请检查选中内容"

💡 实用提示：

• 图标建议使用512x512px PNG格式，支持Retina显示
• on_error 字段支持HTML格式，可添加换行<br>和强调<b>标签

实现核心逻辑

#!/bin/bash
# Source/main.sh

# 错误处理：检查输入是否为空
if [ -z "$POPCLIP_TEXT" ]; then
  echo "请选择需要处理的文本"
  exit 1
fi

# 核心功能：反转文本
echo "$POPCLIP_TEXT" | rev

🔧 添加执行权限：

chmod +x Source/main.sh

---

如何通过深度配置实现高级功能

基础配置参数详解

参数	类型	说明	示例值
name	字符串	扩展显示名称	"文本工具集"
icon	路径	图标文件相对路径	"Icons/tool.png"
actions[].title	字符串	菜单项显示文本	"转换为大写"
actions[].script	路径	执行脚本路径	"Source/upper.sh"

高级触发规则配置

通过requirements字段定义精确触发条件：

# 高级触发配置示例
requirements:
  # 文本长度限制：1-100字符
  min_chars: 1
  max_chars: 100
  # 应用白名单：仅在指定应用中显示
  apps:
    - com.apple.TextEdit
    - com.microsoft.VSCode
  # 文本模式匹配：仅当包含URL时触发
  pattern: "^https?://"

💡 实用提示：

• pattern 使用JavaScript正则语法，需转义特殊字符（如\.com）
• 可通过not_apps字段排除特定应用，实现"除Safari外都显示"的需求

多动作扩展配置

通过定义多个actions实现功能集合：

name: "文本工具箱"
icon: Icons/toolbox.png
actions:
  - title: "转为大写"
    script: Source/upper.sh
    # 仅当文本长度<500时显示
    requirements: {max_chars: 500}
  - title: "转为小写"
    script: Source/lower.sh
    # 仅当文本包含字母时显示
    requirements: {pattern: "[A-Za-z]"}

---

如何通过调试技巧解决常见问题

日志调试法

🔧 启用详细日志：

# 在脚本中添加调试输出
echo "输入文本: $POPCLIP_TEXT" > ~/popclip_debug.log

常见错误处理

1. 脚本无响应

   • 检查是否添加执行权限：chmod +x script.sh
   • 验证脚本首行解释器声明：#!/bin/bash

2. 图标不显示

   • 确认路径正确：icon: Icons/icon.png（区分大小写）
   • 检查图片格式：必须为PNG，建议使用512x512px

3. 触发条件失效

   • 使用pattern: ".*"测试基础匹配
   • 通过min_chars: 0移除长度限制

开发工具推荐

• PlistEdit Pro：可视化编辑配置文件
• Script Editor：调试AppleScript类型扩展
• PopClip Console：在系统偏好设置中查看实时日志

---

通过本文介绍的核心概念、实战步骤和深度配置方法，开发者可快速构建功能丰富的PopClip扩展。建议从简单功能入手，逐步尝试高级触发规则和多动作组合，充分利用macOS的文本处理能力提升工作效率。