CopyQ 脚本 API 深度解析：自动化剪贴板管理的终极指南

CopyQ 脚本 API 深度解析：自动化剪贴板管理的终极指南

CopyQ hluk/CopyQ: CopyQ 是一个高级剪贴板管理器，具有强大的编辑和脚本功能，可以保存系统剪贴板的内容并在以后使用。 项目地址: https://gitcode.com/gh_mirrors/co/CopyQ

前言

CopyQ 作为一款强大的剪贴板管理工具，其真正的威力在于它提供的脚本功能。通过脚本，用户可以完全自定义剪贴板的行为，实现自动化处理、内容转换、智能管理等高级功能。本文将全面解析 CopyQ 的脚本 API，帮助开发者和技术爱好者掌握这一强大工具。

脚本基础

脚本执行方式

CopyQ 脚本可以通过多种方式执行：

1. 在动作或命令对话框中执行：当脚本首行以 copyq: 开头时
2. 通过命令行执行：
   • copyq eval '<SCRIPT>' 直接执行脚本
   • 通过管道输入脚本：cat script.js | copyq eval -
   • 执行特定函数：copyq <SCRIPT_FUNCTION> <ARG1> <ARG2>...

脚本语言特性

CopyQ 脚本基于 ECMAScript（类似现代 JavaScript），支持大多数 JavaScript 特性。开发者可以：

• 使用常见的 JavaScript 语法和控制结构
• 定义和使用函数
• 操作复杂数据结构
• 处理异常

核心 API 详解

系统控制函数

窗口管理

• show()/hide()/toggle() - 控制主窗口显示状态
• showAt(x, y, [width, height]) - 在指定位置显示窗口
• visible()/focused() - 检查窗口状态

剪贴板监控

• enable()/disable() - 启用/禁用剪贴板监控
• monitoring() - 检查监控状态
• ignore() - 忽略当前剪贴板内容（不触发自动命令）

剪贴板操作

基本操作

• clipboard([mimeType]) - 获取剪贴板内容
• copy(text) - 设置剪贴板文本
• copy(mimeType, data) - 设置特定格式的剪贴板内容
• paste() - 模拟粘贴操作（发送 Shift+Insert）

高级功能

• hasClipboardFormat(mimeType) - 检查剪贴板是否包含特定格式
• isClipboard() - 判断当前自动命令是否由剪贴板变化触发

标签页管理

基本操作

• tab() - 获取所有标签页名称
• tab(tabName) - 设置当前脚本操作的标签页
• removeTab(tabName) - 删除标签页
• renameTab(oldName, newName) - 重命名标签页

内存管理

• unload([tabNames...]) - 卸载标签页内容（释放内存）
• forceUnload() - 强制卸载（即使有编辑器打开）

项目操作

读写操作

• count()/size() - 获取项目数量
• read(mimeType, row) - 读取特定项目的内容
• write(row, mimeType, data) - 写入新项目
• change(row, mimeType, data) - 修改现有项目

项目管理

• add(text) - 添加新项目
• insert(row, text) - 在指定位置插入项目
• remove(row) - 删除项目
• move(row) - 移动选中项目

用户交互

通知与弹窗

• popup(title, message, [time]) - 显示临时通知
• notification() - 显示带按钮的高级通知

菜单与对话框

• menu() - 打开上下文菜单
• action() - 打开动作对话框
• edit(row) - 编辑项目内容

实用技巧与最佳实践

自动化处理示例

// 自动处理复制的URL
if (isClipboard() && str(clipboard()).startsWith("http")) {
    var url = str(clipboard());
    var title = "自动保存的链接";
    add(url + "\n" + title);
    popup("链接已保存", url);
}

高级通知示例

// 带操作按钮的通知
notification(
    '.title', '处理完成',
    '.message', '要如何处理这个项目？',
    '.button', '复制', 'copyq:copy(str(input()))', '',
    '.button', '编辑', 'copyq:edit(-1)', '',
    '.time', 10000  // 10秒后自动消失
);

配置管理

// 获取和修改配置
var currentMaxItems = config('maxitems');
config('maxitems', 500);  // 增加最大项目数
toggleConfig('autostart');  // 切换开机自启

常见问题解答

Q：如何在脚本中处理多种数据格式？

A：可以使用 hasClipboardFormat() 检查格式，然后使用 clipboard(mimeType) 获取特定格式内容。例如：

if (hasClipboardFormat('text/html')) {
    var html = str(clipboard('text/html'));
    // 处理HTML内容
}

Q：为什么我的自动命令没有触发？

A：检查是否：

1. 剪贴板监控已启用 (monitoring() 返回 true)
2. 没有在脚本中调用 ignore()
3. 自动命令已正确配置并启用

结语

CopyQ 的脚本 API 提供了极其强大的剪贴板自动化能力。通过掌握这些 API，你可以实现：

• 智能剪贴板历史管理
• 内容自动格式化与转换
• 与其他工具的深度集成
• 自定义工作流自动化

建议从简单脚本开始，逐步尝试更复杂的功能，最终打造出完全符合个人需求的剪贴板管理系统。

CopyQ hluk/CopyQ: CopyQ 是一个高级剪贴板管理器，具有强大的编辑和脚本功能，可以保存系统剪贴板的内容并在以后使用。 项目地址: https://gitcode.com/gh_mirrors/co/CopyQ