QOwnNotes 脚本 Hooks 完全指南:从笔记生命周期到动态高亮与自定义 AI 后端的 21 个挂钩点

原创2026-10-12 13:24:421,361 阅读
文章标签:桌面应用知识管理富文本插件系统跨平台

QOwnNotes 脚本 Hooks 完全指南:从笔记生命周期到动态高亮与自定义 AI 后端的 21 个挂钩点

QOwnNotes 内置的 QML 脚本引擎为 Markdown 笔记应用提供了强大的扩展能力,而 Hooks(钩子) 正是脚本与主程序交互的核心通道:脚本只需在 QtObject / Script 组件内定义与约定同名的函数,QOwnNotes 就会在笔记保存、打开、粘贴、渲染、加标签等关键时刻自动回调。本文将基于官方脚本文档(webpage/src/scripting/hooks.md 及其英文原版),逐个讲解 21 个内置挂钩点的签名、触发时机、返回约定与实战示例,并深入源码(scriptingservice.cpp、qownnotesmarkdownhighlighter.cpp、tagmanager.cpp)印证其底层调用机制,帮助你写出可落地、可复用、性能合格的 QOwnNotes 脚本。

阅读前提:所有 Hook 均以 JavaScript(QML 兼容语法)编写,存放在 docs/scripting/examples/ 目录下的 .qml 文件中;示例脚本与 Hook 签名一一对应,可作为开发时的直接模板。


一、Hook 是什么:QML 脚本与主程序的约定式回调

在 QOwnNotes 中,一个脚本本质上是一个 QML 对象(通常继承 QtObject 或 Script),例如:

import QtQml 2.0
import QOwnNotesTypes 1.0

QtObject {
    function init() {
        script.log("Script init");
    }
}

QOwnNotes 通过 scriptingservice.cpp 中的 methodExistsForObject() / methodExists() 检测脚本对象上是否定义了特定签名的函数,一旦命中就会在对应事件发生时调用。以笔记打开为例,源码中的调用链如下(见 scriptingservice.cpp 第 941 行附近):

// Calls the noteOpenedHook function for all script components
if (methodExistsForObject(object, QStringLiteral("noteOpenedHook(QVariant)"))) {
    QMetaObject::invokeMethod(object, "noteOpenedHook", ...);
}

所有 Hook 都遵循一个共同约定:返回空字符串 / 空数组 / false 表示“不做任何修改、交给 QOwnNotes 默认行为”,返回非空值则接管该行为。掌握了这个约定,就能理解下文几乎所有 Hook 的设计逻辑。


二、笔记生命周期 Hook:保存、打开与双击

2.1 onNoteStored —— 笔记写入磁盘时

onNoteStored 在笔记被存储到磁盘后调用,适合做日志记录、统计或外部同步触发的旁路任务:

/**
 * 当笔记存储到磁盘时调用
 * 你不能修改已存储的笔记,因为你在手工编辑它们的同时
 * 修改存储内容会造成混乱
 *
 * @param {NoteApi} note - 被存储笔记的 note 对象
 */
function onNoteStored(note);

示例脚本 example.qml 展示了其典型用法——读取 note.id、note.name、note.fileName 以及通过 note.tagNames() 获取全部标签名并写入日志:

function onNoteStored(note) {
    script.log("fileName was stored!");
    script.log(note.id);
    script.log(note.name);
    script.log(note.fileName);

    var tagNameList = note.tagNames();
    script.log(tagNameList);
}

从源码结构看(scriptingservice.cpp 第 204 行),该 Hook 通过 onNoteStored(QVariant) 的签名检测并被 SLOT 连接调用。由于此时笔记已经落盘,此 Hook 不能返回内容来修改笔记文本——这是它与命名类 Hook 的本质区别。

2.2 noteOpenedHook —— 笔记打开后

/**
 * 在笔记被打开后调用
 *
 * @param {NoteApi} note - 被打开的笔记对象
 */
function noteOpenedHook(note);

最简实现见 on-note-opened.qml,它打开笔记时在日志中输出完整文件路径:

function noteOpenedHook(note) {
    script.log(note.fullNoteFilePath);
}

