写在前面

Typora 是一款以“所见即所得”著称的 Markdown 编辑器，其简洁优雅的设计赢得了大量开发者和写作者的青睐。然而，Typora 官方并未提供正式的插件系统，这在某种程度上限制了用户对编辑器的深度定制能力。好在开源社区的力量是强大的——通过逆向工程、代码注入以及社区贡献的插件框架，开发者完全可以在 Typora 上实现媲美 IDE 的扩展能力。

本指南将带你从零开始，全面掌握 Typora 插件的开发技能，从最基础的环境搭建、核心框架理解，到实战项目落地、主题定制，最终打造一个专属于自己的 IDE 式写作环境。全文约 2 万字，建议先通读了解全貌，再根据实际需要深入各章节。

重要提示：Typora 官方并未正式提供插件 API，当前社区插件方案通过对 Typora 的程序文件进行修改来实现功能扩展。使用此类方案时，请确保遵守 Typora 软件许可协议，并在个人学习与使用的合理范围内进行。对开源项目的扩展应尽可能通过贡献代码的方式实现，这种方式的可持续性更强。若项目有商业应用需求，建议考虑官方授权的定制方案。

第 1 章 环境准备与基础概念

1.1 为什么需要为 Typora 开发插件？

Typora 的核心优势在于“即时预览”——用户在输入 Markdown 语法时，内容即时渲染为格式化文本，这种无缝体验极大降低了写作时的认知负荷。Typora 原生支持 100+ 种编程语言的语法高亮、LaTeX 数学公式渲染、Mermaid 流程图绘制等基础功能。

然而，对于追求极致效率的开发者而言，原生功能仍存在局限：

  • 多文件管理不足：原生 Typora 无法同时打开多个文档并在标签页间快速切换；

  • 搜索能力有限：缺少跨文件的复杂关键词组合搜索；

  • 编辑增强缺失：没有章节折叠、代码块增强、模板系统等现代化编辑特性；

  • 工作流割裂：与 Git、图床、CI/CD 等开发工具的集成需手动处理。

这正是插件系统的价值所在。通过插件，开发者可以将 Typora 从一个优雅的 Markdown 编辑器，升级为功能完备的技术文档写作平台。

1.2 插件开发现状：核心框架与社区方案

目前，Typora 插件的开发主要围绕一个核心开源项目展开：obgnail/typora_plugin。

该项目为 Typora 提供了超过 60 个内置插件，涵盖标签页管理、多关键词搜索、代码增强、图表支持等功能。项目采用三层架构设计：

  1. 核心基础设施层：提供配置加载、插件加载、共享服务（utils）、国际化等功能；

  2. 插件基类层：定义 IPlugin、BasePlugin、BaseCustomPlugin 三大基类；

  3. 功能插件层：60+ 内置插件 + 用户自定义插件。

所有插件遵循标准的七阶段生命周期模型，通过统一的 API 与 Typora 交互。

1.3 开发环境搭建

1.3.1 基础工具链
工具用途说明
Typora目标编辑器建议版本 ≥0.9.98
Node.jsJavaScript 运行时插件开发的基础环境
npm / yarn包管理工具用于依赖管理
VS Code代码编辑器推荐用于插件开发
Git版本控制获取源码和管理版本
1.3.2 获取插件框架源码

bash

# 克隆项目仓库（建议使用 GitCode 镜像，访问更稳定）
git clone https://gitcode.com/gh_mirrors/ty/typora_plugin

# 或直接下载 ZIP 压缩包
# 访问 https://github.com/obgnail/typora_plugin，选择 "Download ZIP"
1.3.3 安装插件框架

自动安装（推荐） ：

Windows 系统：

bash

# 进入插件 bin 目录
cd typora_plugin/plugin/bin/
# 双击运行 install_windows_amd_x64.exe 或右键以 PowerShell 运行 install_windows.ps1

Linux 系统：

bash

cd typora_plugin/plugin/bin/
sudo chmod +x install_linux.sh && sudo ./install_linux.sh

手动安装（理解其原理，对后续开发有帮助）：

  1. 找到 Typora 安装目录中包含 window.html 的文件夹：

    • 正式版：Typora/resources/window.html

    • 免费版/Beta版：Typora/resources/app/window.html

  2. 将下载的 plugin 文件夹复制到该目录下；

  3. 编辑 window.html，找到 <script src="./app/window/frame.js" defer="defer"></script>，在其后插入：

    html

    <script src="./plugin/index.js" defer="defer"></script>

  4. 保存文件并重启 Typora。

安装完成后，重启 Typora，在编辑区右键菜单中看到“常用插件”选项即表示安装成功。

1.4 开启调试工具

