Соглашения

На этой странице собраны правила, которые повторяются на нескольких страницах базы знаний: как называть элементы, как собирать программу, что делать перед загрузкой проекта. У каждого правила есть смысл (что будет, если нарушить), пример из учебного проекта «Демо-зал» и ссылка на страницу, где оно разобрано подробно.

Как называть элементы

Правило. Имя элемента пишут по схеме Группа_Объект_тип: латиницей, без пробелов, слова с заглавной буквы, части через _. Тип — суффикс в конце имени:

Суффикс	Элемент
`b`	кнопка
`lb`	лейбл (подпись)
`fr`	фрейм
`bg`	фон
`sl`	слайдер
`ls`	список
`tm`	время
`grp`	группа кнопок, которые выбираются по одной (в «Демо-зале»: `Nav_grp`, `Src_grp`, `Lay_grp`, `Cam_grp`, `VcsMode_grp`)

Зачем. Имя элемента — его ID: по нему программа в U-Logic находит элемент. По общему префиксу группы одно правило обрабатывает всю группу (например, все кнопки Src_*). По суффиксу сразу видно, кнопка это или ползунок. Регистр важен: Nav_Home_b и nav_home_b для программы — разные элементы. UI-Designer не проверяет имя при вводе: ошибка видна, только когда программа не находит элемент.

Пример из «Демо-зала».

Имя	Что означает
`Nav_Home_b`	вкладка «Главная» (`Nav` — навигация)
`Src_Cam1_b`	источник «Камера 1» (`Src` — источники)
`Mic_01_b`	место 1 за столом на экране «Микрофоны»
`Hdr_Screen_b`	кнопка «Экран» в шапке
`Pop_Yes_b`	кнопка «Выключить» в окне подтверждения

Подробно. «Первый интерфейс», раздел «Как называть элементы»; для кнопок — «Кнопки и состояния», раздел «Имя кнопки — её ID».

Одно имя на всём пути

Правило. Имя, которое вы дали элементу в UI-Designer, не меняется во всей цепочке: в узлах, в таблицах настроек, в подписках устройства. Оно совпадает буква в букву, с тем же регистром, без лишних пробелов. По умолчанию каждому элементу — своё имя. Элементы готовой программы лучше не переименовывать.

Зачем.

Узлы ничего не обрезают и не приводят к одному регистру: Src_Cam1_b и src_cam1_b для них разные элементы.
Если двум элементам дали одно имя, в списке узла они сливаются в одну строку, и программа не отличит один элемент от другого.
Если переименовать элемент после того, как программа готова, программа ищет старое имя и не находит элемент. Правила с шаблоном и имена внутри ваших узлов change сами не обновятся.
Строя интерфейс под готовую программу или программу под готовый интерфейс, сначала договоритесь об именах: исправить их потом дороже, чем придумать сразу.
Элементы появляются в списках узлов после «Сохранить» и «Опубликовать» в UI-Designer. Добавили кнопку, но не опубликовали — в узле её нет.

Пример из «Демо-зала». Имя кнопки служит ключом в таблице настроек зала и именем подписки на звуковом процессоре. Поэтому уведомление процессора приходит уже с именем кнопки, которую надо перекрасить, и ничего переводить не нужно. Кнопка Snd_Hall_mute_b на экране «Звук» и кнопка «Звук в зале» в шапке (Hdr_Sound_b) показывают один и тот же mute: на этот канал подписаны два имени.

Подробно. «Связь интерфейса с программой», разделы «Имя элемента — это ID» и «Одно имя на всём пути»; ключ в таблице — в «Первой программе по шагам», блок C; правила ui - switch по шаблонам имён — в «Приёме событий».

Как раскладывать программу по блокам

Правило. Блок — группа узлов с комментарием-заголовком. Блоки идут сверху вниз, узлы внутри блока — слева направо, провода — только вперёд. Между блоками стоят пары link in и link out, а не длинные провода через всю вкладку. На вкладку — один UI - Panel in и один UI - Panel out, остальные блоки подключены к ним через link. Блоки пронумерованы.

Зачем. По этим правилам программу легко читать и чинить: каждый приём лежит в своём подписанном блоке.

Пример из «Демо-зала». Вся программа лежит на одной вкладке. Блок 1 называется «1. Старт: настройки зала и адресная книга», блок 2 — «2. Связь с панелью»: в нём единственные UI - Panel in и UI - Panel out вкладки, а остальные блоки подключены через пары link. Блок 4 — «4. Экран: источник — подсветка по ответу матрицы».

Подробно. «Программа «Демо-зал»: обзор», разделы «Как читать вкладку» и «Правила, по которым собран «Демо-зал»»; узлы link — в «Узлы «Общие»».

Остальные правила, по которым собран «Демо-зал»

Правило и смысл. Остальные правила того же списка. Полный список из двенадцати правил — на странице обзора.