它常被用于:打开笔记时自动展开某些内容、记录阅读历史、或按笔记属性切换应用状态。

2.3 noteDoubleClickedHook —— 笔记列表双击时

/**
 * 在笔记被双击后调用
 *
 * @param {NoteApi} note - 被点击的笔记对象
 */
function noteDoubleClickedHook(note);

最有价值的应用是把双击行为重定向到外部编辑器。external-note-open.qml 通过注册设置变量 executablePath 让用户选择外部编辑器,然后在双击时用 script.startDetachedProcess() 启动它:

function noteDoubleClickedHook(note) {
    // 用笔记路径作为参数启动外部编辑器
    script.startDetachedProcess(executablePath, [note.fullNoteFilePath]);
}

设置变量通过 settingsVariables 数组注册(type 为 "file" 时可弹出文件选择器),该机制在 methods-and-objects.md 的 “Registering script settings variables” 一节有完整说明。


三、媒体与附件插入 Hook:改写插入的 Markdown

3.1 insertMediaHook —— 插入媒体文件时

当媒体文件被插入当前笔记(即被复制到媒体文件夹并生成 图片 形式的 Markdown)时,此 Hook 会被调用:

/**
 * @param fileName string 源媒体文件的路径(在复制到媒体文件夹之前)
 * @param markdownText string 媒体文件的 Markdown 文本,例如
 *                        my-image
 * @return string 媒体文件的新 Markdown 文本
 */
function insertMediaHook(fileName, markdownText);

多脚本竞争规则:若多个脚本都定义了此函数,第一个返回非空字符串的脚本生效。因此默认返回 "" 表示不接管(见 example.qml):

function insertMediaHook(fileName, markdownText) {
    script.log("mediafile was inserted: " + fileName);
    return "";
}

实际场景中,你可以用它改写图片链接为绝对路径、压缩图片后再插入、或为图片附带自定义标题。仓库中的 absolute-media-links.qml 正是这一思路的完整实现。

3.2 insertAttachmentHook —— 插入附件时

与媒体 Hook 对称,附件插入时触发:

/**
 * @param fileName string 源附件文件的路径(在复制到附件文件夹之前)
 * @param markdownText string 附件文件的 Markdown 文本,例如
 *                        my-file.txt
 * @return string 附件文件的新 Markdown 文本
 */
function insertAttachmentHook(fileName, markdownText);

同样遵循“第一个返回非空字符串的脚本获胜”的规则,默认返回空字符串即可保持默认插入行为。

3.3 insertingFromMimeDataHook —— Ctrl+Shift+V 粘贴 HTML/媒体时

当使用 Ctrl + Shift + V 把剪贴板中的 HTML 或媒体粘贴进笔记时触发,允许你完全接管要插入的内容:

/**
 * @param text QMimeData 对象的文本
 * @param html QMimeData 对象的 HTML
 * @returns 要插入的字符串(替换 QMimeData 对象的文本)
 */
function insertingFromMimeDataHook(text, html);

insert-headline-with-link-from-github-url.qml 展示了它的经典用法:检测剪贴板中的 GitHub Issue URL,用 script.downloadUrlToString() 抓取页面、解析标题,然后返回一段 Markdown 标题 + 链接文本:

function insertingFromMimeDataHook(text, html) {
    text = text.trim();
    var re = /^http[s]?:\/\/github\.com.+\/issues\//igm;
    if (re.test(text)) {
        var output = script.downloadUrlToString(text);
        var re2 = /<span class="\s*js-issue-title">([^>]+)<\/span>/im;
        var result2 = re2.exec(output);
        if (result2 !== null) {
            var headline = entityToHtml(result2[1].trim());
            // 生成要粘贴的 Markdown
            return "## " + headline + "\n- <" + text + ">\n";
        }
    }
    return ""; // 不做任何修改,走默认粘贴
}

另一个参照示例是 note-text-from-5pm-mail.qml,它会识别从特定邮件系统复制来的文本并转换成笔记格式。


四、链接标题 Hook:接管网页标题抓取

4.1 fetchUrlTitleHook —— 链接对话框抓取标题前

