# @gravity-ui/markdown-editor 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/markdown-editor/

版本：15\.50\.0
npm 元数据更新时间：2026-11-11T14:01:05.960Z
中文译文更新时间：2026-11-16T23:43:04.509Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gravity-ui/markdown-editor
原文对照：https://npmcn.com/package/%40gravity-ui/markdown-editor/?lang=original
项目主页：https://github.com/gravity-ui/markdown-editor#readme
源码仓库：https://github.com/gravity-ui/markdown-editor

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：10.5 MB，5123 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：49 个
- peer 依赖：katex ^0\.16\.9，react ^16\.14\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，lowlight ^3\.0\.0，react-dom ^16\.14\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，markdown-it ^13\.0\.0，highlight\.js ^11\.8\.0，@gravity-ui/uikit ^7\.1\.0，@diplodoc/transform ^4\.43\.0，@gravity-ui/components ^4\.10\.0，@diplodoc/cut-extension ^0\.5\.0 \|\| ^0\.6\.1 \|\| ^0\.7\.1 \|\| ^1\.0\.0，@diplodoc/file-extension ^0\.2\.1，@diplodoc/html-extension ^2\.3\.2，@diplodoc/tabs-extension ^3\.5\.1，@diplodoc/latex-extension ^1\.0\.3 \|\| ^2\.0\.0，@diplodoc/mermaid-extension ^1\.0\.0 \|\| ^2\.0\.0，@diplodoc/quote-link-extension ^0\.1\.3，@diplodoc/folding-headings-extension ^0\.1\.0
- 首次发布：2024-06-07T12:14:06.670Z
- 最新版本发布：2026-11-11T14:01:05.307Z
- 近 30 天下载量：44757（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：163（近 12 个月 39 个）

## 中文简介

Markdown wysiwyg 和 markup 编辑器

## 安装

```sh
npm install @gravity-ui/markdown-editor
```

也可以使用：`pnpm add @gravity-ui/markdown-editor`、`yarn add @gravity-ui/markdown-editor`、`bun add @gravity-ui/markdown-editor`

## README

