Class VaadinCKEditor

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.AbstractField<com.vaadin.flow.component.customfield.CustomField<String>, String>
com.vaadin.flow.component.customfield.CustomField<String>
com.wontlost.ckeditor.VaadinCKEditor
All Implemented Interfaces:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.BlurNotifier<com.vaadin.flow.component.customfield.CustomField<String>>, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.Focusable<com.vaadin.flow.component.customfield.CustomField<String>>, com.vaadin.flow.component.FocusNotifier<com.vaadin.flow.component.customfield.CustomField<String>>, com.vaadin.flow.component.HasAriaLabel, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasEnabled, com.vaadin.flow.component.HasHelper, com.vaadin.flow.component.HasLabel, com.vaadin.flow.component.HasSize, com.vaadin.flow.component.HasStyle, com.vaadin.flow.component.HasTheme, com.vaadin.flow.component.HasValidation, com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>, com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>, com.vaadin.flow.component.shared.HasTooltip, com.vaadin.flow.component.shared.HasValidationProperties, com.vaadin.flow.component.shared.InputField<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>, Serializable
@Tag("vaadin-ckeditor") @JsModule("./vaadin-ckeditor/vaadin-ckeditor.ts") @NpmPackage(value="ckeditor5",version="47.4.0") @NpmPackage(value="lit",version="^3.3.2") public class VaadinCKEditor extends com.vaadin.flow.component.customfield.CustomField<String> implements com.vaadin.flow.component.HasAriaLabel
Vaadin CKEditor 5 component.

Modular CKEditor 5 integration with plugin-based customization.

Usage examples:

// Use preset
VaadinCKEditor editor = VaadinCKEditor.create()
    .withPreset(CKEditorPreset.STANDARD)
    .build();

// Custom plugins (dependencies auto-resolved)
VaadinCKEditor editor = VaadinCKEditor.create()
    .withPlugins(CKEditorPlugin.BOLD, CKEditorPlugin.ITALIC, CKEditorPlugin.IMAGE_CAPTION)
    .withToolbar("bold", "italic", "|", "insertImage")
    .build();
// IMAGE_CAPTION automatically includes IMAGE plugin as dependency

// Customize preset
VaadinCKEditor editor = VaadinCKEditor.create()
    .withPreset(CKEditorPreset.BASIC)
    .addPlugin(CKEditorPlugin.TABLE)
    .withLanguage("zh-cn")
    .build();

Dependency Resolution:

The builder automatically resolves plugin dependencies by default. For example, adding IMAGE_CAPTION will automatically include the IMAGE plugin.

// Auto-resolve with recommended plugins for full feature set
VaadinCKEditor editor = VaadinCKEditor.create()
    .withPlugins(CKEditorPlugin.IMAGE)
    .withDependencyMode(DependencyMode.AUTO_RESOLVE_WITH_RECOMMENDED)
    .build();
// Includes IMAGE plus recommended: IMAGE_TOOLBAR, IMAGE_CAPTION, IMAGE_STYLE, IMAGE_RESIZE

// Strict mode - fail if dependencies missing
VaadinCKEditor editor = VaadinCKEditor.create()
    .withPlugins(CKEditorPlugin.IMAGE_CAPTION) // Missing IMAGE dependency
    .withDependencyMode(DependencyMode.STRICT)
    .build(); // Throws IllegalStateException

// Manual mode - no dependency checking
VaadinCKEditor editor = VaadinCKEditor.create()
    .withPlugins(CKEditorPlugin.ESSENTIALS, CKEditorPlugin.PARAGRAPH, CKEditorPlugin.BOLD)
    .withDependencyMode(DependencyMode.MANUAL)
    .build();
