markdownEditor

markdownEditor позволяет пользователям писать и просматривать контент Markdown.

XML-элемент	`markdownEditor`
Java-класс	`JmixMarkdownEditor`

XML-элемент

markdownEditor

Java-класс

JmixMarkdownEditor

Обзор

Основы

ДЕМО

Используйте 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.
            """);
}

Значение компонента — объект String с исходной Markdown-разметкой.

`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());
}

Привяжите компонент к атрибуту сущности типа String, который хранит Markdown-текст.

Режимы

Редактор имеет два режима, которые можно выбрать в заголовке:

Edit позволяет пользователям вводить и форматировать Markdown-текст.
Preview отображает текущее значение как отформатированный HTML.

Режим по умолчанию - Edit.

Начальный режим можно декларативно задать с помощью XML-атрибута mode.

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

Если readOnly = true, компонент показывает только отрендеренный предварительный просмотр. Панель инструментов и вкладки режимов скрыты, а значение нельзя изменить.

Текущий режим также можно получать и изменять программно с помощью серверного API. При изменении режима компонент генерирует ModeChangeEvent, содержащий новый режим и признак того, кем инициировано изменение — пользователем или приложением.

В режиме Edit вкладки режимов и панель инструментов форматирования находятся в одной строке заголовка. Если горизонтального пространства недостаточно, дополнительные действия панели инструментов переносятся в меню переполнения в конце строки.

Кнопки панели инструментов отражают форматирование, активное в текущей позиции курсора. Нажатие на уже активную кнопку форматирования удаляет соответствующее форматирование.

Форматы-обертки

Эти действия работают с текущим выделением или с позицией курсора, если ничего не выделено.

Действие Сочетание клавиш Применение Удаление

Действие	Сочетание клавиш	Применение	Удаление
Смелый	`Cmd/Ctrl+B`	Оборачивает выделенный текст в ``. Если ничего не выделено, вставляет `**` и помещает курсор между маркерами.	Удаляет окружающие `**`.
Курсив	`Cmd/Ctrl+I`	Оборачивает выделенный текст в `_`. Если ничего не выделено, вставляет `__` и помещает курсор между маркерами.	Удаляет окружающие `_`.
Код	`Cmd/Ctrl+E`	Оборачивает выделенный текст в один обратный апостроф. Если ничего не выделено, вставляет два обратных апострофа и помещает курсор между ними.	Удаляет окружающие обратные апострофы.
Связь	`Cmd/Ctrl+K`	Оборачивает выделение в виде `[text](url)`. Если ничего не выделено, вставляет `[](url)` и помещает курсор внутрь `[]`.	Удаляет окружающую Markdown-разметку ссылки.

Смелый

Cmd/Ctrl+B

Оборачивает выделенный текст в **. Если ничего не выделено, вставляет **** и помещает курсор между маркерами.

Удаляет окружающие **.

Курсив

Cmd/Ctrl+I

Оборачивает выделенный текст в _. Если ничего не выделено, вставляет __ и помещает курсор между маркерами.

Удаляет окружающие _.

Код

Cmd/Ctrl+E

Оборачивает выделенный текст в один обратный апостроф. Если ничего не выделено, вставляет два обратных апострофа и помещает курсор между ними.

Удаляет окружающие обратные апострофы.

Связь

Cmd/Ctrl+K

Оборачивает выделение в виде [text](url). Если ничего не выделено, вставляет [](url) и помещает курсор внутрь [].

Удаляет окружающую Markdown-разметку ссылки.

Построчные форматы

Эти действия работают с текущей строкой или с каждой выделенной строкой, если выбрано несколько строк.

Действие Применение Удаление

Действие	Применение	Удаление
Заголовок	Добавляет префикс `##` в начало строки.	Удаляет префикс `##` .
Цитировать	Добавляет префикс `>` в начало строки.	Удаляет префикс `>` .
Неупорядоченный список	Добавляет префикс `-` в начало строки.	Удаляет префикс `-` .
Упорядоченный список	Добавляет префикс `1.` в начало строки.	Удаляет префикс нумерованного списка.
Список задач	Добавляет префикс `- [ ]` в начало строки.	Удаляет префикс `- [ ]` .

Заголовок

Добавляет префикс ## в начало строки.

Удаляет префикс ## .

Цитировать

Добавляет префикс > в начало строки.

Удаляет префикс > .

Неупорядоченный список

Добавляет префикс - в начало строки.

Удаляет префикс - .

Упорядоченный список

Добавляет префикс 1. в начало строки.

Удаляет префикс нумерованного списка.

Список задач

Добавляет префикс - [ ] в начало строки.

Удаляет префикс - [ ] .

Если выбрано несколько строк и все они уже имеют целевой формат, нажатие кнопки панели инструментов удаляет его из всех выбранных строк. В противном случае формат применяется ко всем выбранным строкам, у которых его еще нет.

Компонент поддерживает навигацию с клавиатуры между тремя логическими областями фокуса:

Вкладки режимов
Панель инструментов
Текстовая область

Tab перемещает фокус между этими областями. Клавиши со стрелками используются для навигации внутри активной области. Нажмите Escape на панели инструментов, чтобы вернуть фокус в текстовую область.

Если некоторые действия панели инструментов перенесены в меню переполнения ···, при открытии меню фокус получает первый пункт. В меню клавиши ArrowUp и ArrowDown перемещают между пунктами, а Escape и Tab закрывают меню и возвращают фокус на кнопку переполнения.

Изменения форматирования интегрируются со стеком отмены браузера, поэтому стандартные сочетания клавиш работают ожидаемым образом:

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`	Задаёт фон общей строки заголовка, содержащей вкладки и панель инструментов.	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

--jmix-markdown-editor-default-width

Задаёт ширину компонента по умолчанию.

Aura, Lumo

--jmix-markdown-editor-header-background

Задаёт фон общей строки заголовка, содержащей вкладки и панель инструментов.

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.

Поскольку значение компонента хранится как исходная Markdown-строка, валидаторы notBlank и size полезны для проверки того, что содержимое присутствует и имеет ожидаемую длину.

Для markdownEditor доступны следующие предопределённые валидаторы:

XML-элемент	`validators`
Предопределённые валидаторы	custom - notBlank - notEmpty - notNull - size

XML-элемент

validators

Предопределённые валидаторы

custom - notBlank - notEmpty - notNull - size

Варианты темы

ДЕМО

Используйте атрибут themeNames, чтобы применить один или несколько вариантов темы.

Вариант Описание Поддерживается в

Вариант	Описание	Поддерживается в
`helper-above-field`	Отображает помощник над полем, под меткой.	Aura, Lumo
`toolbar-align-start`	Выравнивает кнопки панели инструментов по начальной стороне заголовка с учетом текущего направления текста.	Aura, Lumo
`toolbar-align-center`	Центрирует кнопки панели инструментов внутри заголовка и скрывает разделитель.	Aura, Lumo
`toolbar-align-end`	Выравнивает кнопки панели инструментов по краю заголовка с учетом текущего направления текста и скрывает разделитель.	Aura, Lumo

helper-above-field

Отображает помощник над полем, под меткой.

Aura, Lumo

toolbar-align-start

Выравнивает кнопки панели инструментов по начальной стороне заголовка с учетом текущего направления текста.

Aura, Lumo

toolbar-align-center

Центрирует кнопки панели инструментов внутри заголовка и скрывает разделитель.

Aura, Lumo

toolbar-align-end

Выравнивает кнопки панели инструментов по краю заголовка с учетом текущего направления текста и скрывает разделитель.

Aura, Lumo

Атрибуты

markdownEditor имеет следующие уникальные атрибуты:

Имя Описание По умолчанию

Имя	Описание	По умолчанию
`mode`	Устанавливает редактор mode.	`EDIT`

mode

Устанавливает редактор mode.

EDIT

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 имеет следующие уникальные обработчики:

Имя Описание

Имя	Описание
`ModeChangeEvent`	`JmixMarkdownEditor.ModeChangeEvent` срабатывает, когда редактор переключается между `Edit` и `Preview` mode. Событие содержит новый режим и флаг, указывающий, было ли изменение инициировано пользователем или приложением.
`validator`	Проверяет значение компонента.

ModeChangeEvent

JmixMarkdownEditor.ModeChangeEvent срабатывает, когда редактор переключается между Edit и Preview mode. Событие содержит новый режим и флаг, указывающий, было ли изменение инициировано пользователем или приложением.

validator

Проверяет значение компонента.

markdownEditor имеет следующие общие обработчики:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - statusChangeHandler

Элементы

Компонент markdownEditor может содержать следующие вложенные элементы: tooltip и validators.

Смотрите также

markdown для рендеринга контента Markdown без возможности редактирования.

markdownEditor

Обзор

Основы

markdownEditor связанный с данными

Режимы

Действия панели инструментов

Форматы-обертки

Построчные форматы

Навигация с клавиатуры

CSS-свойства

Интернационализация

Валидация

Варианты темы

Атрибуты

Обработчики

Элементы

Смотрите также

`markdownEditor` связанный с данными