Как получить элемент управляемой формы в 1С

Обращение к элементу управляемой формы — одна из базовых операций при разработке на платформе 1С:Предприятие 8.3. Через элемент формы разработчик меняет видимость, доступность, заголовок, цвет, программно заполняет поля и управляет поведением интерфейса без изменения конфигурации в конфигураторе.

Ключевое отличие управляемых форм от обычных: код выполняется в разделённом контексте «клиент-сервер», поэтому доступ к элементам формы возможен только из модуля формы, а не из модулей объектов или общих модулей напрямую. Попытка обратиться к элементу формы извне модуля формы — самая частая причина ошибок у начинающих разработчиков.

В материале разобраны основные способы получения элемента: через коллекцию Элементы, через ЭтаФорма.Элементы, поиск по имени, работа с динамически созданными элементами, а также проверка результата и типичные ошибки с примерами кода.

Где находится коллекция элементов управляемой формы

В модуле управляемой формы доступно свойство Элементы (полное обращение — ЭтаФорма.Элементы). Это коллекция типа «ЭлементыФормы», содержащая все визуальные элементы, размещённые на форме: поля ввода, кнопки, таблицы, группы, декорации.

Коллекция существует только в контексте формы. Если вы пишете код в модуле объекта, модуле менеджера или общем модуле, свойства Элементы там нет — обращение вызовет ошибку «Переменная не определена». Чтобы управлять формой извне, нужно сначала получить саму форму (например, через ПолучитьФорму() или через параметр в обработчике оповещения), а затем обращаться к её свойству Элементы.

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

Получение элемента по имени через Элементы

Самый распространённый способ — прямое обращение по имени элемента, заданному в конфигураторе в свойстве «Имя»:

&НаКлиенте
Процедура СкрытьПолеКомментария(Команда)
Элементы.Комментарий.Видимость = Ложь;
КонецПроцедуры

Здесь Комментарий — имя элемента формы, указанное разработчиком при создании формы в конфигураторе или заданное автоматически при добавлении реквизита на форму. Если элемент с таким именем не существует, платформа выдаст ошибку «Поле объекта не обнаружено».

Альтернатива — метод Найти(), который возвращает найденный элемент или Неопределено, если элемента нет. Это безопаснее, когда существование элемента зависит от условий (например, элемент добавлен программно не всегда):

&НаСервере
Процедура НастроитьФорму()
ЭлементКомментарий = Элементы.Найти("Комментарий");
Если ЭлементКомментарий <> Неопределено Тогда
ЭлементКомментарий.Видимость = Ложь;
КонецЕсли;
КонецПроцедуры

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
    Элемент = ЭтаФорма.Элементы.Найти("Номенклатура");
    Если Элемент <> Неопределено Тогда
        Элемент.Доступность = Ложь;
    КонецЕсли;
КонецПроцедуры

Обращение к элементу через ЭтаФорма и из внешнего кода

Конструкции Элементы.Имя и ЭтаФорма.Элементы.Имя в модуле формы равнозначны: ЭтаФорма — это ссылка на текущую форму, и обращение без неё платформа разрешает автоматически. Явное указание ЭтаФорма полезно для читаемости, когда в процедуре есть локальные переменные с похожими именами.

Из внешнего кода (например, из общего модуля или из другой формы) элемент получают через полученный объект формы:

ФормаДокумента = ПолучитьФорму("Документ.РеализацияТоваровУслуг.ФормаОбъекта");
Элемент = ФормаДокумента.Элементы.Найти("ТаблицаТовары");

Учтите ограничение: ПолучитьФорму() создаёт форму, но не открывает её. Если форма уже открыта у пользователя, вы получите новый экземпляр, и изменения не отразятся на видимой форме. Для работы с уже открытой формой используйте оповещения (Оповестить / ОбработкаОповещения) или передавайте форму как параметр при открытии.

Работа с динамически созданными элементами

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

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

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

После программного добавления элемент доступен в коллекции наравне с созданными в конфигураторе: Элементы.Найти("ПолеСкидка") вернёт его до тех пор, пока форма не будет пересоздана.

1. 1
   Откройте форму в конфигураторе и узнайте точное имя нужного элемента (свойство «Имя»)
2. 2
   В модуле формы создайте процедуру с нужной директивой (&НаКлиенте или &НаСервере)
3. 3
   Обратитесь к элементу: Элементы.ИмяЭлемента или Элементы.Найти("ИмяЭлемента")
4. 4
   При использовании Найти() проверьте результат на Неопределено
5. 5
   Измените нужное свойство: Видимость, Доступность, ТолькоПросмотр, Заголовок
6. 6
   Запустите форму в режиме предприятия и проверьте поведение

Элементы таблицы формы и подчинённые элементы

Таблица формы (например, табличная часть документа) — тоже элемент, и у неё есть собственные подчинённые элементы: колонки, кнопки командной панели. Обратиться к колонке можно двумя способами: напрямую по имени через общую коллекцию Элементы или через подчинённые элементы таблицы.

&НаКлиенте
Процедура НастроитьКолонку()
// Прямое обращение по имени колонки
Элементы.ТоварыЦена.Видимость = Ложь;

// Через подчинённые элементы таблицы
ТаблицаТовары = Элементы.Товары;
Для Каждого Подчиненный Из ТаблицаТовары.ПодчиненныеЭлементы Цикл
// обход колонок
КонецЦикла;
КонецПроцедуры

Обратите внимание: имя колонки по умолчанию формируется как имя таблицы плюс имя реквизита (ТоварыЦена), но разработчик мог его переименовать. Перед написанием кода сверьтесь с именем в конфигураторе.

Для получения текущих данных строки таблицы (а не элемента-колонки) используется свойство ТекущиеДанные: Элементы.Товары.ТекущиеДанные.Цена. Это частая путаница: Элементы.Товары.Цена не сработает, потому что у таблицы нет свойства с именем колонки.

Проверка результата и типичные ошибки

После получения элемента убедитесь, что вы работаете с тем объектом: проверьте тип элемента через ТипЗнч(), если код универсальный. Для полей ввода это ПолеФормы, для таблиц — ТаблицаФормы, для кнопок — КнопкаФормы. Набор доступных свойств у разных типов различается: например, ПутьКДанным есть у поля, но нет у кнопки.

Самая частая ошибка — «Поле объекта не обнаружено (ИмяЭлемента)». Причины: опечатка в имени, элемент расположен на другой форме (например, на форме списка, а не форме объекта), элемент был удалён при доработке конфигурации, а код остался. Вторая типичная ошибка — обращение к Элементы вне модуля формы или в клиентской процедуре попытка программно добавить элемент.

Ещё одна ловушка — обращение к элементу в обработчике ПриОткрытии на клиенте, когда элемент создаётся программно на сервере в ПриСозданииНаСервере позже по логике условий. Порядок вызова: сначала серверное создание, потом клиентское открытие, поэтому обычно всё корректно, но при условном создании элемента проверка на Неопределено обязательна.

FAQ