React ProseMirror

<p align="center"> <img src="https://yellow-cdn.veclightyear.com/ab5030c0/25a75303-c3db-45ca-9e2a-e13fd4a5fe46.png" alt="React ProseMirror 标志" width="120px" height="120px"/> <br> <em>一个功能齐全的库，用于安全地集成 ProseMirror 和 React。</em> <br> </p>

安装

npm:

npm install @nytimes/react-prosemirror

yarn:

yarn add @nytimes/react-prosemirror

<!-- toc -->

• 问题
• 解决方案
  • 在 React 中渲染 ProseMirror 视图
    • useEditorEffect
    • useEditorEventCallback
    • useEditorEventListener
  • 使用 React 构建 NodeViews
• API
  • ProseMirror
  • useEditorState
  • useEditorEventCallback
  • useEditorEventListener
  • useEditorEffect
  • useNodePos
  • useNodeViews
  • react

<!-- tocstop -->

问题

React 是一个用于开发响应式用户界面的框架。为了使更新高效，React 将更新分为多个阶段，以便可以批量处理更新。在第一阶段，应用程序代码渲染虚拟文档。在第二阶段，React DOM 渲染器通过将实际文档与虚拟文档进行协调来完成更新。ProseMirror View 库在单阶段更新中渲染 ProseMirror 文档。与 React 不同，它还允许浏览器的内置编辑功能在某些情况下修改文档，从视图更新而不是相反的方式派生状态更新。

可以同时使用 React DOM 和 ProseMirror View，但安全地使用 React DOM 渲染 ProseMirror View 组件需要仔细考虑每个框架采用的渲染方法之间的差异。React 更新的第一阶段应该没有副作用，这要求 ProseMirror View 的更新发生在第二阶段。这意味着在第一阶段，React 组件实际上可以访问与 EditorView 中不同（较新）版本的 EditorState。因此，分发事务的代码可能会基于不正确的状态分发事务。调用 ProseMirror 视图方法的代码可能会对其状态做出错误的假设，导致不正确的行为或错误。

解决方案

有两种不同的方向来集成 ProseMirror 和 React：你可以在 React 组件内渲染 ProseMirror EditorView，也可以使用 React 组件来渲染 ProseMirror NodeViews。这个库提供了实现这两个目标的工具。

在 React 中渲染 ProseMirror 视图

这个库提供了一组 React 上下文和用于消费它们的钩子，确保从 React 组件安全地访问 EditorView。这允许我们构建包含 ProseMirror 视图的 React 应用程序，即使 EditorState 被提升到 React 状态，或像 Redux 这样的全局状态管理系统中。

使用这些上下文的最简单方法是使用 <ProseMirror/> 组件。<ProseMirror/> 组件可以受控或非受控使用，并接受一个"mount"属性，用于指定 ProseMirror EditorView 应该挂载到哪个 DOM 节点上。

import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";
import { ProseMirror } from "@nytimes/react-prosemirror";

const defaultState = EditorState.create({ schema });
export function ProseMirrorEditor() {
  // 重要的是，mount 被存储为状态，
  // 而不是 ref，这样当它被设置时
  // ProseMirror 组件会重新渲染
  const [mount, setMount] = useState<HTMLElement | null>(null);

  return (
    <ProseMirror mount={mount} defaultState={defaultState}>
      <div ref={setMount} />
    </ProseMirror>
  );
}

EditorState 也可以轻松地从 ProseMirror 组件中提升出来，作为 prop 传递。

import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";
import { ProseMirror } from "@nytimes/react-prosemirror";

export function ProseMirrorEditor() {
  const [mount, setMount] = useState<HTMLElement | null>(null);
  const [state, setState] = useState(EditorState.create({ schema }));

  return (
    <ProseMirror
      mount={mount}
      state={state}
      dispatchTransaction={(tr) => {
        setState((s) => s.apply(tr));
      }}
    >
      <div ref={setMount} />
    </ProseMirror>
  );
}

