@96fun/markeditor
v1.0.0
Published
旗舰级 Markdown 编辑器与渲染引擎(Monaco Editor + ReactMarkdown),可独立安装、构建与发布
Maintainers
Readme
@96fun/markeditor
English | 简体中文
基于 Monaco Editor + ReactMarkdown 的旗舰级 Markdown 编辑器 / 渲染引擎,独立开源组件。
零宿主耦合:i18n 与主题通过 React Context 注入,未注入时使用内置英文文案与浅色主题兜底,可独立运行、独立测试、独立发布。
特性
- 三态工作台:编辑 / 预览 / 分屏
- Monaco 编辑 + ReactMarkdown 渲染
- 双向同步滚动(分段锚点插值 + 动作源互斥锁,根治回弹死循环)
- Mermaid 本地矢量编译、KaTeX 数学公式、GFM 表格 / 任务列表
- 代码块(语法高亮 / 一键复制 / 全屏)、目录树、admonition 提示框
- 大纲提取 + Scroll Spy + 点击精准跳转
- 字号缩放、明暗主题
- 纯逻辑(大纲提取 / slug 生成 / 翻译函数)可独立单元测试
安装
npm install @96fun/markeditor以下为 peerDependencies,由宿主提供(npm 7+ 会自动安装缺失项;宿主已有时会复用同一实例,不会重复落地):
| 包 | 说明 |
| :--- | :--- |
| react / react-dom | ≥18 |
| @mui/material / @mui/icons-material | UI 组件栈,宿主已有则直接复用 |
| @emotion/react / @emotion/styled | MUI 的样式引擎 |
| monaco-editor | Monaco 本体;未配置时 @monaco-editor/react 默认从 CDN 加载,宿主可 loader.config({ monaco }) 指向本地实例 |
| mermaid | 可选。宿主已有则直接复用;未安装时 mermaid 代码块降级为源码展示,不影响其余功能 |
样式
数学公式(KaTeX)样式不内嵌在 JS 中,使用编辑器渲染时需引入:
import '@96fun/markeditor/style.css';基础用法
import { MarkdownEditor } from '@96fun/markeditor';
export function App() {
return (
<MarkdownEditor
content="# Hello Markdown"
filePath="docs/readme.md"
onSave={(content) => save(content)}
onChange={(content) => setDirty(true)}
onOpenFile={(path) => open(path)}
/>
);
}依赖注入(可选)
未注入时使用内置英文文案与浅色主题;注入后完全复用宿主的多语言与明暗主题:
import {
MarkdownEditor,
I18nProvider,
ThemeProvider,
} from '@96fun/markeditor';
<I18nProvider value={{ t, locale }}>
<ThemeProvider value={{ isDark }}>
<MarkdownEditor content={markdown} filePath="readme.md" />
</ThemeProvider>
</I18nProvider>;Props
| 属性 | 类型 | 说明 |
| :--- | :--- | :--- |
| content | string | Markdown 源文本 |
| filePath | string | 文件路径(用于相对链接解析与快捷键) |
| onSave | (content: string) => void \| Promise<void> | 保存回调(宿主负责落盘) |
| onChange | (content: string) => void | 内容变更回调 |
| readOnly | boolean | 只读模式(默认 false) |
| initialViewMode | 'edit' \| 'preview' \| 'split' | 初始视图(默认 preview) |
| onOpenFile | (path: string) => void | 打开链接 / 相对文件的回调 |
| resolvePath | (baseFilePath: string, href: string) => string | 相对路径解析(未提供时原样透传) |
纯逻辑 API(可测试)
import {
generateHeadingBaseId, // slug 生成
extractHeadings, // 大纲提取(跳过代码块、处理重名、兼容 CRLF)
createTranslator, // 翻译函数工厂
en, // 内置英文文案
} from '@96fun/markeditor';测试
npm test
# node --test tests/*.test.mjs集成测试(Playwright × Storybook)
场景统一维护在 stories/MarkdownEditor.stories.tsx,由 Playwright 以 双形态 驱动:
| 形态 | 场景源 | 验收目标 |
| :--- | :--- | :--- |
| test:e2e:serve | Storybook dev(6006) | dev 转换链路(别名指向 src/ 源码) |
| test:e2e:build | Storybook 静态产物(5177) | 真实发布产物(别名指向 dist/index.js) |
| 场景(story) | 覆盖内容 |
| :--- | :--- |
| Basic | 分屏下编辑与预览共存,onChange / onSave 链路 |
| I18n + Dark Theme | I18nProvider / ThemeProvider 注入(文案替换 + Monaco 暗色主题) |
| Read Only | 只读模式:工具栏禁用、输入被丢弃 |
| Rendering | GFM 表格 / 任务列表 / 代码块 / KaTeX / admonition / Mermaid |
npm run test:e2e:serve # Storybook dev + 源码别名
npm run test:e2e:build # build + STORYBOOK_DIST 构建 + vite preview 承载
npm run test:e2e # 两者依次执行
npm run storybook # 手动打开组件工作台(http://localhost:6006)
npm run storybook:build # 输出 storybook-static/ 静态文档站serve 与 dist 双形态全绿才算集成测试通过(同时覆盖 dev 转换问题与发布产物问题)。
Monaco 经 .storybook/preview.tsx 走本地 node_modules 加载(离线可跑测试);
组件库默认行为仍为 CDN,宿主可自行 loader.config({ monaco }) 覆盖。
构建与发布
# 类型检查 + 构建 + 单元测试
npm run check
# 查看将进入 npm 包的文件(不实际发布)
npm pack --dry-run
# 发布到官方 npm Registry(scoped public 包)
npm publishprepublishOnly 会自动执行 check,prepack 会重新生成 dist,避免发布未构建或未通过测试的产物。
许可证
MIT
