markdownEditor

markdownEditor 支持编写和预览 Markdown 内容。

XML 元素

markdownEditor

Java 类

JmixMarkdownEditor

概览

Markdown editor

基本用法

使用 markdownEditor,为用户提供输入 Markdown 文本并带有快速格式控制工具和即时预览。

XML
<markdownEditor id="markdownEditor" label="MarkdownEditor" helperText="Helper text"/>
Java
@ViewComponent
protected MarkdownEditor markdownEditor;

@Subscribe
protected void onInit(InitEvent event) {
    markdownEditor.setValue("""
            # Markdown Editor

            Use the **toolbar** or _keyboard shortcuts_ to format text.

            - Bulleted list item
            - [Link to jmix.io](https://www.jmix.io)
            - `inline code`

            > Switch to the **Preview** tab to see the rendered result.
            """);
}

组件的值是一个包含原始 Markdown 标记的 String。

数据感知的 markdownEditor

与其他输入组件一样,markdownEditor 也可以使用 dataContainer 和 property 与实体的属性绑定。

XML
<data>
    <instance id="orderDc"
              class="io.jmix.uisamples.entity.Order"
              fetchPlan="_local"/>
</data>
<layout>
    <markdownEditor id="markdownEditor" label="Order description"
                    dataContainer="orderDc" property="description"/>
    <hbox>
        <span text="Value in the container:" css="flex-shrink: 0;"/>
        <span id="spanValue"/>
    </hbox>
</layout>
Java
@ViewComponent
protected InstanceContainer<Order> orderDc;
@ViewComponent
protected Span spanValue;

@Autowired
protected Metadata metadata;

@Subscribe
protected void onInit(View.InitEvent event) {
    Order order = metadata.create(Order.class);
    order.setDescription("""
            ## Order description

            **Customer:** John Doe

            **E-mail:** j.doe@jmix.io

            **Comment:** Deliver as quickly as possible.
            """);
    orderDc.setItem(order);
}

@Subscribe("markdownEditor")
protected void onMarkdownEditorValueChange(ComponentValueChangeEvent<MarkdownEditor, String> changeEvent) {
    spanValue.setText(orderDc.getItem().getDescription());
}

将组件与实体中保存 Markdown 文本的 String 属性绑定。

模式

编辑器有两种模式,可通过 header 切换:

  • Edit 支持用户输入和格式化 Markdown 文本。

  • Preview 将当前值渲染为格式化的 HTML。

默认模式为 Edit。

可以使用 mode XML 属性以声明方式配置组件的初始模式。

<markdownEditor id="markdownEditorField"
                mode="PREVIEW"/>

如果 readOnly = true,组件仅显示渲染后的预览。隐藏工具栏和模式标签页,且值无法更改。

当前模式也可以通过服务端 API 进行读取和编程式更改。当模式更改时,组件会触发一个 ModeChangeEvent,事件中包含新模式以及一个标志,指示该更改是由用户还是应用程序发起的。

工具栏的操作

在 Edit 模式下,模式标签页和格式化工具栏共享同一个 header。如果没有足够的水平空间,多余的工具栏操作会被移至该行末尾的溢出菜单中。

工具栏按钮状态与当前光标位置处的格式对应。点击已激活的格式化按钮会移除相应的格式。

包装格式

这些操作作用于当前选中的内容,或者当未选中任何内容时,作用于光标位置。

操作 快捷键 应用 移除

粗体

Cmd/Ctrl+B

将选中文本用 ** 包装。如果未选中任何内容,则插入 **** 并将光标置于标记之间。

移除周围的 **。

斜体

Cmd/Ctrl+I

将选中文本用 _ 包装。如果未选中任何内容,则插入 __ 并将光标置于标记之间。

移除周围的 _。

代码

Cmd/Ctrl+E

将选中文本用单个反引号包装。如果未选中任何内容,则插入两个反引号并将光标置于它们之间。

移除周围的反引号。

链接

Cmd/Ctrl+K

将选中内容包装为 [text](url)。如果未选中任何内容,则插入 [](url) 并将光标置于 [] 内。

移除周围的 Markdown 链接标记。

行格式

这些操作作用于当前行,或者当选中多行时,作用于每一行。

操作 应用 移除

标题

在行首添加 ## 前缀。

移除 ## 前缀。

引用

在行首添加 > 前缀。

移除 > 前缀。

无序列表

在行首添加 - 前缀。

移除 - 前缀。

有序列表

在行首添加 1. 前缀。

移除数字列表前缀。

任务列表

在行首添加 - [ ] 前缀。

移除 - [ ] 前缀。

当选中多行且所有行都已具有目标格式时,点击工具栏按钮会从所有选中行中移除该格式。否则,该格式会应用于那些没有该格式的选中行。

