【React 插件】@uiw/react-md-editor 使用教程：从基础使用到自定义扩展

1.背景

@uiw/react-md-editor 是一款基于 React 和 TypeScript 的轻量级 Markdown 编辑器插件。

它支持实时预览、GitHub 风味 Markdown 语法、暗黑模式、工具栏自定义等核心功能，同时提供丰富的扩展接口（如自定义命令、插件集成）。

其基于 textarea 的封装设计，不依赖 CodeMirror/Monaco 等重型编辑器，性能优异且易于集成，专为现代 Web 应用设计。

本文将从基础安装到高级配置，详细介绍其核心用法与优化技巧。

2.快速安装

安装依赖通过 npm 或 yarn、pnpm 安装核心包：

bash 复制代码

npm install @uiw/react-md-editor
# 或
pnpm add @uiw/react-md-editor
# 或
yarn add @uiw/react-md-editor

3.基础使用

3.1 基础组件示例。

js 复制代码

import { useState } from 'react';
import MDEditor from '@uiw/react-md-editor';

const textSample = `# 欢迎使用 Markdown 编辑器！
这是 **React Markdown Editor** 的一个示例。
## ✨ 功能
- 实时预览
- 支持自定义样式
- 代码高亮
- 自动聚焦到文本末尾

## 📦 示例代码

\`\`\`javascript
function hello() {
  console.log("Hello, world!");
}
\`\`\`
`;

function App() {
  const [value, setValue] = useState<string>(textSample);
  return (
    <MDEditor
      value={value}
      onChange={(val) => setValue(val ?? '')}
      height={800}
    />
  );
}

export default App;

关键参数：

value：绑定 Markdown 文本内容。
onChange：监听文本变化并更新状态

效果：

左侧编辑区输入 Markdown，右侧实时预览渲染后的 HTML。
支持快捷键（如 Ctrl+B 加粗、Ctrl+I 斜体）。

4.核心功能详解

4.1 实时预览与模式切换

默认行为：编辑器自动分栏显示编辑区和预览区。

禁用预览 ：通过 preview="edit" 强制显示单栏编辑模式。

js 复制代码

import { useState } from 'react';
import MDEditor from '@uiw/react-md-editor';

function App() {
  const [value, setValue] = useState<string>('hello world');
  return (
    <MDEditor
  	  value={value}
      onChange={(val) => setValue(val ?? '')}
      height={800}
      preview="edit"
	/>
  ) 
};

纯预览模式 ：使用 <MDEditor.Markdown source={value} /> 单独渲染 Markdown

js 复制代码

import { useState } from 'react';
import MDEditor from '@uiw/react-md-editor';

function App() {
  const [value, setValue] = useState<string>('hello world');
  return (
   	<MDEditor.Markdown source={value} />
  ) 
};

4.2 自定义工具栏

通过 commands 和 extraCommands 扩展或隐藏工具栏按钮：

ps：

如果需要隐藏 commands 与 extraCommands 功能，可以把对应的值是设置为[]

eg: commands={[]}

js 复制代码

import { getCommands, getExtraCommands } from '@uiw/react-md-editor/commands-cn';
 
<MDEditor
  commands={[...getCommands()]} // 基础命令（加粗、斜体等）
  extraCommands={[...getExtraCommands()]} // 扩展命令（表格、任务列表等）
/>

4.3 自定义命令

实现 customCommand 接口添加按钮：

js 复制代码

import { getCommands, getExtraCommands } from '@uiw/react-md-editor/commands-cn';
import type { ICommand, TextState, TextAreaTextApi } from '@uiw/react-md-editor';
import MDEditor from '@uiw/react-md-editor';

const customCommand: ICommand = {
  name: 'title3',
  keyCommand: 'title3',
  buttonProps: { 'aria-label': '插入 H3 标题' },
  icon: (
    <svg width="12" height="12" viewBox="0 0 20 20" fill="none">
      <path d="M3 4v12M3 10h8M11 4v12M17 8v4M15 10h4" stroke="currentColor" strokeWidth="1.2"/>
    </svg>
  ),
  execute: (_: TextState, api: TextAreaTextApi) => {
    api.replaceSelection('### 自定义标题\n');
  },
};

function App() {
  const [value, setValue] = useState<string>(textSample);

  return (
    <div>
      <MDEditor
        value={value}
        onChange={(val) => setValue(val ?? '')}
        height={800}
        commands={[customCommand]}
      />
    </div>
  );
}

4.2 性能优化

禁用滚动同步 ：当 enableScroll={true} 时，编辑区与预览区滚动同步可能导致卡顿，建议默认关闭：

js 复制代码

<MDEditor enableScroll={false} />

虚拟滚动 ：处理长文档时，可结合 react-window 或 react-virtualized 实现虚拟滚动，减少 DOM 节点。

4.3 样式定制

通过 CSS 类名破坏性覆盖默认样式：

js 复制代码

<MDEditor className="my-editor" />

css 复制代码

.my-editor .w-md-editor-text-pre > code {
  font-size: 16px;
  line-height: 1.5;
}

4.4 主题切换

data-color-mode参数：

light 默认值
dark

js 复制代码

<MDEditor data-color-mode="dark" />

5.总结

@uiw/react-md-editor 以轻量、易用为核心优势，通过灵活的配置可满足从简单文档编辑到复杂知识管理系统的需求。

5.1 适用场景

博客系统
支持富文本内容创作，兼容技术文档的代码块和语法高亮。
知识管理系统
提供结构化文档编辑能力，支持表格、列表等复杂格式。
在线教育平台
暗黑模式和实时预览适合长时间写作，工具栏自定义可适配教学场景。
Next.js 项目
官方提供 Next.js 集成示例，支持服务端渲染（SSR）环境。

5.2 优势与局限

优势
- 轻量级：无外部编辑器依赖，打包体积小。
- 易用性：开箱即用，文档完善，适合快速集成。
- 灵活性：支持自定义工具栏、快捷键和样式，适应多样化需求。
局限
- 功能精简：相比 Monaco Editor 等重型编辑器，缺少高级功能（如自动补全、多光标编辑）。
- 样式覆盖需谨慎 ：部分 CSS 属性需通过 !important 强制覆盖，可能影响维护性。

5.3 生态与支持

社区活跃
GitHub 仓库获 2.5k+ Star，持续更新版本（最新 v4.0.8），修复问题并新增功能（如行操作、国际化）。
扩展性
支持通过插件机制扩展 Markdown 语法（如数学公式、流程图），需结合 rehype 或 remark 生态库。

5.4 推荐理由

@uiw/react-md-editor 是 React 生态中兼顾性能与功能的优质选择，尤其适合以下场景：

需要快速集成 Markdown 编辑器的中小型项目。
追求低依赖、高定制化的开发者。
希望减少学习成本，直接使用 TypeScript 类型安全的团队。

若项目需要更复杂的功能（如协作编辑、AI 辅助写作），可考虑基于该组件二次开发或选择更重型的专业编辑器。

6 参考

官网文档链接