codeEditor

ДЕМО

codeEditor - это компонент для отображения и ввода исходного кода. Он представляет собой многострочное текстовое поле с подсветкой синтаксиса, опциональным полем печати и боковой панелью с номерами строк.

codeEditor основан на встраиваемом редакторе кода Ace, написанном на JavaScript.

XML-элемент	`codeEditor`
Java-класс	`CodeEditor`
Атрибуты	id - alignSelf - classNames - colspan - css - dataContainer - defaultSuggestionsEnabled - enabled - errorMessage - focusShortcut - fontSize - height - helperText - highlightActiveLine - highlightGutterLine - label - liveSuggestionsEnabled - maxHeight - maxWidth - minHeight - minWidth - mode - printMarginColumn - property - readOnly - required - requiredMessage - showGutter - showLineNumbers - showPrintMargin - tabIndex - suggestOn - textWrap - theme - title - useSoftTabs - visible - width
Обработчики	AttachEvent - BlurEvent - ClientValidatedEvent - ComponentValueChangeEvent - CompositionEndEvent - CompositionStartEvent - CompositionUpdateEvent - DetachEvent - FocusEvent - InputEvent - KeyDownEvent - KeyPressEvent - KeyUpEvent - statusChangeHandler - validator
Элементы	tooltip - validator

XML-элемент

codeEditor

Java-класс

CodeEditor

Атрибуты

id - alignSelf - classNames - colspan - css - dataContainer - defaultSuggestionsEnabled - enabled - errorMessage - focusShortcut - fontSize - height - helperText - highlightActiveLine - highlightGutterLine - label - liveSuggestionsEnabled - maxHeight - maxWidth - minHeight - minWidth - mode - printMarginColumn - property - readOnly - required - requiredMessage - showGutter - showLineNumbers - showPrintMargin - tabIndex - suggestOn - textWrap - theme - title - useSoftTabs - visible - width

Обработчики

AttachEvent - BlurEvent - ClientValidatedEvent - ComponentValueChangeEvent - CompositionEndEvent - CompositionStartEvent - CompositionUpdateEvent - DetachEvent - FocusEvent - InputEvent - KeyDownEvent - KeyPressEvent - KeyUpEvent - statusChangeHandler - validator

Элементы

tooltip - validator

Основы

Пример использования codeEditor:

<codeEditor id="codeEditor"
            mode="XML"
            width="50%"/>

Привязка данных

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

Следующий пример создает codeEditor, связанный с данными.

<data>
    <instance id="orderReportDc"
              class="com.company.onboarding.entity.OrderReport"> (1)
        <loader id="orderReportDl"/>
        <fetchPlan extends="_base"/> (2)
    </instance>
</data>
    <codeEditor mode="XML"
                dataContainer="orderReportDc"
                property="code"/> (3)

1	`InstanceContainer` для сущности `OrderReport`.
2	Встроенный план выборки экземпляра сущности, находящегося в контейнере.
3	Привязка компонента к контейнеру данных и свойству. Атрибут `dataContainer` содержит ссылку на контейнер данных `orderReportDc`, а атрибут `property` ссылается на атрибут сущности `code`.

Режим отображения кода

ДЕМО

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

По умолчанию режим подсветки синтаксиса - CodeEditorMode.PLAIN_TEXT.

Пример:

<codeEditor id="myCodeEditor"
            mode="JAVASCRIPT"/>

В этом примере атрибут mode установлен в значение JAVASCRIPT, что настраивает редактор для кода JavaScript.

Тематический стиль

ДЕМО

Атрибут theme используется для определения визуального оформления и стиля редактора. Он позволяет выбрать предопределенную тему, которая изменяет цветовую схему, шрифт и другие эстетические элементы редактора кода.

Список поддерживаемых тем определяется в перечислении CodeEditorTheme.

Автодополнение

LIVE DEMO

Компонент codeEditor поддерживает функции автодополнения.

Автодополнение может предлагать стандартные варианты в зависимости от режима, если установить атрибут defaultSuggestionsEnabled в true:

<codeEditor mode="GROOVY" defaultSuggestionsEnabled="true"/>

Вы можете предоставить свои варианты, используя обработчик suggester, например:

<codeEditor id="codeEditorWithCustomSuggestions"/>

@Install(to = "codeEditorWithCustomSuggestions", subject = "suggester")
private List<Suggestion> codeEditorWithCustomSuggestionsSuggester(Suggester.SuggestionContext context) {
    String text = context.getText();
    int cursorPosition = context.getCursorPosition();
    // If autocompletion is requested after "user."
    if (cursorPosition == text.indexOf("user.") + 5) {
        // Return a list of suggestions for properties of the User entity
        return metadata.getClass(User.class).getProperties().stream()
                .map(property -> new Suggestion(property.getName(), property.getName()))
                .toList();
    } else {
        return List.of();
    }
}

По умолчанию всплывающее окно автодополнения открывается при нажатии пользователем сочетания клавиш:

Windows и Linux: Ctrl-Space
macOS: ⌥-Space или ⌃-Space (в зависимости от настроек системы)

Если атрибут suggestOn установлен в регулярное выражение, всплывающее окно автодополнения открывается автоматически при вводе пользователем соответствующей строки. Например, если suggestOn="\.", автодополнение сработает после ввода точки.