键盘导航

该组件支持跨三个逻辑焦点区域的键盘导航:

  • 模式标签页

  • 工具栏

  • 文本区域

Tab 键在这些区域之间移动焦点。方向键在激活区域内导航。在工具栏中按 Escape 键可将焦点返回到文本区域。

如果某些工具栏操作被移入溢出 ··· 菜单,则当菜单打开时,第一个菜单项会获得焦点。在菜单中,ArrowUp 和 ArrowDown 选择前一个和后一个菜单项,而 Escape 和 Tab 关闭菜单并将焦点返回到溢出按钮。

格式变更集成了浏览器的 undo 栈,因此标准快捷键也有效:

  • Cmd/Ctrl+Z 撤销格式更改和输入更改。

  • Cmd/Ctrl+Shift+Z 或 Ctrl+Y 重做格式更改和输入更改。

CSS 属性

可以通过在应用程序主题中使用 CSS 自定义属性,或通过 css 属性来定制组件。

<markdownEditor id="markdownEditCss"
                css="--jmix-markdown-editor-default-width: 32rem;
                     --jmix-markdown-editor-header-background: var(--lumo-contrast-5pct);"/>
属性 描述 支持的主题

--jmix-markdown-editor-default-width

设置组件的默认宽度。

Aura, Lumo

--jmix-markdown-editor-header-background

设置包含标签页和工具栏的共享 header 行的背景。

Aura, Lumo

--jmix-markdown-editor-toolbar-button-padding

控制工具栏按钮的内边距。

Aura, Lumo

--jmix-markdown-editor-toolbar-button-border-width

控制工具栏按钮的边框宽度。

Aura, Lumo

--jmix-markdown-editor-toolbar-button-border-color

控制工具栏按钮的边框颜色。

Aura, Lumo

--jmix-markdown-editor-toolbar-button-border-radius

控制工具栏按钮的边框圆角。

Aura, Lumo

--jmix-markdown-editor-toolbar-button-text-color

控制工具栏按钮的文本颜色。

Aura, Lumo

--jmix-markdown-editor-toolbar-button-background

控制工具栏按钮的背景。

Aura, Lumo

--jmix-markdown-editor-tab-padding

控制标签页的内边距。

Aura, Lumo

--jmix-markdown-editor-tab-text-color

控制标签页的文本颜色。

Aura, Lumo

--jmix-markdown-editor-tab-background

控制标签页的背景。

Aura, Lumo

国际化

所有用户可见的字符串都有英文默认值,并且可以独立覆盖。

组件为以下内容提供默认标题:

  • 标签页:Edit、Preview

  • 工具栏操作:Heading、Bold、Italic、Quote、Code、Link、Unordered list、Ordered list、Task list

  • 溢出菜单按钮

  • 工具栏可访问名称

如果应用程序只覆盖了这些字符串的一部分,所有其他标题将继续使用其默认值。

验证

如需检查 markdownEditor 组件中输入的值,可以在内部的 validators 元素中使用 validator。

由于组件值存储为原始 Markdown 字符串,像 notBlank 和 size 这样的验证器对于检查内容是否存在以及在预期长度范围内很有帮助。

以下预定义验证器可用于 markdownEditor:

XML 元素

validators

预定义验证器

custom - notBlank - notEmpty - notNull - size

样式版本

使用 themeNames 属性配置一个或多个样式。

样式 描述 支持的主题

helper-above-field

在字段上方(标签下方)渲染帮助文本。

Aura, Lumo

toolbar-align-start

根据当前文本方向,将工具栏按钮向 header 起始侧对齐。

Aura, Lumo

toolbar-align-center

在 header 中居中对齐工具栏按钮并隐藏分隔线。

Aura, Lumo

toolbar-align-end

根据当前文本方向,将工具栏按钮向 header 末尾侧对齐,并隐藏分隔线。

Aura, Lumo

XML 属性

以下是 markdownEditor 特有的属性:

名称 描述 默认值

mode

设置编辑器的 模式。

EDIT

下面是 markdownEditor 支持的其他通用属性:

事件和处理器

下面是 markdownEditor 的特殊事件和处理器:

名称 描述

ModeChangeEvent

当编辑器在 Edit 和 Preview 模式 之间切换时触发的 JmixMarkdownEditor.ModeChangeEvent。该事件包含新模式以及一个标志,指示更改是由用户还是由应用程序发起的。

validator

验证组件值。

下面是 markdownEditor 支持的其他通用事件:

XML 内部元素

一个 markdownEditor 可以包含 tooltip and validators 作为其内部元素。

参考

  • markdown 了解无编辑能力的 Markdown 内容渲染。