在“链接对话框”中,QOwnNotes 尝试从 URL 抓取网页标题之前会调用此 Hook:

/**
 * @param url string 需要抓取标题的 URL
 * @return string 该 URL 的标题;返回空字符串则让 QOwnNotes 自己去抓取
 */
function fetchUrlTitleHook(url);

多脚本场景下同样是“第一个返回非空字符串者胜”。典型用途是让内网或需要认证的系统也能获得标题,见 fetch-url-title-with-kanboard-cli.qml:它配置了 kanboard-cli 路径和 URL 前缀白名单,用 script.startSynchronousProcess() 同步调用 CLI 获取任务标题:

function fetchUrlTitleHook(url) {
    var taskId = taskIdFromConfiguredPrefix(url);
    if (taskId === "") {
        return "";
    }
    var result = script.startSynchronousProcess(
        kanboardCliPath, ["--json", "task", "get", taskId]);
    try {
        var task = JSON.parse(String(result));
        return task.title || "";
    } catch (error) {
        script.log("Could not fetch Kanboard task title: " + error);
    }
    return "";
}

注意:此处使用 startSynchronousProcess 会阻塞 UI 线程,应只用于快速命令;耗时操作请优先考虑下文 onDetachedProcessCallback 的异步方案。


五、笔记命名 Hook:文件名、显示名与新笔记标题

5.1 handleNoteTextFileNameHook —— 自定义笔记文件名

当设置中启用 “允许笔记文件名与标题不同” 时,笔记写入磁盘前会调用此 Hook,允许你改写文件名(不含扩展名):

/**
 * 当笔记被存储到磁盘时调用(需要设置中启用
 * "允许笔记文件名与标题不同")
 *
 * 允许你修改笔记文件的名称
 * 注意:你必须自己处理重名问题!
 *
 * 如果笔记文件名不应被修改,返回空字符串
 *
 * @param {NoteApi} note - 被存储笔记的 note 对象
 * @return {string} 笔记的文件名
 */
function handleNoteTextFileNameHook(note);

use-tag-names-in-filename.qml 给出了完整范例——把标签名追加到文件名中:

function handleNoteTextFileNameHook(note) {
    var fileName = note.name;                       // 当前笔记名作为回退
    var noteLines = note.noteText.split("\n");
    if (noteLines.length > 0) {
        fileName = noteLines[0];                    // 用首行做文件名基础
    }
    var tagNameList = note.tagNames();
    if (tagNameList.length > 0) {
        fileName += " [" + tagNameList.join("] [") + "]";
    }
    // 检查同名文件是否已存在(防止重名覆盖)
    var noteExists = script.noteExistsByFileName(fileName + ".md", note.id);
    script.log("note " + (noteExists ? "exists" : "doesn't exist"));
    return fileName;
}

源码调用路径见 scriptingservice.cpp 第 881~916 行:先对单个对象调用 handleNoteTextFileNameHook(QVariant),再对所有脚本组件汇总。

5.2 handleNoteNameHook —— 自定义笔记显示名

/**
 * 当需要确定某个笔记的名称时调用
 *
 * 允许你修改笔记在列表中显示的名称
 *
 * 如果名称不应被修改,返回空字符串
 *
 * @param {NoteApi} note - 被存储笔记的 note 对象
 * @return {string} 笔记的名称
 */
function handleNoteNameHook(note);

这个名称主要用于列表展示。文档特别提醒:如果设置中启用了“用文件名作为笔记名”,就不太适合使用此 Hook(两者逻辑会互相干扰)。示例中的一行实现即可在列表里追加后缀:

function handleNoteNameHook(note) {
    return note.name + " some text";
}

5.3 handleNewNoteHeadlineHook —— 新笔记标题模板

在笔记创建之前调用,允许改写标题,是实现“新笔记模板”的首选途径:

/**
 * 在笔记创建之前调用
 *
 * 允许你在笔记创建前修改笔记标题
 * 注意:你必须保证笔记名称唯一,否则新笔记不会被创建,
 * 只会出现在笔记列表中
 *
 * 你可以用这个函数创建笔记模板
 *
 * @param headline 将用于创建标题的文本
 * @return {string} 笔记的标题
 */
