BeforePasteEvent

Go back to Plugin events

BeforePasteEvent provides a chance for plugin to change the content before it is pasted into editor.

interface ClipboardData {
    snapshotBeforePaste: string;
    originalFormat: DefaultFormat;
    image: File;
    text: string;
    html: string;
}

const enum PasteOption {
    PasteHtml = 0,
    PasteText = 1,
    PasteImage = 2,
}

interface BeforePasteEvent extends PluginEvent {
    clipboardData: ClipboardData;
    fragment: DocumentFragment;
    pasteOption: PasteOption;
}

clipboardData: It is an object contains all related data for pasting, including:

• snapshotBeforePaste: An editor content snapshot before pasting happens. This is used for changing paste format (see below)
• originalFormat: The format state at cursor before pasting. This is used for changing paste format (see below)
• image: If the copied data contains image format, this will be the image blob. Otherwise it is null.
• text: If the copied data contains plain text format, this will be the plain text string. Otherwise it is null.
• html: If the copied data contains HTML format, this will be the html string. Otherwise it is null.

fragment: While clipboardData contains all raw data from clipboard, here fragment is an HTML Document Fragment which will be inserted into content if pasteOption is set to PasteHtml, otherwise it will be an empty fragment. Plugins can modify this fragment and write back its HTML string to clipboardData. Then the fianl result will be the modified content of fragment.

pasteOption: There are 3 options for pasteing: html, text and image. Paste plugin will determine one of these options before triggering BeforePasteEvent according to the content in clipboard. Plugins can also change the option. For example, sometimes when pasting an inline image, we may want to upload the image first and then paste the image with url to retrieve final image from server. Then we can handle BeforePasteEvent, get the image blob, change its pasteOption to HTML, and add a placeholder HTML element to fragment, and upload the blob. After image is uploaded and url is generated, we can replace the placeholder with the image url:

onPluginEvnet(event: PluginEvent) {
    // Check if the event is BeforePasteEvent
    if (event.eventType == PluginEventType.BeforePaste) {
        let beforePasteEvent = <BeforePasteEvent>event;
        
        // Check if pasting image
        if (beforePasteEvent.pasteOption == PasteOption.PasteImage) {
            
            // Get image blob
            let image = beforePasteEvent.clipboardData.image;

            // Get placeholder DOM node
            let placeholder = this.createPlaceholder(image);

            // Modify the pasting content and option
            beforePasteEvent.fragment.appendChild(placeholder);
            beforePasteEvent.clipboardData.html = placeholder.outerHTML;
            beforePasteEvent.pasteOption = PasteOption.PasteHtml;

            // Start upload image and handle async result
            this.uploadImage(image).then((url: string) => {
                
                // Check editor availability in async callback
                if (this.editor) {
                    
                    // Create final IMG node
                    let img = this.editor.getDocument().createElement('img') as HTMLImageElement;
                    img.src = url;
                    this.editor.replaceNode(placeholder, img);
                }
            });
        }
    }
}

private createPlaceholder(img: File): Node { ... }

private async uploadImage(img: File): Promise<string> { ... }

For more information, please reference to Paste plugin.

More info

Package: roosterjs-editor-types

Support from: 6.5.0

Source code: BeforePasteEvent.ts