ProseMirror 组件会确保在每个渲染周期后，EditorView 总是使用最新的 EditorState 更新。由于同步 EditorView 是一个副作用，它必须在 React 渲染生命周期的效果阶段发生，在所有 ProseMirror 组件的子组件运行其渲染函数之后。这意味着从其他 React 组件访问 EditorView 时需要特别小心。为了抽象掉这种复杂性，React ProseMirror 提供了两个钩子：useEditorEffect 和 useEditorEventCallback。这两个钩子都可以在 ProseMirror 组件的任何子组件中使用。

useEditorEffect

通常，需要将 React 组件相对于 ProseMirror 文档中的特定位置进行定位。例如，你可能有一个需要定位在用户光标处的小部件。为了确保这种定位在 EditorView 与最新的 EditorState 同步时发生，我们可以使用 useEditorEffect。

// SelectionWidget.tsx
import { useRef } from "react"
import { useEditorEffect } from "@nytimes/react-prosemirror"

export function SelectionWidget() {
  const ref = useRef()

  useEditorEffect((view) => {
    if (!ref.current) return

    const viewClientRect = view.dom.getBoundingClientRect()
    const coords = view.coordsAtPos(view.state.selection.anchor))

    ref.current.style.top = coords.top - viewClientRect.top;
    ref.current.style.left = coords.left - viewClientRect.left;
  })
return (
  <div
    ref={ref}
    style={{
      position: "absolute"
    }}
  />
)
}

// ProseMirrorEditor.tsx
import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";

import { SelectionWidget } from "./SelectionWidget.tsx";

export function ProseMirrorEditor() {
  const [mount, setMount] = useState<HTMLElement | null>(null);
  const [state, setState] = useState(EditorState.create({ schema }))

  return (
    <ProseMirror
      mount={mount}
      state={state}
      dispatchTransaction={(tr) => {
        setState(s => s.apply(tr))
      }}
    >
      {/*
        我们必须将所有需要访问EditorView的组件
        作为ProseMirror组件的子组件挂载
      */}
      <SelectionWidget />
      <div ref={setMount} />
    </ProseMirror>
  )
}

useEditorEventCallback

通常还需要响应用户操作(如鼠标点击和键盘事件)来分发事务或执行副作用。注意:如果你需要响应来自contenteditable元素内部的键盘事件,你应该使用useEditorEventListener。

然而,如果你需要响应从React组件(如工具提示或工具栏按钮)分发的某些事件来分发事务,你可以使用useEditorEventCallback来创建一个稳定的函数引用,该函数可以安全地访问EditorView的最新值。

// BoldButton.tsx
import { toggleMark } from "prosemirror-commands";
import { useEditorEventCallback } from "@nytimes/react-prosemirror";

export function BoldButton() {
  const onClick = useEditorEventCallback((view) => {
    const toggleBoldMark = toggleMark(view.state.schema.marks.bold);
    toggleBoldMark(view.state, view.dispatch, view);
  });

  return <button onClick={onClick}>加粗</button>;
}

// ProseMirrorEditor.tsx
import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";

import { BoldButton } from "./BoldButton.tsx";

export function ProseMirrorEditor() {
  const [mount, setMount] = useState<HTMLElement | null>(null);
  const [state, setState] = useState(EditorState.create({ schema }));

  return (
    <ProseMirror
      mount={mount}
      state={state}
      dispatchTransaction={(tr) => {
        setEditorState((s) => s.apply(tr));
      }}
    >
      {/*
        我们必须将所有需要访问EditorView的组件
        作为ProseMirror组件的子组件挂载
      */}
      <BoldButton />
      <div ref={setMount} />
    </ProseMirror>
  );
}

useEditorEventListener

useEditorEventCallback生成可以作为事件处理程序传递给React组件的函数。但是,如果你需要监听源自contenteditable节点内部的事件,这些事件监听器需要注册到EditorView的handleDOMEvents属性。

你可以使用useEditorEventListener钩子来实现这一点。它接收一个eventType和一个事件监听器。事件监听器遵循ProseMirror的handleDOMEvents属性的常规语义:

• 返回true或调用event.preventDefault将阻止其他监听器运行。
• 返回true不会自动调用event.preventDefault; 如果你想阻止默认的contenteditable行为,你必须调用event.preventDefault。

