QOwnNotes 脚本开发实战指南:基于 QML 的插件系统从入门到进阶
QOwnNotes 脚本开发实战指南:基于 QML 的插件系统从入门到进阶
QOwnNotes 内置了一套基于 Qt QML 的脚本系统,用户可以用 JavaScript 编写扩展,在纯文本 Markdown 笔记工作流中注入自动化能力——从"笔记保存时执行命令""粘贴剪贴板 HTML 时自定义转换",到"用 @ 标签实现自定义标签体系""接入 OpenAI 兼容的本地大模型"等。本文以官方脚本文档为主线,结合仓库源码与示例脚本,系统讲解脚本的编写、加载、Hook 事件、可调用的 API 对象与方法,帮助你从零开始写出第一个可运行的 QOwnNotes 脚本,并进阶到自定义操作、脚本设置面板与源码级原理理解。
一、脚本是什么:JavaScript + Qt QML 文件
QOwnNotes 的脚本本质上是写在 Qt QML 文件中的 JavaScript(QML 全称 Qt Modeling Language,是 Qt 框架的声明式 UI 语言,同时天然支持嵌入 JavaScript 逻辑)。脚本文件以 .qml 为扩展名,通过 import 引入 Qt 基础模块与 QOwnNotes 自定义类型,即可被 QOwnNotes 的脚本引擎加载执行。
下面是最小的"Hello World"脚本(也是官方文档给出的标准骨架):
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 核心模块,提供QtObject、Timer、Qt全局对象等基础能力;import QOwnNotesTypes 1.0:引入 QOwnNotes 自定义类型,例如Script、NoteApi、TagApi、NoteSubFolderApi、MainWindow等,这些类型在 src/api 与 src/services 中由 C++ 注册进 QML 引擎;Script { ... }:脚本根对象。QOwnNotes 在加载脚本时实例化该对象,并查找其中定义的特殊函数作为事件入口;function init():脚本引擎初始化时会被自动调用的入口函数,是绝大多数脚本注册自定义动作、设置变量的起点;script.log(...):向 QOwnNotes 的 Log panel(日志面板)输出调试信息,等价于控制台console.log。
仓库中的 docs/scripting/examples/example.qml 提供了一个更完整的模板:它同时演示了 init()、onNoteStored、handleNoteTextFileNameHook、noteToMarkdownHtmlHook、insertMediaHook、insertAttachmentHook、insertingFromMimeDataHook 以及一个每 30 秒触发一次的 Timer,是学习全部 Hook 用法的首选参考。
提示:由于脚本主体是 JavaScript,你可以使用 ES6 模板字符串、正则表达式、
Date对象等 JS 特性,与 C++ 暴露出来的 QML 对象无缝混编。
二、把脚本添加进 QOwnNotes
QML 脚本文件可以放在本机任意位置,然后在 QOwnNotes 中通过**脚本设置(Scripting settings)**面板添加:
- 打开菜单 Settings(设置)→ Scripting(脚本);
- 点击
Add script(添加脚本)按钮,选择本地.qml文件;部分版本提供Add local script(添加本地脚本)按钮; - 脚本出现在列表中后即被加载,引擎会立即调用其
init()函数。
除了加载本地文件,脚本设置面板还支持直接从 **Script repository(脚本仓库)**在线安装社区维护的脚本,安装后同样出现在脚本列表中,可随时启用/禁用。
官方提供了一大批开箱即用的示例脚本,位于仓库 docs/scripting/examples,是快速上手的最佳起点。下面是与各类能力对应的代表性示例:
| 能力类别 | 示例脚本 |
|---|---|
| 自定义动作 | custom-actions.qml |
| 自动补全 | autocompletion.qml |
| 自定义标签体系 | note-tagging.qml、note-tagging-by-object.qml |
| 加密扩展 | encryption-keybase.qml、encryption-pgp.qml、encryption-rot13.qml |
| 预览样式定制 | preview-styling.qml、custom-stylesheet.qml |
| 编辑器高亮 | highlighting.qml、custom-highlighting.qml |
| AI 能力接入 | ai-autocompletion.qml、custom-openai-backends.qml |
| 笔记模板 | custom-new-note-headline.qml |
| 外部进程与回调 | callback.qml、execute-command-after-note-update.qml |
| 剪贴板/粘贴增强 | paste-full-image-url.qml、selected-markdown-to-bbcode.qml |
| WebSocket 远程控制 | websocket-server.qml、websocket-client.qml |
三、调试利器:script.log() 与日志面板
script.log(text) 是脚本开发中最常用的调试手段。它对应 src/services/scriptingservice.h 中声明的 Q_INVOKABLE void log(QString text),会把文本写入 QOwnNotes 的 Log panel(日志面板)。
打开日志面板的方式:菜单 Window(窗口)→ Panels(面板)→ Log(日志)。所有脚本的日志输出都会汇总到这里,包括脚本引擎自身的报错信息,是排查"脚本没生效""变量取值不对"等问题的第一现场。
示例:
function init() {
script.log("脚本初始化完成");
script.log(script.currentNote().name); // 输出当前笔记名
}
四、Hook 机制:脚本如何被 QOwnNotes 调用
Hook(钩子)是脚本与 QOwnNotes 之间的双向桥梁:QOwnNotes 在特定事件发生时,会去调用脚本中定义了同名函数的入口,把笔记对象、文本等上下文作为参数传入,并接收脚本的返回值。完整说明见 webpage/src/scripting/hooks.md。下表汇总了全部内置 Hook 及其触发时机:
| Hook | 触发时机 | 关键参数 |
|---|---|---|
onNoteStored |
笔记写入磁盘后 | note(NoteApi) |
noteOpenedHook |
笔记打开后 | note |
noteDoubleClickedHook |
笔记被双击后 | note |
insertMediaHook |
媒体文件插入当前笔记时,返回非空字符串的脚本优先生效 | fileName, markdownText |
insertAttachmentHook |
附件插入当前笔记时,多脚本时首个返回非空者生效 | fileName, markdownText |
fetchUrlTitleHook |
链接对话框中抓取网页标题前,返回空串则交还 QOwnNotes 抓取 | url |
insertingFromMimeDataHook |
通过 Ctrl + Shift + V 粘贴 HTML 或媒体文件时 |
text, html |
handleNoteTextFileNameHook |
笔记存盘时(需开启"允许笔记文件名与标题不同"设置),可修改文件名,返回空串表示不修改 | note |
handleNoteNameHook |
确定笔记显示名称时(主要在列表展示用),返回空串表示不修改 | note |
handleNewNoteHeadlineHook |
创建新笔记前,可做笔记模板;注意需自行保证标题唯一 | headline |
preNoteToMarkdownHtmlHook |
Markdown 转 HTML 之前,可改写传给转换器的 Markdown(如渲染 LaTeX、mermaid),不影响笔记本身 | note, markdown, forExport |
noteToMarkdownHtmlHook |
Markdown 转 HTML 之后,可改写最终 HTML(如预览注入自定义样式) | note, html, forExport |
encryptionHook |
需要加密/解密文本时 | text, password, decrypt |
noteTaggingHook |
自定义笔记标签机制,action 为 "add"/"remove"/"rename"/"list" |
note, action, tagName, newTagName |
noteTaggingByObjectHook |
同 noteTaggingHook,但以 TagApi 对象代替标签名,list 返回标签 id 列表 |
note, action, tag, newTagName |
autocompletionHook |
编辑器触发自动补全(如 Ctrl + Space)时,返回补全候选字符串列表 |
无 |
websocketRawDataHook |
Web Companion 浏览器扩展通过右键菜单发送数据时 | requestType, pageUrl, pageTitle, rawData, screenshotDataUrl |
onDetachedProcessCallback |
startDetachedProcess() 启动的脚本线程执行完毕时 |
callbackIdentifier, resultSet, cmd, thread |
windowStateChangedHook |
窗口状态改变后,取值 "minimized"/"maximized"/"fullscreen"/"active"/"nostate" |
windowState |
layoutSwitchedHook |
布局切换时 | oldUuid, newUuid |
openAiBackendsHook |
OpenAI 服务配置重载时,可返回自定义后端配置列表 | 无 |
highlightingHook |
语法高亮时对每个可见文本块调用(调用频繁,务必保持实现轻量) | text, previousBlockState |
4.1 自定义标签体系:noteTaggingHook 实战
noteTaggingHook 允许脚本接管笔记标签的增删改查逻辑。以 docs/scripting/examples/note-tagging.qml 为例,它把笔记正文中 @tag1、@tag2 形式的文本当作标签:
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":
noteText = noteText.replace(tagRegExp, "");
return noteText;
case "rename":
noteText = noteText.replace(tagRegExp, "@" + newTagName);
return noteText;
case "list":
var re = new RegExp("\\B@([^\\s,]+)", "gi"), result, tagNameList = [];
while ((result = re.exec(noteText)) !== null) {
if (tagNameList.indexOf(result[1]) == -1) {
tagNameList.push(result[1]);
}
}
return tagNameList; // 返回标签名列表
}
return "";
}
启用该 Hook 后,QOwnNotes 界面上的标签树、批量打标签、批量移除、拖拽移动标签等操作都会经由该函数处理。官方文档特别提醒:list 动作必须在每次重载笔记目录或标签树时对每个笔记执行,务必保持其高性能;若想绕过"标签必须挂在标签树根节点"的限制,可以使用 noteTaggingByObjectHook 配合 TagApi 对象操作整个标签树(参考 note-tagging-by-object.qml)。
4.2 接入本地大模型:openAiBackendsHook
openAiBackendsHook 在 OpenAI 服务配置重载时被调用(脚本引擎重载也会触发),用来注册自定义的 OpenAI API 兼容后端,例如自建 LLM、ChatGPT、Claude 或 Ollama 等。返回值为后端配置对象数组:
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"],
},
];
}
配合 docs/scripting/examples/custom-openai-backends.qml 与 variables.qml 中介绍的"脚本设置变量"机制,可以把 baseUrl、apiKey 等存入脚本设置,实现可配置的后端管理。脚本侧还可以通过 script.aiComplete(prompt)(见 scriptingservice.h)直接对当前选中的 AI 模型发起补全请求,参考 ai-autocompletion.qml。
4.3 动态语法高亮:highlightingHook 与 addHighlightingRule
编辑器高亮有两种脚本化途径:
- 静态规则
script.addHighlightingRule(pattern, shouldContain, state, capturingGroup, maskedGroup):为正则模式指定一个高亮状态,适合固定语法;重载形式可追加formatStyle参数(QVariantMap,支持foregroundColor、backgroundColor、bold、italic、underline、fontSize)实现自定义配色; - 动态 Hook
highlightingHook(text, previousBlockState):对每个可见文本块逐块调用,返回高亮区间数组,可实现上下文感知的复杂高亮。
highlightingHook 的返回区间对象支持 start、length、state、foregroundColor、backgroundColor、bold、italic、underline、fontSize 等字段。示例——把所有 FIXME 标红加粗下划线:
function highlightingHook(text, previousBlockState) {
var highlights = [];
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;
}
由于该 Hook 在每次按键时都会对所有可见文本块执行,官方文档明确警告必须保持实现极简;纯静态的高亮应优先使用 addHighlightingRule(详见 highlighting.qml、custom-highlighting.qml)。
五、脚本可用的对象与 API
QOwnNotes 通过 QML 类型系统把 C++ 类暴露给脚本,完整定义见 webpage/src/scripting/classes.md。核心对象如下。
5.1 NoteApi:笔记对象
NoteApi 封装了一条笔记的全部信息,其 C++ 定义见 src/api/noteapi.h,主要属性与方法:
class NoteApi {
Q_PROPERTY(int id)
Q_PROPERTY(QString name)
Q_PROPERTY(QString fileName)
Q_PROPERTY(QString fullNoteFilePath)
Q_PROPERTY(QString fullNoteFileDirPath)
Q_PROPERTY(QString relativeNoteFileDirPath)
Q_PROPERTY(int noteSubFolderId)
Q_PROPERTY(QString noteText)
Q_PROPERTY(QString decryptedNoteText)
Q_PROPERTY(bool hasDirtyData)
Q_PROPERTY(QQmlListProperty<TagApi> tags)
Q_PROPERTY(QDateTime fileCreated)
Q_PROPERTY(QDateTime fileLastModified)
Q_INVOKABLE QStringList tagNames()
Q_INVOKABLE bool addTag(QString tagName)
Q_INVOKABLE bool removeTag(QString tagName)
Q_INVOKABLE bool renameNoteFile(QString newName)
Q_INVOKABLE QString toMarkdownHtml(bool forExport = true)
Q_INVOKABLE QString getFileURLFromFileName(QString localFileName)
Q_INVOKABLE bool allowDifferentFileName()
Q_INVOKABLE QString getNoteUrlForLinkingToNoteId(int noteId)
};
fileCreated 与 fileLastModified 是 JavaScript 原生 Date 对象,可直接用 getFullYear()、toISOString() 等方法处理,或用 Qt.formatDateTime 格式化。示例:
script.log(note.fileCreated.toISOString());
script.log(note.fileLastModified.getFullYear());
// 将笔记重命名为 "new name.md"
note.renameNoteFile("new name");
// 检查是否允许笔记文件名与标题不同
script.log(note.allowDifferentFileName());
5.2 NoteSubFolderApi:笔记子文件夹
class NoteSubFolderApi {
Q_PROPERTY(int id)
Q_PROPERTY(QString name)
Q_PROPERTY(QQmlListProperty<NoteApi> notes)
Q_INVOKABLE static NoteSubFolderApi *fetchNoteSubFolderById(int id);
Q_INVOKABLE static NoteSubFolderApi *activeNoteSubFolder();
Q_INVOKABLE static QList<QObject*> fetchNoteSubFoldersByParentId(int parentId);
Q_INVOKABLE QString relativePath();
Q_INVOKABLE QString fullPath();
};
注意:NoteSubFolderApi 是静态方法型 API,需先在脚本里通过 Qt.createQmlObject 创建空对象再调用:
var noteSubFolderQmlObj = Qt.createQmlObject(
"import QOwnNotesTypes 1.0; NoteSubFolder{}", mainWindow, "noteSubFolder",
);
// 打印当前激活子文件夹的完整路径与相对路径
var noteSubFolder = noteSubFolderQmlObj.activeNoteSubFolder();
script.log(noteSubFolder.fullPath());
script.log(noteSubFolder.relativePath());
// 遍历子文件夹内的笔记
for (var idx in noteSubFolder.notes) {
var note = noteSubFolder.notes[idx];
}
5.3 TagApi:标签对象
class TagApi {
Q_PROPERTY(int id)
Q_PROPERTY(QString name)
Q_PROPERTY(int parentId)
Q_PROPERTY(QQmlListProperty<NoteApi> notes)
Q_INVOKABLE TagApi fetchByName(const QString &name, int parentId = 0)
Q_INVOKABLE QStringList getParentTagNames()
};
获取标签的推荐方式是通过 script.getTagByNameBreadcrumbList() 按"面包屑路径"查找(自动创建缺失标签):
// 获取标签 "home" 及其下所有笔记
var tag = script.getTagByNameBreadcrumbList(["home"]);
var notes = tag.notes;
for (var idx in notes) {
script.log(notes[idx].name);
}
5.4 MainWindow:主窗口控制
class MainWindow {
Q_INVOKABLE void reloadTagTree();
Q_INVOKABLE void reloadNoteSubFolderTree();
Q_INVOKABLE void buildNotesIndexAndLoadNoteDirectoryList(
bool forceBuild = false, bool forceLoad = false);
Q_INVOKABLE void focusNoteTextEdit();
Q_INVOKABLE bool createNewNoteSubFolder(QString folderName = "");
Q_INVOKABLE void insertHtmlAsMarkdownIntoCurrentNote(QString html);
Q_INVOKABLE void reloadCurrentNoteByNoteId();
Q_INVOKABLE QStringList getLayoutUuidList();
Q_INVOKABLE QString getLayoutUuid(const QString &layoutName);
Q_INVOKABLE void setCurrentLayout(const QString &uuid);
Q_INVOKABLE bool removeNoteTab(int index);
Q_INVOKABLE QList<int> getNoteTabNoteIdList();
Q_INVOKABLE bool jumpToTag(int tagId);
};
典型用法(参考 custom-actions.qml):
// 强制重载笔记列表
mainWindow.buildNotesIndexAndLoadNoteDirectoryList(true, true);
// 在标签树中跳转到标签 "test"
var tag = script.getTagByNameBreadcrumbList(["test"]);
mainWindow.jumpToTag(tag.id);
// 获取所有在标签页中打开的笔记 id 并逐个处理
var noteIds = mainWindow.getNoteTabNoteIdList();
noteIds.forEach(function (noteId) {
var note = script.fetchNoteById(noteId);
});
六、常用脚本方法:从进程调用到笔记操作
QOwnNotes 在 ScriptingService(C++ 实现见 src/services/scriptingservice.h)上暴露了大量 Q_INVOKABLE 方法,脚本内通过全局对象 script 调用。完整清单见 webpage/src/scripting/methods-and-objects.md,下面按场景归纳最常用的部分。
6.1 调用外部程序
后台异步调用(不阻塞 UI 线程)——startDetachedProcess:
script.startDetachedProcess("/path/to/my/program", ["my parameter"]);
批量启动 100 个进程并配合 onDetachedProcessCallback 回调统计进度(参考 callback.qml):
for (var i = 0; i < 100; i++) {
var dur = Math.floor(Math.random() * 10) + 1;
script.startDetachedProcess("sleep", [`${dur}s`], "my-callback", i);
}
function onDetachedProcessCallback(callbackIdentifier, resultSet, cmd, thread) {
if (callbackIdentifier == "my-callback") {
// thread[1] 是该标识符剩余的线程数,为 0 表示整批完成
script.log(`#${thread[1]} i[${thread[0]}] t${cmd[1]}`);
}
}
同步调用并等待输出——startSynchronousProcess(适合脚本内直接取用命令结果的场景,例如 encryption-keybase.qml 中调用 keybase 命令):
var result = script.startSynchronousProcess(
"/path/to/my/program",
["my parameter"],
"data", // 写入进程的输入数据(可选)
"/path/to/execute/in", // 工作目录(可选)
);
6.2 操作当前笔记与编辑器
var note = script.currentNote(); // 获取当前笔记对象(NoteApi)
script.noteTextEditWrite("My custom text"); // 在光标处写入文本
var text = script.noteTextEditSelectedText(); // 读取选中文本
script.noteTextEditSelectAll(); // 全选
script.noteTextEditSelectCurrentLine(); // 选中当前行
script.noteTextEditSelectCurrentWord(); // 选中当前词
script.noteTextEditSetSelection(start, end); // 设置选区
script.noteTextEditSetCursorPosition(10); // 光标跳到第 11 个字符
script.noteTextEditSetCursorPosition(-1); // 跳到笔记末尾
script.noteTextEditCurrentWord(true); // 读取当前词(含 @ 等前缀字符)
script.noteTextEditCurrentBlock(); // 读取当前文本块
noteTextEditWrite 与 noteTextEditSelectAll 组合即可整体覆盖当前笔记内容——这正是 custom-actions.qml 中 transformTextRot13 动作的实现方式。
6.3 媒体、附件与网络下载
// 将 URL 下载为字符串
var html = script.downloadUrlToString("https://www.qownnotes.org");
// 下载 URL 到媒体文件夹,返回 Markdown 图片文本
var markdown = script.downloadUrlToMedia(
"http://latex.codecogs.com/gif.latex?\frac{1}{1+sin(x)}",
);
// 把本地图片插入媒体文件夹
var markdown = script.insertMediaFile("/path/to/your/image.png");
// 把本地文件作为附件插入 attachments 文件夹
var markdown = script.insertAttachmentFile("/path/to/your/file.png");
// 重新生成笔记预览
script.regenerateNotePreview();
6.4 笔记与标签查询
script.fetchNoteByFileName("my note.md"); // 按文件名取笔记
script.fetchNoteById(243); // 按 id 取笔记
script.noteExistsByFileName("my note.md", note.id); // 判断笔记是否存在(可忽略自身 id)
script.setCurrentNote(note); // 跳转到指定笔记
script.setCurrentNote(note, true); // 在新标签页打开(未打开时)
script.jumpToNoteSubFolder("a sub folder/sub"); // 跳转笔记子文件夹
// 按正文子串搜索笔记(返回 id 列表,支持忽略重音)
var noteIds = script.fetchNoteIdsByNoteTextPart("mytext");
var accentInsensitive = script.fetchNoteIdsByNoteTextPart("avion", true);
// 按名称搜索标签(同样支持忽略重音)
var tags = script.searchTagsByName("game");
script.tagCurrentNote("favorite"); // 给当前笔记打标签
// 选中笔记
script.log(script.selectedNotesPaths()); // 所有选中笔记的路径
script.log(script.selectedNotesIds()); // 所有选中笔记的 id
6.5 文件、剪贴板与路径工具
script.setClipboardText("text to copy"); // 复制纯文本到剪贴板
script.setClipboardText("<b>html</b>", true); // 以 HTML MIME 数据复制
var clipboardText = script.clipboard(); // 读取剪贴板文本
var clipboardHtml = script.clipboard(true); // 读取剪贴板 HTML
script.fileExists(filePath); // 判断文件存在
var data = script.readFromFile(filePath); // 读取文件文本(默认 UTF-8)
script.writeToFile(filePath, html, true); // 写文件,可自动创建父目录
script.cacheDir("my-script-id"); // 获取系统缓存目录下的脚本子目录
script.clearCacheDir("my-script-id"); // 清空该缓存目录
script.toNativeDirSeparators("c:/winnt/system32"); // 转为平台原生分隔符(Windows 下返回 c:\winnt\system32)
script.fromNativeDirSeparators("c:\\winnt\\system32"); // 反向转换
script.dirSeparator(); // 获取平台分隔符(Windows 下为 "\")
// 读取脚本自身所在目录(需先声明属性)
property string scriptDirPath;
6.6 弹窗与交互
script.informationMessageBox("The text I want to show", "Some optional title");
// 问题弹窗,buttons 为 QMessageBox::StandardButton 的位或组合
var result = script.questionMessageBox(
"The text I want to show", "Some optional title",
0x01000000 | 0x02000000, // Apply | Help
0x02000000, // 默认选中 Help
);
var fileName = script.getOpenFileName("Please select an image", "/home/user/images", "Images (*.png *.xpm *.jpg)");
var outFile = script.getSaveFileName("Please select HTML file to save", "output.html", "HTML (*.html)");
// 三种输入对话框;点 Cancel 或按 Esc 时返回空字符串
var item = script.inputDialogGetItem("combo box", "Please select an item", ["Item 1", "Item 2", "Item 3"]);
var text = script.inputDialogGetText("line edit", "Please enter a name", "current text");
var longText = script.inputDialogGetMultiLineText("multi-line edit", "Please enter a text", "current text");
// 文本差异对话框:text2 可编辑,用于人审 AI 改写结果等场景
var result = script.textDiffDialog("AI Text Tool", "Resulting text", text, aiResult);
七、为脚本配置参数:settingsVariables 设置变量
通过 settingsVariables 属性,脚本可以声明一组在脚本设置面板中展示的配置项,用户无需改代码即可调整行为。需要先在脚本中声明同名 property,再在 settingsVariables 数组中描述每个字段(完整示例见 docs/scripting/examples/variables.qml):
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", // 必须与上面的 property 同名
"name": "I am a line edit",
"description": "Please enter a valid string:",
"type": "string",
"default": "My default value",
},
{
"identifier": "myStringSecret",
"name": "I am a password field",
"type": "string-secret", // 密码输入框
},
{
"identifier": "myBoolean",
"name": "I am a checkbox",
"text": "Check this 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"},
}
];
支持的 type 字段包括:string(单行文本)、string-secret(密码)、boolean(复选框)、text(多行文本)、integer(数字)、file(文件选择)、directory(目录选择)、selection(下拉选项,配合 items 映射)。
如果需要在加载时用代码动态覆盖变量(例如按操作系统设置不同默认值),可以实现 registerSettingsVariables() 函数:
function registerSettingsVariables() {
if (script.platformIsWindows()) {
settingsVariables[3].default = "pandoc.exe"; // Windows 下覆盖默认值
}
}
此外,script.setPersistentVariable(key, value) / script.getPersistentVariable(key, defaultValue) 提供跨脚本共享的持久化存储(键名建议带前缀如 PersistentVariablesTest/myVar,参考 persistent-variables.qml);script.getApplicationSettingsVariable(key) 可读取 QOwnNotes 自身的应用设置项。
八、自定义动作与脚本标签:打造个人工具栏
8.1 registerCustomAction:注册菜单项与按钮
script.registerCustomAction() 可以把脚本功能注册为菜单项、工具栏按钮,甚至在笔记编辑右键菜单中出现,是"把脚本变成日常操作"的核心入口。方法签名(见 scriptingservice.h):
void registerCustomAction(QString identifier, QString menuText,
QString buttonText, // 为空则不显示按钮
QString icon, // 图标文件路径或 freedesktop 主题图标名
bool useInNoteEditContextMenu = false,
bool hideButtonInToolbar = false,
bool useInNoteListContextMenu = false);
随后实现 customActionInvoked(identifier) 处理触发事件。一个完整的自定义动作脚本:
import QtQml 2.0
import QOwnNotesTypes 1.0
Script {
function init() {
script.registerCustomAction("mycustomaction1", "Menu text");
script.registerCustomAction("mycustomaction2", "Menu text", "Button text");
script.registerCustomAction("mycustomaction3", "Menu text", "Button text", "task-new");
script.registerCustomAction("mycustomaction4", "Menu text", "Button text",
"/usr/share/icons/breeze/actions/24/view-calendar-tasks.svg");
}
function customActionInvoked(identifier) {
switch (identifier) {
case "mycustomaction1": script.log("Action 1"); break;
case "mycustomaction2": script.log("Action 2"); break;
case "mycustomaction3": script.log("Action 3"); break;
case "mycustomaction4": script.log("Action 4"); break;
}
}
}
扩展能力与注意事项:
- 自定义动作可在 Shortcuts(快捷键)设置 中绑定本地/全局快捷键;
- freedesktop 主题图标(如
task-new)主要在 Linux 下可用,macOS/Windows 下建议用scriptDirPath拼接脚本自带图标的绝对路径; - 可用命令行参数
--action customAction_<identifier>在应用启动后直接触发某个自定义动作; - 综合示例见 custom-actions.qml:它演示了用 KWrite 打开当前笔记、生成会议笔记模板、ROT13 文本变换、跳转标签等真实用法。
8.2 registerLabel / setLabelText:脚本信息标签
脚本标签(Scripting panel 中的信息卡片)支持纯文本或 HTML,文本可选中、链接可点击,还支持指向笔记、任务、Deck 卡片等的内部链接(URL 处理逻辑见 src/utils/urlhandler.cpp)。需要先在 Window / Panels 菜单中启用 Scripting 面板。
function init() {
script.registerLabel("html-label",
"<strong>Strong</strong> HTML text<br />with three lines<br />" +
"and a <a href='https://www.qownnotes.org'>link to a website</a>.");
script.registerLabel("counter-label");
}
property QtObject timer: Timer {
interval: 1000
repeat: true
running: true
property int count: 0
onTriggered: {
count++;
script.setLabelText("counter-label", "count = " + count);
}
}
完整演示见 scripting-label-demo.qml。
九、界面样式定制与颜色模式
9.1 addStyleSheet:全局样式注入
script.addStyleSheet(stylesheet) 可以把 Qt 样式表(QSS)注入应用,实现全局 UI 定制,例如放大笔记列表字号:
script.addStyleSheet("QTreeWidget#noteTreeWidget {font-size: 30px;}");
控件名可从 *.ui 文件获取(如 src/mainwindow.ui);QWidget {background-color: black; color: white;} 这类基础规则会对几乎所有控件生效。可参考 src/libraries/qdarkstyle/style.qss 了解可定制项。若想给笔记预览注入 CSS,应改用 noteToMarkdownHtmlHook。
9.2 颜色模式控制
getColorModes()、getCurrentColorModeId()、switchToColorMode(idOrName) 三件套让脚本可以管理"颜色模式"(系统/深色等,捆绑了深色模式、图标主题与编辑器配色方案):
// 在内置浅色与深色模式间切换
const isDark = script.getCurrentColorModeId() === "ColorMode-dark";
script.switchToColorMode(isDark ? "ColorMode-light" : "ColorMode-dark");
内置颜色模式 id 为 ColorMode-light 与 ColorMode-dark;自定义模式会生成形如 ColorMode-3f2a9c1e-... 的 id,因此 switchToColorMode 也支持按名称匹配(先查 id 再查名称)。addStyleSheet 注入的样式在切换颜色模式后仍然保留。完整示例见 toggle-color-mode.qml。
十、更多高级主题
- WebSocket 远程控制:
WebSocketServer可让外部客户端远程操控 QOwnNotes,WebSocket可让脚本作为客户端监听/连接套接字,分别见 websocket-server.qml 与 websocket-client.qml。使用前需安装 Qt 的 QML websocket 库(Ubuntu 下为qml-module-qtwebsockets)。 - 日期时间格式化:直接用 QML 引擎内置的
Qt.formatDateTime(date, format)、Qt.formatDate、Qt.formatTime,无需自写格式化函数。常用占位符:yyyy(四位年份)、MM(补零月份)、dd(补零日)、HH/hh(24/12 小时制小时)、mm(分钟)、ss(秒)、AP(AM/PM)。占位符区分大小写且不支持YYYY/DD写法;单引号内的文本不做解析,如"yyyy-MM-dd 'at' HH:mm"。参考 journal-entry.qml。 - 触发菜单动作:
script.triggerMenuAction(objectName)可以程序化触发 QOwnNotes 主菜单动作,动作的objectName可从 src/mainwindow.ui 中按英文菜单标题搜索获得。示例(参考 disable-readonly-mode.qml):
// 切换只读模式
script.triggerMenuAction("actionAllow_note_editing");
// 关闭只读模式(checked 参数为 1 表示仅当状态不同时才触发)
script.triggerMenuAction("actionAllow_note_editing", 1);
- 在脚本中使用加密 Hook:
encryptionHook(text, password, decrypt)允许接入自定义加密方案(Keybase、PGP、ROT13 等),示例见 encryption-keybase.qml、encryption-pgp.qml、encryption-rot13.qml。
十一、源码级原理:脚本引擎如何工作
从 src/services/scriptingservice.h 可以看出脚本引擎的核心设计:
ScriptingService是单例(static ScriptingService *instance()),持有一个QQmlEngine *与QMap<int, ScriptComponent> _scriptComponents,其中ScriptComponent由QQmlComponent *component、QObject *object与Script script组成——每个脚本对应一个独立的 QML 组件实例;- 所有暴露给脚本的方法都以
Q_INVOKABLE声明,QML 侧即可直接调用;从引擎到脚本的事件回调则通过callXxxHook(...)系列方法转发,例如callNoteToMarkdownHtmlHook()、callHandleNoteOpenedHook()、callEncryptionHook()、callAutocompletionHook()、callOpenAiBackendsHook()、callHighlightingHook()等; - Hook 存在性预检:引擎在 C++ 侧用
methodExists()/noteTaggingHookExists()/highlightingHookExists()等方法判断脚本是否实现了某个 Hook,从而决定是否把事件路由给它——这也解释了为什么"只要脚本中定义了noteTaggingHook,标签处理就立即被接管"; - 高亮规则由
getHighlightingRules()收集后交给 src/helpers/qownnotesmarkdownhighlighter.cpp 的语法高亮器统一调度; - 自定义动作通过信号槽完成闭环:
onCustomActionInvoked(identifier)槽收到主界面转发来的触发信号后,再分发到对应脚本对象的customActionInvoked方法; registerSettingsVariables()返回的变量列表保存在QHash<int, QList<QVariant>> _settingsVariables中,按脚本 id 索引,脚本设置面板据此渲染表单控件。
笔记对象 NoteApi 继承自实体类 Note(见 src/entities/note.h),因此脚本拿到的 note 既是数据载体也具备 renameNoteFile()、toMarkdownHtml() 等操作能力。这条"实体即 API"的设计,使得脚本能直接操纵 QOwnNotes 的核心数据模型。
十二、快速上手路线图
- 跑通最小脚本:新建
hello.qml,写入开头的最小骨架,在脚本设置中添加并观察日志面板输出; - 读示例:对照 docs/scripting/examples 中的 example.qml 和 custom-actions.qml,理解
init与各 Hook 的配合方式; - 接入用户配置:按 variables.qml 声明
settingsVariables,把脚本参数化; - 注册自定义动作:用
registerCustomAction+customActionInvoked把常用功能固化为菜单项/按钮,并在 Shortcuts 中绑定快捷键; - 查阅完整 API:方法全集见 webpage/src/scripting/methods-and-objects.md,对象属性见 webpage/src/scripting/classes.md,Hook 完整签详见 webpage/src/scripting/hooks.md。
说明:本文所有脚本能力均以当前仓库(QOwnNotes)代码为准;脚本运行效果受 Qt 版本与平台影响,跨平台脚本建议用
platformIsLinux()/platformIsOSX()/platformIsWindows()做分支判断。