插件开发离不开调试。Typora 基于 Electron，支持使用 Chrome DevTools：

  • Windows / Linux：查看 → 开发者工具显示切换 菜单项打开 DevTools。

  • macOS：帮助 → 启用调试模式，然后右键编辑区选择“检查元素”。

通过 DevTools，你可以：

  • 实时查看和修改 DOM 结构；

  • 在 Console 中执行 JavaScript 代码测试插件逻辑；

  • 使用 Sources 面板给插件代码设置断点调试；

  • 监控网络请求和性能数据。

第 2 章 核心概念：插件系统的三大支柱

在动手开发之前，有必要深入理解 Typora 插件系统的三个核心概念：插件基类体系、生命周期管理、Utils 工具库。掌握了这些，你就掌握了插件开发的“道”。

2.1 插件基类体系：IPlugin → BasePlugin → BaseCustomPlugin

插件系统定义了三个基类，所有插件都必须继承其中之一。

2.1.1 IPlugin —— 一切插件的根基

IPlugin 是所有插件的基类，定义了插件生命周期的契约规范。它通过构造函数接收三个参数并初始化五个实例属性：

javascript

// 构造函数签名
constructor(fixedName, setting, i18n)

// 实例属性
this.fixedName   // string - 插件唯一标识符，如 "window_tab"
this.pluginName  // string - 从配置或 i18n 获取的显示名称
this.config      // object - 从 TOML 配置合并而来的插件设置
this.utils       // object - 40+ 服务模块的统一访问入口
this.i18n        // object - 绑定到当前插件的国际化助手

this.utils 是插件与 Typora 交互的主桥梁，在第 2.3 节会详细介绍。

2.1.2 BasePlugin —— 核心功能插件

BasePlugin 继承自 IPlugin，增加了一个 call(action, meta) 方法：

javascript

class BasePlugin extends IPlugin {
    call(action, meta) {
        // 根据 action 参数执行不同功能
        switch(action) {
            case 'doSomething':
                // 执行某功能
                break;
            case 'doAnother':
                // 执行另一功能
                break;
        }
    }
}

BasePlugin 适用于需要暴露多个动作入口的复杂插件，例如一个右键菜单中有多个子功能项的场景。大多数内置插件（如标签页插件 MarkmapPlugin）都基于此类实现。

2.1.3 BaseCustomPlugin —— 用户自定义插件

BaseCustomPlugin 是为用户编写的简单插件设计的，它实现了 selector/hint/callback 三方法模式：

方法返回值作用
selector(context)CSS 选择器字符串决定插件在何时可用（光标位置匹配时显示）
hint(context)字符串右键菜单中显示的提示文本
callback(anchorNode)void插件被点击时执行的核心逻辑

CustomPlugin 管理器会自动检查 selector 条件，并在匹配时动态显示菜单项。

✅ 选择指南：

  • 简单功能的上下文菜单插件 → 继承 BaseCustomPlugin

  • 需要暴露多个动作入口的复杂插件 → 继承 BasePlugin

  • 两者都不满足？说明你可能需要直接实现 IPlugin

2.2 生命周期方法：插件从加载到执行的完整旅程

理解生命周期是插件开发的关键。每个插件在加载时，loadPlugins 会按固定顺序执行以下生命周期方法：

生命周期执行顺序表
阶段方法必填用途
1beforeProcess()❌数据预加载、配置校验、决定是否继续加载
2style()❌返回 CSS 字符串，注入到文档中
3styleTemplate()❌返回模板配置，用于动态 CSS 生成
4html()❌返回 HTML 字符串，注入到 DOM 中
5hotkey()❌注册键盘快捷键
6init()❌初始化插件状态和数据结构
7process()❌绑定事件监听器，执行主要逻辑
8afterProcess()❌清理和收尾工作
各阶段详解

beforeProcess()：数据准备的哨兵

javascript

async beforeProcess() {
    // 可以异步加载数据
    const data = await fetchSomeData();
    
    // 返回 utils.stopLoadPluginError 可终止插件加载
    if (!data) {
        return this.utils.stopLoadPluginError;
    }
    
    // 其他返回值则继续加载
    this.myData = data;
}

常见的 beforeProcess 用途：从本地文件加载插件所需数据、校验 Typora 版本兼容性（WindowTabPlugin 中有典型实现）、将用户配置的规则别名转换为规范名称（MarkdownLintPlugin 示例）。

style() 与 styleTemplate()：注入 CSS 样式

style() 返回纯 CSS 字符串，适用于简单的静态样式注入：

javascript

style() {
    return `
        .my-plugin-highlight {
            background-color: #ffeb3b;
        }
    `;
}