function handleNewNoteHeadlineHook(headline);

custom-new-note-headline.qml 演示了如何在标题后自动追加“=` 下划线”并补上换行:

function handleNewNoteHeadlineHook(headline) {
    var text = headline + " - my custom note name " + "\n";
    var underline = "";
    for (var i = 0; i < (text.length - 1); i++) {
        underline += "=";
    }
    return text + underline;
}

六、Markdown/HTML 渲染 Hook:预览与导出的二次加工

这两个 Hook 分别作用于 Markdown → HTML 转换之前 和 转换之后,且都接收 forExport 参数以区分“导出”与“预览”场景,是多脚本协作渲染复杂内容(LaTeX 数学公式、mermaid 图表、自定义样式)的关键位置。

6.1 preNoteToMarkdownHtmlHook —— 转换前改写 Markdown

/**
 * 在笔记的 Markdown HTML 生成之前调用
 *
 * 允许你修改传给 markdown-to-html 转换器的内容
 *
 * 例如可以用在多个脚本中,把代码(如 LaTeX 数学或 mermaid)
 * 渲染成预览所需的图形表示
 *
 * 这个过程不会修改笔记本身
 *
 * @param {NoteApi} note - 笔记对象
 * @param {string} markdown - 即将被转换成 html 的 markdown
 * @param {bool} forExport - 若 html 用于导出则为 true,用于预览则为 false
 * @return {string} 修改后的 markdown;若无需修改则返回空字符串
 */
function preNoteToMarkdownHtmlHook(note, markdown, forExport);

它“不会修改笔记本身”,因此非常适合做只影响展示的预处理——比如把代码块里的 LaTeX 语法替换为可被渲染器识别的形式。

6.2 noteToMarkdownHtmlHook —— 转换后改写 HTML

/**
 * 当笔记的 Markdown HTML 生成时调用
 *
 * 允许你修改这个 html
 * 例如在笔记预览之前被调用
 *
 * 该函数可在多个脚本中用于修改预览的 html
 *
 * @param {NoteApi} note - 笔记对象
 * @param {string} html - 即将被渲染的 html
 * @param {bool} forExport - 若 html 用于导出则为 true,用于预览则为 false
 * @return {string} 修改后的 html;若无需修改则返回空字符串
 */
function noteToMarkdownHtmlHook(note, html, forExport);

example.qml 用它给预览页顶部插入自定义标题与水平分割线:

function noteToMarkdownHtmlHook(note, html, forExport) {
    // 在预览顶部显示自定义标题和水平分割线
    return html.replace("body>",
        "body><h1>Custom preview for note " + note.name + "</h1><hr />");
}

preview-styling.qml 则提供了更完整的预览样式定制范例。文档同时提示:受支持的内联 CSS 样式以 Qt 的 Supported HTML Subset 为限。


七、加密 Hook:接管加解密实现

7.1 encryptionHook —— 自定义加密算法

当需要加密或解密笔记文本时调用,可完全替换 QOwnNotes 内置的 AES 加密,接入自选算法(如 PGP、Keybase 或娱乐性的 ROT13):

/**
 * 当文本需要加密或解密时调用
 *
 * @param text string 需要加密或解密的文本
 * @param password string 密码
 * @param decrypt bool 若为 false 表示要求加密,若为 true 表示要求解密
 * @return 加密/解密后的文本
 */
function encryptionHook(text, password, decrypt);

encryption-rot13.qml 用不到 10 行实现了完整的 ROT13 加解密,并在 init() 中用 script.encryptionDisablePassword() 关闭密码对话框:

function init() {
    script.encryptionDisablePassword();
}

function encryptionHook(text, password, decrypt) {
    text = text.replace(/[a-zA-Z]/g, function(c){
        return String.fromCharCode((c <= "Z" ? 90 : 122) >=
            (c = c.charCodeAt(0) + 13) ? c : c - 26);
    });
    return text;
}

生产级实现可参考 encryption-pgp.qml 与 encryption-keybase.qml,它们通过调用外部 PGP / Keybase 命令完成加解密。


八、标签系统 Hook:接管整个标签机制

QOwnNotes 默认用独立数据库管理标签,而 noteTaggingHook / noteTaggingByObjectHook 允许你用笔记内文本(如 @tag1、@tag2)实现自己的标签体系。

8.1 noteTaggingHook —— 基于标签名的标签机制

/**
 * 处理笔记的标签
 *
 * 当标签被添加、移除、重命名,或需要列出笔记标签时调用
 *
 * @param note
 * @param action 可以是 "add"、"remove"、"rename" 或 "list"
 * @param tagName 要添加、移除或重命名的标签名
 * @param newTagName action = "rename" 时重命名成的标签名
 * @return 笔记文本字符串;若 action = "list" 则返回标签名列表
 */
function noteTaggingHook(note, action, tagName, newTagName);

一旦有脚本实现了 noteTaggingHook,笔记标签的处理就完全移交给它。文档明确列出了经由 QOwnNotes UI 触发后应支持的能力清单:

  • 初次激活时从笔记中导入 @tag 类标签并覆盖现有标签分配(标签树不会丢失,仅丢失旧的笔记关联;仍可把标签移入其他标签;若标签树中存在多个同名标签,取第一个匹配项);
  • 向笔记添加标签 → 向笔记文本追加标签;
  • 从笔记移除标签 → 从笔记文本删除标签;
  • 在标签列表中删除标签 → 从所有相关笔记中删除;
  • 在标签列表中重命名标签 → 在所有相关笔记中重命名;
  • 笔记列表中的批量打标签 → 向所选笔记批量添加标签;
  • 笔记列表中的批量移除标签 → 从所选笔记批量移除;
  • 在标签面板移动标签时,应用会对所有选中标签及其子标签在所有笔记上触发一系列 add / remove 动作。

note-tagging.qml 给出了基于正则的完整实现,其 list 分支从笔记文本中提取 @tag 列表:

function noteTaggingHook(note, action, tagName, newTagName) {
    var noteText = note.noteText;
    var tagRegExp = RegExp("\\B@" + escapeRegExp(tagName) + "\\b");
    switch (action) {
        case "add":
            if (noteText.search(tagRegExp) > 0) { return ""; }   // 已存在
            noteText += "\n@" + tagName;                          // 追加到末尾
            return noteText;
        case "remove":
            return noteText.replace(tagRegExp, "");
        case "rename":
            return noteText.replace(tagRegExp, "@" + newTagName);
        case "list":
            var re = new RegExp("\\B@([^\\s,]+)", "gi"),
                result, tagNameList = [];
            while ((result = re.exec(noteText)) !== null) {
                var tagName = result[1];
                if (tagNameList.indexOf(tagName) == -1) {
                    tagNameList.push(tagName);
                }
            }
            return tagNameList;
    }
    return "";
}

⚠️ 性能警告:list 动作必须足够快

文档特别强调:list 动作在每次笔记文件夹或标签树重载时都会对所有笔记执行一次。从 tagmanager.cpp 可以看到,reloadTagTree() 在标签增删改、批量操作、同步等多个路径被反复调用(如第 46 行定义、第 333/360/451/498 行等约 20 处调用点)。因此:

  • list 内部严禁发起同步网络请求、启动外部进程等慢操作;
  • 保持实现为纯文本正则匹配,避免不必要的对象创建。

8.2 noteTaggingByObjectHook —— 基于 TagApi 对象的标签机制

与 noteTaggingHook 类似,但不再局限于标签树根部的标签名,可以自由使用整个标签树;参数从 tagName 字符串换成 TagApi 对象,list 动作需要返回标签 ID 列表:

/**
 * 处理笔记的标签
 *
 * 当标签被添加、移除、重命名,或需要列出笔记标签时调用
 *
 * @param note
 * @param action 可以是 "add"、"remove"、"rename" 或 "list"
 * @param tag 要添加、移除或重命名的标签
 * @param newTagName action = "rename" 时重命名成的标签名
 */
function noteTaggingByObjectHook(note, action, tag, newTagName);

这也意味着:为了给 list 动作提供已存在的标签 ID 列表,你需要自行创建缺失的标签。note-tagging-by-object.qml 展示了核心思路:用 tag.name 取得标签名,用 script.getTagByNameBreadcrumbList(...) 与 tag.fetchByName(...) 将文本标签解析为 tag.id,list 时返回 ID 列表(对 tagId == 0 的情况需自行创建标签)。


九、编辑器增强 Hook:自动补全与动态高亮

9.1 autocompletionHook —— 注入自动补全条目

当在笔记中触发自动补全(例如按下 Ctrl + Space)时,返回要加入补全列表的字符串数组:

/**
 * 为所有脚本组件调用 autocompletionHook 函数
 * 当在笔记中触发自动补全时调用
 *
 * @return QStringList 补全列表的文本
 */
function callAutocompletionHook();

autocompletion.qml 给出了“以 @ 开头的词补全标签”的实用实现:

function autocompletionHook() {
    // 获取当前词(连同词前的非单词字符,以便拿到 "@")
    var word = script.noteTextEditCurrentWord(true);
    if (!word.startsWith("@")) {
        return [];
    }
    // 去掉 "@",对标签做子串搜索
    var tags = script.searchTagsByName(word.substr(1));
    return tags;
}

9.2 highlightingHook —— 逐文本块动态语法高亮

此 Hook 在编辑器语法高亮期间对每个可见文本块调用,可以做出超越静态正则规则(addHighlightingRule)的、上下文感知的动态高亮:

/**
 * 在语法高亮期间为每个文本块调用,支持上下文感知的动态高亮
 *
 * @param text {QString} 当前被高亮文本块的内容
 * @param previousBlockState {int} 上一个文本块的高亮器状态
 *     (首块为 -1)
 * @return {Array} 高亮区间对象数组,每个对象包含:
 *     start {int} - 文本中的起始位置
 *     length {int} - 要高亮的字符数
 *     state {int} - 使用的 HighlighterState(可选,仅自定义时为 -1)
 *     foregroundColor {string} - 前景色名称或十六进制(可选)
 *     backgroundColor {string} - 背景色名称或十六进制(可选)
 *     bold {bool} - 粗体(可选)
 *     italic {bool} - 斜体(可选)
 *     underline {bool} - 下划线(可选)
 *     fontSize {int} - 字号(可选)
 */
function highlightingHook(text, previousBlockState) {
  var highlights = [];

  // 示例:把所有 "FIXME" 高亮为红色粗体加下划线
  var re = /FIXME/g;
  var match;
  while ((match = re.exec(text)) !== null) {
    highlights.push({
      start: match.index,
      length: match[0].length,
      foregroundColor: "#ff0000",
      underline: true,
      bold: true,
    });
  }

  return highlights;
}

源码层面的调用路径见 qownnotesmarkdownhighlighter.cpp:在 highlightBlock() 中按顺序先应用静态规则(highlightScriptingRules,第 130 行),再调用 highlightScriptingHook(text)(第 134 行);后者在第 227~249 行检查 highlightingHookExists()(带缓存标记,仅当至少一个脚本提供了该 Hook 才执行),以 baseBlockState(previousBlockState()) 传入上一个块状态,最后把返回的区间逐个应用为 QTextCharFormat。

⚠️ 性能警告:高频调用,务必轻量

文档明确指出:该 Hook 在每个按键、每个可见文本块上都会被调用,因此:

  • 实现必须极快,避免任何重型计算、正则回溯失控或对象频繁创建;
  • 如果只是静态正则高亮,应优先使用 addHighlightingRule 或带自定义颜色的 addHighlightingRule(参数含 foregroundColor、backgroundColor、bold、italic、underline、fontSize,详见 methods-and-objects.md 第 2102~2164 行处的示例);
  • 可对照 highlighting.qml(静态规则 + 动态 Hook 混合使用)与 custom-highlighting.qml 两份示例理解两种方式的分工。

十、外部集成 Hook:WebSocket、后台进程与 AI 后端

10.1 websocketRawDataHook —— 浏览器扩展数据接入

当 QOwnNotes Web Companion 浏览器扩展通过浏览器右键菜单发送数据时触发:

/**
 * @param requestType 可以是 "page" 或 "selection"
 * @param pageUrl 发起请求的网页 URL
 * @param pageTitle 发起请求的网页标题
 * @param rawData 传输的数据:requestType 为 "page" 时是 html,
 *                为 "selection" 时是纯文本
 * @param screenshotDataUrl 发起请求网页的截图数据 URL
 * @return true 表示数据已被某个 Hook 处理
 */
function callHandleWebsocketRawDataHook(requestType, pageUrl, pageTitle, rawData, screenshotDataUrl);

参考示例:layouts.qml 与 websocket-raw-data-selection-in-note.qml(后者演示把选中文本写入当前笔记)。同目录还有 websocket-server.qml、websocket-client.qml 可作为理解通信机制的补充。

10.2 onDetachedProcessCallback —— 后台进程完成回调

当 startDetachedProcess 启动的脚本线程执行完毕时回调,用于避免阻塞 UI 线程的异步外部命令编排:

/**
 * 当脚本线程执行完毕时调用。
 * 提示:thread[1]==0 有助于判断某个标识符的一批进程是否全部结束。
 *
 * @param {QString} callbackIdentifier - 调用 startDetachedProcess() 时提供的 id
 * @param {QString} resultSet - 进程结果
 * @param {QVariantList} cmd - 完整命令数组
 *     [0-可执行文件路径, 1-参数, 2-退出码]
 * @param {QVariantList} thread - 线程信息数组
 *     [0-传入的回调参数, 1-该标识符的剩余线程数]
 */
function onDetachedProcessCallback(callbackIdentifier, resultSet, cmd, thread);

callback.qml 展示了高并发用法:在 init() 中批量启动 100 个 sleep 子进程(共用标识符 "callback-example"),在回调里用 thread[1] 判断剩余线程数、thread[0] 拿到每个进程传入的回调参数:

function init() {
    log("init");
    for (var i = 0; i < 100; i++) {
        var dur = Math.floor(Math.random() * 10) + 1;
        script.startDetachedProcess("sleep", [`${dur}s`], "callback-example", i);
    }
}

function onDetachedProcessCallback(callBackIdentifier, resultSet, cmd, thread) {
    if (callBackIdentifier == "callback-example") {
        log(`#${thread[1]} i[${thread[0]}] t${cmd[1]}`);
    }
}

