QOwnNotes脚本开发指南：方法与对象详解

概述

QOwnNotes作为一款强大的开源笔记应用，提供了丰富的脚本接口，允许用户通过JavaScript/QML脚本扩展应用功能。本文将深入解析QOwnNotes提供的核心方法与对象，帮助开发者更好地利用脚本功能实现自动化操作。

外部程序调用

后台运行外部程序

startDetachedProcess方法允许在后台启动外部程序，不会阻塞主线程：

/**
 * 启动后台进程
 * @param executablePath 可执行文件路径
 * @param parameters 参数列表
 * @param callbackIdentifier 回调标识符(可选)
 * @param callbackParameter 回调参数(可选)
 * @param processData 写入进程的数据(可选)
 * @param workingDirectory 工作目录(可选)
 * @return 成功返回true，失败返回false
 */
script.startDetachedProcess("/usr/bin/program", ["arg1", "arg2"]);

典型应用场景包括：

• 执行系统命令
• 调用其他程序处理笔记内容
• 批量处理任务

同步执行外部程序

startSynchronousProcess会等待程序执行完成并返回输出：

var output = script.startSynchronousProcess(
  "/usr/bin/grep",
  ["-i", "keyword", "/path/to/file"]
);

适用于需要获取执行结果的场景，如：

• 调用命令行工具处理文本
• 执行加密/解密操作
• 获取系统信息

笔记操作

获取当前笔记信息

// 获取当前笔记对象
var note = script.currentNote();

// 获取当前笔记文件夹路径
var folderPath = script.currentNoteFolderPath();

通过这些方法可以：

• 读取和修改当前笔记内容
• 获取笔记元数据
• 实现笔记自动处理逻辑

创建新笔记

script.createNote("新笔记标题\n===\n\n内容...");

创建笔记时可指定Markdown格式内容，系统会自动解析。

媒体文件处理

下载并插入媒体

// 下载URL内容到媒体文件夹
var imgMarkdown = script.downloadUrlToMedia("http://example.com/image.png");

// 插入本地媒体文件
var localImg = script.insertMediaFile("/tmp/photo.jpg");

这些方法会自动处理：

• 文件下载
• 媒体文件命名
• 生成正确的Markdown引用格式

附件管理

// 插入附件文件
var attachment = script.insertAttachmentFile("/path/to/document.pdf");

附件会存储在笔记的专用附件目录中。

用户界面交互

自定义动作

// 注册自定义动作
script.registerCustomAction(
  "my-action",         // 唯一标识符
  "菜单文本",          // 菜单显示文本
  "按钮文本",          // 工具栏按钮文本(可选)
  "edit-copy"          // 图标名称或路径(可选)
);

// 动作触发回调
function customActionInvoked(identifier) {
  if (identifier === "my-action") {
    script.log("动作已执行");
  }
}

自定义动作可以：

• 添加到菜单和工具栏
• 分配快捷键
• 集成到右键上下文菜单

日志输出

script.log("调试信息");
script.log("<b>HTML格式</b>日志");

日志会显示在脚本面板中，支持HTML格式。

文本编辑控制

操作笔记编辑器

// 获取选中文本
var selected = script.noteTextEditSelectedText();

// 写入文本
script.noteTextEditWrite("插入的内容");

// 全选文本
script.noteTextEditSelectAll();

// 设置选区
script.noteTextEditSetSelection(start, end);

这些方法提供了对笔记编辑器的精细控制，可用于：

• 文本转换插件
• 自动补全功能
• 批量编辑操作

实用工具方法

剪贴板操作

// 获取剪贴板内容
var clipboardText = script.clipboard();
var clipboardHtml = script.clipboard(true);

标签组件

// 注册标签
script.registerLabel("status", "准备就绪");

// 更新标签内容
script.setLabelText("status", "处理中...");

标签可用于显示脚本运行状态或动态信息。

最佳实践建议

1. 错误处理：始终检查关键操作的返回值
2. 性能优化：批量操作使用回调而非同步等待
3. 用户体验：通过标签和日志提供操作反馈
4. 资源管理：大文件操作使用临时目录
5. 兼容性：考虑跨平台路径差异

通过合理组合这些方法，可以开发出功能强大的笔记处理脚本，如自动备份、内容转换、外部工具集成等高级功能。