Документация Engee

Маски кодовых ячеек

Работа с масками кодовых ячеек также подробно рассмотрена в примере Маскирование кодовых ячеек интерактивных скриптов

Для более удобной параметризации и наглядного представления кода зачастую используются интерактивные элементы управления. Ими могут выступать различные поля ввода данных, списки, слайдеры и т.д. В Engee такие элементы реализуются в редакторе скриптов interactive script icon с помощью масок кодовых ячеек.

Маска кодовых ячеек masks script pool 1 — это инструмент, который превращает переменные в кодовых ячейках скриптов Engee в интерактивные элементы управления. Наложение маски позволяет полностью скрыть код ячеек, при этом сохранив их полную работоспособность.

Создание маски кодовой ячейки

Для создания маски кодовой ячейки наведите курсор на кодовую ячейку и в инструментах выберите Маска masks script pool 1 и Добавить поле:

masks script pool 2

Добавление поля откроет интерактивное меню. В зависимости от типа поля, меню добавления меняет свои опции (меняются доступные типы переменной и/или появляются дополнительные настройки). Всего доступно четыре типа:

  • Выпадающий список (dropdown) — это выпадающий список опций с выбором одного варианта. При нажатии на выпадающий список дается выбрать нужный вариант.

    masks script pool 4

    Пример выпадающего списка

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

    masks script pool 7

    После сохранения кодовая ячейка сменит свой вид:

    masks script pool 8

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

    dropdown_variable = "1" # @param ["1","2","3"] {allow-input:true}

    Изменяя этот код можно менять содержимое маски без обращения к инструменту Маска masks script pool 1.

  • Поле ввода (input) — это окно для ввода данных.

    masks script pool 3

    Пример поля ввода

    Создадим пустую кодовую ячейку и добавим маску поля ввода со следующими настройками:

    masks script pool 9

    Здесь плейсхолдер — это текст, который отображается внутри поля ввода, пока не будут введены какие-либо данные. Обычно используется, чтобы дать подсказку о том, какую информацию нужно ввести. Например, для поля даты отлично подойдет вариант Введите дату в формате ГГГГ-ММ-ДД.

    Получим следующий вариант:

    masks script pool 10

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

    date_of_birth = "2025-01-16" # @param {type:"date",placeholder:"Введите дату в формате ГГГГ-ММ-ДД"}

    Исходя из названия переменной нам нужно дату рождения, а не сегодняшнюю дату (проставленную системой автоматически), поэтому поменяем дату на нужную. Поменять дату можно как в маске, так и в самой кодовой ячейке, просто выставив корректную дату вместо указанных "2025-01-16".

    При удалении даты маски можно увидеть, что плейсхолдер работает корректно и улучшает пользовательский опыт:

    masks script pool 11

  • Markdown — это представление разметки на языке Markdown для реализации кодовых масок.

    masks script pool 5

    Пример Markdown

    Создадим пустую кодовую ячейку и добавим маску Markdown со следующими настройками:

    masks script pool 12

    # Построение синусойды
    
    Для построения простой синусойды используйте следующие блоки:
    
    |Блоки в модели|Описание|
    | --------- | -------- |
    |[Sine wave](https://engee.com/helpcenter/stable/ru/base-lib-sources/sine-wave.html)|Генератор синусоидального сигнала.|
    |[Terminator](https://engee.com/helpcenter/stable/ru/base-lib-sinks/terminator.html)|Заглушка выходного порта.|

    Получим следующий вариант:

    masks script pool 13

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

    # @markdown # Построение синусойды
    # @markdown
    # @markdown Для построения простой синуосойды используйте следующие блоки:
    # @markdown
    # @markdown |Блоки в модели|Описание|
    # @markdown | --------- | -------- |
    # @markdown |[Sine wave](https://engee.com/helpcenter/stable/ru/base-lib-sources/sine-wave.html)|Генератор синусоидального сигнала.|
    # @markdown |[Terminator](https://engee.com/helpcenter/stable/ru/base-lib-sinks/terminator.html)|Заглушка выходного порта.|
  • Слайдер (slider) — это представление ползунка (слайдера) с выбором значений из заданного диапазона. Выбор значения из диапазона реализован перемещением ползунка по шкале.

    masks script pool 6

    Пример слайдера

    Создадим пустую кодовую ячейку и добавим маску слайдера со следующими настройками:

    masks script pool 14

    Получим следующий вариант:

    masks script pool 15

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

    уровень_громкости = 0 # @param {type:"slider",min:0,max:100,step:1}

Для редактирования наложенной маски наведите на нее курсор мыши и нажмите иконку masks script pool 15. Поскольку код маскированных ячеек является полностью рабочим — можно редактировать не только маску, но и код ячейки.

Для добавления нового поля, скрытия кода или скрытия маски повторно воспользуйтесь контекстным меню маски masks script pool 1:

masks script pool 16

Создание масок без интерфейса редактора

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

В некоторых случаях может быть удобнее создавать маску не прибегая к контекстному меню создания маски masks script pool 1, поэтому рассмотрим этот процесс подробнее.

Для создания масок вручную нужно самостоятельно воссоздать синтаксис, состоящий из:

  • Имени элемента управления. Некоторые из элементов имеют свои параметры для настройки поведения.;

  • Комментария # и параметра, начинающегося с @.

Элементы управления масок кодовых ячеек уже описаны выше, их всего четыре. Для ручного создания каждого элемента свой собственный подход. Рассмотрим примеры для каждого из них:

dropdown — это выпадающий список опций с выбором одного варианта. При нажатии на выпадающий список дается выбрать нужный вариант.

Описание типов и подтипов выпадающего списка
  • string — тип выпадающего списка, который позволяет выбрать одну из заранее определенных строковых опций. Такой элемент интерфейса часто используется для выбора одного значения из множества возможных, представленных в виде строк. Бывает двух подтипов — editable и not_editable:

    • string_editable — подтип выпадающего списка, который позволяет вводить текст для фильтрации существующих опций.

      Пример:

      dropdown_string_editable = "test3" # @param ["test1", "test2", "test3"] {allow-input:true}

      dropdown string editable

    • string_not_editable — подтип выпадающего списка, который не позволяет вводить и редактировать текст.

      Пример:

      dropdown_string_not_editable = "test2" # @param ["test1", "test2", "test3"]

      dropdown string not editable

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

    • raw_editable — подтип выпадающего списка, который позволяет вводить и редактировать произвольные и нестандратные данные.

      Пример:

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

      dropdown raw editable

    • raw_not_editable — подтип выпадающего списка, который не позволяет вводить и редактировать произвольные и нестандратные данные.

      Пример:

      dropdown_raw_not_editable = 1 # @param [1, "input_raw", "false", '"string"'] {type:"raw"}

      dropdown raw not editable

input — это окно для ввода данных.

Описание типов окна ввода

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

  • boolean — это тип ввода, который позволяет выбирать между двумя значениями: True (истина) или False (ложь).

    Пример:

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

    input boolean

  • date — это тип ввода, который позволяет выбрать дату из календаря.

    Пример:

    input_date = "2024-07-20" # @param {type:"date"}

    input date

  • integer — это тип ввода, который позволяет вводить только целые числа. Введенные в маске значения будут отражены в коде и наоборот.

    Пример:

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

    input integer

  • number — это тип ввода, который позволяет вводить числовые значения (включая дробные числа).

    Пример:

    input_number = 10.0 # @param {type:"number"}

    input number

  • raw — это тип ввода, который позволяет вносить произвольные данные любого типа данных (строки, списки, словари и другие объекты).

    Пример:

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

    input raw

  • string — это тип ввода, который позволяет вводить текстовые данные.

    Пример:

    input_string = "text" # @param {type:"string"}

    input string

slider — это представление ползунка (слайдера) с выбором значений из заданного диапазона. Выбор значения из диапазона реализован перемещением ползунка по шкале.

Описание типов слайдера
  • slider_integer — тип слайдера, который позволяет выбирать только целые значения в заданном диапазоне.

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

    slider 2

  • slider_number — тип слайдера, который позволяет выбирать значения, включая дробные числа, в заданном диапазоне.

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

    slider 1

markdown — это представление разметки на языке Markdown для реализации кодовых масок.

Описание возможностей markdown

С помощью кодовой маски @markdown реализуются:

  • Заголовки

    # @markdown # Заголовок первого уровня
    # @markdown ## Заголовок второго уровня

    markdown mask 1

  • Таблицы

    # @markdown | Опция | Описание |
    # @markdown | ----- | -------- |
    # @markdown | текст |   текст  |

    markdown mask 2

  • Списки:

    • Нумерованные

      # @markdown 1. First item
      # @markdown 2. Second item
      # @markdown 3. Third item
      # @markdown    1. Indented item
      # @markdown    2. Indented item
      # @markdown 4. Fourth item

      markdown mask 3

    • Маркированные

      # @markdown + Sub-lists are made by indenting 2 spaces:
      # @markdown   - Marker character change forces new list start:
      # @markdown     * Ac tristique libero volutpat at
      # @markdown     * Facilisis in pretium nisl aliquet
      # @markdown     - Nulla volutpat aliquam velit
      # @markdown + Very easy!

      markdown mask 4

  • Классическая разметка

    # @markdown > Classic markup: :wink: :cry: :laughing: :yum:

    markdown mask 5