ProseMirror入门教程：从安装到实现第一个编辑器-优快云博客

ProseMirror入门教程：从安装到实现第一个编辑器

【免费下载链接】prosemirror The ProseMirror WYSIWYM editor 项目地址: https://gitcode.com/gh_mirrors/pr/prosemirror

ProseMirror是一个基于contentEditable的富文本编辑器库，支持协作编辑和自定义文档结构，采用WYSIWYM（所见即所得的修改）模式。本文将从环境搭建到实现基础编辑器功能，带你快速上手这个强大的编辑器框架。

项目简介

ProseMirror的核心优势在于其模块化设计和可扩展性。不同于传统编辑器，它将文档模型与视图分离，通过自定义Schema（模式）控制文档结构，同时提供协作编辑支持。项目结构清晰，主要模块包括：

核心模块：处理文档模型、状态管理和视图渲染
插件系统：支持扩展编辑器功能
示例配置：提供基础编辑器的快速启动方案

项目文档和示例可参考官方文档。

环境准备

安装前提

在开始前，请确保你的开发环境满足以下要求：

Node.js 14.0+
npm/yarn包管理器
Git版本控制工具

获取源码

通过Git克隆仓库到本地：

git clone https://gitcode.com/gh_mirrors/pr/prosemirror.git
cd prosemirror

安装依赖

使用yarn安装项目依赖（官方推荐使用yarn以避免npm的兼容性问题）：

yarn install

快速启动示例

项目提供了完整的演示示例，位于demo/index.html。启动开发服务器查看效果：

bin/pm dev-start

访问http://localhost:8080/demo/即可看到默认编辑器界面：

实现基础编辑器

核心概念

在动手编码前，先了解几个核心概念：

Schema：定义文档结构，包括允许的节点类型和标记
EditorState：管理编辑器的状态，包含文档内容和选择范围
EditorView：负责编辑器的DOM渲染和用户交互
Plugins：扩展编辑器功能的插件系统

基础实现步骤

1. 创建HTML容器

首先创建编辑器的HTML页面结构，保存为basic-editor.html：

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>基础ProseMirror编辑器</title>
  <link rel="stylesheet" href="demo/parent/view/style/prosemirror.css">
  <link rel="stylesheet" href="demo/parent/menu/style/menu.css">
  <style>
    .editor-container {
      margin: 20px auto;
      max-width: 800px;
      border: 1px solid #ccc;
      padding: 10px;
    }
  </style>
</head>
<body>
  <div class="editor-container"></div>
  <script type="module" src="basic-editor.js"></script>
</body>
</html>

2. 编写编辑器逻辑

创建TypeScript文件basic-editor.ts，实现基础编辑器功能：

import { Schema, DOMParser } from "prosemirror-model";
import { EditorView } from "prosemirror-view";
import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";
import { addListNodes } from "prosemirror-schema-list";
import { exampleSetup } from "prosemirror-example-setup";

// 扩展基础Schema，添加列表支持
const customSchema = new Schema({
  nodes: addListNodes(schema.spec.nodes as any, "paragraph block*", "block"),
  marks: schema.spec.marks
});

// 创建初始文档内容
const doc = DOMParser.fromSchema(customSchema).parse(
  document.createElement("div")
);

// 创建编辑器状态
const state = EditorState.create({
  doc,
  plugins: exampleSetup({ schema: customSchema })
});

// 创建编辑器视图
const view = new EditorView(document.querySelector(".editor-container"), {
  state
});

// 暴露视图实例到全局，方便调试
(window as any).editorView = view;

3. 关键代码解析

Schema扩展：

const customSchema = new Schema({
  nodes: addListNodes(schema.spec.nodes as any, "paragraph block*", "block"),
  marks: schema.spec.marks
});

这段代码扩展了基础Schema，添加了列表节点支持，使编辑器能够处理有序和无序列表。

编辑器初始化：

const state = EditorState.create({
  doc,
  plugins: exampleSetup({ schema: customSchema })
});

exampleSetup插件集合提供了基础编辑功能，包括菜单、快捷键和输入规则，无需从零开始实现这些功能。

4. 运行效果

编译TypeScript并在浏览器中打开basic-editor.html，你将看到一个具备以下功能的编辑器：

文本格式化（粗体、斜体、代码）
列表编辑（有序/无序列表）
块级元素（段落、引用、代码块）
基本快捷键支持

自定义编辑器功能

修改编辑器样式

ProseMirror使用CSS类控制外观，你可以通过自定义CSS调整编辑器样式。例如修改编辑器内容区样式：

.ProseMirror {
  padding: 8px;
  min-height: 300px;
  background: #fff;
  border: 1px solid #eee;
  border-radius: 4px;
}

添加自定义菜单按钮

通过插件系统扩展编辑器工具栏，添加自定义功能按钮。例如添加一个"插入水平线"按钮：

import { Plugin } from "prosemirror-state";
import { MenuItem } from "prosemirror-menu";
import { icons } from "prosemirror-menu";

const hrItem = new MenuItem({
  title: "插入水平线",
  icon: icons.horizontal_rule,
  run(state, dispatch) {
    const { tr } = state;
    tr.replaceSelectionWith(schema.nodes.horizontal_rule.create());
    dispatch(tr);
  }
});

// 将按钮添加到菜单插件
const customPlugins = exampleSetup({ schema: customSchema }).concat(
  new Plugin({
    props: {
      menuContent: () => [hrItem]
    }
  })
);

项目结构解析

ProseMirror采用模块化设计，核心代码分布在多个子模块中：

prosemirror/
├── demo/                # 演示示例代码
│   ├── index.html       # 演示页面
│   ├── demo.ts          # 演示编辑器实现
│   └── demo.css         # 演示样式
├── package.json         # 项目配置
└── tsconfig.json        # TypeScript配置

主要模块功能：

prosemirror-model：文档模型和Schema定义
prosemirror-view：编辑器视图和DOM交互
prosemirror-state：状态管理
prosemirror-schema-basic：基础文档结构定义

常见问题解决

依赖安装失败

如果遇到依赖安装问题，尝试清除npm缓存后重新安装：

npm cache clean --force
yarn install

编辑器无法加载

检查浏览器控制台是否有报错，常见原因包括：

模块路径错误
Schema定义问题
DOM容器未找到

自定义Schema不生效

确保正确扩展基础Schema，并在编辑器初始化时使用自定义Schema：

// 错误示例
const state = EditorState.create({
  doc,
  plugins: exampleSetup({ schema }) // 使用了基础schema而非自定义schema
});

总结

通过本文的学习，你已经掌握了ProseMirror的基础使用方法，包括：

环境搭建和项目结构
基础编辑器实现
自定义Schema和插件
样式修改和功能扩展

ProseMirror的强大之处在于其灵活性和可扩展性，通过自定义Schema和插件，你可以构建满足特定需求的编辑器。要深入学习，建议参考以下资源：

祝你在富文本编辑器开发的道路上越走越远！

【免费下载链接】prosemirror The ProseMirror WYSIWYM editor 项目地址: https://gitcode.com/gh_mirrors/pr/prosemirror

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考