React 19 打造本地 Markdown 笔记编辑器:代码高亮、Mermaid 图表、全文搜索实战指南

0 阅读7分钟

工具狮 (Toolion) · Markdown 编辑器
技术栈:React 19 + TypeScript + Vite + Tailwind CSS · 存储:IndexedDB / localStorage · 渲染:marked + highlight.js + mermaid
支持中英文双语 · 桌面端与移动端自适应 · 纯前端本地运行,无需后端


一、文章摘要

本文介绍一款基于 React 19 的纯前端 Markdown 笔记编辑器,全部数据存储于浏览器本地(IndexedDB + localStorage),无需联网即可使用。核心功能包括 Markdown 实时预览、17 种编程语言语法高亮、Mermaid 流程图/时序图渲染、全文笔记搜索、查找替换、文档大纲跳转、标签分类筛选、Markdown/JSON 导入导出、深浅色主题切换、中英文国际化及移动端自适应。适合前端开发者参考本地优先(local-first)应用的开发实践。

关键词:React Markdown 编辑器、本地 Markdown 笔记、marked highlight.js、Mermaid 渲染、IndexedDB 存储、React 19 前端项目、Markdown 全文搜索


二、前言

Markdown 因轻量、易读、易转换的特性,成为技术文档、知识笔记与博客写作的主流格式。市面上优秀的 Markdown 编辑器众多,但许多依赖云端同步,隐私与离线使用受限;或功能过重、加载缓慢。