Правило	Смысл	Пример из «Демо-зала»
Настройки зала — в одном узле, логика читает их по ключу	номера входов и имена лежат в картах («имя кнопки → параметры»); их записывает при запуске один узел `change`, остальные берут строку по ключу; логика не держит чисел у себя	блок 1; выражение `demoMatrix[msg.payload.object]`
Шаблон вместо копий	группа кнопок с общей частью имени — одно правило; вид группы кнопок с одинаковым поведением — один шаблон	одно правило `ui - switch` по шаблону `Src_*_b` ловит все семь кнопок источников
Один `device - command` на устройство	команда — в `msg.command`, параметры — в `msg.parameters`	узел «Матрица: подать вход» отправляет команду `route`
Вид кнопок — по ответу устройства	нажатие запускает команду, а подсвечивает кнопку ответ: так на панели видно то, что действительно произошло (источник мог переключиться и с пульта, а команда могла не пройти)	блок 4: подсветка по ответу матрицы
Сценарий — список шагов	список `[{устройство, команда, параметры}]` в одном `change`, исполнение — в одном блоке шагов; время задают узлами `delay` и `trigger`	блок 11 «Шаги сценариев и подписки»
Простое делайте узлами `change` и `switch`	узел `function` нужен только для сложной логики; дайте ему имя и комментарий «вход / выход»	—
Переключатели — средствами UI-Designer	кнопку отмечают флажком «Отметить как toggle», программа получает `value_changed` и разбирает его `switch` или `change`; узел `toggle - helper` не используется	`Vcs_Mic_b` с правилом `value_changed`
Состояние — в памяти потока	одно имя в памяти записывает один узел, остальные его только читают: так проще понять, кто менял значение	блок 7: состояние мест хранится в памяти потока
Подписки и опрос — после подключения	запускайте их от первого выхода `device - command`: пока соединения нет, команда теряется	блок 11

Подробно. «Программа «Демо-зал»: обзор», раздел «Правила, по которым собран «Демо-зал»»; приём событий и шаблоны — «Приём событий»; команды и ответы — «Команды устройствам и ответы»; переключатели — «Переключатели и группы».

Копия перед загрузкой и правкой

Правило. Прежде чем загружать проект или делать крупную правку, нажмите «Скачать проект» и сохраните файл. Копия нужна и для интерфейсов, и для программы.

Зачем. «Загрузить проект» заменяет проект целиком: всё, чего нет в архиве, пропадёт. В редакторе драйверов подтверждения перед заменой нет. Вернуть прежнее можно, только загрузив сохранённую копию тем же способом. В редакторе драйверов нет отмены сохранения и нет подтверждения при удалении драйвера: прежний код тоже можно вернуть только из копии.

Что ещё нужно знать о копии:

копия интерфейсов содержит опубликованное состояние, а не последние неопубликованные правки: сначала опубликуйте проект;
в копию программы не попадают неразвёрнутые правки: перед «Скачать проект» нажмите «Развернуть»;
пароли подключений устройств в копию не входят: после загрузки их нужно ввести заново;
загружайте сначала интерфейсы, потом программу: программа находит кнопки и надписи по именам, и пока интерфейса нет, ей не к чему обращаться.

Пример из «Демо-зала». Перед загрузкой программы «Демо-зал» вы нажимаете «Скачать проект» в редакторе драйверов и сохраняете файл — это копия ваших потоков и драйверов. Если вы добавляете только вкладку через flow.json, сохраните копию потоков: меню → «Экспорт» → все потоки → «Скачать».

Подробно. «Проекты: загрузить и скачать»; «Программа «Демо-зал»: обзор», раздел «Загрузка программы «Демо-зал»»; «Редактор драйверов»; копия интерфейсов — «UI-Designer».

Оформление интерфейса

Правило. Это не требования редактора, а опыт «Демо-зала». Интерфейс получается спокойным и читаемым, если держаться шести правил:

Правило	Зачем	В «Демо-зале»
Светлая тема: белые карточки с мягкой тенью на светло-сером фоне	глянцевый экран панели в освещённом зале не теряет текст в бликах, а белый фон не утомляет за рабочий день	вкладка «Звук»: светлые карточки
Акцент — только у того, что включено или выбрано; остальное нейтральное	когда яркого цвета мало, он сразу показывает, что происходит	выбранная вкладка и источник — синие, включённый переключатель — зелёный, опасное действие («Выключить всё») — красное
Крупные цели касания: кнопка не меньше 72 пикселей по меньшей стороне	на панели 10″ с экраном 1920 × 1200 это около 8 мм: палец не промахивается, кнопки можно нажимать не глядя	кнопки интерфейса
Крупный текст: не меньше 24 пикселей	—	основные подписи кнопок — 26–30, значения — 48 и 72
Единые отступы и скругления	—	поля — 32 пикселя, промежутки между карточками — 24, углы скруглены одинаково для каждого вида элементов
Один шрифт, два начертания	—	Inter Tight, обычный и жирный

Подробно. «Оформление интерфейса», раздел «Несколько правил, которые работают»; там же палитра с ролями цветов.

Правила Скриптера

Правило. Настройка — один раз в On Start, дальше только реакции. Подписки объявляйте в On Start; в On Message оставляйте только действия.

Зачем.

Подписка (onTap, on, onValueChanged, onStatus и другие) — правило, которое должно работать всё время, пока работает узел.
Подписка, объявленная в On Message, создаётся заново на каждое сообщение, а старые остаются. Одно нажатие запускает все накопленные обработчики сразу (после 50 сообщений — 50 раз), а память растёт, пока узел не остановят.
Вручную снимать подписки не нужно: при остановке узла или «Развернуть» Скриптер снимает подписки на панель и устройства и останавливает таймеры. Новое «Развернуть» безопасно: On Start создаёт подписки с нуля, двойных не будет.
Ошибка в одном обработчике или таймере не останавливает остальные.

Пример. Подписка на кнопку Src_Cam1_b объявлена один раз в On Start, а в On Message стоит только действие в ответ на пришедшее сообщение:

// On Start: правильно — один раз
panel.onTap('Src_Cam1_b', () => matrix.send('route', { input: 1, output: 1 }));
// On Message: только действие в ответ на пришедшее сообщение
if (msg.topic === 'camera') camera.send('recallPreset', { preset: msg.payload });

Подробно. «Скриптер: логика кодом», раздел «Правила»; если что-то не работает — там же, раздел «Устранение неполадок».