你可以使用这个钩子在NodeViews中实现自定义行为:

import { useEditorEventListener } from "@nytimes/react-prosemirror";

function Paragraph({ node, children }) {
  const nodeStart = useNodePos();

  useEditorEventListener("keydown", (view, event) => {
    if (event.code !== "ArrowDown") {
      return false;
    }
    const nodeEnd = nodeStart + node.nodeSize;
    const { selection } = view.state;
    if (selection.anchor < nodeStart || selection.anchor > nodeEnd) {
      return false;
    }
    event.preventDefault();
    alert("不允许按下键!");
    return true;
  });

  return <p>{children}</p>;
}

使用React构建NodeViews

集成React和ProseMirror的另一种方式是让ProseMirror使用React组件渲染NodeViews。这比前面的部分稍微复杂一些。这个库提供了一个useNodeViews钩子、一个用于增强NodeView构造函数的工厂函数,以及react,一个用于维护React组件层次结构的ProseMirror插件。

useNodeViews接收一个从节点名称到扩展的NodeView构造函数的映射。NodeView构造函数必须至少返回一个dom属性和一个component属性,但也可以返回任何其他NodeView属性。以下是它的使用示例:

import {
  useNodeViews,
  useEditorEventCallback,
  NodeViewComponentProps,
  react,
} from "@nytimes/react-prosemirror";
import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";

// Paragraph基本上是一个普通的React组件,接收并渲染其子元素。
// 实际的子元素将由ProseMirror构建并传入这里。
// 查看NodeViewComponentProps类型以了解会传递给NodeView组件的其他属性。
function Paragraph({ children }: NodeViewComponentProps) {
  const onClick = useEditorEventCallback((view) => view.dispatch(whatever));
  return <p onClick={onClick}>{children}</p>;
}

// 确保你的ReactNodeViews在组件外部定义,或者正确地进行了记忆化。
// 如果nodeView属性更新,ProseMirror将拆解并重建所有NodeViews,
// 如果这个对象没有稳定的引用,将导致无限递归。
const reactNodeViews = {
  paragraph: () => ({
    component: Paragraph,
    // 我们将Paragraph组件本身渲染到一个div元素中
    dom: document.createElement("div"),
    // 我们将段落节点的ProseMirror内容渲染到一个span中,
    // 该span将作为子元素传递给Paragraph组件。
    contentDOM: document.createElement("span"),
  }),
};

const state = EditorState.create({
  schema,
  // 如果你使用useNodeViews或useNodePos钩子,
  // 必须添加react插件。
  plugins: [react()],
});

function ProseMirrorEditor() {
  const { nodeViews, renderNodeViews } = useNodeViews(reactNodeViews);
  const [mount, setMount] = useState<HTMLElement | null>(null);

  return (
    <ProseMirror mount={mount} nodeViews={nodeViews} defaultState={state}>
      <div ref={setMount} />
      {renderNodeViews()}
    </ProseMirror>
  );
}

API

ProseMirror