Если атрибут liveSuggestionsEnabled установлен в true, предложения будут появляться автоматически по мере ввода текста, без необходимости ручного вызова или настройки атрибута suggestOn. Все обработчики suggester будут запрашивать варианты, как только пользователь введёт какой-либо символ слова. Обратите внимание, что живое автодополнение может потреблять значительные ресурсы при работе с большим объёмом контента или сложными обработчиками, поэтому по умолчанию liveSuggestionsEnabled имеет значение false.

Валидация

Чтобы проверить значения, введенные в компонент codeEditor вы можете использовать валидатор в элементе validators.

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

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

XML-элемент

validators

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

custom - email - notBlank - notEmpty - notNull - regexp - size

Атрибуты

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

Ниже приведены атрибуты, специфичные для codeEditor:

Название	Описание	Значение по умолчанию
defaultSuggestionsEnabled	Автодополнение предлагает варианты по умолчанию, в зависимости от языкового режима.	`false`
fontSize	Устанавливает размер шрифта для кода в редакторе.	`1rem`
highlightActiveLine	Устанавливает выделение активной строки. Если выделение включено, строка, на которой находится курсор, будет выделена.	`true`
highlightGutterLine	Устанавливает выделение текущей строки в боковой панели с номерами строк. Если выделение включено, строка в боковой панели, на которой находится курсор, будет выделена.	`true`
liveSuggestionsEnabled	Открывать всплывающее окно автодополнения автоматически при наборе текста пользователем.	`false`
mode	Устанавливает подсветку синтаксиса для определенного режима. Список поддерживаемых режимов определяется в перечислении `CodeEditorMode`. Смотрите Режим отображения кода.	`CodeEditorMode.PLAIN_TEXT`
printMarginColumn	Управляет положением колонки отступа для печати. Эта колонка представляет собой визуальную вертикальную линию, которая помогает с форматированием кода и его удобочитаемостью, особенно при печати.	`80`
showGutter	Определяет, отображается ли боковая панель (вертикальная область слева от редактора). Боковая панель обычно показывает номера строк, что упрощает навигацию и ссылку на конкретные строки в коде.	`true`
showLineNumbers	Управляет отображением номеров строк в редакторе. Эта функция помогает с навигацией и ссылкой на конкретные строки в коде.	`true`
showPrintMargin	Используется для управления видимостью линии отступа для печати. Эта линия представляет собой вертикальную направляющую, которая появляется в редакторе кода и помогает разработчикам визуально разделить код, который поместится на печатной странице, от кода, который будет обрезан.	`true`
suggestOn	A regular expression to trigger autocompletion when the user enters a matching string. Регулярное выражение для вызова автодополнения при вводе пользователем соответствующей строки.
textWrap	Определяет, должны ли длинные строки кода переноситься (разбиваться на несколько строк), чтобы поместиться в видимую область редактора, или же они должны отображаться как одна строка, которая выходит за пределы ширины окна.	`false`
theme	Устанавливает визуальную тему редактора кода. Смотрите Тематический стиль.	`CodeEditorTheme.TEXTMATE`
useSoftTabs	Устанавливает режим представления символа табуляции. В режиме мягких табуляций символ табуляции отображается как серия пробелов. В режиме жестких табуляций символ табуляции отображается как специальный символ `\t`.	`true`

Название

Описание

Значение по умолчанию

defaultSuggestionsEnabled

Автодополнение предлагает варианты по умолчанию, в зависимости от языкового режима.

false

fontSize

Устанавливает размер шрифта для кода в редакторе.

1rem

highlightActiveLine

Устанавливает выделение активной строки. Если выделение включено, строка, на которой находится курсор, будет выделена.

true

highlightGutterLine

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

true

liveSuggestionsEnabled

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

false

mode

Устанавливает подсветку синтаксиса для определенного режима. Список поддерживаемых режимов определяется в перечислении CodeEditorMode. Смотрите Режим отображения кода.

CodeEditorMode.PLAIN_TEXT

printMarginColumn

Управляет положением колонки отступа для печати. Эта колонка представляет собой визуальную вертикальную линию, которая помогает с форматированием кода и его удобочитаемостью, особенно при печати.

80

showGutter

Определяет, отображается ли боковая панель (вертикальная область слева от редактора). Боковая панель обычно показывает номера строк, что упрощает навигацию и ссылку на конкретные строки в коде.

true

showLineNumbers

Управляет отображением номеров строк в редакторе. Эта функция помогает с навигацией и ссылкой на конкретные строки в коде.

true

showPrintMargin

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

true

suggestOn

A regular expression to trigger autocompletion when the user enters a matching string. Регулярное выражение для вызова автодополнения при вводе пользователем соответствующей строки.

textWrap

Определяет, должны ли длинные строки кода переноситься (разбиваться на несколько строк), чтобы поместиться в видимую область редактора, или же они должны отображаться как одна строка, которая выходит за пределы ширины окна.

false

theme

Устанавливает визуальную тему редактора кода. Смотрите Тематический стиль.

CodeEditorTheme.TEXTMATE

useSoftTabs

Устанавливает режим представления символа табуляции. В режиме мягких табуляций символ табуляции отображается как серия пробелов. В режиме жестких табуляций символ табуляции отображается как специальный символ \t.

true