styleTemplate() 返回模板配置，允许 CSS 值根据插件配置动态计算：

javascript

styleTemplate() {
    return {
        css: `.my-element { color: {{color}}; }`,
        args: { color: this.config.highlightColor || 'blue' }
    };
}

hotkey()：注册快捷键

javascript

hotkey() {
    return [
        { hotkey: "ctrl+shift+s", callback: () => this.doSave() },
        { hotkey: "ctrl+alt+f", callback: () => this.doFormat() }
    ];
}

process()：主要逻辑的舞台

这是大多数插件的核心——绑定事件监听、初始化 UI 组件、注册自定义命令等。

javascript

process() {
    // 监听 Typora 的事件
    document.addEventListener('click', (e) => {
        if (e.target.matches('.my-selector')) {
            this.handleClick(e);
        }
    });
}
⚠️ 生命周期执行的关键注意点

  • 方法可以不实现：所有方法都是可选的，按需实现即可；

  • 执行顺序固定：从 beforeProcess 到 afterProcess 严格按序执行；

  • 支持异步：beforeProcess 支持 async/await，其他方法建议保持同步或谨慎处理异步；

  • 终止机制：beforeProcess 返回 utils.stopLoadPluginError 可以提前终止该插件的整个加载流程，适合在不满足条件时优雅退出。

2.3 Utils 工具库：统一的服务入口

Utils 框架是整个插件系统的核心服务层，它通过混入（Mixin）架构将 40 多种服务整合到一个统一的 utils 对象中。每个插件实例通过 this.utils 访问这些服务。

2.3.1 Utils 整体架构

text

Utils 框架 = 静态工具函数 + 服务 Mixin 模块

  • 静态工具函数：直接通过 this.utils.methodName() 调用，如文件操作、系统信息获取；

  • 服务 Mixin 模块：通过 this.utils.mixinName.methodName() 调用，如 this.utils.notification.show()。

2.3.2 核心 Mixin 服务模块速查
服务模块核心方法典型用途
this.utils.notificationshow(msg)向用户显示通知消息
this.utils.hotkeyHubregister(), unregister()热键注册与管理
this.utils.contextMenuregister(), unregister()右键菜单项注册
this.utils.dialogalert(), confirm(), prompt()对话框控制
this.utils.eventHubpublishEvent(), subscribeEvent()插件间事件通信
this.utils.stateRecordersave(), load()插件状态持久化
this.utils.styleTemplaterregister()动态 CSS 模板管理
this.utils.configOpsget(), set()配置读写操作
this.utils.i18nt()国际化文本翻译
2.3.3 文件系统操作

utils 提供了丰富的文件系统操作方法：

javascript

// 获取用户主目录
const home = this.utils.getHomeDir();

// 获取当前 Typora 编辑的文件路径
const filePath = this.utils.getFilePath();

// 获取临时文件夹路径
const tmp = this.utils.tempFolder;

// 使用 Node.js 核心模块
const path = this.utils.Package.Path;
const fs = this.utils.Package.FsExtra;
2.3.4 运行时环境信息

javascript

// 版本信息
console.log(this.utils.typoraVersion);   // Typora 版本号
console.log(this.utils.nodeVersion);     // Node.js 版本
console.log(this.utils.electronVersion); // Electron 版本
console.log(this.utils.chromeVersion);   // Chrome 版本

// 环境检测
console.log(this.utils.isBetaVersion);   // 是否为 Beta 版
console.log(this.utils.separator);       // 路径分隔符（\ 或 /）
2.3.5 插件间通信与协作

utils 提供了跨插件调用方法，让插件之间可以相互协作：

javascript

// 获取其他插件实例
const tabPlugin = this.utils.getBasePlugin('window_tab');
const custom = this.utils.getCustomPlugin('myPlugin');

// 调用其他插件的方法
this.utils.callPluginFunction('window_tab', 'switchToNext', ...args);

// 生成动态菜单项（根据当前上下文自动判断可用性）
this.utils.updatePluginDynamicActions(fixedName, anchorNode, notInContextMenu);
2.3.6 静态常量与特殊值

utils 定义了几个重要的特殊值：

常量类型说明
utils.nonExistSelector"__non_exist__"插件暂时不可用时返回
utils.disableForeverSelector"__disabled__"插件永久禁用时返回
utils.stopLoadPluginErrorSymbolbeforeProcess 返回此值可停止插件加载
utils.protocolRootstringTypora 内部资源的基础 URL
2.3.7 网络请求处理

开发涉及外部 API 的插件时（如 AI 补全、图床上传），应使用 utils.fetch 而非全局 fetch：

javascript

// ❌ 避免使用（可能遇到跨域限制）
fetch('https://api.example.com/data');

