1С: как обратиться к элементу формы списка

Форма списка в 1С — это управляемая форма, в которой выводится таблица справочника, документа или другого объекта. Чтобы программно управлять этой таблицей — читать текущую строку, менять отбор, оформлять строки цветом, — нужно получить доступ к элементу формы, обычно это таблица с именем «Список». Обращение выполняется через коллекцию Элементы объекта формы.

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

Как устроена форма списка и где искать элемент

В управляемой форме списка всегда есть два ключевых объекта, которые часто путают. Первый — элемент формы типа «Таблица формы», обычно называется Список. Он отвечает за визуальное отображение: колонки, выделение, режим выбора. Второй — реквизит формы того же имени, который хранит сами данные. Если включён динамический список, этот реквизит имеет тип «ДинамическийСписок».

Чтобы узнать точное имя элемента, откройте форму списка в конфигураторе и посмотрите дерево элементов формы. Таблица, у которой в свойстве «ПутьКДанным» указан реквизит списка, и есть нужный элемент. Имя может отличаться от «Список» — например, «СписокДокументов» или «ТаблицаЗаказов», если разработчик переименовал его.

Разделение важно на практике: через Элементы.Список вы управляете отображением и получаете текущую строку, а через ЭтаФорма.Список (реквизит) — меняете запрос, отбор, параметры и порядок. Обращение к несуществующему имени вызовет ошибку «Поле объекта не обнаружено», поэтому сначала сверьте имя в конфигураторе.

Обращение к элементу формы через коллекцию Элементы

Базовый синтаксис обращения из модуля формы выглядит так: Элементы.Список — если имя известно заранее, либо Элементы["Список"] — если имя хранится в переменной. Оба варианта возвращают объект типа «ТаблицаФормы», через который доступны свойства и методы элемента.

// Прямое обращение по имени
ТаблицаСписка = Элементы.Список;

// Обращение через строковое имя — удобно в универсальных процедурах
ИмяЭлемента = "Список";
ТаблицаСписка = Элементы[ИмяЭлемента];

// Примеры работы со свойствами
Элементы.Список.ТолькоПросмотр = Истина;
Элементы.Список.Видимость = Ложь;
Элементы.Список.Шапка = Ложь;

Через объект таблицы формы можно управлять отображением строк, обходить колонки и менять поведение. Например, Элементы.Список.ПодчиненныеЭлементы содержит колонки таблицы, а Элементы.Список.РежимВыделения определяет, можно ли выделять несколько строк.

Учтите, что коллекция Элементы доступна только в контексте формы. В модуле объекта, общем модуле или модуле менеджера такого обращения нет — туда нужно передавать либо форму целиком, либо уже извлечённые данные.

Как получить текущую строку и её данные

Самая частая задача — прочитать данные строки, на которой стоит курсор. Для этого у таблицы формы есть свойства ТекущиеДанные и ТекущаяСтрока. Первое возвращает объект с данными строки, второе — идентификатор строки (для динамического списка это ссылка на объект).

ТекущиеДанные = Элементы.Список.ТекущиеДанные;
Если ТекущиеДанные = Неопределено Тогда
// Строка не выбрана — обязательно проверяйте
Возврат;
КонецЕсли;

СсылкаНаДокумент = ТекущиеДанные.Ссылка;
НомерДокумента = ТекущиеДанные.Номер;

Проверка на Неопределено обязательна: если список пуст или фокус не на строке, ТекущиеДанные вернёт Неопределено, и обращение к полю вызовет ошибку. Это одна из самых распространённых причин падения обработчиков команд в формах списка.

Для множественного выделения используйте Элементы.Список.ВыделенныеСтроки — это массив идентификаторов выделенных строк. Его удобно перебирать, когда команда должна обработать сразу несколько объектов, например провести группу документов.

Для Каждого Строка Из Элементы.Список.ВыделенныеСтроки Цикл
    // Строка — ссылка на объект (для динамического списка)
    ОбработатьДокумент(Строка);
КонецЦикла;

Работа с динамическим списком: отбор, параметры, порядок

