QOwnNotes 脚本 Hooks 完全指南:从笔记生命周期到动态高亮与自定义 AI 后端的 21 个挂钩点
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 |
布局切换 | 无返回值 |
三条贯穿全文的黄金准则:
- 返回空值 = 交还默认行为:几乎所有带返回值的 Hook 都以此为约定,多脚本竞争时“第一个返回非空者胜”;
- 性能红线:
noteTaggingHook的list与highlightingHook都是高频回调(前者随reloadTagTree在 tagmanager.cpp 中反复触发,后者每次按键对每个可见文本块触发),务必保持纯计算、轻量实现; - 不修改已落盘内容:
onNoteStored阶段不能再改笔记文本,命名类 Hook(handleNoteTextFileNameHook)才拥有改写文件的入口。
所有示例脚本均可在 docs/scripting/examples 目录下找到;Hook 的完整清单与英文原版定义可对照 webpage/src/scripting/hooks.md,脚本方法与对象的详细说明见 methods-and-objects.md。把本文中的签名与示例结合,即可着手构建属于你自己的 QOwnNotes 扩展脚本。