// ✅ 优先使用 utils.fetch（内置代理支持，绕过浏览器安全限制）
this.utils.fetch('https://api.example.com/data', {
    timeout: 10000  // 可配置超时
});

utils.fetch 基于 node-fetch 实现，具有更稳定的网络请求处理能力，尤其适用于 HTTPS 请求场景。

第 3 章 实战：从零开发一个完整插件

理论知识学到手了，是时候动手了。本章将以一个 “选中文本 + 自定义翻译” 插件为例，带你完整走通插件开发的每一步。

3.1 目标规划：我们要做一个什么插件？

功能描述：在 Typora 中选中一段文本，通过右键菜单调用“中英互译”，从第三方翻译 API 获取结果，并弹窗或直接替换原文本。

这包含了插件开发的核心要素：上下文感知（selector）、右键菜单集成（hint/callback）、网络请求（utils.fetch）、用户交互（utils.dialog）。

3.2 文件结构创建

bash

# 进入自定义插件目录
cd typora_installation/plugin/custom/plugins/

# 创建你的插件文件
touch translate.js

自定义插件必须放在 ./plugin/custom/plugins/ 目录下，LoadPlugins 函数会自动扫描该目录加载插件。

3.3 编写插件模板

javascript

// translate.js
class TranslatePlugin extends BaseCustomPlugin {
    // 静态方法：返回 CSS 选择器，决定插件何时可用
    selector = () => {
        // 当有文本被选中时，此插件才出现在右键菜单
        return window.getSelection().toString().trim().length > 0 
            ? ':root'   // 任意位置都有效
            : this.utils.nonExistSelector;  // 返回特殊值表示不可用
    };

    // 静态方法：右键菜单显示的提示文字
    hint = () => {
        return '翻译选中文本 (中英互译)';
    };

    // 回调函数：用户点击时执行的核心逻辑
    callback = async (anchorNode) => {
        const selectedText = window.getSelection().toString().trim();
        if (!selectedText) return;

        try {
            const translated = await this.translateText(selectedText);
            this.utils.dialog.alert(`翻译结果：\n${translated}`);
        } catch (err) {
            this.utils.dialog.alert('翻译失败：' + err.message);
        }
    };

    // 辅助方法：调用翻译 API
    async translateText(text) {
        // 检测语言，决定翻译方向
        const isChinese = /[\u4e00-\u9fa5]/.test(text);
        const targetLang = isChinese ? 'en' : 'zh-CN';

        // 使用免费翻译 API（示例使用 DeepL 风格接口，实际请申请有效 key）
        // 生产环境请在全局配置中存储 API Key，避免硬编码
        const url = `https://api.mymemory.translated.net/get?q=${encodeURIComponent(text)}&langpair=${isChinese ? 'zh|en' : 'en|zh'}`;
        
        const response = await this.utils.fetch(url);
        const data = await response.json();
        
        if (data && data.responseData && data.responseData.translatedText) {
            return data.responseData.translatedText;
        }
        throw new Error('未获取到翻译结果');
    }
}

module.exports = { plugin: TranslatePlugin };

3.4 关键代码深度解析

selector() 方法的工作原理：

selector 返回的 CSS 选择器决定了右键菜单何时显示该插件项。CustomPlugin 管理器会持续检查当前光标位置的元素是否匹配该选择器。特殊返回值 utils.nonExistSelector 会让插件从菜单中隐藏。

callback(anchorNode) 参数：

anchorNode 是触发右键菜单时的锚点节点，即选区的起始锚点。对于需要操作 DOM 的插件来说，这个参数非常有用——比如要在光标位置插入内容，就可以基于 anchorNode 定位。

utils.fetch 的优势：

本插件中使用 this.utils.fetch 而非全局 fetch，因为前者基于 node-fetch 库实现，能完全绕过浏览器安全限制，内置代理支持，且可配置超时机制。

3.5 测试与调试

  1. 重启 Typora；

  2. 打开一个 Markdown 文档，选中一段文本（中英文皆可）；

  3. 右键点击选中的文本，在右键菜单中看到“翻译选中文本 (中英互译)”菜单项；

  4. 点击菜单项，等待 API 响应，弹出翻译结果对话框。

若菜单项未出现，请检查：

  • 插件文件是否在正确的路径 (plugin/custom/plugins/)；

  • 模块导出格式是否正确：module.exports = { plugin: YourPluginClass }；

  • Typora 是否已正确加载插件系统（右键菜单中有“常用插件”选项）；

  • 是否选中了有效的文本（selector 条件满足）。

