QOwnNotes 脚本开发完全指南:基于 QML 与 JavaScript 的插件体系深入解析
QOwnNotes 脚本开发完全指南:基于 QML 与 JavaScript 的插件体系深入解析
QOwnNotes 是一款以纯文本文件为核心的笔记与待办事项管理工具,支持 Markdown 语法以及 Nextcloud / ownCloud 云同步。它的强大之处在于内置了一套基于 Qt QML 与 JavaScript 的脚本(Scripting)引擎,允许用户用轻量级的 .qml 文件为笔记应用注入自定义动作、自动化流程、编辑器增强乃至全新的业务能力。本篇指南将以官方文档(webpage/src/scripting/README.md 及其法文版 webpage/src/fr/scripting/README.md)为骨架,结合仓库源码与示例脚本,系统讲解脚本的编写方式、加载路径、生命周期、钩子(Hooks)机制、可用 API 对象与实战调试技巧。读完本文,你将能够独立编写、安装并调试自己的 QOwnNotes 脚本,把笔记应用改造成贴合个人工作流的自动化工具。
一、脚本的本质:JavaScript 写成的 Qt QML 文件
官方文档开宗明义:一个 QOwnNotes 脚本主要就是写在 Qt QML 文件里的 JavaScript 代码(Qt QML 是 Qt 的声明式语言框架,JavaScript 是其内建的脚本语言)。
最小的可用脚本只需要三个部分:两个 import 声明、一个 Script 根对象、一个 init() 函数。官方文档给出了如下最小示例:
import QtQml 2.0
import QOwnNotesTypes 1.0
Script {
/**
* 将在脚本引擎初始化时被执行
*/
function init() {
script.log("Hello world!");
}
}
逐行拆解:
import QtQml 2.0:导入 Qt QML 基础模块,提供Timer、QtObject等内置类型;import QOwnNotesTypes 1.0:导入 QOwnNotes 暴露给脚本的自定义类型(如Script、NoteApi、TagApi等,定义于 src/api/ 与 src/entities/);Script { ... }:QOwnNotes 提供的根类型,QML 引擎加载后即为一个脚本组件(ScriptComponent);init():脚本引擎初始化时自动回调的入口函数,是注册自定义动作、设置默认参数的最佳位置。
从源码结构看,脚本的加载与执行由 ScriptingService 负责:它内部持有一个 QQmlEngine * 实例与一组 QMap<int, ScriptComponent> _scriptComponents,其中 ScriptComponent 由 QQmlComponent、QObject 与一个 Script 实体组成(见 src/services/scriptingservice.h),每个启用的脚本在引擎初始化时都会通过 initComponent() 被实例化为一个独立的 QML 组件对象。
用 script.log() 输出日志
文档特别强调:调试脚本时使用 script.log() 命令,日志会写入 日志面板(Log panel),该面板可以在菜单 窗口 / 面板(Window / Panels) 中开启。底层实现对应 ScriptingService::log 这个 Q_INVOKABLE 方法,任何脚本内都能通过 script.log("...") 直接调用。
二、在哪里放置脚本、如何加载脚本
QML 脚本文件可以放在你喜欢的任何位置,无需与笔记目录绑定。文档给出了两种加载途径,均位于 脚本设置(Scripting settings) 界面中:
- 添加本地脚本:点击设置界面中的
添加脚本(Add script)/添加本地脚本(Add local script)按钮,从文件系统中选择你的.qml文件。QOwnNotes 会把脚本登记进内部数据库(脚本实体定义见 src/entities/script.h),包含name、identifier、infoJson、settingsVariablesJson、priority、enabled等字段; - 从脚本仓库安装:在脚本设置界面中可以直接从官方 脚本仓库(Script repository) 安装脚本。仓库中的每个脚本都带有一个
infoJson元数据(版本、最低应用版本、描述、作者、平台支持等信息,对应 ScriptInfoJson),QOwnNotes 会根据minAppVersion与platformList判断当前应用是否满足运行条件。
社区还维护了一个用于检索脚本的 Web 应用,可以直接搜索仓库中的可用脚本。官方文档建议新手先阅读示例脚本以快速上手——仓库中维护了一整套可直接运行的示例,位于 docs/scripting/examples/,涵盖自定义动作、自动补全、加密、标签、WebSocket、AI 补全等五十余个场景。
脚本优先级与启用
从 Script 实体的字段可以看出,每个脚本还带有 priority(优先级)与 enabled(启用开关)属性。当多个脚本定义了同名钩子时,执行顺序会受优先级影响——例如 insertMediaHook、insertAttachmentHook 等文档明确指出“如果多个脚本都定义了该函数,则第一个返回非空字符串的脚本胜出”。
三、钩子(Hooks):让脚本响应应用生命周期事件
钩子是 QOwnNotes 脚本体系的核心机制:你不需要主动“调用” QOwnNotes,而是在脚本里定义特定命名的函数,由 QOwnNotes 在对应事件发生时回调。官方文档(webpage/src/scripting/hooks.md)完整收录了全部钩子签名,下面按功能分组列出核心钩子:
| 钩子函数 | 触发时机 | 关键参数 / 返回值 |
|---|---|---|
onNoteStored(note) |
笔记写入磁盘后 | note:被存储的 NoteApi 对象;注意:不允许修改已存储的笔记 |
noteOpenedHook(note) |
笔记被打开后 | note:被打开的笔记对象 |
noteDoubleClickedHook(note) |
笔记被双击后 | note:被点击的笔记对象 |
insertMediaHook(fileName, markdownText) |
媒体文件插入当前笔记时 | 返回新的 markdown 文本,多脚本时首个非空返回值生效 |
insertAttachmentHook(fileName, markdownText) |
附件文件插入当前笔记时 | 同上,返回新的 markdown 文本 |
fetchUrlTitleHook(url) |
链接对话框抓取网页标题前 | 返回标题字符串;返回空串则交给 QOwnNotes 自行抓取 |
insertingFromMimeDataHook(text, html) |
用 Ctrl + Shift + V 粘贴 HTML 或媒体时 |
返回要插入的替换文本 |
handleNoteTextFileNameHook(note) |
笔记存储到磁盘时(需开启“允许文件名与标题不同”) | 返回修改后的文件名;空串表示不修改 |
handleNoteNameHook(note) |
确定笔记显示名称时 | 返回修改后的显示名称;主要用于列表展示 |
handleNewNoteHeadlineHook(headline) |
创建新笔记之前 | 返回新标题;可用于实现笔记模板,需自行保证标题唯一 |
preNoteToMarkdownHtmlHook(note, markdown, forExport) |
Markdown 转 HTML 之前 | 返回修改后的 markdown;可用于渲染 LaTeX、mermaid 等 |
noteToMarkdownHtmlHook(note, html, forExport) |
Markdown 转 HTML 生成时 | 返回修改后的 HTML;预览与导出都会触发 |
encryptionHook(text, password, decrypt) |
需要加密 / 解密文本时 | 返回加解密后的文本;可用它接入 Keybase、PGP 等外部加密工具 |
noteTaggingHook(note, action, tagName, newTagName) |
标签增删改查时 | action 取值 "add" / "remove" / "rename" / "list";可实现基于 @tag 文本的自定义标签机制 |
noteTaggingByObjectHook(note, action, tag, newTagName) |
同上 | 参数为 TagApi 对象而非标签名,list 动作需返回 tag id 列表,可深度利用整棵标签树 |
autocompletionHook() |
自动补全被触发时(如按下 Ctrl + Space) |
返回要加入补全列表的字符串数组 |
websocketRawDataHook(经 callHandleWebsocketRawDataHook) |
Web Companion 浏览器扩展通过右键菜单发送数据时 | requestType 为 "page" 或 "selection";返回 true 表示已处理 |
onDetachedProcessCallback(callbackIdentifier, resultSet, cmd, thread) |
后台进程线程执行完毕时 | 配合 startDetachedProcess() 使用,thread[1]==0 可判断整批进程是否结束 |
windowStateChangedHook(windowState) |
窗口状态改变后 | 取值 "minimized"、"maximized"、"fullscreen"、"active"、"nostate" |
layoutSwitchedHook(oldUuid, newUuid) |
布局切换时 | 传入新旧布局 UUID |
openAiBackendsHook() |
OpenAI 服务配置重载时(脚本引擎重载也会触发) | 返回自定义 AI 后端配置对象数组(见下文示例) |
highlightingHook(text, previousBlockState) |
编辑器语法高亮期间对每个文本块调用 | 返回高亮区间对象数组,支持动态、上下文感知高亮 |
其中两个钩子尤其值得展开。
noteToMarkdownHtmlHook:深度定制预览与导出
该钩子在 Markdown 转 HTML 后、渲染前被调用,常用于在预览顶部注入自定义头部。官方示例 docs/scripting/examples/example.qml 展示了最直接的用法:
function noteToMarkdownHtmlHook(note, html, forExport) {
script.log("noteToMarkdownHtmlHook was called");
// 在预览顶部插入自定义标题与水平分隔线
return html.replace("body>", "body><h1>Custom preview for note " + note.name + "</h1><hr />");
}
文档同时提醒:预览渲染的 HTML 仅支持 Qt 定义的受支持子集,自定义 CSS 样式需以该子集为上限。
openAiBackendsHook:注册自定义 AI 后端
该钩子在 OpenAI 服务配置重载时被调用,用于注册自定义的 OpenAI API 兼容后端(如自建的 LLM 网关、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"],
},
];
}
文档建议将后端配置(如 apiKey)通过脚本设置变量(settingsVariables)来管理,而不是硬编码在脚本中(详见第五节)。完整参考实现见 docs/scripting/examples/custom-openai-backends.qml。
钩子的源码级证据
所有钩子的调用入口都集中在 ScriptingService 中,例如:
callNoteToMarkdownHtmlHook(note, html, forExport)(scriptingservice.h)负责在 HTML 生成后遍历所有脚本组件调用noteToMarkdownHtmlHook;callHighlightingHook(text, previousBlockState)(scriptingservice.h)配合highlightingHookExists()判断是否有脚本注册了动态高亮钩子;noteTaggingHookExists()(scriptingservice.h)用于检测是否已有脚本接管标签机制——文档明确指出:一旦某个启用的脚本实现了noteTaggingHook,笔记的标签管理就会全部交由该函数处理,包括从笔记文本导入@tag、添加/移除/重命名标签、批量打标签等操作。
文档对 noteTaggingHook 有一个重要警告:list 动作必须在每次笔记文件夹或标签树重载时对每一条笔记执行,因此务必保证 list 实现足够快,否则会影响整个应用在标签重载(reloadTagTree)时的响应。
四、脚本可用的方法与对象:script.* API 速查
脚本中通过全局对象 script 调用 QOwnNotes 暴露的功能方法。官方文档(webpage/src/scripting/methods-and-objects.md)收录了全部方法,以下是按用途分组的核心 API:
4.1 进程与系统操作
// 后台启动外部程序(异步,配合 onDetachedProcessCallback 获取结果)
script.startDetachedProcess("/path/to/my/program", ["my parameter"]);
// 同步启动外部程序并等待返回输出
var result = script.startSynchronousProcess("/path/to/my/program", ["my parameter"], "data", "/path/to/execute/in");
// 平台判断
if (script.platformIsLinux()) { /* ... */ }
if (script.platformIsOSX()) { /* ... */ }
if (script.platformIsWindows()) { /* ... */ }
// 路径分隔符处理(Windows 下 toNativeDirSeparators("c:/winnt/system32") 返回 "c:\winnt\system32")
script.log(script.toNativeDirSeparators("c:/winnt/system32"));
后台批量启动进程的经典用法来自文档示例:循环启动 100 个 sleep 进程,并用 onDetachedProcessCallback 统一回收结果:
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]}`);
}
}
4.2 笔记与文件夹访问
// 当前笔记文件夹路径
var path = script.currentNoteFolderPath();
// 当前笔记对象(NoteApi)
var note = script.currentNote();
// 按文件名 / id 获取笔记
script.fetchNoteByFileName("my note.md");
script.fetchNoteById(243);
// 判断笔记文件是否存在(可忽略指定笔记 id)
script.noteExistsByFileName("my note.md", note.id);
// 跳转到指定笔记(asTab=true 时在新标签页打开)
script.setCurrentNote(note, true);
// 跳转到笔记子文件夹(支持相对路径与分隔符)
script.jumpToNoteSubFolder("a sub folder/sub");
// 获取所有选中笔记的路径 / id 列表
script.log(script.selectedNotesPaths());
script.log(script.selectedNotesIds());
4.3 编辑器操作
// 向当前光标位置写入文本
script.noteTextEditWrite("My custom text");
// 读取选中文本、全选、选中当前行 / 当前词
var text = script.noteTextEditSelectedText();
script.noteTextEditSelectAll();
script.noteTextEditSelectCurrentLine();
script.noteTextEditSelectCurrentWord();
// 精确控制选区与光标
script.noteTextEditSetSelection(script.noteTextEditSelectionStart() - 1, script.noteTextEditSelectionEnd() + 1);
script.noteTextEditSetCursorPosition(-1); // -1 跳到笔记末尾
script.log(script.noteTextEditCursorPosition());
// 读取当前词(withPreviousCharacters=true 可把 "@" 等非单词字符一起取回)
var word = script.noteTextEditCurrentWord(true);
// 读取当前块(配合 AI 补全使用)
var block = script.noteTextEditCurrentBlock();
4.4 剪贴板、媒体与附件
// 读取剪贴板(asHtml=true 时以 HTML 形式读取)
var clipboardText = script.clipboard();
var clipboardHtml = script.clipboard(true);
// 写入剪贴板(asHtml=true 时写入 HTML MIME 数据)
script.setClipboardText("text to copy");
// 下载 URL 到字符串 / 到媒体文件夹
var html = script.downloadUrlToString("https://www.qownnotes.org");
var markdown = script.downloadUrlToMedia("http://latex.codecogs.com/gif.latex?\\frac{1}{1+sin(x)}");
// 将本地媒体 / 附件文件插入到对应文件夹,返回 markdown 文本或 URL
var markdown = script.insertMediaFile("/path/to/your/image.png");
var markdown = script.insertAttachmentFile("/path/to/your/file.png");
4.5 标签与搜索
// 给当前笔记打标签
script.tagCurrentNote("favorite");
// 按“面包屑路径”创建或获取标签(自动创建缺失的父级)
var tag = script.getTagByNameBreadcrumbList(["level1", "level2", "level3"]);
// 按名称子串搜索标签(ignoreAccents=true 可忽略拉丁字母重音)
var tags = script.searchTagsByName("game");
var tags = script.searchTagsByName("cafe", true);
// 按笔记文本搜索,返回笔记 id 列表
var noteIds = script.fetchNoteIdsByNoteTextPart("mytext");
noteIds.forEach(function (noteId) {
var note = script.fetchNoteById(noteId);
});
4.6 界面与交互
// 信息提示框
script.informationMessageBox("The text I want to show", "Some optional title");
// 问答框(buttons 使用 Qt QMessageBox 的 StandardButton 枚举值)
var result = script.questionMessageBox("The text I want to show", "Some optional title", 0x01000000 | 0x02000000, 0x02000000);
// 打开 / 保存文件对话框
var fileName = script.getOpenFileName("Please select an image", "/home/user/images", "Images (*.png *.xpm *.jpg)");
var fileName = script.getSaveFileName("Please select HTML file to save", "output.html", "HTML (*.html)");
// 输入对话框(单行、多行、下拉选择;点击 Cancel 或按 Esc 返回空串)
var result = script.inputDialogGetItem("combo box", "Please select an item", ["Item 1", "Item 2", "Item 3"]);
var result = script.inputDialogGetText("line edit", "Please enter a name", "current text");
var result = script.inputDialogGetMultiLineText("multi-line edit", "Please enter a text", "current text");
// 文本差异对比对话框(text2 为可编辑文本,可用于 AI 改写前后的对比确认)
var result = script.textDiffDialog("AI Text Tool", "Resulting text", text, aiResult);
// 触发菜单动作(objectName 可在 mainwindow.ui 中按英文菜单名搜索)
script.triggerMenuAction("actionAllow_note_editing", 1); // 关闭只读模式
4.7 文件与持久化
// 读写文件、判断存在(readFromFile 默认 UTF-8,可指定 codec)
if (script.fileExists(filePath)) {
var data = script.readFromFile(filePath);
}
script.writeToFile(filePath, html, true); // createParentDirs=true 时自动创建父目录
// 脚本级缓存目录(可按 subDir 分区)
var cacheDirForScript = script.cacheDir("my-script-id");
script.clearCacheDir("my-script-id");
// 持久变量:全局跨脚本共享,key 务必使用有意义的前缀
script.setPersistentVariable("PersistentVariablesTest/myVar", result);
script.log(script.getPersistentVariable("PersistentVariablesTest/myVar", "nothing here yet"));
// 读取应用设置项(注意:设置可能为空,defaultValue 仅在设置完全不存在时生效)
script.log(script.getApplicationSettingsVariable("gitExecutablePath"));
4.8 AI 补全与颜色模式
// 使用当前选中的 AI 模型完成提示词(需先在 AI 工具栏中启用 AI 系统)
var text = script.aiComplete("Tell me how do you feel today?");
// 列出全部颜色模式并切换(内置模式 id 为 ColorMode-light / ColorMode-dark)
script.getColorModes().forEach(function (mode) {
script.log(mode.name + " (" + mode.id + "), editor color schema: " + mode.editorColorSchemaName);
});
const isDark = script.getCurrentColorModeId() === "ColorMode-dark";
script.switchToColorMode(isDark ? "ColorMode-light" : "ColorMode-dark");
五、脚本设置变量(settingsVariables):让用户可配置你的脚本
官方文档详细介绍了脚本设置变量的机制:脚本作者把变量定义为 QML 属性,并在名为 settingsVariables 的 variant 属性中注册元信息,用户在脚本设置界面中就可以直观地配置这些值。
5.1 支持的变量类型
| 类型标识 | 控件形态 | 说明 |
|---|---|---|
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": "myText",
"name": "I am textbox",
"description": "Please enter your text:",
"type": "text",
"default": "This can be a really long text\nwith multiple lines.",
},
{
"identifier": "myInt",
"name": "I am a number selector",
"description": "Please enter a number:",
"type": "integer",
"default": 42,
},
{
"identifier": "myFile",
"name": "I am a file selector",
"description": "Please select the file:",
"type": "file",
"default": "pandoc",
},
{
"identifier": "myDirectory",
"name": "I am a directory selector",
"description": "Please select the directory:",
"type": "directory",
"default": "/home",
},
{
"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"},
}
];
5.2 用 registerSettingsVariables() 动态覆盖
如果需要根据运行环境动态调整默认值(比如 Windows 上把默认可执行文件改成 pandoc.exe),可以额外定义一个特殊函数 registerSettingsVariables(),它会在注册之后再次被调用以覆盖变量:
function registerSettingsVariables() {
if (script.platformIsWindows()) {
settingsVariables[3].default = "pandoc.exe";
}
}
底层上,脚本设置变量由 ScriptingService::registerSettingsVariables 与 _settingsVariables 哈希表承载(见 scriptingservice.h),并且每个脚本实体通过 settingsVariablesJson 字段持久化(见 src/entities/script.h)。完整参考示例见 docs/scripting/examples/variables.qml。
六、脚本可直接使用的类(Classes)
除了 script 对象,QOwnNotes 还向脚本暴露了若干可实例化的类型,官方文档(webpage/src/scripting/classes.md)对其逐一说明。
6.1 NoteApi:笔记对象
NoteApi 是脚本中最常用的对象,封装了单条笔记的全部信息(定义见 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)
};
典型用法:
script.log(note.fileCreated.toISOString());
script.log(note.fileLastModified.getFullYear());
// 将笔记重命名为 "new name.md"
note.renameNoteFile("new name");
// 检查是否允许笔记文件名与标题不同
script.log(note.allowDifferentFileName());
// 遍历笔记的标签
var tags = note.tags;
for (var i in tags) {
script.log(tags[i].name);
}
注意 fileCreated / fileLastModified 是 QDateTime 对象,可以直接使用 JavaScript Date 的方法,或用 Qt.formatDateTime 格式化(详见下文第七节)。
6.2 NoteSubFolderApi:笔记子文件夹
NoteSubFolderApi 提供子文件夹的层级遍历能力,官方文档示例展示了如何用 Qt.createQmlObject 在脚本中实例化它:
var noteSubFolderQmlObj = Qt.createQmlObject(
"import QOwnNotesTypes 1.0; NoteSubFolder{}",
mainWindow,
"noteSubFolder",
);
// 打印所有子文件夹名称
noteSubFolderQmlObj.fetchNoteSubFoldersByParentId(parentId).forEach(function (nsf) {
script.log(nsf.name);
});
// 获取当前激活的子文件夹并打印路径
var noteSubFolder = noteSubFolderQmlObj.activeNoteSubFolder();
script.log(noteSubFolder.fullPath());
script.log(noteSubFolder.relativePath());
// 遍历子文件夹内的所有笔记
for (var idx in noteSubFolder.notes) {
var note = noteSubFolder.notes[idx];
}
6.3 TagApi:标签对象
TagApi 用于按名称或父级获取标签,并遍历标签下的笔记:
// 获取标签 "home"
var tag = script.getTagByNameBreadcrumbList(["home"]);
// 获取该标签下的所有笔记
var notes = tag.notes;
for (var idx in notes) {
var note = notes[idx];
script.log(note.name);
}
6.4 MainWindow:主窗口控制
MainWindow 对象(脚本中直接以 mainWindow 引用)提供窗口级操作,例如刷新笔记索引、创建子文件夹、插入 HTML、切换布局、跳转标签:
// 强制重载笔记列表
mainWindow.buildNotesIndexAndLoadNoteDirectoryList(true, true);
// 在当前子文件夹创建新子文件夹
mainWindow.createNewNoteSubFolder("My fancy folder");
// 以 Markdown 形式把 HTML 插入当前笔记(自动下载远程图片)
mainWindow.insertHtmlAsMarkdownIntoCurrentNote("<h2>my headline</h2>some text");
// 切换到名为 "Edit" 的布局
mainWindow.setCurrentLayout(mainWindow.getLayoutUuid("Edit"));
// 跳转到标签树中的 "test" 标签
var tag = script.getTagByNameBreadcrumbList(["test"]);
mainWindow.jumpToTag(tag.id);
// 获取所有已打开标签页中的笔记 id
var noteIds = mainWindow.getNoteTabNoteIdList();
noteIds.forEach(function (noteId) {
var note = script.fetchNoteById(noteId);
});
七、日期时间格式化:直接用 Qt.formatDateTime
文档提醒脚本作者不必自写日期格式化函数——QML 引擎已提供 Qt.formatDateTime、Qt.formatDate、Qt.formatTime。常用的占位符如下:
| 占位符 | 含义 | 示例 |
|---|---|---|
yyyy / yy |
四位 / 两位年份 | 2026 / 26 |
MM / M |
带前导零 / 不带前导零的月份 | 09 / 9 |
MMM / MMMM |
缩写 / 全称本地化月份名 | Sep / September |
dd / d |
带前导零 / 不带前导零的日 | 05 / 5 |
ddd / dddd |
缩写 / 全称本地化星期名 | Tue / Tuesday |
HH |
24 小时制小时 | 07 |
hh |
12 小时制小时(配合 AP) |
07 |
mm |
分钟 | 04 |
ss |
秒 | 09 |
AP / ap |
AM / PM | AM |
注意:占位符区分大小写(yyyy 是年份、MM 是月份、mm 是分钟),不支持的 YYYY、DD 等写法,且 ISO 周数也不支持。单引号内的文本不会被解释为占位符,例如 "yyyy-MM-dd 'at' HH:mm"。用法示例:
var date = new Date();
script.log(Qt.formatDateTime(date, "yyyy-MM-dd")); // "2026-09-29"
script.log(Qt.formatDateTime(date, "dddd, d. MMMM yyyy 'at' HH:mm")); // "Tuesday, 29. September 2026 at 14:05"
// 用当前年月给笔记打标签,如 "2026-09"
script.tagCurrentNote(Qt.formatDateTime(date, "yyyy-MM"));
// 同样适用于笔记的时间属性
var note = script.currentNote();
script.log(Qt.formatDateTime(note.fileLastModified, "yyyy-MM-dd HH:mm:ss"));
八、实战示例:从官方示例脚本到自己的第一个脚本
官方文档在 docs/scripting/examples/ 中提供了五十余个可直接运行参考的示例脚本。下面拆解两个最具代表性的例子,演示钩子与 API 的组合用法。
8.1 综合示例 example.qml:认识生命周期与多钩子共存
docs/scripting/examples/example.qml 是一个几乎覆盖所有核心钩子的“全家桶”脚本,其骨架如下:
import QtQml 2.0
import QOwnNotesTypes 1.0
QtObject {
// 脚本被 QOwnNotes 加载时调用
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);
var tagNameList = note.tagNames();
script.log(tagNameList);
}
// 媒体插入时调用(返回空串表示不干预)
function insertMediaHook(fileName, markdownText) {
script.log("mediafile was inserted: " + fileName);
return "";
}
// 定时器:每 30 秒输出当前笔记信息
property QtObject timer: Timer {
interval: 30000
repeat: true
running: true
property int count: 0
onTriggered: {
count++;
script.log("count = " + count);
var note = script.currentNote();
if (note) {
var tags = note.tags;
for (var i in tags) {
script.log(tags[i].name);
}
var tagNameList = note.tagNames();
script.log(tagNameList);
}
}
}
}
这个示例展示了三个重要技巧:
- 根对象不一定要用
Script,QtObject同样可以被 QOwnNotes 识别为脚本组件; - 钩子函数与普通 QML 属性(如
Timer)可以在同一个脚本中共存; script.currentNote()可能返回空对象,使用前务必判空。
8.2 自定义动作 custom-actions.qml:注册菜单项与按钮
docs/scripting/examples/custom-actions.qml 演示了 registerCustomAction 的完整用法——这是把脚本能力暴露给用户界面的标准途径:
import QtQml 2.0
import QOwnNotesTypes 1.0
QtObject {
function init() {
// 仅创建菜单项,无按钮
script.registerCustomAction("openWithKWrite", "Open with KWrite", "KWrite");
// 菜单项 + 按钮 + freedesktop 主题图标
script.registerCustomAction("createMeetingNote", "Create meeting note", "Meeting note", "task-new");
// 菜单项 + 按钮 + 右键菜单启用(第 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的参数完整签名是(identifier, menuText, buttonText, icon, useInNoteEditContextMenu, hideButtonInToolbar, useInNoteListContextMenu),其中icon可以是 freedesktop 主题图标名(Linux 下可用)或脚本内的图标文件路径(跨平台推荐);- 自定义动作可以继续在 快捷键设置(Shortcuts settings) 中绑定全局或局部快捷键;
- 应用启动后也可以通过命令行参数
--action customAction_<identifier>直接触发自定义动作。
8.3 自动补全 autocompletion.qml:钩子 + 编辑器 API 组合
docs/scripting/examples/autocompletion.qml 用两个 API 实现了“输入 @ 时自动补全标签”的实用功能:
import QtQml 2.0
import QOwnNotesTypes 1.0
Script {
function autocompletionHook() {
// 取回当前词及前面的非单词字符(以便拿到 "@")
var word = script.noteTextEditCurrentWord(true);
if (!word.startsWith("@")) {
return [];
}
// 去掉 "@" 后按名称子串搜索标签
var tags = script.searchTagsByName(word.substr(1));
return tags;
}
}
这个例子清晰展示了“钩子提供触发时机、API 提供数据能力”的协作模式:noteTextEditCurrentWord(true) 是编辑器读取 API,searchTagsByName() 是标签搜索 API,而 autocompletionHook 则把它们编织成一个完整功能。
九、调试与日志:用好日志面板
官方文档明确建议使用 script.log() 进行日志记录。结合源码,以下调试手段值得掌握:
- 日志面板:在菜单 窗口 / 面板(Window / Panels) 中开启 日志面板,
script.log()的所有输出都会实时显示; - init() 探针:脚本加载失败时,
init()不会执行;在init()第一行写入script.log("Script init")可快速判断脚本是否被引擎成功加载; - 脚本重载:修改脚本后可在脚本设置中重载,脚本内部也可以调用
script.reloadScriptingEngine()主动触发引擎重载(见 scriptingservice.h); - 钩子是否生效:文档指出,某些钩子(如
noteTaggingHook)只要被任一启用的脚本实现就会接管对应功能,可通过noteTaggingHookExists()(scriptingservice.h)等检测方法从源码层面理解行为差异——如果多脚本同时定义了“首胜”类钩子,务必留意脚本的优先级与加载顺序。
十、给脚本仓库贡献与问题反馈
官方文档对脚本生态的参与路径做了明确说明:
- 使用脚本仓库中的脚本遇到问题,或有功能请求,请在脚本仓库的 issue 页面提交;
- 想把自己写的脚本提交到脚本仓库,请遵循脚本仓库的贡献说明;
- 需要访问 QOwnNotes 目前尚未暴露给脚本的功能,或有任何问题与想法,请在 QOwnNotes 主仓库的 issue 页面提交。
此外,仓库根目录的 AGENTS.md、README.md 以及 CHANGELOG.md 可以帮助你了解项目整体约定与版本演进。
结语
QOwnNotes 的脚本体系是一个“JavaScript 编写、QML 承载、钩子驱动、API 赋能”的轻量插件平台:.qml 文件带来声明式结构与 Qt 生态能力,init() 提供生命周期入口,二十余个命名钩子让脚本可以精准插入笔记生命周期、编辑器、标签、预览、加密、AI 等环节,而 script 对象与 NoteApi、TagApi、MainWindow 等暴露类型则提供了完整的数据访问与界面控制能力。从本文的示例出发,结合 docs/scripting/examples/ 中的五十余个官方示例,你可以快速构建属于自己的自动化工作流——无论是自定义菜单动作、标签机制、外部命令集成,还是接入自建 AI 后端。