import type { EditorState, Plugin, Transaction } from "prosemirror-state";
import type { EditorProps, EditorView, Plugin } from "prosemirror-view";
import type { ReactNode } from "react";
```typescript
interface ProseMirrorProps extends EditorProps {
  mount: HTMLElement | null;
  children?: ReactNode | null;
  defaultState?: EditorState;
  state?: EditorState;
  plugins?: readonly Plugin[];
  dispatchTransaction?(this: EditorView, tr: Transaction): void;
}

type ProseMirror = (props: ProseMirrorProps) => JSX.Element;

渲染一个ProseMirror视图。

mount 属性必须是一个实际的HTMLElement实例。代表mount的JSX元素应作为子元素传递给ProseMirror组件。

有关其他属性的信息，请参阅ProseMirror文档。

使用示例:

function MyProseMirrorField() {
  const [mount, setMount] = useState(null);

  return (
    <ProseMirror mount={mount}>
      <div ref={setMount} />
    </ProseMirror>
  );
}

useEditorState

type useEditorState = () => EditorState;

提供对当前EditorState值的访问。

useEditorEventCallback

type useEditorEventCallback = <T extends unknown[]>(
  callback: (view: EditorView | null, ...args: T) => void
) => void;

返回一个稳定的函数引用，用作事件处理器回调。

回调函数将以EditorView实例作为其第一个参数。

useEditorEventListener

type useEditorEventListener = <EventType extends DOMEventMap>(
  eventType: EventType,
  listener: (view: EditorView, event: DOMEventMap[EventType]) => boolean
) => void;

在EditorView的DOM节点上附加一个事件监听器。更多详情请参阅ProseMirror文档。

useEditorEffect

type useEditorEffect = (
  effect: (editorView: EditorView | null) => void | (() => void),
  dependencies?: React.DependencyList
) => void;

注册一个布局效果，在EditorView使用最新的EditorState和Decorations更新后运行。

效果可以接受一个EditorView实例作为参数。这个钩子应该用于执行依赖于EditorView的布局效果，例如基于ProseMirror位置定位DOM节点。

通过这个钩子注册的布局效果仍会在所有DOM变更之后同步触发，但它们会在EditorView更新之后触发，即使EditorView存在于祖先组件中。

使用示例:

import { useRef } from "react"
import { useEditorEffect } from "@nytimes/react-prosemirror"

export function SelectionWidget() {
  const ref = useRef()

  useEditorEffect((view) => {
    if (!ref.current) return

    const viewClientRect = view.dom.getBoundingClientRect()
    const coords = view.coordsAtPos(view.state.selection.anchor))

    ref.current.style.top = coords.top - viewClientRect.top;
    ref.current.style.left = coords.left - viewClientRect.left;
  })

  return (
    <div
      ref={ref}
      style={{
        position: "absolute"
      }}
    />
  )
}

useNodePos

type useNodePos = () => number;

返回节点在文档中的当前位置。取代了传递给NodeView的ProseMirror的getPos函数，该函数在React渲染函数中使用是不安全的。

此钩子只能在使用useNodeViews渲染的React组件中使用。

useNodeViews

/**
 * ProseMirror的NodeViewConstructor类型的扩展，包括
 * `component`，用于渲染NodeView的React组件。
 * 除`component`和`dom`外的所有属性都是可选的。
 */
type ReactNodeViewConstructor = (
  node: Node,
  view: EditorView,
  getPos: () => number,
  decorations: readonly Decoration[],
  innerDecorations: DecorationSource
) => {
  dom: HTMLElement | null;
  component: React.ComponentType<NodeViewComponentProps>;
  contentDOM?: HTMLElement | null;
  selectNode?: () => void;
  deselectNode?: () => void;
  setSelection?: (
    anchor: number,
    head: number,
    root: Document | ShadowRoot
  ) => void;
  stopEvent?: (event: Event) => boolean;
  ignoreMutation?: (mutation: MutationRecord) => boolean;
  destroy?: () => void;
  update?: (
    node: Node,
    decorations: readonly Decoration[],
    innerDecoration: DecorationSource
  ) => boolean;
};

type useNodeViews = (nodeViews: Record<string, ReactNodeViewConstructor>) => {
  nodeViews: Record<string, NodeViewConstructor>;
  renderNodeViews: () => ReactElement[];
};

用于创建和渲染由React组件驱动的NodeViewConstructors的钩子。要使用这个钩子，你还必须在你的EditorState中包含react。

component可以是任何接受NodeViewComponentProps的React组件。它将作为props接收nodeViewConstructor的所有参数，除了editorView。需要直接访问EditorView的NodeView组件应使用useEditorEventCallback、useEditorEventListener和useEditorEffect钩子来确保安全访问。

对于有内容的节点，NodeView组件还将传递一个包含空元素的children prop。ProseMirror将把内容节点渲染到这个元素中。与ProseMirror一样，contentDOM属性的存在决定了一个NodeView是否有内容（即NodeView是否有应由ProseMirror管理的可编辑内容）。

react

type react = Plugin<Map<number, string>>;

一个ProseMirror插件，用于维护React节点视图的正确层次结构。

如果你使用useNodeViews或useNodePos，你必须在你的EditorState中包含这个插件。