3.6 进阶功能扩展思路

  • 增加快捷键支持：在插件类中实现 hotkey() 方法，注册 ctrl+shift+t 直接触发翻译；

  • 配置 API Key：在全局配置文件中添加 API Key 配置项，通过 this.config 读取；

  • 多翻译引擎支持：在右键菜单中设计二级菜单，让用户选择使用哪个翻译服务（通过 BasePlugin 的 call() 方法实现多 action）；

  • 替换原文模式：增加一个选项让用户选择“显示对话框”还是“直接替换选中文本”。

学习要点总结：本实战体现了 BaseCustomPlugin 的典型开发模式——通过 selector 控制可用性，hint 提供菜单文案，callback 实现核心逻辑。同时演示了如何利用 utils.fetch 发起网络请求、utils.dialog 进行用户交互，以及节点参数 anchorNode 的基础应用。掌握这些模式后，你就可以举一反三开发各类上下文感知插件了。

第 4 章 深入原理：插件系统是如何工作的？

如果你不只是想用插件，还想真正理解它“为什么这样工作”，这一章是为你准备的。理解了 Typora 的底层架构，你在插件开发中遇到的问题就能迎刃而解。

4.1 Typora 基于 Electron 的本质

Typora 本身是一个 Electron 应用。Electron 采用“主进程 + 渲染进程”的双进程架构：主进程负责创建窗口和管理应用生命周期；每个窗口运行独立的渲染进程，本质上是一个 Chromium 浏览器实例。

关键点在于：

  • Typora 的编辑器界面就是渲染进程中运行的 HTML/JS 代码；

  • 插件通过对渲染进程的 DOM 和 JavaScript 运行环境进行修改，实现功能扩展。

4.2 启动初始化：从 entry() 到 LoadPlugins

插件系统的启动入口是 plugin/index.js，它注册了一个 window.addEventListener("load", ...) 监听器，在 Typora 窗口完全加载后执行初始化。

整个初始化流程如下图所示（流程图描绘了从监听 Load 事件到最终完成所有插件加载的完整路径）：

entry() 函数按顺序执行以下关键任务：

  1. 环境一致性：require('polyfill.js') 补全缺失的现代 JS 特性；

  2. 组件注册：require('components.js') 注册自定义 Web Components（如 fast-window、fast-dialog）；

  3. 版本兼容性检查：调用 utils.compareVersion() 检测 Typora 版本，低于 0.9.98 则静默中止；

  4. 配置加载：加载全局配置和插件启用状态；

  5. Mixin 初始化：实例化 utils 框架中的所有 Mixin 服务模块；

  6. loadPlugins 启动：遍历所有插件并执行其生命周期方法。

4.3 注入技术：修改 window.html 的意义

插件框架的核心注入点是对 window.html 的修改——这是 Typora 窗口的初始 HTML 文件。通过在 frame.js 脚本后插入 <script src="./plugin/index.js">，插件代码得以在 Typora 自身核心代码加载完成后立即执行。

这种注入方式类似于浏览器扩展脚本（Tampermonkey），其优势在于：

  • 加载时机精确：在 Typora 核心功能初始化后立即执行，不干扰原生流程；

  • 环境完整继承：插件代码可以直接访问 Typora 暴露的全局对象和方法；

  • 易于管理：通过一个 index.js 入口统一管理所有插件模块。

4.4 事件中心与通信机制

成熟的插件系统需要完善的事件分发机制。在 Typora 插件框架中，EventHub 服务模块（通过 utils.eventHub 访问）提供了发布-订阅模式：

javascript

// 订阅事件（在插件 init() 或 process() 中）
this.utils.eventHub.subscribeEvent('document:loaded', (data) => {
    console.log('文档加载完成', data);
});

// 发布事件（任何插件均可调用）
this.utils.eventHub.publishEvent('document:loaded', { path: filePath });

这种模式允许插件在不同时机注入自定义逻辑，实现插件间的松耦合协作。

4.5 “注入 vs 原生 API”——两种开发范式的选择

维度官方 API注入式扩展
稳定性随官方更新稳定可能因 Typora 版本更新失效
能力边界官方定义的功能集合理论上无限制，可访问 Electron 完整能力
开发复杂度低，文档完备高，需逆向分析 Typora 内部结构
合规风险低需注意软件许可条款

由于 Typora 官方未提供正式插件 API，当前社区方案基于注入式扩展。开发者应当了解其技术本质，在适当范围内使用。

4.6 多版本兼容性设计：如何让插件“活得更久”

不同 Typora 版本的内部实现可能发生变化，导致插件失效。插件框架通过以下机制应对兼容性问题：

  1. 版本检测：在 beforeProcess() 中调用 utils.compareVersion() 检测版本并决定是否继续加载；

  2. API 兼容层：utils 框架对不同 Typora 版本的差异进行了封装；

  3. 渐进式降级：对于可能不存在的方法，通过特性检测（if (typeof obj.method === 'function')）实现优雅降级。

