Маскирование кодовых ячеек интерактивных скриптов¶

В данном примере демонстрируется возможность добавления масок в кодовые ячейки интерактивных скриптов.

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

Основы использования¶

Маска - это настроенный пользовательский интерфейс кодовой ячейки.

Кодовая ячейка маскируется, если в неё добавлен хотя бы один специальный комментарий типа # @param или # @markdown.

Комментарии # @param предназначены для добавления в кодовую ячейку интерактивных параметров:

Текстовых полей (input);
Флаговых кнопок (checkbox);
Выпадающих списков (dropdown);
Ползунков (slider).

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

Между редактором кода и элементами маски организована двусторонняя связь:

При изменении значения переменной в графическом интерфейсе, автоматически изменится и значение в кодовой ячейке;
И наоборот, при изменении значения переменной в кодовой ячейке, изменится значение в графическом интерфейсе.

Комментарии # @markdown предназначены для добавления в кодовую ячейку разметки на языке Markdown (именно этот язык используется в текстовых ячейках редактора скриптов Engee). Используя простой и понятный синтаксис Markdown сразу после специального комментария, можно сделать маску ещё более наглядной.

По умолчанию редактор кода и графический интерфейс отображаются одновременно. Для того чтобы скрыть отображение кода, необходимо произвести двойной клик по маске. Чтобы вновь отобразить код, можно нажать на кнопку "Показать код" или повторить двойной клик по ячейке.

Интерактивные параметры¶

Для того чтобы добавить текстовое поле ввода строковой переменной, используйте специальный комментарий # @param {type:"string"}:

input_string = "Hello, world!" # @param {type:"string"}

Для добавления текстового поля ввода произвольного числа, необходимо использовать специальный комментарий # @param {type:"number"}:

input_number = -0.123456789 # @param {type:"number"}

Текстовое поле ввода целочисленной переменной можно добавить с использованием специального комментария # @param {type:"integer"}:

input_integer = 42 # @param {type:"integer"}

Для добавления текстового поля ввода в свободном формате (наиболее гибкий вариант, т. к. тип данных переменной не ограничивается), необходимо использовать специальный комментарий # @param {type:"raw"}:

input_raw = input_string # @param {type:"raw"}

Для того чтобы добавить флаговую кнопку, используйте специальный комментарий # @param {type:"boolean"}:

input_boolean = false # @param {type:"boolean"}

Календарь с возможностью выбора даты (будет записана в строковую переменную в формате YYYY-MM-DD) можно добавить с использованием специального комментария # @param {type:"date"}:

input_date = "2024-09-03" # @param {type:"date"}

Для того чтобы добавить выпадающий список выбора строковой переменной, используйте специальный комментарий # @param [""], перечислив внутри массива все возможные варианты:

dropdown_string = "Первый" # @param ["Первый", "Второй", "Третий"]

Если необходимо объединить выпадающий список выбора строковой переменной с возможностью ввода, можно использовать специальный комментарий # @param [""] {allow-input:true}

dropdown_string_editable = "Нулевой" # @param ["Первый", "Второй", "Третий"] {allow-input:true}

Для того чтобы добавить выпадающий список выбора переменной в свободном формате, используйте специальный комментарий # @param [""] {type:"raw"}, перечислив внутри массива все возможные варианты:

dropdown_raw = "Engee" # @param [""Engee"", "input_raw", "false", "42"] {type:"raw"}

Если необходимо объединить выпадающий список выбора переменной в свободном формате с возможностью ввода, можно использовать специальный комментарий # @param [""] {type:"raw", allow-input:true}

dropdown_raw_editable = true # @param [""Engee"", "input_raw", "false", "42"] {type:"raw", allow-input:true}

Чтобы добавить ползунок, используйте специальный комментарий # @param {type:"slider", min:x, max:y, step:z}, подставив вместо:

x - минимальное значение;
y - максимальное значение;
z - шаг:

slider_number = 0.5 # @param {type:"slider", min:-1, max:1, step:0.01}

slider_integer = 50 # @param {type:"slider", min:1, max:100, step:1}

Язык разметки Markdown¶

Заголовки:

# @markdown # Заголовок 1
# @markdown ## Заголовок 2
# @markdown ### Заголовок 3
# @markdown #### Заголовок 4
# @markdown ##### Заголовок 5
# @markdown ###### Заголовок 6

Параграфы и переносы строк:

# @markdown Чтобы создать новый параграф, вставьте пустую строку между двумя строками текста.
# @markdown  
# @markdown Для переноса строки внутри одного параграфа  
# @markdown используйте два пробела в конце строки.

Выделение текста:

# @markdown *курсив*
# @markdown _italic_
# @markdown  
# @markdown **жирный**
# @markdown __bold__
# @markdown  
# @markdown ***жирный курсив***
# @markdown ___bold italic___
# @markdown  
# @markdown ~~зачёркнутый strikethrough~~

Нумерованный список:

# @markdown 1. Первый пункт
# @markdown 2. Второй пункт
# @markdown 3. Третий пункт

Маркированый список:

# @markdown - Первый пункт
# @markdown - Второй пункт
# @markdown - Третий пункт

Вложенный список:

# @markdown 1. Первый пункт
# @markdown     - Первый подпункт
# @markdown     - Второй подпункт
# @markdown 2. Второй пункт

Ссылка:

# @markdown [Telegram-канал Engee](https://t.me/engee_com)

Изображение:

# @markdown ![Текст описания](	https://static.tildacdn.com/tild3266-6131-4465-b233-613634326336/Engee_logo-05.svg)

Строка кода:

# @markdown `using Plots`

Блок кода:

# @markdown ```Julia
# @markdown x = range(0, 10, length=100)
# @markdown y = sin.(x)
# @markdown plot(x, y)
# @markdown ```

Цитата:

# @markdown > Первый уровень
# @markdown >> Второй уровень
# @markdown >>> Третий уровень

Горизонтальная линия:

# @markdown ---

Таблица:

# @markdown | Заголовок 1 | Заголовок 2 |
# @markdown | ----------- | ----------- |
# @markdown | Ячейка 1    | Ячейка 2    |
# @markdown | Ячейка 3    | Ячейка 4    |

Эмодзи:

# @markdown :smile:
# @markdown :laughing:
# @markdown :blush:

HTML-теги:

# @markdown <kbd>CTRL</kbd> + <kbd>V</kbd>

Выводы¶

Данный пример демонстрирует возможность маскирования кодовых ячеек. Это простой и в то же время функциональный способ сделать интерактивные скрипты ещё более отзывчивыми и доступными!