See Also:

  • Nested Class Summary

    Nested classes/interfaces inherited from class com.vaadin.flow.component.AbstractField

    com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<C,V>

    Nested classes/interfaces inherited from interface com.vaadin.flow.component.BlurNotifier

    com.vaadin.flow.component.BlurNotifier.BlurEvent<C>

    Nested classes/interfaces inherited from interface com.vaadin.flow.component.FocusNotifier

    com.vaadin.flow.component.FocusNotifier.FocusEvent<C>

    Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue

    com.vaadin.flow.component.HasValue.ValueChangeEvent<V>, com.vaadin.flow.component.HasValue.ValueChangeListener<E>

  • Method Summary

    Modifier and Type
    Method
    Description
    com.vaadin.flow.shared.Registration
    addAutosaveListener(com.vaadin.flow.component.ComponentEventListener<AutosaveEvent> listener)
    Add autosave event listener.
    com.vaadin.flow.shared.Registration
    addContentChangeListener(com.vaadin.flow.component.ComponentEventListener<ContentChangeEvent> listener)
    Add content change event listener.
    com.vaadin.flow.shared.Registration
    addEditorErrorListener(com.vaadin.flow.component.ComponentEventListener<EditorErrorEvent> listener)
    Add editor error event listener.
    com.vaadin.flow.shared.Registration
    addEditorReadyListener(com.vaadin.flow.component.ComponentEventListener<EditorReadyEvent> listener)
    Add editor ready event listener.
    com.vaadin.flow.shared.Registration
    addFallbackListener(com.vaadin.flow.component.ComponentEventListener<FallbackEvent> listener)
    Add fallback event listener.
    boolean
    cancelUpload(String uploadId)
    Cancel the specified upload task.
    void
    cleanupListeners()
    Clean up all event listeners.
    void
    clear()
    Clear editor content
    static VaadinCKEditorBuilder
    create()
    Create editor builder.
    protected String
    generateModelValue()
     
    int
    getActiveUploadCount()
    Get the number of active uploads.
    int
    getCharacterCount()
    Get character count of content (excluding HTML tags).
    ErrorHandler
    getErrorHandler()
    Get error handler.
    FallbackEvent.FallbackMode
    getFallbackMode()
    Get fallback mode.
    HtmlSanitizer
    getHtmlSanitizer()
    Get HTML sanitizer.
    Optional<String>
    getId()
     
    EventDispatcher.ListenerStats
    getListenerStats()
    Get statistics of registered listeners.
    String
    getPlainText()
    Get plain text content (strip HTML tags)
    String
    getSanitizedHtml()
    Get sanitized HTML (remove dangerous tags)
    String
    getSanitizedValue()
    Get sanitized content.
    UploadHandler
    getUploadHandler()
    Get upload handler.
    String
    getValue()
     
    static String
    getVersion()
    Get version
    int
    getWordCount()
    Get word count of content.
    boolean
    hasActiveUploads()
    Check if there are uploads in progress.
    void
    insertText(String text)
    Insert text at cursor position
    boolean
    isContentEmpty()
    Check if content is empty.
    boolean
    isReadOnly()
     
    String
    sanitizeHtml(String html, org.jsoup.safety.Safelist safelist)
    Sanitize HTML with specified rules
    void
    setAllowConfigRequiredPlugins(boolean allow)
    Allow plugins that require special configuration (CloudServices, Minimap, etc.).
    void
    setAnnotationSidebarEnabled(boolean enabled)
    Enable annotation sidebar for collaboration features (DECOUPLED type only).
    void
    setAutosaveCallback(Consumer<String> callback)
    Set autosave callback
    void
    setCommentPermissionEnforcerEnabled(boolean enabled)
    启用评论权限强制插件，隐藏非当前用户评论的 Edit/Remove 下拉菜单。
    void
    setDocumentOutlineEnabled(boolean enabled)
    Enable Document Outline sidebar (DECOUPLED type only).
    void
    setErrorHandler(ErrorHandler handler)
    Set error handler.
    void
    setFallbackMode(FallbackEvent.FallbackMode mode)
    Set fallback mode.
    void
    setGeneralHtmlSupportEnabled(boolean enabled)
    Enable general HTML support
    void
    setHeight(String height)
     
    void
    setHideToolbar(boolean hide)
    Set toolbar visibility
    void
    setHtmlSanitizer(HtmlSanitizer sanitizer)
    Set HTML sanitizer.
    void
    setId(String id)
    Set editor ID.
    void
    setMinimapEnabled(boolean enabled)
    Enable minimap (DECOUPLED type only)
    void
    setMinimapSimplePreview(boolean enabled)
    Enable simple preview mode for minimap (DECOUPLED type only).
    protected void
    setModelValue(String value, boolean fromClient)
     
    void
    setOverrideCssUrl(String url)
    Set custom CSS URL
    protected void
    setPresentationValue(String value)
     
    void
    setReadOnly(boolean readOnly)
     
    void
    setReadOnlyWithToolbarAction(boolean readOnly)
    Enable read-only mode and hide toolbar
    void
    setSynchronized(boolean sync)
    Set synchronous update mode
    void
    setUploadHandler(UploadHandler handler)
    Set upload handler.
    void
    setValue(String value)
     
    void
    setWidth(String width)
     
    static VaadinCKEditor
    withPreset(CKEditorPreset preset)
    Quick create editor with preset

    Methods inherited from class com.vaadin.flow.component.customfield.CustomField

    add, addThemeVariants, getLabel, remove, removeThemeVariants, setLabel, updateValue

    Methods inherited from class com.vaadin.flow.component.AbstractField

    addValueChangeListener, getEmptyValue, isEmpty, valueEquals

    Methods inherited from class com.vaadin.flow.component.Component

    addListener, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getListeners, getLocale, getParent, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onAttach, onDetach, onEnabledStateChanged, removeFromParent, scrollIntoView, scrollIntoView, set, setElement, setVisible

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface com.vaadin.flow.component.AttachNotifier

    addAttachListener

    Methods inherited from interface com.vaadin.flow.component.BlurNotifier

    addBlurListener

    Methods inherited from interface com.vaadin.flow.component.DetachNotifier

    addDetachListener

    Methods inherited from interface com.vaadin.flow.component.Focusable

    addFocusShortcut, blur, focus, focus, getTabIndex, setTabIndex

    Methods inherited from interface com.vaadin.flow.component.FocusNotifier

    addFocusListener

    Methods inherited from interface com.vaadin.flow.component.HasAriaLabel

    getAriaLabel, getAriaLabelledBy, setAriaLabel, setAriaLabelledBy

    Methods inherited from interface com.vaadin.flow.component.HasElement

    getElement

    Methods inherited from interface com.vaadin.flow.component.HasEnabled

    isEnabled, setEnabled

    Methods inherited from interface com.vaadin.flow.component.HasHelper

    getHelperComponent, getHelperText, setHelperComponent, setHelperText

    Methods inherited from interface com.vaadin.flow.component.HasSize

    getHeight, getHeightUnit, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getWidth, getWidthUnit, setHeight, setHeightFull, setMaxHeight, setMaxHeight, setMaxWidth, setMaxWidth, setMinHeight, setMinHeight, setMinWidth, setMinWidth, setSizeFull, setSizeUndefined, setWidth, setWidthFull

    Methods inherited from interface com.vaadin.flow.component.HasStyle

    addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

    Methods inherited from interface com.vaadin.flow.component.HasTheme

    addThemeName, addThemeNames, getThemeName, getThemeNames, hasThemeName, removeThemeName, removeThemeNames, setThemeName, setThemeName

    Methods inherited from interface com.vaadin.flow.component.shared.HasTooltip

    getTooltip, setTooltipMarkdown, setTooltipText

    Methods inherited from interface com.vaadin.flow.component.HasValidation

    setManualValidation

    Methods inherited from interface com.vaadin.flow.component.shared.HasValidationProperties

    getErrorMessage, isInvalid, setErrorMessage, setInvalid

    Methods inherited from interface com.vaadin.flow.component.HasValue

    addValueChangeListener, getEmptyValue, getOptionalValue, isEmpty

    Methods inherited from interface com.vaadin.flow.component.HasValueAndElement

    isRequiredIndicatorVisible, setRequiredIndicatorVisible

  • Method Details

    • create

      public static VaadinCKEditorBuilder create()
      Create editor builder.
      Returns:
      a new builder instance

    • withPreset

      public static VaadinCKEditor withPreset(CKEditorPreset preset)
      Quick create editor with preset

    • generateModelValue

      protected String generateModelValue()
      Specified by:
      generateModelValue in class com.vaadin.flow.component.customfield.CustomField<String>

    • setPresentationValue

      protected void setPresentationValue(String value)
      Specified by:
      setPresentationValue in class com.vaadin.flow.component.customfield.CustomField<String>

    • getValue

      public String getValue()
      Specified by:
      getValue in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>
      Overrides:
      getValue in class com.vaadin.flow.component.AbstractField<com.vaadin.flow.component.customfield.CustomField<String>, String>

    • getSanitizedValue

      public String getSanitizedValue()
      Get sanitized content. If HtmlSanitizer is set, applies sanitization; otherwise returns original content.
      Returns:
      sanitized HTML content

    • setValue

      public void setValue(String value)
      Specified by:
      setValue in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>
      Overrides:
      setValue in class com.vaadin.flow.component.AbstractField<com.vaadin.flow.component.customfield.CustomField<String>, String>

    • setModelValue

      protected void setModelValue(String value, boolean fromClient)
      Overrides:
      setModelValue in class com.vaadin.flow.component.AbstractField<com.vaadin.flow.component.customfield.CustomField<String>, String>

    • setId

      public void setId(String id)
      Set editor ID. Note: This sets both the Vaadin component ID and the internal editorId property. The editorId is used for frontend component identification.
      Overrides:
      setId in class com.vaadin.flow.component.Component
      Parameters:
      id - the ID to set, or null to generate a random ID

    • getId

      public Optional<String> getId()
      Overrides:
      getId in class com.vaadin.flow.component.Component

    • setReadOnly

      public void setReadOnly(boolean readOnly)
      Specified by:
      setReadOnly in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>
      Specified by:
      setReadOnly in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>

    • isReadOnly

      public boolean isReadOnly()
      Specified by:
      isReadOnly in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>
      Specified by:
      isReadOnly in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>

    • setWidth

      public void setWidth(String width)
      Specified by:
      setWidth in interface com.vaadin.flow.component.HasSize

    • setHeight

      public void setHeight(String height)
      Specified by:
      setHeight in interface com.vaadin.flow.component.HasSize

    • setHideToolbar

      public void setHideToolbar(boolean hide)
      Set toolbar visibility

    • setReadOnlyWithToolbarAction

      public void setReadOnlyWithToolbarAction(boolean readOnly)
      Enable read-only mode and hide toolbar

    • setMinimapEnabled

      public void setMinimapEnabled(boolean enabled)
      Enable minimap (DECOUPLED type only)

    • setMinimapSimplePreview

      public void setMinimapSimplePreview(boolean enabled)
      Enable simple preview mode for minimap (DECOUPLED type only). When true, minimap renders content as simple boxes for better performance. Use this option if the minimap updates too slowly with large documents.
      Parameters:
      enabled - true to enable simple preview mode

    • setDocumentOutlineEnabled

      public void setDocumentOutlineEnabled(boolean enabled)
      Enable Document Outline sidebar (DECOUPLED type only). Requires DocumentOutline plugin to be loaded (premium feature).
      Parameters:
      enabled - true to enable document outline

    • setAnnotationSidebarEnabled

      public void setAnnotationSidebarEnabled(boolean enabled)
      Enable annotation sidebar for collaboration features (DECOUPLED type only). Provides container for Comments, TrackChanges and PresenceList UI.
      Parameters:
      enabled - true to enable annotation sidebar and presence list

    • setCommentPermissionEnforcerEnabled

      public void setCommentPermissionEnforcerEnabled(boolean enabled)
      启用评论权限强制插件，隐藏非当前用户评论的 Edit/Remove 下拉菜单。 需要同时启用 annotationSidebarEnabled 和 CommentsRepository 插件。
      Parameters:
      enabled - true 启用评论权限 UI 强制

    • setGeneralHtmlSupportEnabled

      public void setGeneralHtmlSupportEnabled(boolean enabled)
      Enable general HTML support

    • setAllowConfigRequiredPlugins

      public void setAllowConfigRequiredPlugins(boolean allow)
      Allow plugins that require special configuration (CloudServices, Minimap, etc.). When enabled, these plugins won't be automatically filtered out by the plugin resolver. This is automatically set to true when premium plugins requiring CloudServices are used.

    • setSynchronized

      public void setSynchronized(boolean sync)
      Set synchronous update mode

    • setOverrideCssUrl

      public void setOverrideCssUrl(String url)
      Set custom CSS URL

    • setAutosaveCallback

      public void setAutosaveCallback(Consumer<String> callback)
      Set autosave callback

    • clear

      public void clear()
      Clear editor content
      Specified by:
      clear in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<com.vaadin.flow.component.customfield.CustomField<String>, String>, String>

    • insertText

      public void insertText(String text)
      Insert text at cursor position

    • getPlainText

      public String getPlainText()
      Get plain text content (strip HTML tags)

    • getSanitizedHtml

      public String getSanitizedHtml()
      Get sanitized HTML (remove dangerous tags)

    • sanitizeHtml

      public String sanitizeHtml(String html, org.jsoup.safety.Safelist safelist)
      Sanitize HTML with specified rules

    • getCharacterCount

      public int getCharacterCount()
      Get character count of content (excluding HTML tags).
      Returns:
      character count

    • getWordCount

      public int getWordCount()
      Get word count of content.
      Returns:
      word count

    • isContentEmpty

      public boolean isContentEmpty()
      Check if content is empty.
      Returns:
      true if content is empty or contains only whitespace

    • getVersion

      public static String getVersion()
      Get version

    • addEditorReadyListener

      public com.vaadin.flow.shared.Registration addEditorReadyListener(com.vaadin.flow.component.ComponentEventListener<EditorReadyEvent> listener)
      Add editor ready event listener. Fired when the editor is fully initialized and ready to accept user input.

      Usage example:

      editor.addEditorReadyListener(event -> {
    logger.info("Editor ready in {} ms", event.getInitializationTimeMs());
    event.getSource().focus();
});
      Parameters:
      listener - the event listener
      Returns:
      registration object for removing the listener

    • addEditorErrorListener

      public com.vaadin.flow.shared.Registration addEditorErrorListener(com.vaadin.flow.component.ComponentEventListener<EditorErrorEvent> listener)
      Add editor error event listener. Fired when the editor encounters an error.

      Usage example:

      editor.addEditorErrorListener(event -> {
    EditorError error = event.getError();
    if (error.getSeverity() == ErrorSeverity.FATAL) {
        Notification.show("Editor error: " + error.getMessage(),
            Notification.Type.ERROR_MESSAGE);
    }
});
      Parameters:
      listener - the event listener
      Returns:
      registration object for removing the listener

    • addAutosaveListener

      public com.vaadin.flow.shared.Registration addAutosaveListener(com.vaadin.flow.component.ComponentEventListener<AutosaveEvent> listener)
      Add autosave event listener. Fired when editor content is auto-saved.
      Parameters:
      listener - the event listener
      Returns:
      registration object for removing the listener

    • addContentChangeListener

      public com.vaadin.flow.shared.Registration addContentChangeListener(com.vaadin.flow.component.ComponentEventListener<ContentChangeEvent> listener)
      Add content change event listener. Fired when editor content changes.
      Parameters:
      listener - the event listener
      Returns:
      registration object for removing the listener

    • addFallbackListener

      public com.vaadin.flow.shared.Registration addFallbackListener(com.vaadin.flow.component.ComponentEventListener<FallbackEvent> listener)
      Add fallback event listener. Fired when the editor triggers fallback mode due to an error.
      Parameters:
      listener - the event listener
      Returns:
      registration object for removing the listener

    • setErrorHandler

      public void setErrorHandler(ErrorHandler handler)
      Set error handler.
      Parameters:
      handler - the error handler

    • getErrorHandler

      public ErrorHandler getErrorHandler()
      Get error handler.
      Returns:
      the error handler, may be null

    • setHtmlSanitizer

      public void setHtmlSanitizer(HtmlSanitizer sanitizer)
      Set HTML sanitizer.
      Parameters:
      sanitizer - the HTML sanitizer

    • getHtmlSanitizer

      public HtmlSanitizer getHtmlSanitizer()
      Get HTML sanitizer.
      Returns:
      the HTML sanitizer, may be null

    • setUploadHandler

      public void setUploadHandler(UploadHandler handler)
      Set upload handler.
      Parameters:
      handler - the upload handler

    • getUploadHandler

      public UploadHandler getUploadHandler()
      Get upload handler.
      Returns:
      the upload handler, may be null

    • setFallbackMode

      public void setFallbackMode(FallbackEvent.FallbackMode mode)
      Set fallback mode.
      Parameters:
      mode - the fallback mode

    • getFallbackMode

      public FallbackEvent.FallbackMode getFallbackMode()
      Get fallback mode.
      Returns:
      the current fallback mode

    • getListenerStats

      public EventDispatcher.ListenerStats getListenerStats()
      Get statistics of registered listeners. Used for debugging and monitoring.
      Returns:
      listener statistics

    • cleanupListeners

      public void cleanupListeners()
      Clean up all event listeners. Usually called before component destruction.

    • hasActiveUploads

      public boolean hasActiveUploads()
      Check if there are uploads in progress.
      Returns:
      true if there are active uploads

    • getActiveUploadCount

      public int getActiveUploadCount()
      Get the number of active uploads.
      Returns:
      active upload count

    • cancelUpload

      public boolean cancelUpload(String uploadId)
      Cancel the specified upload task.
      Parameters:
      uploadId - the upload ID
      Returns:
      true if successfully cancelled