Программное создание элементов управляемой формы в 1С 8.3: поля, группы, кнопки и команды

Коллекция Элементы (ВсеЭлементыФормы): методы Добавить и Вставить

В управляемой форме 1С 8.3 все визуальные элементы — поля, группы, таблицы, кнопки и декорации — находятся в свойстве формы Элементы, которое имеет платформенный тип ВсеЭлементыФормы. Программное добавление элементов на форму 1С 8.3 доступно только на сервере (в процедурах с директивой &НаСервере), чаще всего в событийном обработчике ПриСозданииНаСервере.

У коллекции ВсеЭлементыФормы есть два метода для создания новых элементов: Добавить() помещает элемент в конец выбранного родителя, а Вставить() размещает его строго перед указанным существующим элементом того же родителя:

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
    // 1. Добавление в конец группы Шапка
    ПолеКомментария = Элементы.Добавить(
        "КомментарийЭкспедитора",
        Тип("ПолеФормы"),
        Элементы.ГруппаШапка);
    ПолеКомментария.Вид = ВидПоляФормы.ПолеВвода;
    ПолеКомментария.ПутьКДанным = "Объект.Комментарий";

    // 2. Вставка перед конкретным элементом внутри той же группы
    ПолеСрочности = Элементы.Вставить(
        "ПризнакСрочности",
        Тип("ПолеФормы"),
        Элементы.ГруппаШапка,
        Элементы.КомментарийЭкспедитора);
    ПолеСрочности.Вид = ВидПоляФормы.ПолеФлажка;
    ПолеСрочности.ПутьКДанным = "Объект.СрочнаяДоставка";
КонецПроцедуры

Обратите внимание: при вызове Элементы.Вставить() четвёртый параметр (элемент, перед которым вставляем) обязательно должен быть непосредственно подчинён тому же Родителю, который передан третьим параметром. Если передать элемент из другой группы, платформа выбросит ошибку времени выполнения.

Второй параметр методов Добавить() и Вставить() всегда принимает объект Тип("..."). В зависимости от переданного типа метод возвращает соответствующий объект элемента управляемой формы со своим набором свойств и перечислением Вид:

Программное создание групп и вкладок: ГруппаФормы

Чтобы аккуратно разместить новые поля на типовой форме (особенно при доработке в расширении), сначала создают контейнер — Тип("ГруппаФормы"). Сразу после добавления группе задают Вид из перечисления ВидГруппыФормы:

• ВидГруппыФормы.ОбычнаяГруппа — блок с вертикальной или горизонтальной группировкой (свойство Группировка = ГруппировкаПодчиненныхЭлементовФормы.Горизонтальная или Вертикальная) и настройкой рамки/сворачивания через Поведение = ПоведениеОбычнойГруппы.Свертываемая;
• ВидГруппыФормы.Страницы — контейнер вкладок (табов), внутрь которого добавляются только группы с видом Страница;
• ВидГруппыФормы.Страница — отдельная вкладка внутри группы Страницы.

&НаСервере
Процедура ДобавитьВкладкуДопСведений()
    // Если на форме уже есть группа страниц "ГруппаСтраницы", добавляем в неё новую вкладку
    НоваяСтраница = Элементы.Добавить(
        "СтраницаЛогистика",
        Тип("ГруппаФормы"),
        Элементы.ГруппаСтраницы);
    НоваяСтраница.Вид = ВидГруппыФормы.Страница;
    НоваяСтраница.Заголовок = "Логистика";

    // Внутри вкладки создаём обычную горизонтальную группу без заголовка
    ГруппаРеквизитов = Элементы.Добавить(
        "ГруппаЛогистикаПоля",
        Тип("ГруппаФормы"),
        НоваяСтраница);
    ГруппаРеквизитов.Вид = ВидГруппыФормы.ОбычнаяГруппа;
    ГруппаРеквизитов.Группировка = ГруппировкаПодчиненныхЭлементовФормы.Горизонтальная;
    ГруппаРеквизитов.Отображение = ОтображениеОбычнойГруппы.Нет;
    ГруппаРеквизитов.ОтображатьЗаголовок = Ложь;
КонецПроцедуры

Создание полей ввода, флажков и надписей: ПолеФормы и ПутьКДанным

Для отображения данных создают элемент с типом Тип("ПолеФормы"). Чтобы элемент появился на форме и отображал нужный элемент управления, выполните два шага:

1. Задайте Вид из перечисления ВидПоляФормы (по умолчанию ставится ПолеВвода; для других контролов укажите ПолеФлажка, ПолеНадписи, ПолеПереключателя и т.д.).
2. Привяжите элемент к существующему реквизиту через ПутьКДанным (например, "Объект.Грузополучатель" для реквизита документа или "ДополнительныйКомментарий" для реквизита формы).

