QOwnNotes 脚本开发实战:基于 QML/JavaScript 的扩展系统从入门到进阶

原创2026-10-12 01:16:591,874 阅读
文章标签:桌面应用知识管理富文本插件系统跨平台

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 抓取。

加密

自定义标签体系

  • 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)(按钮取值见 Qt QMessageBox::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 的示例脚本,是入门与进阶的最好教材,例如:

主题 示例脚本
综合入门 example.qml、callback.qml
自定义动作 custom-actions.qml、favorite-note.qml
笔记打开/存储 on-note-opened.qml、external-note-open.qml、execute-command-after-note-update.qml
自定义标签 note-tagging.qml、note-tagging-by-object.qml、use-tag-names-in-filename.qml
编辑器/高亮/补全 autocompletion.qml、highlighting.qml、custom-highlighting.qml
预览与样式 preview-styling.qml、custom-stylesheet.qml
加密 encryption-keybase.qml、encryption-pgp.qml、encryption-rot13.qml
外部工具集成 paste-latex-image.qml、paste-full-image-url.qml、fetch-url-title-with-kanboard-cli.qml、note-from-jira-issue.qml
数据统计/日记 journal-entry.qml、weather-stats.qml、note-stats.qml、zettelkasten.qml
输入对话框/标签 input-dialogs.qml、scripting-label-demo.qml
网页/浏览器 websocket-server.qml、websocket-client.qml、websocket-raw-data-new-note.qml
AI ai-autocompletion.qml、custom-openai-backends.qml
窗口/布局 window-state-changed.qml、layouts.qml、toggle-color-mode.qml
其他 export-notes-as-one-html.qml、external-note-diff.qml、meeting-note.qml、disable-readonly-mode.qml

结语与进一步阅读

QOwnNotes 脚本系统以 QML + JavaScript 为语言、以 script 对象和生命周期钩子为核心 API,覆盖了笔记存储、预览渲染、标签、加密、高亮、自动补全、外部进程、AI 乃至 WebSocket 远程控制等方方面面。建议按以下路径深入学习:

掌握这些接口后,无论是自动化日常笔记流程、接入团队内部工具,还是打造个性化的编辑体验,都可以通过一个轻量的 .qml 文件完成,无需重新编译主程序。

登录后查看全文
QOwnNotes