QOwnNotes 脚本开发实战:基于 QML/JavaScript 的扩展系统从入门到进阶
QOwnNotes 脚本开发实战:基于 QML/JavaScript 的扩展系统从入门到进阶
QOwnNotes 内置了一套以 QML + JavaScript 为核心的脚本引擎,允许用户在不改动 C++ 主程序的前提下,通过编写 .qml 脚本文件来扩展编辑器、预览、笔记存储、标签、加密、自动补全等几乎每一个核心环节。本文以官方脚本入门文档为主线,结合仓库内的钩子(Hooks)文档、方法对象文档与 50 余个官方示例脚本,系统讲解脚本的编写、加载、调试、生命周期钩子与常用 API,帮助你从零开始打造属于自己的 QOwnNotes 扩展。
脚本的本质:Qt QML 文件中的 JavaScript
QOwnNotes 的脚本主要就是写在 Qt QML 文件 里的 JavaScript。QML 是 Qt 的声明式语言,脚本通过 import 引入 QML 模块和 QOwnNotes 暴露的扩展类型,然后在对象内部定义 QML/JavaScript 支持的函数、属性和对象。
最小的脚本只需要引入两个模块、声明一个 Script 对象,并定义一个 init() 入口函数:
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 基础模块,提供Timer、QtObject等基础类型;import QOwnNotesTypes 1.0:引入 QOwnNotes 暴露给脚本的扩展类型(如Script、NoteApi、TagApi、NoteSubFolderApi等);init():脚本引擎初始化时被调用的入口函数,等价于 C++ 侧脚本的"构造函数"。
从源码实现看,QML 组件由 scriptingservice.cpp 中的 initComponent() 加载:它用 QQmlComponent 加载脚本文件、component->create() 创建对象,随后设置 scriptDirPath 属性、注册脚本设置变量,并在对象存在 init() 方法时通过 QMetaObject::invokeMethod(object, "init") 调用它。若脚本加载出错,错误信息会写入日志,无效脚本甚至会被自动移除。
对象不一定非得是 Script。官方示例 example.qml 就使用了 QtObject,一样可以定义钩子函数和 Timer 定时器,说明脚本引擎的核心是"对象 + 可被调用的方法",而非固定的根类型。
安装与加载脚本:本地添加与脚本仓库
QML 脚本文件可以放置在任意位置,然后在 QOwnNotes 的 Scripting 设置(脚本设置) 中添加。设置界面中提供了 Add script(添加脚本)与 Add local script(添加本地脚本)按钮,用于指向本地磁盘上的 .qml 文件。
除了本地文件,你还可以在脚本设置中直接从 脚本仓库(Script repository) 在线安装社区维护的脚本。仓库中每个脚本由 ScriptInfoJson 描述(见 script.h),包含 name、identifier、version、minAppVersion、script、description、platformList 等元数据;platformSupported 与 appVersionSupported 会用于判断脚本是否适配当前平台与应用版本。若脚本由仓库安装,QOwnNotes 会依据 identifier 管理其本地目录、更新与变更日志。
社区还提供了一款用于按关键字检索脚本的 Web 应用(QOwnNoteScriptsList),可据此快速找到感兴趣的现成脚本。对于仓库脚本的任何问题、疑问或功能请求,应在脚本仓库的 issue 页面提交;若想把自己写的脚本提交到仓库,则需遵循仓库维护者给出的提交流程说明。
提示:调试脚本最简单的方式是使用
script.log(),输出会出现在 Log 面板(日志面板) 中,该面板可在 窗口 / 面板(Window / Panels) 菜单中开启。
脚本生命周期:从加载到卸载
脚本生命周期由 ScriptingService 管理(见 scriptingservice.h 的 ScriptComponent 结构)。每个脚本对象注册进 _scriptComponents 时,会按 (priority << 10) + scriptId 计算一个键,用来决定多个脚本响应同一钩子时的先后顺序——也就是说,脚本的 priority(优先级)属性直接参与钩子调度,这在多个脚本同时实现 noteToMarkdownHtmlHook 等钩子时非常关键。
脚本中还可以声明 property string scriptDirPath;,脚本加载时该属性会被自动设置为脚本所在目录的路径(以原生目录分隔符形式),便于脚本加载同目录下的图标、资源或配置文件。
常用调试方法:script.log 与日志面板
script.log(text) 是脚本开发中使用频率最高的方法,它把文本写入日志部件(即 Log 面板)。结合 example.qml 可以看到典型的调试习惯——在 init()、各钩子函数、定时器回调中输出上下文信息:
function onNoteStored(note) {
script.log("fileName was stored!");
script.log(note.id);
script.log(note.name);
script.log(note.fileName);
}
日志面板不仅显示 script.log 的输出,也会显示脚本加载、钩子调用耗时等引擎侧信息,是排查脚本问题的一线工具。
事件钩子(Hooks):在生命周期节点插入你的逻辑
QOwnNotes 脚本引擎最大的价值在于钩子(Hooks):在笔记存储、打开、预览渲染、媒体插入、标签维护、加密、自动补全等节点,只要脚本定义了对应名称的函数,引擎就会自动调用。完整钩子清单见 hooks.md,下面按功能域分组介绍。
笔记打开与存储
onNoteStored(note):笔记写入磁盘后触发。官方文档特别提醒:不要在此钩子里修改已存储的笔记,因为你很可能正在同时手工编辑它,强行改动会造成混乱。noteOpenedHook(note):笔记打开完成后触发。noteDoubleClickedHook(note):笔记被双击后触发(参考 external-note-open.qml,可用来实现双击用外部程序打开笔记)。
笔记文件与名称
handleNoteTextFileNameHook(note):仅在设置中开启"允许笔记文件名与标题不同"时触发,返回笔记的新文件名;返回空字符串表示不改名。注意重复文件名需要自己处理(参考 use-tag-names-in-filename.qml,可将标签名拼进文件名)。handleNoteNameHook(note):在确定笔记显示名称时触发,返回空字符串表示不修改。笔记名称主要用于列表展示;文档建议当"使用文件名作为笔记名"设置生效时不要使用此钩子。handleNewNoteHeadlineHook(headline):在创建新笔记前触发,可用于笔记模板;若返回的标题不唯一,新笔记不会被创建,而只是在笔记列表中被找到(参考 custom-new-note-headline.qml)。
预览与导出(Markdown ↔ HTML)
preNoteToMarkdownHtmlHook(note, markdown, forExport):在 Markdown 转 HTML 之前触发,可改写传给转换器的 Markdown;典型用途是在多个脚本中把 LaTeX 数学公式或 mermaid 图渲染为预览用的图形表示。此过程不会改动笔记本身。noteToMarkdownHtmlHook(note, html, forExport):在 Markdown 转 HTML 之后触发,可改写最终 HTML(例如给预览注入自定义页头和分隔线,见 preview-styling.qml)。forExport为true表示 HTML 用于导出而非预览。insertMediaHook(fileName, markdownText):媒体文件插入当前笔记时触发,返回新的 Markdown 文本;多个脚本都定义时,第一个返回非空字符串的脚本生效。insertAttachmentHook(fileName, markdownText):附件插入当前笔记时触发,语义同上。insertingFromMimeDataHook(text, html):使用Ctrl + Shift + V向笔记粘贴 HTML 或媒体文件时触发,返回应替换QMimeData内容的字符串(参考 insert-headline-with-link-from-github-url.qml)。fetchUrlTitleHook(url):链接对话框中 QOwnNotes 抓取网页标题之前触发,返回标题;返回空字符串则仍由 QOwnNotes 抓取。
加密
encryptionHook(text, password, decrypt):文本需要加解密时触发。官方提供了三种自定义加密示例:encryption-keybase.qml、encryption-pgp.qml、encryption-rot13.qml,可据此接入 PGP、Keybase 等外部加密工具。
自定义标签体系
noteTaggingHook(note, action, tagName, newTagName):实现自己的标签机制,例如在笔记文本中使用@tag1、@tag2这类特殊文本。action取值"add"、"remove"、"rename"或"list",返回笔记文本(前三种)或标签名列表(list)。- 一旦某个脚本激活并实现了
noteTaggingHook,笔记标签处理就全部交给该函数; - 从笔记导入
@tag类标签、在标签树移动标签、批量加/删标签、重命名标签等界面操作都会被转发为一系列add/remove动作; - 警告:
list动作必须在每次重载笔记文件夹或标签树时对每一条笔记执行,一定要写得足够快。
- 一旦某个脚本激活并实现了
noteTaggingByObjectHook(note, action, tag, newTagName):与noteTaggingHook类似,但参数是TagApi对象而非标签名,list动作返回的是标签 id 列表,因此你可以使用整个标签树而不是根级标签列表,但需要自行创建缺失的标签(参考 note-tagging-by-object.qml)。
编辑器与自动补全
autocompletionHook():在笔记中触发自动补全(如按下Ctrl + Space)时返回要加入补全列表的字符串列表(参考 autocompletion.qml)。highlightingHook(text, previousBlockState):语法高亮期间对编辑器中的每个文本块调用,允许做上下文感知的动态高亮,返回高亮范围对象数组(含start、length、state、foregroundColor、backgroundColor、bold、italic、underline、fontSize)。官方示例用正则把所有FIXME标红加粗下划线。- 警告:该钩子调用非常频繁(每次击键、每个可见文本块都会触发),务必保持实现轻量;静态正则高亮应优先使用
addHighlightingRule。
- 警告:该钩子调用非常频繁(每次击键、每个可见文本块都会触发),务必保持实现轻量;静态正则高亮应优先使用
外部进程与状态变化
onDetachedProcessCallback(callbackIdentifier, resultSet, cmd, thread):startDetachedProcess()启动的后台进程执行完毕后触发;cmd为<a href="https://link.gitcode.com/i/07110b834de4ea8b16f288382c91bd24" target="_blank">可执行路径, 参数, 退出码],thread[1]可用来判断某标识符的一批进程是否全部结束(参考 [callback.qml)。windowStateChangedHook(windowState):窗口状态变化后触发,取值可为"minimized"、"maximized"、"fullscreen"、"active"或"nostate"(参考 window-state-changed.qml)。layoutSwitchedHook(oldUuid, newUuid):界面布局切换时触发(参考 layouts.qml)。
浏览器扩展与 AI 后端
websocketRawDataHook(对应脚本函数callHandleWebsocketRawDataHook(requestType, pageUrl, pageTitle, rawData, screenshotDataUrl)):QOwnNotes Web Companion 浏览器扩展通过右键菜单发送数据时触发;requestType可为"page"或"selection",返回true表示数据已被钩子处理。openAiBackendsHook():OpenAI 服务配置重载(包括脚本引擎重载)时触发,可返回自定义 OpenAI 兼容后端配置(如自建 LLM、Claude、Ollama),每个对象含id、name、baseUrl、apiKey、models字段。配合settingsVariables可以把后端配置存入脚本设置(参考 custom-openai-backends.qml)。
暴露的对象与方法:script 对象与核心类
脚本引擎把大量功能挂载在 script 对象上,并把若干实体类直接暴露给 QML。完整清单见 methods-and-objects.md 与 classes.md。
script 对象高频方法
进程与网络
startDetachedProcess(executablePath, parameters, callbackIdentifier, callbackParameter, processData, workingDirectory):后台启动外部程序。批量启动 100 个进程并配合回调的例子:
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") {
script.log(`#${thread[1]} i[${thread[0]}] t${cmd[1]}`);
}
}
startSynchronousProcess(executablePath, parameters, data, workingDirectory):同步启动并等待输出(参考 encryption-keybase.qml)。downloadUrlToString(url):把 URL 下载为字符串;downloadUrlToMedia(url, returnUrlOnly):把 URL 下载到 media 文件夹并返回 Markdown 图片文本(可用于粘贴 LaTeX 公式图片,见 paste-latex-image.qml)。
笔记与文件夹
currentNote():返回当前NoteApi对象。currentNoteFolderPath():返回当前笔记文件夹路径。fetchNoteById(id)/fetchNoteByFileName(fileName, noteSubFolderId):按 id 或文件名取笔记。noteExistsByFileName(fileName, ignoreNoteId, noteSubFolderId):检查笔记文件是否存在。createNote(text):新建笔记;若关闭了"标题决定文件名"设置,需自行重命名文件:
var note = script.currentNote();
note.renameNoteFile("your-filename");
setCurrentNote(note, asTab):跳转到指定笔记(可开新标签页);jumpToNoteSubFolder(path, separator):跳转笔记子文件夹。selectedNotesPaths()/selectedNotesIds():获取当前选中笔记的路径/id 列表。tagCurrentNote(tagName):给当前笔记打标签;getTagByNameBreadcrumbList(nameList, createMissing):按标签面包屑(如["level1","level2","level3"])获取或创建标签对象;searchTagsByName(name, ignoreAccents):按子串搜索标签。
编辑器操作
noteTextEditWrite(text):在光标处写入文本;noteTextEditSelectedText():读取选中文本;noteTextEditSelectAll()/noteTextEditSelectCurrentLine()/noteTextEditSelectCurrentWord():各类选择操作;noteTextEditSetCursorPosition(position):移动光标(-1表示跳到文末);noteTextEditCurrentWord(withPreviousCharacters)/noteTextEditCurrentBlock():读取当前词/当前块。clipboard(asHtml)/setClipboardText(text, asHtml):读取/写入剪贴板。
文件与设置
fileExists(filePath)、readFromFile(filePath, codec)(默认 UTF-8)、writeToFile(filePath, data, createParentDirs):文件读写。setPersistentVariable(key, value)/getPersistentVariable(key, defaultValue):跨脚本全局持久变量,官方建议 key 使用有意义的前缀(如PersistentVariablesTest/myVar);getApplicationSettingsVariable(key, defaultValue):读取应用设置项。cacheDir(subDir)/clearCacheDir(subDir):在系统默认缓存位置创建/清理脚本缓存目录。toNativeDirSeparators(path)/fromNativeDirSeparators(path)/dirSeparator():路径分隔符与平台之间的转换。
界面交互
informationMessageBox(text, title)、questionMessageBox(text, title, buttons, defaultButton)(按钮取值见 QtQMessageBox::StandardButton)、getOpenFileName(...)、getSaveFileName(...)、inputDialogGetItem(title, label, items, current, editable)、inputDialogGetText(...)、inputDialogGetMultiLineText(...)、textDiffDialog(title, label, text1, text2)(text2为可编辑文本,参考 input-dialogs.qml)。platformIsLinux()/platformIsOSX()/platformIsWindows():平台判断。triggerMenuAction(objectName, checked):触发菜单动作(对象名可在 mainwindow.ui 中按英文菜单标题搜索,如actionAllow_note_editing切换只读模式)。getColorModes()/getCurrentColorModeId()/switchToColorMode(idOrName):管理色彩模式(如深浅色切换);内置模式 id 为ColorMode-light/ColorMode-dark,自定义模式 id 为生成的ColorMode-<uuid>,因此switchToColorMode也接受模式名(参考 toggle-color-mode.qml)。aiComplete(prompt):对当前选中的 AI 模型(如 ChatGPT、Claude、Ollama)执行补全,需要在 AI 工具栏或主菜单中启用 AI 系统(参考 ai-autocompletion.qml)。
暴露的类
NoteApi(笔记),见 classes.md:
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 是 QDateTime,可直接用 JavaScript Date 方法,或用 Qt.formatDateTime 格式化。
NoteSubFolderApi(笔记子文件夹):含 id、name、notes 属性及 fetchNoteSubFolderById(id)、activeNoteSubFolder()、fetchNoteSubFoldersByParentId(parentId)、relativePath()、fullPath() 等静态/实例方法。在 QML 中需先用 Qt.createQmlObject 创建实例再调用。
TagApi(标签):含 id、name、parentId、notes 属性及 fetchByName(name, parentId)、getParentTagNames() 方法;配合 script.getTagByNameBreadcrumbList(["home"]) 可获取标签及其全部笔记。
MainWindow(主窗口):提供 reloadTagTree()、reloadNoteSubFolderTree()、buildNotesIndexAndLoadNoteDirectoryList(forceBuild, forceLoad)、focusNoteTextEdit()、createNewNoteSubFolder(folderName)、insertHtmlAsMarkdownIntoCurrentNote(html)(自动下载远程图片并转换 data:image URL 为本地媒体文件)、reloadCurrentNoteByNoteId()、getLayoutUuidList()、getLayoutUuid(name)、setCurrentLayout(uuid)、removeNoteTab(index)、getNoteTabNoteIdList()、jumpToTag(tagId) 等方法,可在脚本中直接驱动主窗口 UI。
自定义动作:把脚本挂到菜单与工具栏
registerCustomAction() 是让脚本"可被用户触发"的标准方式,完整签名:
void ScriptingService::registerCustomAction(
QString identifier, // 动作标识符
QString menuText, // 菜单显示文本
QString buttonText, // 按钮文本(空则不显示按钮)
QString icon, // 图标文件路径或 freedesktop 主题图标名
bool useInNoteEditContextMenu, // 是否出现在笔记编辑右键菜单(默认 false)
bool hideButtonInToolbar, // 是否隐藏工具栏按钮(默认 false)
bool useInNoteListContextMenu); // 是否出现在笔记列表右键菜单(默认 false)
配合 customActionInvoked(identifier) 回调分发:
function init() {
script.registerCustomAction("openWithKWrite", "Open with KWrite", "KWrite");
script.registerCustomAction("createMeetingNote", "Create meeting note", "Meeting note", "task-new");
script.registerCustomAction("noButtonAction", "No button here");
}
function customActionInvoked(identifier) {
switch (identifier) {
case "openWithKWrite":
// 用外部编辑器打开当前笔记
break;
// ...
}
}
细节与注意事项:
- 自定义动作可以在快捷键设置中分配本地与全局快捷键;
- freedesktop 主题图标大多只在 Linux 可用,macOS/Windows 下建议随脚本携带图标文件,并通过
scriptDirPath属性定位脚本目录; - 可以通过命令行参数
--action customAction_<identifier>在应用启动后触发某个自定义动作(详见 CLI 参数文档)。
脚本设置变量:让脚本可配置
在脚本中声明 property 并在 settingsVariables 数组中注册,用户就能在脚本设置界面中配置这些值。支持的类型包括:string(单行输入)、string-secret(密码字段)、boolean(复选框)、text(多行文本框)、integer(数字)、file(文件选择器)、directory(目录选择器)、selection(下拉选择,通过 items 映射定义选项)。示例如下:
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",
"description": "Please enter a valid string:",
"type": "string",
"default": "My default value",
},
{
"identifier": "myStringSecret",
"name": "I am a password field",
"description": "Please enter a valid string:",
"type": "string-secret",
},
{
"identifier": "myBoolean",
"name": "I am a checkbox",
"description": "Some description",
"text": "Check this checkbox",
"type": "boolean",
"default": true,
},
{
"identifier": "mySelection",
"name": "I am an item selector",
"description": "Please select an item:",
"type": "selection",
"default": "option2",
"items": {"option1": "Text for option 1", "option2": "Text for option 2", "option3": "Text for option 3"},
}
];
若想用代码覆盖(例如按操作系统改默认值),可定义 registerSettingsVariables() 函数在注册时动态调整,比如在 Windows 上把 settingsVariables<a href="https://link.gitcode.com/i/4341f48d1b841f917f6ee8d0df413e5d" target="_blank">3].default 改为 "pandoc.exe"。完整变量示例见 [variables.qml。
编辑器高亮扩展
静态正则高亮用 addHighlightingRule(pattern, shouldContain, state, capturingGroup, maskedGroup) 注入,其中 state 对应语法高亮状态编号(如 BlockQuote 为 18、MaskedSyntax 为 24、InlineCodeBlock 为 23),完整状态表见 methods-and-objects.md:
// 把 "BLOCK: some text" 这样的行高亮为引用块(state 18)
script.addHighlightingRule("^BLOCK: (.+)", "BLOCK:", 18);
// 屏蔽(state 24)一行中 32 个字符之后的内容
script.addHighlightingRule("^.{32}(.+)", "", 24, 1, -1);
更灵活的自定义颜色/样式版本是带 formatStyle 参数的重载,支持 foregroundColor、backgroundColor、bold、italic、underline、fontSize,state 传 -1(NoState)表示只用自定义格式:
function init() {
// "IMPORTANT" 显示为黄底红字加粗
script.addHighlightingRule("IMPORTANT", "IMPORTANT", -1, 0, 0, {
foregroundColor: "#ff0000",
backgroundColor: "#ffff00",
bold: true,
});
// "@username" 提及显示为蓝色下划线
script.addHighlightingRule("@\\w+", "@", -1, 0, 0, {
foregroundColor: "#3366cc",
underline: true,
});
}
更多高亮用法参见 highlighting.qml 与 custom-highlighting.qml。
实战示例:一个完整的自定义动作脚本
综合以上知识点,一个"打开当前笔记到外部编辑器"的完整脚本如下(改自 custom-actions.qml):
import QtQml 2.0
import QOwnNotesTypes 1.0
QtObject {
// 脚本目录路径(脚本加载时自动填充)
property string scriptDirPath;
function init() {
// 注册菜单项与工具栏按钮,图标用文件路径(跨平台更可靠)
script.registerCustomAction(
"openWithExternalEditor",
"Open with external editor",
"Editor",
scriptDirPath + "/editor-icon.svg"
);
}
function customActionInvoked(identifier) {
if (identifier === "openWithExternalEditor") {
var note = script.currentNote();
if (note) {
script.startDetachedProcess("/usr/bin/kate", [note.fullNoteFilePath]);
}
}
}
}
官方示例脚本清单
仓库 docs/scripting/examples 目录提供了 50 余个可直接运行、覆盖各类钩子与 API 的示例脚本,是入门与进阶的最好教材,例如:
结语与进一步阅读
QOwnNotes 脚本系统以 QML + JavaScript 为语言、以 script 对象和生命周期钩子为核心 API,覆盖了笔记存储、预览渲染、标签、加密、高亮、自动补全、外部进程、AI 乃至 WebSocket 远程控制等方方面面。建议按以下路径深入学习:
- 入门:本文 + example.qml +
script.log()日志调试; - 进阶:阅读 hooks.md 掌握全部钩子签名;
- API 参考:methods-and-objects.md 与 classes.md;
- 源码验证:脚本引擎核心实现位于 scriptingservice.cpp 与 script.h,可在其中核对钩子调用顺序、优先级计算与脚本生命周期。
掌握这些接口后,无论是自动化日常笔记流程、接入团队内部工具,还是打造个性化的编辑体验,都可以通过一个轻量的 .qml 文件完成,无需重新编译主程序。