尧图网站建设 
Joplin 自定义 CSS 完整指南用 userstyle.css 与 userchrome.css 深度定制笔记渲染与桌面端界面【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 桌面端为高级用户提供了两套基于 CSS 的定制入口userstyle.css负责定制笔记渲染Markdown 预览的样式userchrome.css负责定制整个应用的界面外观。本文以官方文档 Custom CSS 为核心结合仓库源码如 Setting.ts、app.ts详细讲解这两类文件的位置、加载机制、生效条件、打印注意事项与维护风险并给出可落地的样式示例帮助你把 Joplin 调校成符合个人阅读与写作习惯的形态。一、两个文件两种作用域userstyle.css 与 userchrome.cssJoplin 桌面端的 CSS 定制分为两个独立文件二者作用域完全不同官方在源码中将其集中定义在 Setting.ts 的customCssFilenames常量中public static customCssFilenames { JOPLIN_APP: userchrome.css, RENDERED_MARKDOWN: userstyle.css, };文件常量键作用域userstyle.cssRENDERED_MARKDOWN仅作用于渲染后的 Markdown 笔记内容预览窗格同时影响笔记的屏幕显示与打印输出userchrome.cssJOPLIN_APP作用于整个 Joplin 应用界面侧边栏、工具栏、编辑器 chrome 等但不包含渲染后的 Markdown 内容两者的定位差异可以从官方在设置项中写入的默认注释看出见 builtInMetadata.tsuserchrome.css的默认文件头注释明确写着用于样式化整个 Joplin 应用渲染后的 Markdown 除外那部分在 userstyle.css 中定义。二、文件存放位置与如何找到你的配置文件路径这两个文件都存放在 Joplin 的**配置目录profile directory**下文件名固定为userstyle.css与userchrome.css。官方文档给出的典型路径是userstyle.css~/.config/joplin-desktop/userstyle.cssuserchrome.css~/.config/joplin-desktop/userchrome.css但该路径会因操作系统、安装方式与自定义配置目录而不同文档明确提醒你的设备上路径可能不同。最可靠的确认方式有两条在配置界面查看打开 Joplin 的配置Configuration界面进入General常规页页面顶部即显示当前配置目录的准确路径。在外观设置中直接打开/创建文件配置界面的Appearance外观区块提供两个按钮见 builtInMetadata.tsCustom stylesheet for rendered Markdown渲染 Markdown 的自定义样式表对应userstyle.cssCustom stylesheet for Joplin-wide app stylesJoplin 全局应用样式对应userchrome.css。点击按钮会调用shim.openOrCreateFile——如果文件不存在则先创建并写入默认注释然后用系统默认编辑器打开无需手工记忆路径。这两个设置项均标记为advanced: true位于外观区块的高级区域。从源码看文件的实际解析路径由Setting.customCssFilePath()计算得出Setting.tspublic static customCssFilePath(filename: string): string { return ${this.value(rootProfileDir)}/${filename}; }即路径恒等于rootProfileDir配置根目录与固定文件名的拼接这也是为什么文件必须放在配置根目录、且名称必须精确为上述两个名字。三、加载机制应用启动时如何读取这两个文件理解为什么改了 CSS 有时不生效需要先了解加载时机。在 app.ts 中setupCustomCss()负责启动阶段的两个加载动作private async setupCustomCss() { const chromeCssPath Setting.customCssFilePath(Setting.customCssFilenames.JOPLIN_APP); if (await shim.fsDriver().exists(chromeCssPath)) { this.store().dispatch({ // Main window custom CSS type: CUSTOM_CHROME_CSS_ADD, filePath: chromeCssPath, }); } this.store().dispatch({ // Markdown preview pane type: CUSTOM_VIEWER_CSS_APPEND, css: await loadCustomCss(Setting.customCssFilePath(Setting.customCssFilenames.RENDERED_MARKDOWN)), }); }由此可以总结出几条关键结论两者都在应用启动阶段被加载因此新增或修改样式后必须完全退出并重新启动 Joplin才能生效。官方文档特别强调请确保 Joplin 是真正退出而不是最小化到系统托盘tray——最小化到托盘时进程仍在运行重启后看到的仍可能是旧样式。加载策略不同userchrome.css只有在文件已存在时才被读取并注入通过CUSTOM_CHROME_CSS_ADD事件挂到主窗口而userstyle.css无论文件是否存在都会被读取loadCustomCss对不存在的文件会安全返回空内容通过CUSTOM_VIEWER_CSS_APPEND追加到渲染视图的样式表中。userstyle.css采用追加append语义意味着它排在 Joplin 内置 Markdown 样式之后可利用 CSS 层叠规则覆盖默认样式而userchrome.css面向整个应用 UI选择器需要针对桌面端界面结构编写。四、编写你的第一个 userstyle.cssuserstyle.css支持标准 CSS 语法编写时直接针对渲染后的 HTML 元素写规则即可。以下示例演示了最常见的定制方向——调整阅读排版/* 正文字体与行高 */ .note-body { font-family: Noto Serif SC, Source Han Serif SC, Georgia, serif; font-size: 16px; line-height: 1.75; } /* 标题间距与配色 */ .note-body h1, .note-body h2 { color: #1f3864; border-bottom: 1px solid #e0e0e0; padding-bottom: 4px; } /* 代码块背景 */ .note-body pre { background: #f6f8fa; border-radius: 6px; padding: 12px 16px; } /* 行内代码 */ .note-body code { background: #f0f0f0; padding: 2px 4px; border-radius: 3px; }打印注意事项文档明确提醒userstyle.css同时作用于笔记的屏幕显示与打印输出。因此编写时必须考虑打印效果例如不要用白字黑底之类的深色背景方案否则打印出来会浪费大量墨水甚至因背景不打印而出现白字看不见的问题可考虑用media print查询为打印单独设定样式如去除装饰性背景、调整字号。五、编写你的第一个 userchrome.cssuserchrome.css用于定制整个 Joplin 界面。由于它影响范围大编写时建议先用开发者工具DevTools检查目标元素的 class 名再写针对性规则。官方在设置项描述中同样将此类 CSS 视为高级功能示例/* 让侧边栏更紧凑 */ .sidebar { font-size: 13px; } /* 自定义工具栏背景 */ .toolbar { background: #2d2d2d !important; color: #eee; }需要特别说明的是userchrome.css作用于应用界面框架而笔记渲染区域仍由userstyle.css控制两者互不干扰可按需组合使用。六、重要警告这些是高级设置样式可能随版本失效官方在文档中给出了明确的免责声明这段文字同时也被写入设置项描述见 builtInMetadata.tsuserstyle.css 和 userchrome.css 是为方便使用而提供的但它们属于高级设置你定义的样式可能从一个版本失效到下一个版本。如果你想使用它们请做好需要定期维护的心理准备。Joplin 团队无法承诺保持应用 HTML 结构稳定。这意味着一件必须接受的事实Joplin 的界面 DOM 结构不在兼容性承诺范围内。应用升级后你依赖的某个 class 名、DOM 层级可能被重构导致样式失效或错乱。因此升级前留意界面是否出现样式异常必要时回到默认样式尽量使用语义明确、较稳定的选择器减少对深层 DOM 结构的依赖为关键样式做好注释与备份便于版本升级后快速修复若样式问题影响使用且无法快速解决删除或重命名这两个文件即可完全恢复 Joplin 默认外观注意重启应用使其生效。七、相关文档与后续阅读配置界面的完整字段说明见 Configuration screen其中 General 页面顶部显示配置目录路径渲染引擎与 Markdown 支持范围可参考 Markdown若希望以编程方式为笔记注入自定义 HTML/CSS可结合插件机制见 Plugins与插件 API 进一步定制渲染结果其能力边界以对应插件文档为准。小结userstyle.css定制渲染后的 Markdown 笔记含打印userchrome.css定制整个应用界面两者都位于配置根目录文件名固定修改后必须完全退出并重启Joplin 才生效最小化到托盘不算退出文件路径以配置 → General 页顶部显示的配置目录为准也可通过外观区块的两个按钮直接打开/创建两个文件均支持标准 CSSuserstyle.css以追加方式覆盖默认样式二者属高级设置界面 DOM 结构不受版本兼容性承诺保护需接受定期维护的现实。【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Joplin 自定义 CSS 完整指南：用 userstyle.css 与 userchrome.css 深度定制笔记渲染与桌面端界面
Joplin 自定义 CSS 完整指南用 userstyle.css 与 userchrome.css 深度定制笔记渲染与桌面端界面【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 桌面端为高级用户提供了两套基于 CSS 的定制入口userstyle.css负责定制笔记渲染Markdown 预览的样式userchrome.css负责定制整个应用的界面外观。本文以官方文档 Custom CSS 为核心结合仓库源码如 Setting.ts、app.ts详细讲解这两类文件的位置、加载机制、生效条件、打印注意事项与维护风险并给出可落地的样式示例帮助你把 Joplin 调校成符合个人阅读与写作习惯的形态。一、两个文件两种作用域userstyle.css 与 userchrome.cssJoplin 桌面端的 CSS 定制分为两个独立文件二者作用域完全不同官方在源码中将其集中定义在 Setting.ts 的customCssFilenames常量中public static customCssFilenames { JOPLIN_APP: userchrome.css, RENDERED_MARKDOWN: userstyle.css, };文件常量键作用域userstyle.cssRENDERED_MARKDOWN仅作用于渲染后的 Markdown 笔记内容预览窗格同时影响笔记的屏幕显示与打印输出userchrome.cssJOPLIN_APP作用于整个 Joplin 应用界面侧边栏、工具栏、编辑器 chrome 等但不包含渲染后的 Markdown 内容两者的定位差异可以从官方在设置项中写入的默认注释看出见 builtInMetadata.tsuserchrome.css的默认文件头注释明确写着用于样式化整个 Joplin 应用渲染后的 Markdown 除外那部分在 userstyle.css 中定义。二、文件存放位置与如何找到你的配置文件路径这两个文件都存放在 Joplin 的**配置目录profile directory**下文件名固定为userstyle.css与userchrome.css。官方文档给出的典型路径是userstyle.css~/.config/joplin-desktop/userstyle.cssuserchrome.css~/.config/joplin-desktop/userchrome.css但该路径会因操作系统、安装方式与自定义配置目录而不同文档明确提醒你的设备上路径可能不同。最可靠的确认方式有两条在配置界面查看打开 Joplin 的配置Configuration界面进入General常规页页面顶部即显示当前配置目录的准确路径。在外观设置中直接打开/创建文件配置界面的Appearance外观区块提供两个按钮见 builtInMetadata.tsCustom stylesheet for rendered Markdown渲染 Markdown 的自定义样式表对应userstyle.cssCustom stylesheet for Joplin-wide app stylesJoplin 全局应用样式对应userchrome.css。点击按钮会调用shim.openOrCreateFile——如果文件不存在则先创建并写入默认注释然后用系统默认编辑器打开无需手工记忆路径。这两个设置项均标记为advanced: true位于外观区块的高级区域。从源码看文件的实际解析路径由Setting.customCssFilePath()计算得出Setting.tspublic static customCssFilePath(filename: string): string { return ${this.value(rootProfileDir)}/${filename}; }即路径恒等于rootProfileDir配置根目录与固定文件名的拼接这也是为什么文件必须放在配置根目录、且名称必须精确为上述两个名字。三、加载机制应用启动时如何读取这两个文件理解为什么改了 CSS 有时不生效需要先了解加载时机。在 app.ts 中setupCustomCss()负责启动阶段的两个加载动作private async setupCustomCss() { const chromeCssPath Setting.customCssFilePath(Setting.customCssFilenames.JOPLIN_APP); if (await shim.fsDriver().exists(chromeCssPath)) { this.store().dispatch({ // Main window custom CSS type: CUSTOM_CHROME_CSS_ADD, filePath: chromeCssPath, }); } this.store().dispatch({ // Markdown preview pane type: CUSTOM_VIEWER_CSS_APPEND, css: await loadCustomCss(Setting.customCssFilePath(Setting.customCssFilenames.RENDERED_MARKDOWN)), }); }由此可以总结出几条关键结论两者都在应用启动阶段被加载因此新增或修改样式后必须完全退出并重新启动 Joplin才能生效。官方文档特别强调请确保 Joplin 是真正退出而不是最小化到系统托盘tray——最小化到托盘时进程仍在运行重启后看到的仍可能是旧样式。加载策略不同userchrome.css只有在文件已存在时才被读取并注入通过CUSTOM_CHROME_CSS_ADD事件挂到主窗口而userstyle.css无论文件是否存在都会被读取loadCustomCss对不存在的文件会安全返回空内容通过CUSTOM_VIEWER_CSS_APPEND追加到渲染视图的样式表中。userstyle.css采用追加append语义意味着它排在 Joplin 内置 Markdown 样式之后可利用 CSS 层叠规则覆盖默认样式而userchrome.css面向整个应用 UI选择器需要针对桌面端界面结构编写。四、编写你的第一个 userstyle.cssuserstyle.css支持标准 CSS 语法编写时直接针对渲染后的 HTML 元素写规则即可。以下示例演示了最常见的定制方向——调整阅读排版/* 正文字体与行高 */ .note-body { font-family: Noto Serif SC, Source Han Serif SC, Georgia, serif; font-size: 16px; line-height: 1.75; } /* 标题间距与配色 */ .note-body h1, .note-body h2 { color: #1f3864; border-bottom: 1px solid #e0e0e0; padding-bottom: 4px; } /* 代码块背景 */ .note-body pre { background: #f6f8fa; border-radius: 6px; padding: 12px 16px; } /* 行内代码 */ .note-body code { background: #f0f0f0; padding: 2px 4px; border-radius: 3px; }打印注意事项文档明确提醒userstyle.css同时作用于笔记的屏幕显示与打印输出。因此编写时必须考虑打印效果例如不要用白字黑底之类的深色背景方案否则打印出来会浪费大量墨水甚至因背景不打印而出现白字看不见的问题可考虑用media print查询为打印单独设定样式如去除装饰性背景、调整字号。五、编写你的第一个 userchrome.cssuserchrome.css用于定制整个 Joplin 界面。由于它影响范围大编写时建议先用开发者工具DevTools检查目标元素的 class 名再写针对性规则。官方在设置项描述中同样将此类 CSS 视为高级功能示例/* 让侧边栏更紧凑 */ .sidebar { font-size: 13px; } /* 自定义工具栏背景 */ .toolbar { background: #2d2d2d !important; color: #eee; }需要特别说明的是userchrome.css作用于应用界面框架而笔记渲染区域仍由userstyle.css控制两者互不干扰可按需组合使用。六、重要警告这些是高级设置样式可能随版本失效官方在文档中给出了明确的免责声明这段文字同时也被写入设置项描述见 builtInMetadata.tsuserstyle.css 和 userchrome.css 是为方便使用而提供的但它们属于高级设置你定义的样式可能从一个版本失效到下一个版本。如果你想使用它们请做好需要定期维护的心理准备。Joplin 团队无法承诺保持应用 HTML 结构稳定。这意味着一件必须接受的事实Joplin 的界面 DOM 结构不在兼容性承诺范围内。应用升级后你依赖的某个 class 名、DOM 层级可能被重构导致样式失效或错乱。因此升级前留意界面是否出现样式异常必要时回到默认样式尽量使用语义明确、较稳定的选择器减少对深层 DOM 结构的依赖为关键样式做好注释与备份便于版本升级后快速修复若样式问题影响使用且无法快速解决删除或重命名这两个文件即可完全恢复 Joplin 默认外观注意重启应用使其生效。七、相关文档与后续阅读配置界面的完整字段说明见 Configuration screen其中 General 页面顶部显示配置目录路径渲染引擎与 Markdown 支持范围可参考 Markdown若希望以编程方式为笔记注入自定义 HTML/CSS可结合插件机制见 Plugins与插件 API 进一步定制渲染结果其能力边界以对应插件文档为准。小结userstyle.css定制渲染后的 Markdown 笔记含打印userchrome.css定制整个应用界面两者都位于配置根目录文件名固定修改后必须完全退出并重启Joplin 才生效最小化到托盘不算退出文件路径以配置 → General 页顶部显示的配置目录为准也可通过外观区块的两个按钮直接打开/创建两个文件均支持标准 CSSuserstyle.css以追加方式覆盖默认样式二者属高级设置界面 DOM 结构不受版本兼容性承诺保护需接受定期维护的现实。【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考