Если основной реквизит формы — динамический список, управлять содержимым нужно через него, а не через элемент. Обращение из модуля формы: Список или ЭтаФорма.Список. Через этот объект доступны коллекции Отбор, Параметры, Порядок, Группировка и свойство ТекстЗапроса.

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

// Установка параметра запроса
Список.Параметры.УстановитьЗначениеПараметра("ДатаНачала", НачалоМесяца(ТекущаяДата()));

После изменения отбора или параметров динамический список обычно обновляется автоматически. Если данные на экране не перечитались, вызовите Элементы.Список.Обновить() — это принудительно перечитывает отображение таблицы.

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

1. 1
   Откройте форму списка и убедитесь, что реквизит Список — динамический список, а нужное поле есть в запросе
2. 2
   В модуле формы добавьте элемент в Список.Отбор.Элементы с типом ЭлементОтбораКомпоновкиДанных
3. 3
   Укажите ЛевоеЗначение (поле), ВидСравнения, ПравоеЗначение и установите Использование = Истина
4. 4
   Вызовите Элементы.Список.Обновить(), если данные не перечитались автоматически
5. 5
   Проверьте результат: в списке должны остаться только строки, удовлетворяющие условию

Условное оформление и доступ к колонкам

Чтобы раскрасить строки по условию или скрыть колонку, используется коллекция УсловноеОформление динамического списка. Оно работает как отбор плюс набор оформляемых полей и параметров оформления (цвет фона, шрифт, видимость).

ЭлементОформления = Список.УсловноеОформление.Элементы.Добавить();

ОтборОформления = ЭлементОформления.Отбор.Элементы.Добавить(Тип("ЭлементОтбораКомпоновкиДанных"));
ОтборОформления.ЛевоеЗначение = Новый ПолеКомпоновкиДанных("Проведен");
ОтборОформления.ВидСравнения = ВидСравненияКомпоновкиДанных.Равно;
ОтборОформления.ПравоеЗначение = Ложь;

ЭлементОформления.Оформление.УстановитьЗначениеПараметра("ЦветТекста", WebЦвета.Серый);

Для работы с отдельной колонкой обращайтесь к ней как к подчинённому элементу таблицы: Элементы.СписокНомер (имя формируется из имени таблицы и имени колонки, но лучше сверить в конфигураторе). Через элемент колонки можно менять видимость, ширину, заголовок и доступность.

Обращение к элементу извне и контекст вызова

Иногда к форме списка нужно обратиться не из её модуля, а из другой формы или общего кода. Для этого форму сначала получают функцией ПолучитьФорму() или находят среди открытых окон, а затем обращаются к её элементам через объект формы.

ФормаСписка = ПолучитьФорму("Справочник.Номенклатура.ФормаСписка");
ФормаСписка.Список.Отбор.Элементы.Очистить();
ФормаСписка.Открыть();

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

ПараметрыФормы = Новый Структура;
Отбор = Новый Структура("Владелец", ТекущийКонтрагент);
ПараметрыФормы.Вставить("Отбор", Отбор);
ОткрытьФорму("Справочник.Договоры.ФормаСписка", ПараметрыФормы);

Типичные ошибки и как их проверить

Первая ошибка — обращение Элементы.Список в обычной (неуправляемой) форме. В обычных формах используется коллекция ЭлементыФормы, а данные списка доступны через реквизит типа «СправочникСписок» или «ДокументСписок» со своими отборами. Синтаксис несовместим, и код из управляемой формы в обычной не заработает.

Вторая ошибка — чтение ТекущиеДанные в серверном контексте. Свойства текущей строки доступны только на клиенте, потому что выделение строки — клиентское понятие. Если вам нужны данные на сервере, передавайте туда ссылку из текущей строки, а не сам объект данных строки.

Третья ошибка — попытка изменить данные объекта через ТекущиеДанные и ожидать, что они запишутся в базу. Текущие данные строки — это только отображение. Для изменения объекта получите его объектным методом (Ссылка.ПолучитьОбъект()), измените и запишите, затем обновите список.

Частые вопросы