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
    Modifier and Type
    Class
    Description
    static class 
    VaadinCKEditor.Builder
    Deprecated.
    Use VaadinCKEditorBuilder directly instead.
    static class 
    VaadinCKEditor.DependencyMode
    Deprecated.
    Use VaadinCKEditorBuilder.DependencyMode instead.

    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)
    添加自动保存事件监听器。
    com.vaadin.flow.shared.Registration
    addContentChangeListener(com.vaadin.flow.component.ComponentEventListener<ContentChangeEvent> listener)
    添加内容变更事件监听器。
    com.vaadin.flow.shared.Registration
    addEditorErrorListener(com.vaadin.flow.component.ComponentEventListener<EditorErrorEvent> listener)
    添加编辑器错误事件监听器。
    com.vaadin.flow.shared.Registration
    addEditorReadyListener(com.vaadin.flow.component.ComponentEventListener<EditorReadyEvent> listener)
    添加编辑器就绪事件监听器。
    com.vaadin.flow.shared.Registration
    addFallbackListener(com.vaadin.flow.component.ComponentEventListener<FallbackEvent> listener)
    添加降级事件监听器。
    boolean
    cancelUpload(String uploadId)
    取消指定的上传任务
    void
    cleanupListeners()
    清理所有事件监听器。
    void
    clear()
    Clear editor content
    static VaadinCKEditorBuilder
    create()
    Create editor builder.
    protected String
    generateModelValue()
     
    int
    getActiveUploadCount()
    获取活跃上传数量
    int
    getCharacterCount()
    获取内容字符数（不包含 HTML 标签）
    ErrorHandler
    getErrorHandler()
    获取错误处理器。
    FallbackEvent.FallbackMode
    getFallbackMode()
    获取降级模式。
    HtmlSanitizer
    getHtmlSanitizer()
    获取 HTML 清理器。
    Optional<String>
    getId()
     
    EventDispatcher.ListenerStats
    getListenerStats()
    获取已注册监听器的统计信息。
    String
    getPlainText()
    Get plain text content (strip HTML tags)
    String
    getSanitizedHtml()
    Get sanitized HTML (remove dangerous tags)
    String
    getSanitizedValue()
    获取经过清理的内容。
    UploadHandler
    getUploadHandler()
    获取上传处理器。
    String
    getValue()
     
    static String
    getVersion()
    Get version
    int
    getWordCount()
    获取内容单词数
    boolean
    hasActiveUploads()
    检查是否有正在进行的上传
    void
    insertText(String text)
    Insert text at cursor position
    boolean
    isContentEmpty()
    检查内容是否为空
    boolean
    isReadOnly()
     
    String
    sanitizeHtml(String html, org.jsoup.safety.Safelist safelist)
    Sanitize HTML with specified rules
    void
    setAutosaveCallback(Consumer<String> callback)
    Set autosave callback
    void
    setErrorHandler(ErrorHandler handler)
    设置错误处理器。
    void
    setFallbackMode(FallbackEvent.FallbackMode mode)
    设置降级模式。
    void
    setGeneralHtmlSupportEnabled(boolean enabled)
    Enable general HTML support
    void
    setHeight(String height)
     
    void
    setHideToolbar(boolean hide)
    Set toolbar visibility
    void
    setHtmlSanitizer(HtmlSanitizer sanitizer)
    设置 HTML 清理器。
    void
    setId(String id)
    Set editor ID.
    void
    setMinimapEnabled(boolean enabled)
    Enable 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)
    设置上传处理器。
    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()
      获取经过清理的内容。 如果设置了 HtmlSanitizer，则应用清理；否则返回原始内容。
      Returns:
      清理后的 HTML 内容

    • 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)

    • setGeneralHtmlSupportEnabled

      public void setGeneralHtmlSupportEnabled(boolean enabled)
      Enable general HTML support

    • 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()
      获取内容字符数（不包含 HTML 标签）
      Returns:
      字符数

    • getWordCount

      public int getWordCount()
      获取内容单词数
      Returns:
      单词数

    • isContentEmpty

      public boolean isContentEmpty()
      检查内容是否为空
      Returns:
      如果内容为空或只包含空白则返回 true

    • getVersion

      public static String getVersion()
      Get version

    • addEditorReadyListener

      public com.vaadin.flow.shared.Registration addEditorReadyListener(com.vaadin.flow.component.ComponentEventListener<EditorReadyEvent> listener)
      添加编辑器就绪事件监听器。 当编辑器完全初始化并准备好接受用户输入时触发。

      使用示例：

      editor.addEditorReadyListener(event -> {
    logger.info("Editor ready in {} ms", event.getInitializationTimeMs());
    event.getSource().focus();
});
      Parameters:
      listener - 事件监听器
      Returns:
      用于移除监听器的注册对象

    • addEditorErrorListener

      public com.vaadin.flow.shared.Registration addEditorErrorListener(com.vaadin.flow.component.ComponentEventListener<EditorErrorEvent> listener)
      添加编辑器错误事件监听器。 当编辑器遇到错误时触发。

      使用示例：

      editor.addEditorErrorListener(event -> {
    EditorError error = event.getError();
    if (error.getSeverity() == ErrorSeverity.FATAL) {
        Notification.show("编辑器错误: " + error.getMessage(),
            Notification.Type.ERROR_MESSAGE);
    }
});
      Parameters:
      listener - 事件监听器
      Returns:
      用于移除监听器的注册对象

    • addAutosaveListener

      public com.vaadin.flow.shared.Registration addAutosaveListener(com.vaadin.flow.component.ComponentEventListener<AutosaveEvent> listener)
      添加自动保存事件监听器。 当编辑器内容自动保存时触发。
      Parameters:
      listener - 事件监听器
      Returns:
      用于移除监听器的注册对象

    • addContentChangeListener

      public com.vaadin.flow.shared.Registration addContentChangeListener(com.vaadin.flow.component.ComponentEventListener<ContentChangeEvent> listener)
      添加内容变更事件监听器。 当编辑器内容发生变化时触发。
      Parameters:
      listener - 事件监听器
      Returns:
      用于移除监听器的注册对象

    • addFallbackListener

      public com.vaadin.flow.shared.Registration addFallbackListener(com.vaadin.flow.component.ComponentEventListener<FallbackEvent> listener)
      添加降级事件监听器。 当编辑器因错误触发降级模式时触发。
      Parameters:
      listener - 事件监听器
      Returns:
      用于移除监听器的注册对象

    • setErrorHandler

      public void setErrorHandler(ErrorHandler handler)
      设置错误处理器。
      Parameters:
      handler - 错误处理器

    • getErrorHandler

      public ErrorHandler getErrorHandler()
      获取错误处理器。
      Returns:
      错误处理器，可能为 null

    • setHtmlSanitizer

      public void setHtmlSanitizer(HtmlSanitizer sanitizer)
      设置 HTML 清理器。
      Parameters:
      sanitizer - HTML 清理器

    • getHtmlSanitizer

      public HtmlSanitizer getHtmlSanitizer()
      获取 HTML 清理器。
      Returns:
      HTML 清理器，可能为 null

    • setUploadHandler

      public void setUploadHandler(UploadHandler handler)
      设置上传处理器。
      Parameters:
      handler - 上传处理器

    • getUploadHandler

      public UploadHandler getUploadHandler()
      获取上传处理器。
      Returns:
      上传处理器，可能为 null

    • setFallbackMode

      public void setFallbackMode(FallbackEvent.FallbackMode mode)
      设置降级模式。
      Parameters:
      mode - 降级模式

    • getFallbackMode

      public FallbackEvent.FallbackMode getFallbackMode()
      获取降级模式。
      Returns:
      当前降级模式

    • getListenerStats

      public EventDispatcher.ListenerStats getListenerStats()
      获取已注册监听器的统计信息。 用于调试和监控。
      Returns:
      监听器统计信息

    • cleanupListeners

      public void cleanupListeners()
      清理所有事件监听器。 通常在组件销毁前调用。

    • hasActiveUploads

      public boolean hasActiveUploads()
      检查是否有正在进行的上传
      Returns:
      是否有活跃上传

    • getActiveUploadCount

      public int getActiveUploadCount()
      获取活跃上传数量
      Returns:
      活跃上传数

    • cancelUpload

      public boolean cancelUpload(String uploadId)
      取消指定的上传任务
      Parameters:
      uploadId - 上传 ID
      Returns:
      是否成功取消