一个用于安全集成 ProseMirror 和 React 的库。
A fully featured library for safely integrating ProseMirror and React.
Note: React ProseMirror releases are coupled to specific prosemirror-view releases, and are not guaranteed to work with other versions of prosemirror-view. Ensure that your version of prosemirror-view matches the version in React ProseMirror's peer dependencies!
Note: React ProseMirror does not require a specific version of React, React DOM, or React Reconciler. However, you must ensure that your React Reconciler version matches your React/React DOM versions.
| React version | React Reconciler version |
|---|---|
| 19.x | 0.32.0 |
| >= 18.2.0, s.apply(tr)); |
}}
>); }
…tsx // SelectionWidget.tsx import { useRef } from "react"; import { useEditorEffect } from "@handlewithcare/react-prosemirror";
export function SelectionWidget() { const ref = useRef();
useEditorEffect((view) => { if (!view || !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 (
); }
## API
### `ProseMirror`
```tsx
type ProseMirror = (
props: DirectEditorProps &
({ defaultState: EditorState } | { state: EditorState }) & {
children: ReactNode;
nodeViewComponents?: {
[nodeType: string]: ComponentType;
};
nodeViews?: {
[nodeType: string]: NodeViewConstructor;
};
markViewComponents?: {
[markType: string]: ComponentType;
};
markViews?: {
[markType: string]: MarkViewConstructor;
};
}
) => JSX.Element;Renders the ProseMirror editor.
Example usage:
import { EditorState } from "prosemirror-state";
import {
ProseMirror,
ProseMirrorDoc,
reactKeys,
} from "@handlewithcare/react-prosemirror";
export function ProseMirrorEditor() {
return (
);
}ProseMirrorDoctype ProseMirrorDoc = (props: { as?: ReactElement }) => JSX.Element;Renders the actual editable ProseMirror document.
This must be passed as a child to the ProseMirror component. It may be
wrapped in any other components, and other children may be passed before or
after.
Example usage:
import { EditorState } from "prosemirror-state";
import {
ProseMirror,
ProseMirrorDoc,
reactKeys,
} from "@handlewithcare/react-prosemirror";
export function ProseMirrorEditor() {
return (
);
}useEditorStatetype useEditorState = () => EditorState | null;Provides access to the current EditorState value.
useEditorEventCallbacktype useEditorEventCallback = (
callback: (view: EditorView | null, ...args: T) => void
) => void;Returns a stable function reference to be used as an event handler callback.
The callback will be called with the EditorView instance as its first argument.
This hook is dependent on both the EditorContext.Provider and the
LayoutGroup. It can only be used in a component that is mounted as a child of
both of these providers.
useEditorEventListenertype useEditorEventListener = (
eventType: EventType,
listener: (view: EditorView, event: DOMEventMap[EventType]) => boolean
) => void;Attaches an event listener at the EditorView's DOM node. See
the ProseMirror docs
for more details.
useEditorEffecttype useEditorEffect = (
effect: (editorView: EditorView | null) => void | (() => void),
dependencies?: React.DependencyList
) => void;Registers a layout effect to run after the EditorView has been updated with the latest EditorState and Decorations.
Effects can take an EditorView instance as an argument. This hook should be used to execute layout effects that depend on the EditorView, such as for positioning DOM nodes based on ProseMirror positions.
Layout effects registered with this hook still fire synchronously after all DOM mutations, but they do so after the EditorView has been updated, even when the EditorView lives in an ancestor component.
Example usage:
import { useRef } from "react"
import { useEditorEffect } from "@handlewithcare/react-prosemirror"
export function SelectionWidget() {
const ref = useRef()
useEditorEffect((view) => {
if (!view || !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 (
)
}NodeViewComponentPropsinterface NodeViewComponentProps extends AllHTMLAttributes = {
nodeProps: {
decorations: readonly Decoration[];
innerDecorations: DecorationSource;
node: Node;
getPos: () => number;
contentDOMRef: Exclude;
};
ref: LegacyRef;
};
…
ts
type useEditorStateSelector = (selector: (state: EditorState) => Result): ResultSelect a piece of the EditorState, a la Redux’s useSelector.
This hook will only trigger a re-render of the consuming component if the return value of the selector changes.
The provided selector must return the same value when it receieves the same inputs. If the selector creates and returns a new object when it runs, you'll enter a rerender loop.
useNodePostype useNodePos = () => number;
…
tsx
type useStopEvent = (stopEvent: (this: NodeView, view: EditorView, event: Event) => boolean): voidThis hook can be used within a node view component to register a stopEvent handler. Events for which this returns true are not handled by the editor.
useIgnoreMutationtype useIgnoreMutation = (ignoreMutation: (this: NodeView | MarkView, view: EditorView, mutation: ViewMutationRecord) => boolean): voidThis hook can be used within a node view or mark view component to register an ignoreMutation handler. Mutations for which this returns true are not handled by the editor.
useSelectNodetype useSelectNode = (selectNode: () => void, deselectNode?: () => void): voidThis hook can be used within a node view component to register selectNode and deselectNode handlers. The selectNode handler will only be called when a NodeSelection is created whose node is this one.
useIsNodeSelectedtype useIsNodeSelected = (): booleanThis hook can be used within a node view component to subscribe to a boolean value determining whether this node is selected. The hook will return true when a NodeSelection is created whose node is this one.
useIsComposingIntype useIsComposingIn = (): booleanThis hook can be used within a node view component to subscribe to a boolean value determining whether an IME composition is active inside the node.
widgettype widget = (
pos: number,
component: ForwardRefExoticComponent & WidgetComponentProps
>,
spec?: ReactWidgetSpec
) => Decoration(pos, pos, new ReactWidgetType(component, spec))
…
ts
type reorderSiblings = (pos: number, order: number[]): CommandIn order to maintain the React state across node view components, React
ProseMirror uses the reactKeys plugin to track node positions across
transactions and provide them with stable keys. During a reorder, for example
when two nodes are swapped, ProseMirror is unable to track the positions across
the resulting delete and insert steps, and so the reactKeys plugin will assign
new keys to the nodes, causing their node view components to be remounted.
Sometimes, such as when using a drag-and-drop library like framer-motion,
remounting the component being dragged can cause issues. The reorderSiblings
command provides additional metadata to React ProseMirror that allows it to
properly track the new positions for the reordered nodes, allowing it to reuse
the same keys. This prevents any issues that could be caused by unexpected
component remounts.
Reach out to Handle with Care! We're a product development collective with years of experience bringing excellent ideas to life. We love React and ProseMirror, and we're always looking for new folks to work with!
The following companies, organizations, and individuals support Pitter Patter's ongoing development.
Sponsors receive regular updates about development progress, including previews of upcoming features, priority getting issues addressed as we release features, and a direct line of communication to us for support. Funders above a certain threshold join our steering committee — a lightweight governance model where significant contributors help shape our roadmap priorities.
Sponsors
Moment
Lingco
dskrpt
Fastrepl暂无开放 Issues,或尚未同步最近议题。