源码侧,该回调在 scriptingservice.cpp 第 2806 行以 onDetachedProcessCallback(QVariant,QVariant,QVariant,QVariant) 签名被检测并分发。

10.3 openAiBackendsHook —— 注册自定义 OpenAI 后端

当 OpenAI 服务配置被重载(例如脚本引擎重载)时调用,用于注册自定义的 OpenAI API 兼容后端——包括自己的 LLM 服务、ChatGPT、Claude,或本地 Ollama 一类的系统:

/**
 * 当 OpenAI 服务配置被重载时调用
 * 返回包含新 OpenAI 后端配置参数的对象列表
 */
function openAiBackendsHook() {
  return [
    {
      id: "my-custom-ai",
      name: "My Custom AI",
      baseUrl: "http://localhost:5000",
      apiKey: "kDFJkjk3asdm",
      models: ["gpt-3.5-turbo", "gpt-4.0-turbo"],
    },
    {
      id: "my-custom-ai2",
      name: "My Custom AI 2",
      baseUrl: "http://localhost:5001",
      apiKey: "lOikf7eNdb9",
      models: ["gpt-3.5-turbo2", "gpt-4.0-turbo2"],
    },
  ];
}

每个后端对象包含四个关键字段:

字段 含义 示例
id 后端的唯一标识符 "my-custom-ai"
name 在界面中显示的名称 "My Custom AI"
baseUrl API 端点地址 "http://localhost:5000"
apiKey 访问密钥 "kDFJkjk3asdm"
models 可用的模型列表 ["gpt-3.5-turbo", "gpt-4.0-turbo"]