第 5 章 生态资源与进阶开发

5.1 社区插件精选：站在巨人的肩膀上

了解了插件的开发原理，我们再来看看社区已经有哪些优秀的现成插件，这些项目本身也是很好的学习素材。

插件名称功能描述学习要点
window_tab完整的标签页管理了解如何管理多文档状态
search_multi多关键词文件搜索正则表达式处理、跨文件搜索实现
collapse_paragraph章节折叠DOM 操作、节点隐藏/展开
md_padding中英文混排自动加空格文本处理、选区操作
slash_commands类 Notion 的斜杠命令快捷命令注册、代码片段插入
echarts / chart图表组件支持第三方库集成方式
markmap思维导图生成数据结构转换、树形图渲染

这些插件均可在 plugin/plugins/ 或 plugin/custom/plugins/ 目录下找到源码，是理解插件开发模式的绝佳范例。

5.2 进阶功能探索：实现“IDE 级”体验

要打造真正的 IDE 式写作环境，可以尝试以下方向：

AI 补全集成：调用外部 AI API 实现代码补全、文本续写。核心挑战在于网络请求处理和光标控制（Typora 使用 rangy 库管理选区，可通过 utils.getRangy() 获取）。实现要点：

javascript

// 获取光标管理对象
const rangy = this.utils.getRangy();
const selection = rangy.getSelection();
// 保存光标位置，插入内容后恢复
const savedRange = selection.getRangeAt(0).cloneRange();
// ... 插入内容 ...
selection.setSingleRange(savedRange);

外部程序联动：调用系统命令或打开外部应用，例如通过 utils.execCommand 调用 Git 提交、上传图床、启动 Pandoc 转换等。

自定义快捷键体系：通过 hotkey() 方法注册全局快捷键，再配合 utils.hotkeyHub 实现快捷键的启用/禁用开关。

5.3 主题定制与 CSS 扩展

除了功能插件，视觉层面的定制同样重要。Typora 的视觉定制分为三个层级：

层级一：自定义 CSS 覆盖

Typora 支持通过 base.user.css 文件添加全局样式，所有主题都会继承这些样式。存放在 theme 文件夹下的 {current-theme}.user.css 则只对当前主题生效。

css

/* 示例：base.user.css */
:root {
    --custom-font: 'JetBrains Mono', monospace;
}

body {
    font-family: var(--custom-font);
}

/* 自定义代码块样式 */
.md-fences {
    border-radius: 8px;
    background-color: #282c34;
}

/* 调整写作区域宽度 */
#write {
    max-width: 1000px;
}

层级二：完整主题开发

主题是一套完整的 CSS 样式表，定义了从页面背景到代码块的所有视觉呈现。开发主题时可以：

  • 参考官方主题库 theme.typora.io 和社区项目 typora-theme-gallery 的设计模式；

  • 使用主题文件夹下的测试工具：将样式写入 test.css，在浏览器中预览渲染效果；

  • 主题命名使用小写字母，如 mytheme.css。

层级三：通过插件注入动态样式

插件可以在 style() 或 styleTemplate() 中注入 CSS，甚至可以根据配置动态生成样式。

5.4 性能优化建议

插件系统可能影响编辑器性能，开发中需注意：

  • 延迟非关键操作：避免在 process() 中立即执行大量计算，可使用 setTimeout 或 requestIdleCallback 延迟执行；

  • 批量 DOM 操作：使用 DocumentFragment 或字符串拼接减少重排重绘；

  • 事件防抖节流：对高频事件（如键盘输入、滚动）使用 utils.debounce 或 utils.throttle；

  • 避免频繁的 utils.getFilePath() 调用：该方法会访问文件系统，频繁调用影响性能。

第 6 章 进阶实践：构建 IDE 级写作环境

掌握了插件开发的完整技能，接下来我们把这些能力组合起来，从零开始构建一个真正属于你自己的 IDE 级写作环境。

6.1 全方位插件组合方案

IDE 级的写作体验不仅仅是安装几个插件，而是一套体系化的功能组合。以下是推荐的插件组合清单：

分类推荐插件功能
窗口管理window_tab多标签页管理，支持拖拽排序
内容组织collapse_paragraph章节折叠，管理长文档结构
效率输入slash_commands斜杠命令快速插入模板和片段
代码增强fence_enhance代码块复制、折叠、格式美化
搜索search_multi跨文件多关键词搜索
可视化markmap / echarts思维导图和图表绘制
文件管理templater模板快速创建文件

6.2 工作流自动化：效率 10 倍的秘密

