Paste plugin

Go back to Built-in plugins

Paste plugin handles browser onpaste event, do necessary content filtering and formatting, broadcast event to allow other plugins have chance to modify the pasting content, and finally paste content into editor.

Create plugin instance

Paste is a built-in plugin of RoosterJs. When you create an editor with createEditor() API, this plugin is already included.

To manually create an instance of this plugin, you can use its constructor:

constructor(private useDirectPaste?: boolean);

Parameters

Paste plugin has one optional parameter: useDirectPaste. This is an experiment parameter and might be removed in newer versions. By default Paste plugin will get the pasted content by leveraging browser built-in pasting behavior. However this behavior has some issue when process some special content such as content from Microsoft Office products, or the content is including some global CSS styles. To override this behavior, you can set useDirectPaste parameter to true then Paste plugin will get pasted content directly from clipboard.

After get pasted content, Paste plugin do the following preprocess steps:

1. Filter out unsafe HTML
2. Convert global CSS to inline CSS
3. Do some content replacement for better further processing
4. Trigger BeforePasteEvent to allow plugins modify the content to be pasted (See below)

Event

BeforePasteEvent

After preprocessing of HTML content, Paste plugin will trigger BeforePasteEvent. Other plugins can handle this event to make any modification to the content before it is pasted. Paste plugin itself also handle this event to process the content copied from Microsoft Office products.

For more inforation about BeforePasteEvent, please reference to BeforePasteEvent

ContentChangedEvent

BeforePasteEvent is fired before paste happens, while ContentChangedEvent is fired after paste finishes. The change source of ContentChangedEvent for pasting is 'Paste' (ChangeSource.Paste). The data for this event will be the clipboardData. Plugin can handle this event to change paste format. (See below)

For more inforation about ContentChangedEvent, please reference to ContentChangedEvent

Change pasting format

Paste plugin supports 3 different pasting format:

1. PasteOriginal (Default behavior)
2. PasteText
3. PasteAndMergeFormat

    // Paste with original format
    public pasteOriginal(clipboardData: ClipboardData);

    // Paste plain text in current format
    public pasteText(clipboardData: ClipboardData);

    // Paste and keep the original content structure, but apply current format
    public pasteAndMergeFormat(clipboardData: ClipboardData);

Once pasting finishes, we can handle the ContentChangedEvent with source equal to Paste to get clipboardData, then we can call these 3 methods to change the paste format:

onPluginEvent(event: PluginEvent) {
    if (event.eventType == PluginEventType.ContentChanged) {
        let contentChangedEvent = <ContentChangedEvent>event;

        if (contentChangedEvent.source == ChangeSource.Paste) {
            let clipboardData = <ClipboardData>contentChangedEvent.data;

            // Handle the event to allow user choose a paste format
        }
    }
}

Note that these 3 methods are always available to be invoked as long as a valid clipboardData is provided. However, once the content is changed by user after pasting, we should not invoke these methods with the old clipboardData any more since the snapshot there is out of date. Calling these method in that case will lose the new content user just entered.

More info

Package: roosterjs-editor-plugins

Support from: 6.6.0

Source code: Paste.ts