Если самого реквизита на форме ещё нет, его нужно предварительно создать методом формы ИзменитьРеквизиты() и только после этого назначать в ПутьКДанным:

&НаСервере
Процедура ДобавитьПоляДоставкиНаСервере()
    // 1. Создаём реквизиты формы одним вызовом ИзменитьРеквизиты
    НовыеРеквизиты = Новый Массив;
    НовыеРеквизиты.Добавить(Новый РеквизитФормы(
        "КодМаршрута",
        Новый ОписаниеТипов("Строка", , , Новый КвалификаторыСтроки(20)),
        ,
        "Код маршрута"));
    НовыеРеквизиты.Добавить(Новый РеквизитФормы(
        "ТребуетсяПропуск",
        Новый ОписаниеТипов("Булево"),
        ,
        "Требуется пропуск"));
    ИзменитьРеквизиты(НовыеРеквизиты);

    // 2. Поле ввода для строкового реквизита
    ПолеМаршрута = Элементы.Добавить("ПолеКодМаршрута", Тип("ПолеФормы"), Элементы.ГруппаЛогистикаПоля);
    ПолеМаршрута.Вид = ВидПоляФормы.ПолеВвода;
    ПолеМаршрута.ПутьКДанным = "КодМаршрута";
    ПолеМаршрута.Ширина = 15;

    // 3. Поле флажка для булева реквизита
    ПолеПропуска = Элементы.Добавить("ПолеТребуетсяПропуск", Тип("ПолеФормы"), Элементы.ГруппаЛогистикаПоля);
    ПолеПропуска.Вид = ВидПоляФормы.ПолеФлажка;
    ПолеПропуска.ПутьКДанным = "ТребуетсяПропуск";
    ПолеПропуска.ПоложениеЗаголовка = ПоложениеЗаголовкаЭлементаФормы.Право;
КонецПроцедуры

Когда вы добавляете колонку в существующую таблицу формы (например, Элементы.Товары), в качестве родителя в Элементы.Добавить() передавайте саму таблицу Элементы.Товары, а в ПутьКДанным указывайте путь через табличную часть: "Объект.Товары.АртикулПоставщика".

Программное создание команды и кнопки: Команды.Добавить и КнопкаФормы

В управляемой форме 1С 8.3 кнопка не вызывает процедуру модуля напрямую. Между кнопкой и кодом всегда стоит объект КомандаФормы из коллекции Команды (тип КомандыФормы). Поэтому программное добавление кнопки состоит из двух шагов:

1. Создать команду методом Команды.Добавить(ИмяКоманды) и записать в её свойство Действие имя существующей в модуле формы клиентской процедуры с директивой &НаКлиенте.
2. Создать визуальный элемент через Элементы.Добавить(ИмяКнопки, Тип("КнопкаФормы"), Родитель), задать Вид (ВидКнопкиФормы.ОбычнаяКнопка для размещения среди полей или ВидКнопкиФормы.КнопкаКоманднойПанели для командной панели) и связать с командой через ИмяКоманды.

&НаСервере
Процедура ДобавитьКнопкуПроверкиНаСервере()
    // 1. Создаём команду формы и связываем с клиентским обработчиком
    НоваяКоманда = Команды.Добавить("КомандаПроверитьМаршрут");
    НоваяКоманда.Заголовок = "Проверить маршрут";
    НоваяКоманда.Действие = "ПодключитьПроверкуМаршрута";
    НоваяКоманда.Картинка = БиблиотекаКартинок.ВыполнитьПроверку;
    НоваяКоманда.Отображение = ОтображениеКнопки.КартинкаИТекст;
    НоваяКоманда.ИзменяетСохраняемыеДанные = Ложь;

    // 2. Размещаем кнопку в командной панели формы
    Кнопка = Элементы.Добавить(
        "КнопкаПроверитьМаршрут",
        Тип("КнопкаФормы"),
        Элементы.ФормаКоманднаяПанель);
    Кнопка.Вид = ВидКнопкиФормы.КнопкаКоманднойПанели;
    Кнопка.ИмяКоманды = "КомандаПроверитьМаршрут";
КонецПроцедуры

&НаКлиенте
Процедура ПодключитьПроверкуМаршрута(Команда)
    Сообщить("Проверка маршрута запущена: " + КодМаршрута);
КонецПроцедуры

Если кнопка размещается прямо в группе рядом с полями ввода (а не в командной панели), укажите родительскую обычную группу и установите Кнопка.Вид = ВидКнопкиФормы.ОбычнаяКнопка. Сама процедура обработчика команды в модуле формы обязательно должна принимать один параметр (Команда) и иметь директиву компиляции &НаКлиенте.

Подключение обработчиков событий: УстановитьДействие