单文件写作流：

  • 使用 slash_commands 快速插入代码块、表格和数学公式模板；

  • 使用 fence_enhance 的复制功能快速分享代码片段；

  • 使用 md_padding 一键格式化中英文混排。

多文件项目流：

  • 通过 window_tab 管理多个相关文档，使用 Ctrl+Tab 快速切换；

  • search_multi 实现项目级别的全局搜索和替换；

  • templater 自动生成新文件的标准结构。

发布流程：

  • 图床自动上传（自定义上传器）；

  • 调用 Pandoc 导出多种格式（通过外部命令调用）；

  • 一键博客发布（自定义插件集成博客 API）。

6.3 键盘党进阶：打造纯键盘驾驶体验

配合快捷键和 Vim 风格操作，完全脱离鼠标不是梦：

  1. 快捷键体系规划：

    • Ctrl+Tab 切换标签页；

    • Ctrl+W 关闭当前标签；

    • Ctrl+Shift+B 中英文格式化；

    • Ctrl+Shift+F 跨文件搜索。

  2. 结合系统级工具（可选）：配合 espanso（跨平台文本扩展工具）或 AutoHotkey（Windows）实现更复杂的文本替换和自动化。

6.4 自定义 CSS：让编辑器长成你想要的样子

一个现代化的 IDE 风格主题配置示例（放入 base.user.css）：

css

/* 字体与版式 */
body {
    font-family: 'Inter', 'JetBrains Mono', -apple-system, BlinkMacSystemFont, monospace;
    font-size: 16px;
    line-height: 1.6;
}

/* 代码块美化 */
.md-fences {
    background-color: #1e1e2e;
    border-radius: 12px;
    padding: 16px;
    font-family: 'JetBrains Mono', 'Fira Code', monospace;
    font-size: 14px;
}