![Markdown Editor](https://github.com/user-attachments/assets/0b4e5f65-54cf-475f-9c68-557a4e9edb46)

# @gravity-ui/markdown-editor ! (简体中文) [![npm package](https://img.shields.io/npm/v/@gravity-ui/markdown-editor)](https://www.npmjs.com/package/@gravity-ui/markdown-editor) [![CI](https://img.shields.io/github/actions/workflow/status/gravity-ui/markdown-editor/ci.yml?branch=main&label=CI)](https://github.com/gravity-ui/markdown-editor/actions/workflows/ci.yml?query=branch:main) [![Release](https://img.shields.io/github/actions/workflow/status/gravity-ui/markdown-editor/release.yml?branch=main&label=Release)](https://github.com/gravity-ui/markdown-editor/actions/workflows/release.yml?query=branch:main) [![storybook](https://img.shields.io/badge/Storybook-deployed-ff4685)](https://preview.gravity-ui.com/md-editor/)

## Markdown wysiwyg 和 markup 编辑器

MarkdownEditor是和Markdown合作的强大工具,它结合了WYSIWYG和Markup模式. 这意味着您可以在方便的视觉模式下创建和编辑内容,同时也能完全控制标记.

### 主要特点

-   支持基本的Markdown和 [YFM 调频](https://ydocs.tech/) 语法.
-   通过使用ProseMiror和CodeMiror引擎的可扩展性.
-   在WYSIWYG和Markup模式中工作的能力以达到最大灵活性.

## 安装

```shell
npm install @gravity-ui/markdown-editor
```

### 所需依赖关系

请注意,要开始使用软件包,您的项目还必须安装以下设备: `@diplodoc/transform`, (中文(简体) ), `react`, (中文(简体) ), `react-dom`, (中文(简体) ), `@gravity-ui/uikit`, (中文(简体) ), `@gravity-ui/components` 还有一些 看看这个 `peerDependencies` 节 `package.json` 为了准确的信息.

## 开始

Markdown编辑器作为反应钩子提供,以创建编辑器实例和渲染视图的组件.  
设置外观和主题 [UIKit 文档](https://github.com/gravity-ui/uikit?tab=readme-ov-file#styles)。 。 。 .

```tsx
import React from 'react';
import {useMarkdownEditor, MarkdownEditorView} from '@gravity-ui/markdown-editor';

function Editor({onSubmit}) {
  const editor = useMarkdownEditor({allowHTML: false});

  React.useEffect(() => {
    function submitHandler() {
      // Serialize current content to markdown markup
      const value = editor.getValue();
      onSubmit(value);
    }

    editor.on('submit', submitHandler);
    return () => {
      editor.off('submit', submitHandler);
    };
  }, [onSubmit]);

  return <MarkdownEditorView stickyToolbar autofocus editor={editor} />;
}
```

更多信息:

-   [如何在 Create React App 中连接编辑器](https://gravity-ui.github.io/markdown-editor/getting-started/create-react-app.html)
-   [如何添加标记模式的预览](https://gravity-ui.github.io/markdown-editor/getting-started/preview.html)
-   [如何添加 HTML 扩展名](https://gravity-ui.github.io/markdown-editor/extensions/html-block.html)
-   [如何添加 Latex 扩展名](https://gravity-ui.github.io/markdown-editor/extensions/latex-extension.html)
-   [如何添加美人鱼扩展](https://gravity-ui.github.io/markdown-editor/extensions/mermaid-extension.html)
-   [如何写入扩展名](https://gravity-ui.github.io/markdown-editor/develop/extension-creation.html)
-   [如何添加 GPT 扩展](https://gravity-ui.github.io/markdown-editor/extensions/gpt.html)
-   [如何在下标中添加文本绑定扩展](https://gravity-ui.github.io/markdown-editor/develop/extension-with-popup.html)

### 发展

1.  安装节点环境, 版本在 `.nvmrc` 文档。 我们建议使用 [国家核查团](https://github.com/nvm-sh/nvm) 或类似的工具.
2.  安装 [小时](https://pnpm.io/installation),该版本在 `package.json` 在"包装经理"属性.
3.  安装依赖性 : `pnpm i`
4.  运行故事本 dev- server : `pnpm start`

### i18n (英语)

要建立国际化,你只需要使用 `configure`数字 :

```typescript
import {configure} from '@gravity-ui/markdown-editor';

configure({
  lang: 'ru',
});
```

别忘了打电话 `configure()` 从 [用户界面Kit](https://github.com/gravity-ui/uikit?tab=readme-ov-file#i18n) 和其他UI图书馆.

### 捐款

-   [贡献者准则](https://gravity-ui.github.io/markdown-editor/contributing.html)

## 许可证

根据麻省理工学院的许可证分发。 见 [自由主义](https://npmcn.com/package/%40gravity-ui/markdown-editor/LICENSE.txt) 详细情况.

## 对于人工智能特工

用于React的双模版Markdown编辑器,结合了WYSIWYG模式(ProseMiror)和生标记模式(CodeMiror),支持基本的Markdown和YFM.

### 何时使用

-   用可切换的视觉(WYSIWYG)和源(markup)视图来编辑Markdown/YFM内容.
-   您需要一个可扩展编辑器: 自定义标记、节点、工具栏项目,以及通过ProseMiror/CodeMiror引擎的扩展(HTML、LaTeX、Mermaid、GPT).
-   渲染编辑器 UI: 用 `useMarkdownEditor` 并把它变成 `MarkdownEditorView`。 。 。 .

### 不使用时

-   只读 Markdown 渲染到 HTML 而不编辑 – 用 [`@diplodoc/transform`](https://github.com/diplodoc-platform/transform) 并生成输出.
-   普通多行文本输入——使用 `TextArea` 从 [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit)。 。 。 .
-   富文不是Markdown/YFM——这个编辑器是Markdown-first.

### 常见陷阱

-   **这是一个钩子加一个视图,而不是一个组成部分.** 创建实例 `useMarkdownEditor(...)` 并传递给 `<MarkdownEditorView editor={editor} />`; 没有单一 `<MarkdownEditor>` 你直接变身.
-   **通过实例读取值, 而不是控制值 `value` 道具 (英语).** 打电话 `editor.getValue()` (例如: `submit` 事件)将序列化到Markdown;编辑器管理自己的状态.
-   **需要依赖同伴.** 您的项目必须提供 `@diplodoc/transform`, (中文(简体) ), `@gravity-ui/uikit`, (中文(简体) ), `@gravity-ui/components`, (中文(简体) ), `react`,以及 `react-dom` - 检查一下 `peerDependencies` 内 `package.json`。 。 。 .
-   **样式和i18n来自uikit.** 按 uikit 文件设置主题/ 样式并调用 `configure({lang})` 从本套件和 `@gravity-ui/uikit`。 。 。 .

## AI代理的文件

安装版本的可代理读取文档位于 `node_modules/@gravity-ui/markdown-editor/build/docs/INDEX.md`。 。 。 .

## 常见问题

### @gravity-ui/markdown-editor 是什么？

Markdown wysiwyg 和 markup 编辑器

### 如何安装 @gravity-ui/markdown-editor？

在项目目录运行 npm install @gravity-ui/markdown-editor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：katex（^0\.16\.9）、react（^16\.14\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^16\.14\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）、markdown-it（^13\.0\.0）、@gravity-ui/uikit（^7\.1\.0）、@diplodoc/transform（^4\.43\.0）、@gravity-ui/components（^4\.10\.0）、@diplodoc/cut-extension（^0\.5\.0 \|\| ^0\.6\.1 \|\| ^0\.7\.1 \|\| ^1\.0\.0）、@diplodoc/file-extension（^0\.2\.1）、@diplodoc/tabs-extension（^3\.5\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gravity-ui/markdown-editor 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gravity-ui/markdown-editor 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gravity-ui/markdown-editor 可以商用吗？

@gravity-ui/markdown-editor 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gravity-ui/markdown-editor 的下载量有多少？

根据 npm 官方下载统计，@gravity-ui/markdown-editor 在 2026/10/17 – 2026/11/15 这 30 天内被下载 44,757 次，日均约 1,492 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gravity-ui/markdown-editor 还在维护吗？

最新版本 15\.50\.0 发布于 2026/11/11（5 天前）；至今共发布 163 个版本，其中过去 12 个月发布了 39 个；首次发布于 2024/06/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