Программно созданному полю ввода, флажку или таблице часто нужно назначить реакцию на действия пользователя: "ПриИзменении", "НачалоВыбора", "Очистка", "ПриАктивизацииСтроки". Для этого у элементов формы есть серверный метод УстановитьДействие(ИмяСобытия, Действие), а для проверки текущего обработчика — ПолучитьДействие(ИмяСобытия):

&НаСервере
Процедура НастроитьСобытияПоляМаршрута()
    Поле = Элементы.ПолеКодМаршрута;

    // Привязываем клиентские процедуры к событиям элемента
    Поле.УстановитьДействие("ПриИзменении", "ПолеКодМаршрутаПриИзменении");
    Поле.УстановитьДействие("НачалоВыбора", "ПолеКодМаршрутаНачалоВыбора");
    Поле.КнопкаВыбора = Истина;
КонецПроцедуры

&НаКлиенте
Процедура ПолеКодМаршрутаПриИзменении(Элемент)
    КодМаршрута = ВРег(СокрЛП(КодМаршрута));
КонецПроцедуры

&НаКлиенте
Процедура ПолеКодМаршрутаНачалоВыбора(Элемент, ДанныеВыбора, СтандартнаяОбработка)
    СтандартнаяОбработка = Ложь;
    // Логика открытия подбора маршрута
КонецПроцедуры

Сигнатура клиентской процедуры в модуле формы должна точно соответствовать выбранному событию из Синтаксис-помощника: например, для "ПриИзменении" это (Элемент), а для "НачалоВыбора" — (Элемент, ДанныеВыбора, СтандартнаяОбработка).

Перемещение, поиск и удаление элементов: Переместить, Найти, Удалить

Помимо создания, коллекция Элементы позволяет безопасно проверять наличие элемента через Элементы.Найти(Имя), менять его положение в иерархии методом Элементы.Переместить() и полностью удалять элемент с формы методом Элементы.Удалить():

&НаСервере
Процедура ПерестроитьЭлементыФормыНаСервере()
    // 1. Безопасный поиск элемента по имени
    НайденноеПоле = Элементы.Найти("ПолеКодМаршрута");
    Если НайденноеПоле = Неопределено Тогда
        Возврат;
    КонецЕсли;

    // 2. Перемещение элемента в другую группу перед указанным полем
    Элементы.Переместить(
        НайденноеПоле,
        Элементы.ГруппаШапка,
        Элементы.Организация);

    // 3. Удаление ненужного программного элемента
    ЛишнийЭлемент = Элементы.Найти("ПолеТребуетсяПропуск");
    Если ЛишнийЭлемент <> Неопределено Тогда
        Элементы.Удалить(ЛишнийЭлемент);
    КонецЕсли;
КонецПроцедуры

В типовых конфигурациях на БСП скрыть штатный элемент почти всегда безопаснее через Элементы.ИмяЭлемента.Видимость = Ложь, чем вызывать Элементы.Удалить(). Если физически удалить типовое поле, к которому обращаются другие процедуры модуля формы по имени Элементы.ИмяЭлемента, при открытии или записи документа возникнет ошибка обращения к несуществующему свойству.

Частые ошибки при программном создании элементов управляемой формы

• Вызов Элементы.Добавить() на клиенте. Методы модификации коллекции ВсеЭлементыФормы (Добавить, Вставить, Переместить, Удалить) и метод УстановитьДействие() доступны только на сервере. В клиентском коде можно менять лишь свойства уже существующих элементов (например, Видимость, Доступность, ТолькоПросмотр, Заголовок).
• Не заполнено или неверно указано свойство ПутьКДанным у ПолеФормы. В отличие от групп, декораций и кнопок, объект ПолеФормы или ТаблицаФормы обязан быть связан с данными формы. Если забыть указать ПутьКДанным или сослаться на несуществующий реквизит, элемент либо не отобразится на форме, либо вызовет исключение при открытии.
• Создание кнопки без объекта КомандаФормы. Нельзя прописать имя процедуры напрямую в кнопку. Сначала создайте команду через Команды.Добавить(), назначьте ей Действие, а у кнопки укажите ИмяКоманды.
• Попытка передать в Действие серверную процедуру. И свойство Команда.Действие, и второй параметр Элемент.УстановитьДействие() принимают имя процедуры, объявленной в модуле формы строго с директивой &НаКлиенте.
• Несовпадение родителя при вызове Элементы.Вставить(). Четвёртый параметр (элемент-ориентир) должен находиться непосредственно внутри той же группы, которая передана третьим параметром Родитель.
• Дублирование имени элемента при повторном серверном вызове. Имя каждого элемента в коллекции Элементы должно быть уникальным во всей форме. Если процедура генерации может вызываться повторно (не только в ПриСозданииНаСервере), проверяйте существование через Элементы.Найти("ИмяЭлемента") = Неопределено.

Частые вопросы о программном создании элементов формы в 1С 8.3