桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载QOwnNotes Web Companion 是官方出品的浏览器扩展它把浏览器与桌面笔记应用连接起来让你能够随时将网页内容或选中文本剪藏为笔记、截取整页截图并把书签以 Markdown 形式存放在笔记中实现跨浏览器、跨操作系统的书签统一管理。读完本文你将掌握扩展的安装与安全令牌配置、Web Clipper 剪藏与脚本化扩展、书签链接语法与增删改机制以及如何通过 Homepage 建议 API 在自建导航首页中复用同一套书签数据。本文以仓库中的 浏览器扩展官方文档 为骨架结合 WebSocket 服务端实现 与 书签解析实体 等源码进行纵深讲解。功能总览剪藏与书签一个扩展全搞定Web Companion 扩展提供两大核心能力网页剪藏Web Clipper从浏览器页面捕获内容整页或选中文本并可附带当前页面的截图以新笔记的形式写入 QOwnNotes。书签管理Bookmarks将浏览器书签以 Markdown 链接的形式存储在 QOwnNotes 笔记中从而在不同浏览器、不同操作系统之间共享并完全掌控你的书签。使用前有一个关键前提QOwnNotes 桌面应用必须处于运行状态扩展才能与之通信。不过整个过程完全离线——扩展通过本地 WebSocket 与桌面端交互不需要任何互联网连接。从源码看桌面端的 WebSocketServerService 只监听QHostAddress::LocalHost本机回环地址默认端口为 22222调试版为 22223见 getDefaultPort()这也印证了离线、本机通信的设计。安装扩展与配置安全令牌获取扩展按官方文档扩展可从以下渠道获取Chrome Web Store扩展 IDpkgkfnampapjbopomdpnkckbjdnpkbkpFirefox Add-ons 页面Web Companion 项目的 GitHub 仓库安全令牌扩展与桌面端的握手凭证扩展与 QOwnNotes 桌面端通信使用**安全令牌Security Token**进行认证配置步骤如下安装扩展后第一次点击浏览器工具栏中的 QOwnNotes 扩展图标桌面端会弹出包含安全令牌的对话框复制该令牌。进入浏览器的扩展管理页面打开 QOwnNotes 扩展的详情。将令牌粘贴到扩展的 Security Token 字段中完成配对。这一机制的底层逻辑在 processMessage() 中清晰可见桌面端收到扩展发来的每条消息都会先校验其中的token字段若令牌为空或不匹配服务端会返回tokenQuery类型的响应并在桌面端弹出WebSocketTokenDialog要求用户确认令牌之后才继续处理后续消息。令牌本身由Utils::Misc::generateRandomString(8)随机生成8 位随机字符串并经 CryptoService 加密后存储在设置项webSocketServerService/token中。隐私浏览无痕模式如果你需要在隐私浏览窗口中使用扩展必须在扩展的偏好设置中允许扩展在隐私窗口中运行否则隐私窗口中的剪藏与书签功能将不可用。Web Clipper 网页剪藏在网页上点击鼠标右键或先选中一段文本再右键即可看到 QOwnNotes 的剪藏菜单剪藏整页内容或选中的文本QOwnNotes 会据此创建一篇新笔记在剪藏的同时可以对当前网页截取整页截图并随笔记一起保存。从源码层面看剪藏的完整流程是扩展通过 WebSocket 发送newNote或handleRawData类型消息携带pageUrl、contentType、headline、text等字段服务端先调用Utils::Misc::createAbsolutePathsInHtml把 HTML 中形如/my-page.html的相对链接转换为绝对链接基于pageUrl补全域名然后调用mainWindow-createNewNote(...)创建新笔记对于 HTML 内容还会调用insertHtmlAsMarkdownIntoCurrentNote将 HTML 转换为 Markdown 写入笔记见 processMessage() 中newNote/handleRawData分支。剪藏失效的排查清单官方文档专门给出了 Web Clipper 不工作时的排查步骤确认 QOwnNotes 桌面应用正在运行——这是通信的前提确认扩展已用安全令牌完成配置——令牌不匹配时服务端不会处理剪藏请求对应源码中的令牌校验逻辑确认在首次点击扩展图标时接受了浏览器的同意consent对话框Firefox 用户特别注意需要在扩展的“权限”设置中开启可选权限Access your data for all websites访问所有网站的数据否则右键菜单剪藏可能报错TypeError: chrome.tabs.captureVisibleTab is not a function——这是 Firefox 对tabs.captureVisibleTabAPI 的权限限制只有授予该可选权限后截图功能才可用。剪藏可脚本化websocketRawDataHookWeb Clipper 不只是“傻瓜式”剪藏它完全可脚本化当扩展通过浏览器右键菜单发送数据时QOwnNotes 会调用脚本钩子websocketRawDataHook脚本可以拦截、改写甚至完全接管剪藏内容。钩子签名如下见 hooks.md 文档/** * param requestType 请求类型取值 page整页或 selection选中文本 * param pageUrl 发起请求的网页 URL * param pageTitle 发起请求的网页标题 * param rawData 传输的原始数据requestType 为 page 时是 HTML为 selection 时是纯文本 * param screenshotDataUrl 网页截图的 data URL * return true 表示数据已被脚本处理此时不再创建新笔记false 表示走默认剪藏流程 */ function websocketRawDataHook(requestType, pageUrl, pageTitle, rawData, screenshotDataUrl);对应的服务端调用链位于 callHandleWebsocketRawDataHook()当消息类型为handleRawData时服务端解析出requestType、pageUrl、pageTitle、rawData、screenshotDataUrl五个参数并调用钩子若钩子返回true则跳过默认的“创建新笔记”逻辑说明数据已被脚本自行处理见 websocketserverservice.cpp。仓库自带一个可直接参考的示例脚本 websocket-raw-data-selection-in-note.qml它只处理selection类型的请求把网页上选中的文本直接写入当前笔记function websocketRawDataHook(requestType, pageUrl, pageTitle, rawData, screenshotDataUrl) { // 只处理选中文本整页请求忽略 if (requestType ! selection) { return false; } // 将页面选中的文本写入当前笔记 script.noteTextEditWrite(rawData); return true; }书签管理把书签装进笔记如果你希望对浏览器书签拥有完全控制权并在不同浏览器与操作系统间共用QOwnNotes 扩展正是为此设计的。它的核心思想是书签就是笔记里的 Markdown 链接书签数据随笔记走天然跨平台。默认行为当前笔记的链接默认情况下点击浏览器工具栏的 QOwnNotes 图标扩展弹窗会展示当前笔记中的所有链接这些链接会被自动打上current标签。这一行为对应源码中Bookmark::parseBookmarks(text, withBasicUrls)的“基本链接解析”分支bookmark.cpp形如[名称](http://...)的命名链接和形如http://...的裸链接都会被解析出来并标记为current从而在扩展弹窗中呈现。用笔记管理书签bookmarks 标签与 Bookmarks 笔记除了当前笔记你还可以用专门的笔记管理持久书签带有笔记标签bookmarks的笔记标签名可在设置中修改会被视为书签库其中的链接会显示在扩展弹窗中且可以附加标签tags和描述description新书签默认写入一篇名为Bookmarks的笔记笔记名同样可在设置中修改。这两项设置的默认值在源码中一目了然getBookmarksTag()读取设置项webSocketServerService/bookmarksTag默认bookmarksgetBookmarksNoteName()读取设置项webSocketServerService/bookmarksNoteName默认Bookmarks见 websocketserverservice.cpp。新增书签时服务端的createBookmarks()会向Bookmarks笔记追加- 名称 描述形式的 Markdown 行如果该笔记尚不存在会自动创建并打上bookmarks标签见 createBookmarks()。此外扩展还支持一键导入浏览器现有书签到 QOwnNotes。书签链接语法在bookmarks标签的笔记中书签遵循以下 Markdown 语法可以组合使用标签与描述- [页面名称](https://www.example.com) - [页面名称](https://www.example.com) #tag1 #tag2 - [页面名称](https://www.example.com) 仅一段描述 - [页面名称](https://www.example.com) #tag1 #tag2 描述与标签并存 * [页面名称](https://www.example.com) 列表符号 * 同样有效底层解析逻辑见 Bookmark::parseBookmarks()正则([-*]\s\[([^\[\]]?)\]\(([\w-]://.?)\)(.*)$)匹配-/*开头的列表项捕获链接名称、URL 与剩余文本剩余文本中形如#xxx的片段被提取为标签其余部分作为描述。也就是说标签以#前缀、空格分隔描述放在标签之后。你还可以在扩展弹窗中按名称、URL、标签或描述进行搜索。至于当前笔记中正文里的其他链接同样会被解析显示但不带标签和描述对应源码中withBasicUrls参数控制的两类解析路径。书签的增删改在底层如何完成书签数据并非“只读快照”在扩展里编辑或删除书签会真实回写笔记文件新增newBookmarks消息 → createBookmarks() 追加 Markdown 行并落盘删除deleteBookmark消息 → deleteBookmark() 在所有带bookmarks标签的笔记以及Bookmarks命名笔记、当前笔记中按 Markdown 文本精确匹配并移除对应行编辑editBookmark消息 → editBookmark() 在所有相关笔记中替换匹配的 Markdown 行。删除与编辑完成后服务端还会通知主窗口重载当前笔记保证界面与磁盘内容一致。这也解释了为什么书签能“跨浏览器、跨系统”书签本质是你笔记文件夹中的 Markdown 文本只要同步笔记文件夹书签就跟着走了。进阶用 Homepage 建议 API 把书签接入导航首页扩展文档还提到一项衍生能力——Homepage 建议 APIQOwnNotes 可以暴露一个本地 HTTP 端点供 Homepage。在 QOwnNotes 中启用打开设置 - 浏览器扩展 / 命令片段对应设置界面源码 webcompanionsettingswidget.cpp开启Enable socket server启用 Socket 服务器这是 WebSocket 通信的总开关对应设置项enableSocketServer默认开启见 misc.cpp在Bookmark suggestion API分组中勾选Enable Homepage-compatible bookmark suggestions API并设置端口。服务只绑定到127.0.0.1本机回环不会暴露到局域网。端口默认值为22224调试版为 22225设置项为webSocketServerService/bookmarkSuggestionApiPort勾选启用后服务端会在该端口启动一个仅接受 GET 请求的最小 HTTP 服务见 startSuggestionHttpServer() 与 processHttpRequest()。端点与参数端点GET /suggest?q查询词可选参数limit返回条数默认10上限50超出会被钳制见 processHttpRequest()可选参数token若你在 QOwnNotes 中配置了安全令牌则必须携带令牌缺失或不匹配会返回401 Unauthorized见 websocketserverservice.cpp注意这里的“建议 API 令牌”与扩展通信令牌是两套独立令牌建议 API 令牌存储在webSocketServerService/bookmarkSuggestionApiToken设置项中为空时自动生成 32 位随机串并加密保存见 getOrGenerateBookmarkSuggestionApiToken()。如果你使用了docs/homepage下的custom.js需要把QON_TOKEN设为与 QOwnNotes 中配置的同一个安全令牌脚本会在请求建议时自动附加token...。响应是一个 JSON 数组格式为[查询词, [建议1, 建议2, ...]][home, [Homepage, https://example.com/home, Some Home Link]]其中每一条建议可以是书签名称也可以是书签 URL匹配时按“前缀匹配优先、子串匹配兜底”的顺序返回结果会去重并受limit约束相关逻辑见 Bookmark::suggestionStrings()。为了减少开销书签数据带有约 2.5 秒的缓存建议响应也有最多 200 条的结果缓存见 getBookmarksForSuggestions()。Homepage 配置示例在 Homepage 的配置中将search块的suggestionUrl指向本地端点即可search: provider: custom url: https://example.com/search?q suggestionUrl: http://127.0.0.1:22224/suggest?q showSearchSuggestions: true在标准 Homepage 安装中把上述search配置块加入以下任一文件settings.yamlHomepage 全局设置settings.yml同上视你的部署而定挂载到容器内/app/config/settings.yaml的配置文件如果你的 Homepage 部署把配置拆成了多个文件请编辑已经包含searchprovider 设置的那个文件。定制前端资产custom.js 与 custom.css仓库的 docs/homepage 目录提供了一套开箱即用的 Homepage 定制资产custom.js拦截 Homepage 的搜索建议接口响应从http://127.0.0.1:22224/suggest?qquerylimitQON_LIMIT拉取 QOwnNotes 建议并合并展示还会把“名称 URL”成对出现的书签建议映射到实际 URL点击时直接打开书签地址而不是把文本当搜索词提交并防止 Homepage 客户端把合并结果硬性截断到 4 条。custom.css为 QOwnNotes 来源的建议行CSS 类qon-suggestion添加左边框与绿色文字便于视觉区分。custom.js顶部提供了几个可调参数参数默认值作用QON_URLhttp://127.0.0.1:22224/suggest?qQOwnNotes 本地建议 API 地址QON_TOKEN空与 QOwnNotes 中配置的安全令牌一致用于鉴权QON_LIMIT20每次请求获取的 QOwnNotes 建议数量QON_LABEL[QON]建议文本前缀用于在 UI 中标识来源DEBUGfalse设为true时输出调试日志使用要求当你的 Homepage 部署支持加载custom.js/custom.css时将这两个文件放到对应位置例如 Homepage 实例的自定义资产目录修改后建议强制刷新页面以加载新版本如果 Homepage 运行在与 QOwnNotes 不同的机器/容器上需要把这两个文件放到托管 Homepage 的那台实例上它才能查询本机 QOwnNotes 的建议 API 并合并展示启用安全令牌时务必在custom.js中把QON_TOKEN设为与 QOwnNotes 相同的令牌并保持suggestionUrl不变脚本会自动附加令牌参数。安全提示由于书签数据中可能包含敏感的 URL若你需要让端点可被 localhost 之外访问必须在端点前放置反向代理并加以访问限制例如防火墙规则或白名单不要把建议 API 裸暴露到公网。相关文件导航以下文件可以帮助你继续深入本文涉及的每个环节官方英文版扩展文档webpage/src/getting-started/browser-extension.mdHomepage 建议 API 文档webpage/src/getting-started/homepage-suggestion-api.md剪藏钩子完整说明含其他脚本钩子webpage/src/scripting/hooks.md剪藏脚本示例docs/scripting/examples/websocket-raw-data-selection-in-note.qmlWebSocket 服务与建议 API 服务端实现src/services/websocketserverservice.cpp书签解析与建议匹配核心逻辑src/entities/bookmark.cpp“浏览器扩展 / 命令片段”设置界面src/widgets/settings/webcompanionsettingswidget.cppHomepage 定制资产说明与示例docs/homepage/README.md、docs/homepage/custom.js、docs/homepage/custom.css掌握以上内容后你就可以在 QOwnNotes 中搭建一套“浏览器剪藏 笔记书签库 导航首页搜索建议”的完整工作流日常浏览时随手剪藏与截屏书签统一沉淀在 Markdown 笔记里跨设备同步回到 Homepage 导航页时又能直接搜索并打开这些书签全程离线、数据完全归你所有。赞分享桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载相关推荐QOwnNotes Web Companion 浏览器扩展实战指南网页剪辑、跨浏览器书签管理与 Homepage 建议 APIQOwnNotes Web Companion 浏览器扩展实战指南网页剪辑、跨浏览器书签管理与 Homepage 建议 API 本指南围绕 QOwnNotes桌面应用QOwnNotes Web Companion 浏览器扩展使用与原理指南从网页剪藏到跨浏览器书签管理QOwnNotes Web Companion 浏览器扩展使用与原理指南从网页剪藏到跨浏览器书签管理 导读 本文围绕 QOwnNotes 官方博客《QOwnN桌面应用QOwnNotes Web Companion 浏览器扩展网页剪切、跨浏览器书签管理与可脚本化扩展QOwnNotes Web Companion 浏览器扩展网页剪切、跨浏览器书签管理与可脚本化扩展 QOwnNotes Web Companion 是一款配合桌面应用上一篇OpenPanel高级查询技巧利用Clickhouse实现复杂数据分析下一篇MozStumbler 新手指南地图界面、扫描指示与 10 设置项逐项详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考