当前位置：首页 > web >正文

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

web 2025/8/10 15:21:35

1.背景

@uiw/react-md-editor 是一款基于 React 和 TypeScript 的轻量级 Markdown 编辑器插件。
它支持实时预览、GitHub 风味 Markdown 语法、暗黑模式、工具栏自定义等核心功能，同时提供丰富的扩展接口（如自定义命令、插件集成）。
其基于 textarea 的封装设计，不依赖 CodeMirror/Monaco 等重型编辑器，性能优异且易于集成，专为现代 Web 应用设计。
本文将从基础安装到高级配置，详细介绍其核心用法与优化技巧。

2.快速安装

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

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

3.基础使用

3.1 基础组件示例。

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 (<MDEditorvalue={value}onChange={(val) => setValue(val ?? '')}height={800}/>);
}export default App;

关键参数：

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

效果：
在这里插入图片描述

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

4.核心功能详解

4.1 实时预览与模式切换

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

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

import { useState } from 'react';
import MDEditor from '@uiw/react-md-editor';function App() {const [value, setValue] = useState<string>('hello world');return (<MDEditorvalue={value}onChange={(val) => setValue(val ?? '')}height={800}preview="edit"/>) 
};

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

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={[]}

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

4.3 自定义命令

实现 customCommand 接口添加按钮：

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><MDEditorvalue={value}onChange={(val) => setValue(val ?? '')}height={800}commands={[customCommand]}/></div>);
}

4.2 性能优化

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

<MDEditor enableScroll={false} />

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

4.3 样式定制

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

<MDEditor className="my-editor" />

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

4.4 主题切换

data-color-mode参数：

light 默认值
dark

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

5.总结

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

5.1 适用场景

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

5.2 优势与局限

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