本文介绍的是 Toolion 系列工具中的 Markdown 编辑器(项目地址:toolion.cn/markdown-ed… Markdown 笔记应用。经重构后,编辑器新增了代码语法高亮、Mermaid 流程图渲染、全文搜索、查找替换、文档大纲、标签分类、Markdown/JSON 导入导出、深色模式、移动端适配等多项实用功能,全部数据本地存储,无需联网即可使用。


三、核心功能全景

模块功能点说明
编辑所见即所得预览左侧编辑、右侧实时预览,GFM 语法支持
格式化工具栏加粗、斜体、删除线、标题、引用、列表、任务列表、链接、图片、行内代码、代码块、表格、分割线一键插入/包裹 Markdown 语法
代码高亮highlight.js支持 JavaScript/TypeScript/Python/Java/C/C++/C#/Go/Rust/XML/CSS/JSON/YAML/Markdown/SQL/Bash 等 17 种语言
图表渲染mermaid原生渲染流程图、时序图、类图等,随主题切换深浅色
安全XSS 净化基于 DOMParser 的白名单过滤,移除 script/iframe 等危险标签与事件属性
笔记管理新建/编辑/删除/排序支持按更新时间、创建时间、标题排序,标题重复提醒
标签系统标签管理、按标签筛选每个标签自动着色,支持多标签
全文搜索防抖搜索、命中高亮、摘要预览同时匹配标题、正文、标签,结果以模态框展示
查找替换查找上一个/下一个、单独替换、全部替换编辑器内嵌查找替换栏,显示匹配索引
文档大纲H1-H6 标题大纲点击大纲项直接跳转至对应行并滚动到视图中
导入导出导出单个 .md、全部备份为 JSON、导入 .md、导入备份、拖拽导入离线数据可完全备份与迁移
持久化IndexedDB + localStorage 双保险自动防抖保存(1s),页面隐藏时立即持久化
主题深色/浅色模式CSS 变量主题,支持跟随系统主题切换
国际化中文 / 英文界面全双语,可一键切换
快捷键Ctrl+B/I/K/N/F/H/S/E、Tab 缩进、智能回车提升键盘党编辑效率
智能粘贴代码自动识别并包裹为代码块粘贴 3 行以上疑似代码时自动添加语言围栏
移动端响应式布局、编辑/预览切换、侧边栏抽屉适配手机与平板
统计字符数、行数底部状态栏实时显示

在这里插入图片描述 在这里插入图片描述 在这里插入图片描述


四、技术选型

技术版本用途
React19.2.6UI 框架,函数组件 + Hooks
TypeScript6.0.2静态类型检查
Vite8.0.12构建工具与开发服务器
Tailwind CSS3.4.19原子化样式
marked18.0.5Markdown 解析与 HTML 渲染
highlight.js-代码块语法高亮
mermaid-流程图/时序图等图表渲染
idb-keyval-IndexedDB 键值存储(笔记持久化)
react-icons (Fi)5.6.0图标集
React 19 新特性startTransition状态更新不阻塞输入,保证编辑流畅

五、重点功能详解

5.1 Markdown 渲染与 XSS 安全

使用 marked 解析 Markdown,并自定义 Renderer.code 处理代码块:识别 mermaid 语言围栏渲染图表,其余交给 highlight.js 语法高亮;未识别语言则按纯文本转义。

渲染后的 HTML 通过 sanitizeHtml 做白名单过滤:

  • 移除 script、iframe、object、embed、form、input、button、link、meta、base 等标签
  • 移除 style 标签(SVG 内除外)
  • 过滤 javascript: 链接,其余外部链接自动加 target="_blank" 和 rel="noopener noreferrer"
  • 移除所有 on* 事件属性与 srcdoc
  • 给 table 包裹滚动容器,防止宽表撑破布局

5.2 代码语法高亮与 Mermaid 图表

注册 17 种 highlight.js 语言及其常见别名(如 js→javascript、tsx→typescript、yml→yaml、htm/html/vue→xml)。代码块高亮主题随深色/浅色模式切换,通过 CSS 变量(--hl-keyword、--hl-string 等)适配配色。

Mermaid 图表在预览阶段被提取,调用 mermaid.render 生成 SVG 替换原 <pre><code>,渲染失败时回退为高亮代码块并提示语法错误。

5.3 本地持久化(IndexedDB 优先,localStorage 兜底)

笔记数据结构:

interface Note {
  id: string;
  title: string;
  content: string;
  tags: string[];
  createdAt: string;
  updatedAt: string;
}
  • 首次加载优先从 IndexedDB(me-notes)读取;若为空则尝试 localStorage 迁移并写回 IndexedDB
  • 内容变更后 800ms 防抖写入,同时每 1s 持久化一次完整列表
  • pagehide 事件立即强制保存,保证页面关闭时数据不丢失

5.4 全文搜索与命中高亮

标题栏与模态框均提供搜索入口,输入后 150ms 防抖触发,匹配范围包含标题、正文、标签。结果按更新时间倒序排列,命中片段通过 getSnippet 截取并用 highlightText 用 <mark> 标记,点击结果直接打开对应笔记。

5.5 查找替换与大纲

  • 查找替换栏嵌入编辑器上方,支持上一个/下一个跳转、单个替换、全部替换,并显示 当前/总数 索引
  • 大纲面板解析 debouncedContent 中的 H1-H6 标题,排除代码块内的伪标题,点击条目可定位到正文对应行并滚动

5.6 导入导出

操作格式说明
导出单笔记.md以笔记标题命名,下载纯 Markdown 文本
导出全部备份.json包含版本号、导出时间与全部笔记数组
导入备份.json去重校验,ID 冲突自动重新生成
导入 Markdown.md / .markdown文件名作为标题,内容写入新笔记
拖拽导入文件拖入页面自动识别 JSON 备份或 Markdown 文件

5.7 移动端适配

720px 以下触发移动端布局:

  • 顶部隐藏搜索框,改为搜索按钮弹出模态框
  • 底部/顶部出现“编辑器 / 预览”分段切换,两者互斥显示
  • 侧边栏变为可拉开的抽屉,配合半透明遮罩
  • 输入字体自动放大至 16px,防止 iOS 双击缩放

六、核心代码片段

6.1 自定义代码渲染器(marked + highlight.js)

const markedRenderer = new marked.Renderer();
(markedRenderer as any).code = function (...args: any[]) {
  let codeText = '';
  let langRaw = '';
  const first = args[0];
  if (typeof first === 'string') {
    codeText = first;
    langRaw = typeof args[1] === 'string' ? args[1] : '';
  } else if (first && typeof first === 'object') {
    codeText = first.text || '';
    langRaw = first.lang || '';
  }

  const lang = (langRaw || '').trim().split(/\s+/)[0].toLowerCase();
  if (lang === 'mermaid') {
    return `<pre><code class="language-mermaid">${escapeHtml(codeText)}</code></pre>`;
  }

  const validLang = lang && hljs.getLanguage(lang) ? lang : '';
  let highlighted = '';
  if (codeText) {
    if (validLang) {
      try {
        highlighted = hljs.highlight(codeText, { language: validLang, ignoreIllegals: true }).value;
      } catch {
        highlighted = escapeHtml(codeText);
      }
    } else {
      highlighted = escapeHtml(codeText);
    }
  }
  const langClass = validLang || 'plaintext';
  return `<pre><code class="hljs language-${langClass}">${highlighted}</code></pre>`;
};
marked.use({ renderer: markedRenderer });

6.2 防抖自动保存

useEffect(() => {
  if (!isLoaded) return;
  window.clearTimeout(storageTimerRef.current);
  storageTimerRef.current = window.setTimeout(() => {
    set('me-notes', notes).catch(console.error);
    try { localStorage.setItem('me-notes', JSON.stringify(notes)); } catch { }
  }, 1000);
  return () => window.clearTimeout(storageTimerRef.current);
}, [notes, isLoaded]);

6.3 查找下一个与循环匹配

const findNext = useCallback(() => {
  if (matches.length === 0) return;
  const ta = textareaRef.current;
  if (!ta) return;
  const selStart = ta.selectionStart;
  let next = matches.findIndex(m => m > selStart);
  if (next === -1) next = 0;
  setMatchIndex(next);
  ta.focus();
  ta.setSelectionRange(matches[next], matches[next] + findText.length);
}, [matches, findText]);

七、快速上手

7.1 环境要求

  • Node.js 18+
  • pnpm / npm / yarn

7.2 安装与运行

# 进入项目目录
cd apps/markdown-editor

# 安装依赖
npm install

# 启动开发服务器(默认 http://localhost:5173)
npm run dev

# 生产构建
npm run build

# 预览构建产物
npm run preview

# 代码检查
npm run lint

7.3 项目结构

apps/markdown-editor/
├── index.html
├── vite.config.ts
├── tailwind.config.js
├── postcss.config.js
├── src/
│   ├── main.tsx
│   ├── App.tsx          # 主应用:编辑器、预览、侧边栏、搜索、导入导出等
│   ├── index.css        # Tailwind 基础样式 + 自定义主题变量
│   ├── theme.d.ts
│   └── i18n/
│       ├── I18nContext.tsx   # 双语国际化上下文
│       ├── zh.ts             # 中文语言包
│       └── en.ts             # 英文语言包
├── tsconfig.json
└── package.json

八、总结与展望

此次重构将 Toolion Markdown 编辑器从一个基础的写作工具,提升为一款具备代码高亮、Mermaid 图表、全文搜索、查找替换、文档大纲、标签分类、多格式导入导出与移动端适配的本地笔记应用。所有数据均存储在浏览器本地,无需后端,天然适合隐私敏感场景与离线环境。

该工具现已上线:toolion.cn/markdown-ed…