QOwnNotes 脚本开发实战指南:基于 QML 的插件系统从入门到进阶

原创2026-10-15 09:17:451,429 阅读
文章标签:桌面应用知识管理富文本插件系统跨平台

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)**面板添加:

  1. 打开菜单 Settings(设置)→ Scripting(脚本);
  2. 点击 Add script(添加脚本)按钮,选择本地 .qml 文件;部分版本提供 Add local script(添加本地脚本)按钮;
  3. 脚本出现在列表中后即被加载,引擎会立即调用其 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

QOwnNotes 的 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);

十一、源码级原理:脚本引擎如何工作

从 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 的核心数据模型。

十二、快速上手路线图

  1. 跑通最小脚本:新建 hello.qml,写入开头的最小骨架,在脚本设置中添加并观察日志面板输出;
  2. 读示例:对照 docs/scripting/examples 中的 example.qml 和 custom-actions.qml,理解 init 与各 Hook 的配合方式;
  3. 接入用户配置:按 variables.qml 声明 settingsVariables,把脚本参数化;
  4. 注册自定义动作:用 registerCustomAction + customActionInvoked 把常用功能固化为菜单项/按钮,并在 Shortcuts 中绑定快捷键;
  5. 查阅完整 API:方法全集见 webpage/src/scripting/methods-and-objects.md,对象属性见 webpage/src/scripting/classes.md,Hook 完整签详见 webpage/src/scripting/hooks.md。

说明:本文所有脚本能力均以当前仓库(QOwnNotes)代码为准;脚本运行效果受 Qt 版本与平台影响,跨平台脚本建议用 platformIsLinux() / platformIsOSX() / platformIsWindows() 做分支判断。

登录后查看全文
QOwnNotes