markdownEditor
markdownEditor 支持编写和预览 Markdown 内容。
XML 元素 |
|
|---|---|
Java 类 |
|
基本用法
使用 markdownEditor,为用户提供输入 Markdown 文本并带有快速格式控制工具和即时预览。
<markdownEditor id="markdownEditor" label="MarkdownEditor" helperText="Helper text"/>
@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 与实体的属性绑定。
<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>
@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。如果没有足够的水平空间,多余的工具栏操作会被移至该行末尾的溢出菜单中。
工具栏按钮状态与当前光标位置处的格式对应。点击已激活的格式化按钮会移除相应的格式。
包装格式
这些操作作用于当前选中的内容,或者当未选中任何内容时,作用于光标位置。
| 操作 | 快捷键 | 应用 | 移除 |
|---|---|---|---|
粗体 |
|
将选中文本用 |
移除周围的 |
斜体 |
|
将选中文本用 |
移除周围的 |
代码 |
|
将选中文本用单个反引号包装。如果未选中任何内容,则插入两个反引号并将光标置于它们之间。 |
移除周围的反引号。 |
链接 |
|
将选中内容包装为 |
移除周围的 Markdown 链接标记。 |
行格式
这些操作作用于当前行,或者当选中多行时,作用于每一行。
| 操作 | 应用 | 移除 |
|---|---|---|
标题 |
在行首添加 |
移除 |
引用 |
在行首添加 |
移除 |
无序列表 |
在行首添加 |
移除 |
有序列表 |
在行首添加 |
移除数字列表前缀。 |
任务列表 |
在行首添加 |
移除 |
当选中多行且所有行都已具有目标格式时,点击工具栏按钮会从所有选中行中移除该格式。否则,该格式会应用于那些没有该格式的选中行。
键盘导航
该组件支持跨三个逻辑焦点区域的键盘导航:
-
模式标签页
-
工具栏
-
文本区域
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);"/>
| 属性 | 描述 | 支持的主题 |
|---|---|---|
|
设置组件的默认宽度。 |
Aura, Lumo |
|
设置包含标签页和工具栏的共享 header 行的背景。 |
Aura, Lumo |
|
控制工具栏按钮的内边距。 |
Aura, Lumo |
|
控制工具栏按钮的边框宽度。 |
Aura, Lumo |
|
控制工具栏按钮的边框颜色。 |
Aura, Lumo |
|
控制工具栏按钮的边框圆角。 |
Aura, Lumo |
|
控制工具栏按钮的文本颜色。 |
Aura, Lumo |
|
控制工具栏按钮的背景。 |
Aura, Lumo |
|
控制标签页的内边距。 |
Aura, Lumo |
|
控制标签页的文本颜色。 |
Aura, Lumo |
|
控制标签页的背景。 |
Aura, Lumo |
国际化
所有用户可见的字符串都有英文默认值,并且可以独立覆盖。
组件为以下内容提供默认标题:
-
标签页:
Edit、Preview -
工具栏操作:
Heading、Bold、Italic、Quote、Code、Link、Unordered list、Ordered list、Task list -
溢出菜单按钮
-
工具栏可访问名称
如果应用程序只覆盖了这些字符串的一部分,所有其他标题将继续使用其默认值。
样式版本
使用 themeNames 属性配置一个或多个样式。
| 样式 | 描述 | 支持的主题 |
|---|---|---|
|
在字段上方(标签下方)渲染帮助文本。 |
Aura, Lumo |
|
根据当前文本方向,将工具栏按钮向 header 起始侧对齐。 |
Aura, Lumo |
|
在 header 中居中对齐工具栏按钮并隐藏分隔线。 |
Aura, Lumo |
|
根据当前文本方向,将工具栏按钮向 header 末尾侧对齐,并隐藏分隔线。 |
Aura, Lumo |
XML 属性
以下是 markdownEditor 特有的属性:
| 名称 | 描述 | 默认值 |
|---|---|---|
设置编辑器的 模式。 |
|
下面是 markdownEditor 支持的其他通用属性:
id - alignSelf - ariaLabel - ariaLabelledBy - autofocus - classNames - colspan - css - dataContainer - enabled - errorMessage - focusShortcut - height - helperText - justifySelf - label - maxHeight - maxWidth - minHeight - minWidth - placeholder - property - readOnly - required - requiredMessage - tabIndex - themeNames - valueChangeMode - valueChangeTimeout - visible - width
事件和处理器
下面是 markdownEditor 的特殊事件和处理器:
| 名称 | 描述 |
|---|---|
当编辑器在 |
|
验证组件值。 |
下面是 markdownEditor 支持的其他通用事件:
XML 内部元素
一个 markdownEditor 可以包含 tooltip and validators 作为其内部元素。
参考
-
markdown 了解无编辑能力的 Markdown 内容渲染。