/* 标题层次优化 */
h1 { font-size: 2.2em; border-bottom: 3px solid #3b82f6; padding-bottom: 0.3em; }
h2 { font-size: 1.8em; border-bottom: 1px solid #e5e7eb; }
h3 { font-size: 1.5em; }

/* 引用块样式 */
blockquote {
    border-left: 4px solid #3b82f6;
    background: #f8fafc;
    padding: 0.5em 1em;
    border-radius: 0 8px 8px 0;
}

/* 表格优化 */
table {
    border-collapse: separate;
    border-spacing: 0;
    width: 100%;
}

th, td {
    border: 1px solid #e5e7eb;
    padding: 10px 12px;
}

th {
    background: #f1f5f9;
    font-weight: 600;
}

/* 侧边栏宽度调整 */
.sidebar-tab {
    width: 280px;
}

/* 适配暗色模式（自动检测系统主题） */
@media (prefers-color-scheme: dark) {
    .md-fences {
        background-color: #0f172a;
    }
    blockquote {
        background: #1e293b;
    }
    th {
        background: #334155;
    }
}

调试技巧：在 Typora 中通过 DevTools（查看 → 开发者工具显示切换）可以实时检查和调试 CSS 样式，找到你想要修改的目标元素类名。

6.5 进阶：开发一个完整生产力插件（任务清单插件）

掌握了基础，我们来挑战一个完整的自开发插件：任务清单进度统计插件。

功能目标：在文档中统计所有 - [ ] / - [x] 任务，在状态栏显示完成进度百分比。

javascript

// task_progress.js
class TaskProgressPlugin extends BaseCustomPlugin {
    // 任何地方都可用
    selector = () => ':root';
    hint = () => '统计任务进度';

    callback = async () => {
        const stats = this.countTasks();
        this.utils.dialog.alert(
            `📋 任务统计\n\n` +
            `总任务数: ${stats.total}\n` +
            `已完成: ${stats.completed}\n` +
            `待完成: ${stats.pending}\n` +
            `进度: ${stats.percentage}%`
        );
    };

    countTasks() {
        const editorContent = document.querySelector('#write').innerHTML;
        // 正则匹配任务列表格式
        const taskPattern = /<li class="task-list-item">\s*<input type="checkbox"(?: checked)? disabled>/g;
        const completedPattern = /<li class="task-list-item">\s*<input type="checkbox" checked disabled>/g;
        
        const total = (editorContent.match(taskPattern) || []).length;
        const completed = (editorContent.match(completedPattern) || []).length;
        
        return {
            total,
            completed,
            pending: total - completed,
            percentage: total === 0 ? 0 : Math.round((completed / total) * 100)
        };
    }
}

module.exports = { plugin: TaskProgressPlugin };

这个插件展示了如何：

  • 通过 DOM 获取编辑器内容（#write 是 Typora 编辑区域的主容器 ID）；

  • 使用正则表达式解析 Markdown 渲染后的 HTML；

  • 组织数据并以对话框形式反馈用户。

第 7 章 替代方案与横向对比

在深入 Typora 插件开发后，你可能会思考：“这条路值得走吗？有没有更好的选择？” 本章客观对比主流方案，帮助你做出明智选择。

7.1 各方案横向对比

方案插件生态开发门槛插件能力适用场景
Typora + 社区插件60+ 插件，社区维护中等Electron 级能力，几乎无限已有 Typora 使用习惯，需要适度增强
VS Code + Markdown 插件极其丰富，官方支持低（TypeScript 全生态）取决于 VS Code API已经在用 VS Code 的开发者
Obsidian1000+ 插件，官方 API低，文档完善API 完善，限制较多知识管理 + 重度插件需求
Yank Note (yn)支持自定义插件中等内置代码执行、加密等高级功能需要代码执行 + 技术文档一体化

数据参考：截至 2025 年，Yank Note 在 GitHub 上已收获 8.8K+ Star，被称为“Typora 终极替代者”，其在代码执行、加密笔记、绘图引擎等方面具有独特优势。

7.2 何时选择 Typora 插件方案？

  • ✅ 你已经深度使用 Typora，并希望保持其优雅的编辑体验；

  • ✅ 你需要中等程度的增强功能（标签页、搜索、图表）；

  • ✅ 你具备一定的 JavaScript/Node.js 能力，不介意“注入式”方案的技术本质。

7.3 何时考虑其他方案？

  • 你需要官方 API 支持和高稳定性保障 → Obsidian；

  • 你希望在代码编辑器中一体化管理 Markdown 文档 → VS Code；

  • 你需要代码执行、加密笔记、实时图表渲染等开箱即用的功能 → Yank Note；

  • 你需要云端协作和多端同步 → 语雀 / Notion。

个人建议：如果你热爱折腾且对 Typora 情有独钟，插件开发是一条很有成就感的路径。如果你追求稳定和官方支持，Obsidian 或 VS Code 方案更稳妥。无论选择哪种工具，工具最终服务于内容创作，不必在工具本身上耗费过多精力。我见过不少开发者花 3 个月打磨插件配置，却只写了 3 篇博客——这就是典型的“工具控陷阱”。把你的开发热情留在真正提升写作效率的地方，才是插件开发的初心。

附录

A. 常用快捷键速查表

快捷键功能
Ctrl+Tab / Ctrl+Shift+Tab切换/反向切换标签页
Ctrl+W关闭当前标签页
Ctrl+鼠标滚轮在标签页间滚动切换
Ctrl+Shift+B中英文混排格式化
Ctrl+Shift+F跨文件搜索（如果安装了 search_multi）
Ctrl+Shift+P打开搜索框
Ctrl+Shift+1~6快速调整标题级别

B. 配置文件结构速查表

text

Typora 安装目录/
├── window.html                  # 核心注入点
├── plugin/                      # 插件根目录
│   ├── index.js                 # 插件系统入口
│   ├── global/                  # 核心基础设施
│   │   ├── core/                # 核心模块（生命周期、utils、polyfill）
│   │   └── settings/            # 全局配置文件（TOML 格式）
│   ├── plugins/                 # 内置插件（BasePlugin 实现）
│   └── custom/                  # 用户自定义插件
│       └── plugins/             # 在此处放置自定义插件 JS 文件
└── themes/                      # 主题文件目录
    ├── {theme-name}.css         # 主题 CSS 文件
    ├── base.user.css            # 全局用户自定义样式
    └── {theme-name}.user.css    # 主题特定自定义样式

C. 参考资源

写在最后

Typora 插件开发是一条充满挑战但也乐趣无穷的道路。从理解 Electron 应用架构，到掌握基类和生命周期，再到亲手写出第一个属于自己的插件——这是一次真正“由用户变为创造者”的蜕变。

本指南旨在为你提供一份系统性的知识地图，但真正的成长始终来自实践。不妨就从今天开始，尝试开发一个解决你自己写作痛点的小插件。不必追求完美，先跑通一个最简单的功能，看看它是否真的提升了你的写作效率——这才是衡量插件价值的唯一标准。

# mfc # c++
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

开源鸿蒙跨平台直播｜napigen 开源鸿蒙跨端实践：打通 Flutter 与 ArkTS

avatar AtomGit开源社区
cover

玩转 AtomCode！AtomGit「码动四季・开源同行」夏季征稿获奖名单出炉！

avatar AtomGit开源社区
cover

榜单出炉！AtomGit「源启盛夏」暑期开源成长计划正式收官

avatar AtomGit开源社区