文档提示:可以使用 注册脚本设置变量 把后端配置(URL、密钥、模型)存进脚本设置,避免硬编码。custom-openai-backends.qml 提供了完整范例,还额外演示了接入 Groq 服务的 baseUrl(https://api.groq.com/openai/v1/chat/completions)。调用点在 scriptingservice.cpp 第 803~823 行,通过 openAiBackendsHook() 签名检测并聚合各脚本的返回。


十一、界面状态 Hook:窗口状态与布局切换

11.1 windowStateChangedHook —— 窗口状态变化

/**
 * 在触发 WindowStateChange 事件后调用
 *
 * @param {QString} windowState - 新的窗口状态,参数值可以是
 *     "minimized"、"maximized"、"fullscreen"、"active" 或 "nostate"
 */
function windowStateChangedHook(windowState);

window-state-changed.qml 一行实现日志输出:

function windowStateChangedHook(windowState) {
    script.log('Window state changed: ' + windowState);
}

可以据此联动其他行为,例如窗口最小化时暂停某些定时任务。

11.2 layoutSwitchedHook —— 布局切换

/**
 * 当布局切换时调用
 *
 * @param oldUuid 旧布局的 uuid
 * @param newUuid 新布局的 uuid
 */
function layoutSwitchedHook(oldUuid, newUuid);

QOwnNotes 支持多布局(可通过布局预设切换),此 Hook 让你在切换布局时执行自定义动作(如按布局调整工具栏、加载对应脚本状态),示例见 layouts.qml。


十二、实战小结:Hook 选择与开发要点

把全部 21 个 Hook 按“接管还是观察”归个类,便于快速决策:

类别 Hook 触发时机 返回约定
生命周期 onNoteStored 笔记写盘后 无返回值(观察用)
生命周期 noteOpenedHook 笔记打开后 无返回值(观察用)
生命周期 noteDoubleClickedHook 笔记被双击 无返回值
内容插入 insertMediaHook 插入媒体 非空字符串者胜
内容插入 insertAttachmentHook 插入附件 非空字符串者胜
内容插入 insertingFromMimeDataHook Ctrl+Shift+V 粘贴 返回插入文本
链接 fetchUrlTitleHook 链接对话框抓标题前 非空字符串者胜
命名 handleNoteTextFileNameHook 写盘时(需开启设置) 返回文件名,空=不改
命名 handleNoteNameHook 确定显示名时 返回名称,空=不改
命名 handleNewNoteHeadlineHook 新建笔记前 返回标题
渲染 preNoteToMarkdownHtmlHook Markdown→HTML 前 返回 markdown,空=不改
渲染 noteToMarkdownHtmlHook Markdown→HTML 后 返回 html,空=不改
加密 encryptionHook 加解密时 返回加解密文本
标签 noteTaggingHook 标签增删改/列出 返回笔记文本或标签名列表
标签 noteTaggingByObjectHook 同上(对象版) 返回笔记文本或标签 ID 列表
编辑器 autocompletionHook 触发自动补全 返回补全字符串列表
编辑器 highlightingHook 每个文本块高亮 返回高亮区间数组
外部集成 websocketRawDataHook 浏览器扩展发数据 返回 true 表示已处理
外部集成 onDetachedProcessCallback 后台进程结束 无返回值
外部集成 openAiBackendsHook OpenAI 配置重载 返回后端对象数组
界面 windowStateChangedHook 窗口状态变化 无返回值
界面 layoutSwitchedHook 布局切换 无返回值

三条贯穿全文的黄金准则:

  1. 返回空值 = 交还默认行为:几乎所有带返回值的 Hook 都以此为约定,多脚本竞争时“第一个返回非空者胜”;
  2. 性能红线:noteTaggingHook 的 list 与 highlightingHook 都是高频回调(前者随 reloadTagTree 在 tagmanager.cpp 中反复触发,后者每次按键对每个可见文本块触发),务必保持纯计算、轻量实现;
  3. 不修改已落盘内容:onNoteStored 阶段不能再改笔记文本,命名类 Hook(handleNoteTextFileNameHook)才拥有改写文件的入口。

所有示例脚本均可在 docs/scripting/examples 目录下找到;Hook 的完整清单与英文原版定义可对照 webpage/src/scripting/hooks.md,脚本方法与对象的详细说明见 methods-and-objects.md。把本文中的签名与示例结合,即可着手构建属于你自己的 QOwnNotes 扩展脚本。

登录后查看全文
QOwnNotes