QOwnNotes 脚本开发入门:基于 Qt QML 与 JavaScript 的扩展机制实战指南
QOwnNotes 脚本开发入门:基于 Qt QML 与 JavaScript 的扩展机制实战指南
QOwnNotes 是一套以纯文本笔记为核心的笔记与待办事项管理器,其强大的扩展能力建立在 Qt QML + JavaScript 脚本引擎之上。本指南围绕官方脚本入门文档展开,带你从零编写第一个可运行的 QML 脚本,掌握脚本的添加、调试、仓库安装流程,并深入到 ScriptingService 源码层理解钩子(Hook)、自定义动作、设置变量等机制的底层实现。读完本文,你将具备独立编写、调试与分发 QOwnNotes 脚本的完整实战能力。
什么是 QOwnNotes 脚本
QOwnNotes 脚本本质上是一份 Qt QML 文件,其中大部分逻辑以 JavaScript 编写。QML 文件可以放置在磁盘上的任意位置,然后在 QOwnNotes 的脚本设置中添加并启用。
官方入门文档给出了最小可运行示例(见 webpage/src/scripting/README.md):
import QtQml 2.0
import QOwnNotesTypes 1.0
Script {
/**
* Will be run when the scripting engine initializes
*/
function init() {
script.log("Hello world!");
}
}
这份脚本完成了三件事:
import QtQml 2.0:引入 Qt QML 基础模块(定时器、对象模型等);import QOwnNotesTypes 1.0:引入 QOwnNotes 向脚本暴露的专属类型与 API,例如Script根对象、Note、Tag、NoteSubFolder;function init():脚本引擎初始化时自动调用的入口函数,这里通过script.log()向日志面板输出Hello world!。
从源码实现看,Script 这个 QML 根类型并非魔法,而是 C++ 侧注册到 QML 引擎中的真实类型。在 src/services/scriptingservice.cpp 中可以看到注册过程:
// deprecated
qmlRegisterType<NoteApi>("com.qownnotes.noteapi", 1, 0, "NoteApi");
qmlRegisterType<TagApi>("com.qownnotes.tagapi", 1, 0, "TagApi");
qmlRegisterType<NoteApi>("QOwnNotesTypes", 1, 0, "Note");
qmlRegisterType<NoteSubFolderApi>("QOwnNotesTypes", 1, 0, "NoteSubFolder");
qmlRegisterType<TagApi>("QOwnNotesTypes", 1, 0, "Tag");
qmlRegisterType<ScriptApi>("QOwnNotesTypes", 1, 0, "Script");
同时 script 与 mainWindow 两个全局对象被注入到 QML 根上下文(_engine->rootContext()->setContextProperty(...)),这就是脚本里可以直接使用 script.currentNote()、mainWindow.jumpToTag(...) 等接口的原因。
将脚本添加进 QOwnNotes
添加本地脚本
QML 脚本文件可以放在任意位置。在 QOwnNotes 中打开 脚本设置(Scripting settings),点击 Add script / Add local script 按钮即可选择本地的 .qml 文件。
这一交互在 src/widgets/settings/scriptingsettingswidget.cpp 中有完整实现:Add script 按钮实际上是一个带下拉菜单的按钮,包含三个动作:
- Search script repository:在脚本仓库中搜索脚本;
- Check for script updates:检查已安装脚本的更新;
- Add local script:添加本地脚本文件。
选择本地脚本后,QOwnNotes 会弹出文件选择对话框,文件过滤器限定为 QML files (*.qml)(见 scriptingsettingswidget.cpp)。确认后脚本被写入内置数据库,随后脚本引擎自动重载。
脚本引擎重载与校验
每次新增、删除或切换脚本的启用状态时,设置页面都会调用 ScriptingService::instance()->reloadEngine() 重载脚本引擎(见 scriptingsettingswidget.cpp)。值得注意的细节是:只有启用状态真正发生变化时才会触发引擎重载,避免每次点击设置对话框的"确定"按钮都做一次昂贵的引擎重启(见 scriptingsettingswidget.cpp)。
设置页面还会对脚本做即时校验:ScriptingService::validateScript() 会用独立的 QQmlEngine 加载脚本并创建对象,若组件存在错误则返回 errorString(),界面上的校验标签会以红/绿颜色提示"存在脚本错误"或"脚本看起来有效"(见 scriptingsettingswidget.cpp)。
从脚本仓库安装
除了本地脚本,你还可以直接从 脚本仓库(Script repository) 安装社区脚本。仓库元数据(index.json)通过 GitHub Releases 的 metadata-index 资产下载并缓存(缓存有效期 60 秒,见 src/dialogs/scriptrepositorydialog.cpp),随后在对话框中按名称或描述搜索脚本、查看详情并一键安装。
脚本实体在 C++ 侧由 src/entities/script.h 中的 Script 类管理,包含名称、脚本路径、优先级(priority)、启用状态(enabled)、标识符、info.json 元数据、设置变量 JSON 等字段。其中 priority 用于决定多个脚本同时定义同一钩子时的调用顺序——在 scriptingservice.cpp 中,脚本组件以 (priority << 10) + scriptId 作为键存入有序映射,优先级越高越先执行。
用日志面板调试脚本
脚本开发离不开调试输出。官方文档特别提示:可以使用 script.log() 将文本写入 日志面板(Log panel),该面板可通过菜单 Window / Panels 开启。
script.log() 的底层实现在 src/services/scriptingservice.cpp:它向 MainWindow 发出 log 信号,最终进入日志面板的 ScriptingLogType 类型分区。日志面板(src/widgets/logwidget.ui)支持按日志类型过滤,其中就包含专门的 Scripting 复选框,便于在众多日志中单独查看脚本输出。
钩子机制:脚本如何接入笔记生命周期
QOwnNotes 脚本的核心价值在于 钩子(Hook):当笔记发生特定事件时,脚本引擎会调用脚本中定义的同名函数。钩子机制由 ScriptingService 统一调度,脚本加载时先检查对象元方法是否存在(methodExistsForObject),存在才建立连接(见 scriptingservice.cpp)。
最常用的钩子都集中在官方示例脚本中(docs/scripting/examples):
init 与笔记存储钩子
function init() {
script.log("Script init");
}
// 笔记写入磁盘时被调用,只读钩子,不能修改笔记内容
function onNoteStored(note) {
script.log("fileName was stored!");
script.log(note.id);
script.log(note.name);
script.log(note.fileName);
// tagNames() 返回该笔记的全部标签名列表
var tagNameList = note.tagNames();
script.log(tagNameList);
}
完整示例见 docs/scripting/examples/example.qml。
笔记打开钩子
function noteOpenedHook(note) {
script.log(note.fullNoteFilePath);
}
该钩子在笔记被打开后触发,示例见 docs/scripting/examples/on-note-opened.qml。
其他常用钩子一览
ScriptingService 的公开方法(src/services/scriptingservice.h)揭示了完整的钩子清单,包括但不限于:
| 钩子 | 触发时机 |
|---|---|
insertMediaHook(fileName, markdownText) |
向笔记插入媒体文件时 |
insertAttachmentHook(fileName, markdownText) |
向笔记插入附件时 |
noteToMarkdownHtmlHook(note, html, forExport) |
笔记 Markdown 转 HTML(预览或导出)时 |
handleNoteNameHook(note) |
确定笔记显示名称时 |
handleNewNoteHeadlineHook(headline) |
创建新笔记确定标题时 |
noteTaggingHook(note, action, tagName, newTagName) |
笔记标签增删改查时 |
layoutSwitchedHook(oldUuid, newUuid) |
切换工作区布局时(旧版 workspaceSwitchedHook 已弃用) |
autocompletionHook() |
自动补全时 |
highlightingHook(text, previousBlockState) |
编辑器逐块语法高亮时 |
windowStateChangeHook(windowStateStr) |
窗口状态变化时 |
handleWebsocketRawDataHook(...) |
WebSocket 原始数据到达时 |
大多数钩子都约定:返回空字符串表示"不做任何修改",返回新内容则用于替换默认行为。例如 noteToMarkdownHtmlHook 返回修改后的 HTML,否则返回空字符串。
自定义动作:在菜单与工具栏中挂载脚本功能
脚本可以通过 script.registerCustomAction() 注册自定义动作,动作会出现在菜单、工具栏按钮乃至笔记编辑右键菜单中。官方示例(docs/scripting/examples/custom-actions.qml)展示了完整用法:
function init() {
// 创建菜单项 "Open with KWrite" 与按钮 "KWrite"
script.registerCustomAction("openWithKWrite", "Open with KWrite", "KWrite");
// 带 freedesktop 主题图标的菜单项与按钮
script.registerCustomAction("createMeetingNote", "Create meeting note", "Meeting note", "task-new");
// 只有菜单项、不显示按钮
script.registerCustomAction("noButtonAction", "No button here");
// 出现在笔记编辑右键菜单中的动作(第 5 个参数为 true)
script.registerCustomAction("transformTextRot13", "Transform selected text with rot13", "rot13", "text-wrap", true);
}
function customActionInvoked(identifier) {
switch (identifier) {
case "openWithKWrite":
var note = script.currentNote();
script.startDetachedProcess("kwrite", [note.fullNoteFilePath]);
break;
case "createMeetingNote":
var text = "Meeting note " + new Date().toISOString().replace(/:/g, ".") + "\n";
// ... 拼装笔记正文 ...
script.createNote(text);
break;
case "transformTextRot13":
var text = script.noteTextEditSelectedText();
text = text.replace(/[a-zA-Z]/g, function(c){
return String.fromCharCode((c <= "Z" ? 90 : 122) >= (c = c.charCodeAt(0) + 13) ? c : c - 26);
});
script.noteTextEditWrite(text);
break;
}
}
registerCustomAction 的完整签名定义在 src/services/scriptingservice.h:
registerCustomAction(identifier, menuText, buttonText, icon, useInNoteEditContextMenu, hideButtonInToolbar, useInNoteListContextMenu)
其中 useInNoteEditContextMenu 控制动作是否出现在笔记编辑器右键菜单,hideButtonInToolbar 控制是否在工具栏隐藏按钮。当用户触发动作时,customActionInvoked(identifier) 会被调用(由 onCustomActionInvoked 信号槽分发,见 scriptingservice.h)。
脚本设置变量:让脚本可配置
成熟的脚本应该允许用户在不修改代码的情况下调整行为。QOwnNotes 通过在脚本中声明 settingsVariables 属性实现这一点。官方示例(docs/scripting/examples/variables.qml)展示了 8 种受支持的变量类型:
Script {
// 必须先声明属性,运行时才能访问
property string myString;
property string myStringSecret;
property bool myBoolean;
property string myText;
property int myInt;
property string myFile;
property string myDirectory;
property string mySelection;
property variant settingsVariables: [
{ "identifier": "myString", "name": "I am a line edit", "type": "string", "default": "My default value" },
{ "identifier": "myStringSecret", "name": "I am a password field", "type": "string-secret" },
{ "identifier": "myBoolean", "name": "I am a checkbox", "type": "boolean", "default": true },
{ "identifier": "myText", "name": "I am a textbox", "type": "text", "default": "This can be a really long text\nwith multiple lines." },
{ "identifier": "myInt", "name": "I am a number selector", "type": "integer", "default": 42 },
{ "identifier": "myFile", "name": "I am a file selector", "type": "file", "default": "pandoc" },
{ "identifier": "myDirectory", "name": "I am a directory selector", "type": "directory", "default": "/home" },
{ "identifier": "mySelection", "name": "I am an item selector", "type": "selection",
"default": "option2",
"items": {"option1": "Text for option 1", "option2": "Text for option 2", "option3": "Text for option 3"} }
];
function init() {
// 这些变量会由 QOwnNotes 从设置中注入;未设置时使用 default 值
script.log(myString);
script.log(myBoolean);
// ...
}
}
变量声明后,设置界面会自动为每个变量生成对应的输入控件(文本框、密码框、复选框、文件/目录选择器、下拉选择框等)。这在源码中由 ScriptingService::registerSettingsVariables() 完成:脚本对象通过 QML 元对象反射被读取,随后 src/widgets/settings/scriptingsettingswidget.cpp 根据变量列表动态创建 ScriptSettingWidget 并填充到设置页面。
如果希望在脚本加载时用代码覆盖某些默认值(例如按操作系统区分),可以定义 registerSettingsVariables() 函数:
function registerSettingsVariables() {
if (script.platformIsWindows()) {
settingsVariables[3].default = "pandoc.exe";
}
}
持久化变量:跨会话保存数据
与设置变量不同,持久化变量用于保存脚本运行时产生的数据,存储在 QOwnNotes 的配置中(源码中以 "PersistentScripting" 为前缀,见 src/services/scriptingservice.h)。官方示例(docs/scripting/examples/persistent-variables.qml):
// 保存
script.setPersistentVariable("PersistentVariablesTest/myVar", result);
// 读取,带默认值
script.log(script.getPersistentVariable("PersistentVariablesTest/myVar", "nothing here yet"));
建议为变量键添加脚本名前缀(如 PersistentVariablesTest/),避免与其他脚本冲突。
输入对话框与消息框
脚本可以直接调用 Qt 风格的内置对话框,无需自建 UI。官方示例(docs/scripting/examples/input-dialogs.qml):
function customActionInvoked(identifier) {
switch (identifier) {
case "inputDialogGetItem":
var result = script.inputDialogGetItem(
"combo box", "Please select an item", ["Item 1", "Item 2", "Item 3"]);
script.log(result);
break;
case "questionMessageBox":
// 第 4 个参数是 QMessageBox::StandardButton 位掩码
// 0x01000000 = Apply,0x02000000 = Help
var result = script.questionMessageBox(
"The text I want to show", "Some optional title", 0x01000000|0x02000000, 0x02000000);
script.log(result);
break;
}
}
对应的 C++ 实现(src/services/scriptingservice.h)还包含 informationMessageBox、getOpenFileName、getSaveFileName、inputDialogGetText、inputDialogGetMultiLineText、textDiffDialog 等,覆盖绝大多数交互场景。
自定义语法高亮
脚本甚至可以接管 Markdown 编辑器的语法高亮。官方示例(docs/scripting/examples/custom-highlighting.qml)展示了两条路径:
静态规则——用 addHighlightingRule 定义固定模式:
function init() {
// 红色背景 + 白色加粗的 TODO
script.addHighlightingRule("TODO", "TODO", -1, 0, 0, {
"foregroundColor": "#ffffff",
"backgroundColor": "#cc0000",
"bold": true
});
// 绿色斜体的 DONE
script.addHighlightingRule("DONE", "DONE", -1, 0, 0, {
"foregroundColor": "#22aa22",
"italic": true
});
}
动态钩子——用 highlightingHook(text, previousBlockState) 逐块返回高亮区间数组,支持更复杂的上下文感知逻辑(如日期格式、#tag、FIXME 等关键词的正则匹配),示例中给出了完整的实现。
从源码看,静态规则由 addHighlightingRule 收集到 _highlightingRules 向量(见 src/services/scriptingservice.h),供 QOwnNotesMarkdownHighlighter 消费;而 highlightingHook 是否启用会被缓存为布尔标记(scriptingservice.cpp),当没有任何脚本定义该钩子时跳过逐块 QML 调用,避免性能损耗。
自动补全与标签联动
脚本可以通过 autocompletionHook() 向编辑器的自动补全列表注入候选项。官方示例(docs/scripting/examples/autocompletion.qml)实现了一个"输入 @ 自动补全标签名"的功能:
function autocompletionHook() {
// 获取当前词以及词前的非单词字符,以便捕获 "@"
var word = script.noteTextEditCurrentWord(true);
if (!word.startsWith("@")) {
return [];
}
// 去掉 "@" 后按子串模糊搜索标签
var tags = script.searchTagsByName(word.substr(1));
return tags;
}
标签机制同样支持钩子化:如果希望让笔记正文中的 @tag 与 QOwnNotes 标签体系联动,可参考 docs/scripting/examples/note-tagging.qml 中的 noteTaggingHook(note, action, tagName, newTagName) 实现——action 取值 add / remove / rename / list,脚本返回新的笔记文本(或标签名列表)来完成增删改查。
深入引擎:脚本是如何被加载执行的
将以上机制串起来的核心是 ScriptingService(src/services/scriptingservice.cpp)。它的工作流程可以概括为:
- 创建引擎:构造
QQmlEngine,注入script、mainWindow上下文对象,注册QOwnNotesTypes模块中的Note、Tag、NoteSubFolder、Script类型; - 加载组件:
initComponents()从数据库fetchAll(true)取出所有已启用的脚本,逐个调用initComponent()——用QQmlComponent加载脚本文件的本地 URL、创建 QML 对象、记录优先级键、注入scriptDirPath属性、注册设置变量、最后调用init()(见 scriptingservice.cpp); - 挂接钩子:根据脚本对象中实际存在的方法建立信号槽连接或运行时元方法调用;
- 响应重载:
reloadEngine()清理旧组件并重新初始化,且带防重入保护(_isReloadingEngine/_isInitializingComponents),脚本自身调用script.reloadScriptingEngine()时会延迟 500ms 在后台重载,避免应用崩溃(见 scriptingservice.cpp)。
此外,脚本钩子的执行耗时会被记录:调试日志开启时全部记录,否则仅当单次执行超过阈值(默认 500ms,可通过 Debug/scriptProfilingThreshold 配置)时以警告输出,方便定位性能瓶颈(见 scriptingservice.cpp)。
推荐的学习路径
- 通读示例:官方在 docs/scripting/examples 目录下维护了大量可直接运行的示例脚本,涵盖媒体插入、URL 标题抓取、会议笔记生成、日记条目、Zettelkasten、WebSocket 客户端/服务端、AI 自动补全、自定义 OpenAI 后端等丰富场景,是快速上手的捷径;
- 从 Hello World 起步:先跑通本文开头的最小脚本,熟悉添加与日志流程;
- 逐步叠加能力:按"自定义动作 → 设置变量 → 钩子 → 高亮 → 自动补全"的顺序渐进实现;
- 源码对照:遇到 API 疑问时,直接查阅 src/services/scriptingservice.h 中的
Q_INVOKABLE方法清单(这些方法即脚本可调用的script.*接口),以及 src/api/noteapi.h 中Note对象的属性与方法; - 分发脚本:如果要向社区贡献脚本,可遵循脚本仓库的规范提交,用户即可通过 脚本仓库 一键安装与更新。