Пользовательские поля в СКД 1С: выбор, выражения и настройка

Чем пользовательское поле отличается от вычисляемого поля схемы

В отчётах на СКД часто путают два похожих механизма: Вычисляемые поля на одноимённой вкладке конструктора схемы и Пользовательские поля в настройках варианта отчёта. Главное архитектурное различие заключается в том, на каком уровне хранится описание поля и как для него рассчитываются итоги по группировкам.

Вычисляемое поле (ВычисляемоеПолеСхемыКомпоновкиДанных) принадлежит самой схеме компоновки (Схема.ВычисляемыеПоля). Чтобы его добавить, нужен Конфигуратор или программная модификация макета схемы. Само по себе вычисляемое поле считает только детальные записи: чтобы получить по нему сумму или среднее в шапке группировки, разработчик обязан отдельно зарегистрировать его на вкладке «Ресурсы» (коллекция Схема.ПоляИтога).

Пользовательское поле (Настройки.ПользовательскиеПоля) принадлежит конкретному варианту настроек (или пользовательским настройкам КомпоновщикНастроек.ПользовательскиеНастройки). Его может создать аналитик или бухгалтер в режиме «1С:Предприятие» через меню Ещё → Изменить вариант → Пользовательские поля. При этом одно пользовательское поле-выражение сразу совмещает в себе и формулу детальной строки, и формулу ресурса для итоговых записей.

Два вида пользовательских полей: поле-выражение и поле выбора

Коллекция Настройки.ПользовательскиеПоля.Элементы (КоллекцияПользовательскихПолейКомпоновкиДанных) принимает элементы двух платформенных типов. В интерфейсе настроек варианта они создаются кнопками Добавить поле-выражение и Добавить поле выбора.

• Поле-выражение (ПользовательскоеПолеВыражениеКомпоновкиДанных) — позволяет написать произвольные формулы на языке выражений СКД отдельно для детальных строк и отдельно для групповых итогов. Подходит для расчёта наценки, рентабельности, отклонения факта от плана, НДС, веса строки или склейки строковых реквизитов.
• Поле выбора (ПользовательскоеПолеВыборКомпоновкиДанных, в некоторых методических материалах упоминается как ПользовательскоеПолеВыбораКомпоновкиДанных) — визуальный конструктор условной логики (аналог конструкции ВЫБОР КОГДА ... ТОГДА ... КОНЕЦ) без написания кода. Содержит коллекцию вариантов (Варианты.Элементы, в пользовательском интерфейсе — таблица Значения), где для каждого возвращаемого значения настраивается стандартный Отбор СКД.

// 1. Выражение детальных записей (для каждой строки):
ВЫБОР
    КОГДА [Себестоимость] = 0 ТОГДА 0
    ИНАЧЕ ([Сумма выручки] - [Себестоимость]) / [Себестоимость] * 100
КОНЕЦ

// 2. Выражение итоговых записей (для группировок и общих итогов):
ВЫБОР
    КОГДА Сумма([Себестоимость]) = 0 ТОГДА 0
    ИНАЧЕ (Сумма([Сумма выручки]) - Сумма([Себестоимость])) / Сумма([Себестоимость]) * 100
КОНЕЦ

Обратите внимание на важную особенность синтаксиса: когда вы пишете формулу в пользовательском режиме «1С:Предприятие», СКД обращается к полям по их пользовательским заголовкам (если в заголовке есть пробелы, он берётся в квадратные скобки: [Сумма выручки]). Когда же вы задаёте выражение в Конфигураторе или программно из встроенного языка, необходимо использовать системные имена полей (ПутьКДанным), например СуммаВыручки.

Поле-выражение: почему в «Выражении итоговых записей» нужен агрегат

У объекта ПользовательскоеПолеВыражениеКомпоновкиДанных две независимые формулы: выражение детальных записей и выражение итоговых записей. В зависимости от того, какие из них заполнены, компоновщик макета трактует поле по-разному:

1. Заполнено только выражение детальных записей (выражение итоговых записей пустое) — поле ведёт себя как обычное нечисловое поле или измерение. В детальных строках отчёта значения выводятся, а в строках группировок и в «Общем итоге» ячейки остаются пустыми. По такому полю можно группировать данные.
2. Заполнены оба выражения (или только выражение итоговых записей) — поле становится ресурсом. В детальных строках вычисляется первая формула, а на каждом уровне группировки и в общих итогах — вторая.

Самая частая ошибка при настройке пользовательского поля-ресурса — скопировать в поле «Выражение итоговых записей» ту же самую формулу без агрегатной функции, например СуммаПродажи - Себестоимость вместо Сумма(СуммаПродажи) - Сумма(Себестоимость). На уровне группировки процессор компоновки агрегирует множество записей, поэтому без функций Сумма(), Среднее(), Минимум(), Максимум() или Количество() он не сможет свернуть детальные значения и оставит итоговую ячейку пустой либо выдаст ошибку компоновки.

Вторая тонкость касается относительных показателей (процент наценки, рентабельность, средняя цена Сумма(Сумма) / Сумма(Количество)). Нельзя считать итоговый процент как сумму детальных процентов — в выражении итоговых записей всегда делите агрегированную сумму на агрегированную базу с проверкой знаменателя на 0 и NULL через ЕСТЬNULL(..., 0).

Поле выбора: группировка по диапазонам и классификация по условиям

Когда нужно разбить номенклатуру на ценовые сегменты («Эконом», «Стандарт», «Премиум»), классифицировать дебиторскую задолженность по срокам просрочки («До 30 дней», «30–60 дней», «Свыше 60 дней») или подставить одно из нескольких полей в зависимости от флага, удобнее использовать поле выбора (ПользовательскоеПолеВыборКомпоновкиДанных).

Каждая строка таблицы вариантов (объект ВариантПользовательскогоПоляВыборКомпоновкиДанных в коллекции Поле.Варианты.Элементы) содержит три ключевых свойства:

• Отбор (ОтборКомпоновкиДанных) — набор условий (например, Цена < 1000 или группа условий «И» ДнейПросрочки >= 30 И ДнейПросрочки <= 60);
• Значение (Произвольный или ПолеКомпоновкиДанных) — константа (строка, число, ссылка) либо другое поле отчёта, которое вернётся при выполнении отбора;
• Представление (Строка) — текст, который увидит пользователь в ячейке отчёта вместо сырого значения.

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

// Вариант 1: Крупная сделка (Сумма >= 500 000)
ВариантКрупная = ПолеВыбора.Варианты.Элементы.Добавить();
ВариантКрупная.Использование = Истина;
ВариантКрупная.Значение = "Крупная";
ВариантКрупная.Представление = "Крупная (от 500 тыс.)";

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

// Вариант 2: Обычная сделка (Сумма < 500 000)
ВариантОбычная = ПолеВыбора.Варианты.Элементы.Добавить();
ВариантОбычная.Использование = Истина;
ВариантОбычная.Значение = "Обычная";
ВариантОбычная.Представление = "Обычная (до 500 тыс.)";

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

Варианты проверяются сверху вниз до первого совпадения условия Отбор. Если нужно задать ветку «Иначе» (по умолчанию для всех остальных строк), добавьте последним вариантом строку с пустым отбором. Учитывайте правило роли поля выбора: если в условиях Отбор используются только измерения и реквизиты, по такому полю выбора можно делать группировку; если же в условии задействованы ресурсы, СКД считает поле выбора ресурсом.

Как вывести созданное пользовательское поле в отчёт

Само по себе добавление элемента в Настройки.ПользовательскиеПоля ещё не выводит колонку на экран — оно лишь регистрирует новое поле в списке доступных полей настроек (в папке Пользовательские поля). При создании платформа автоматически генерирует для него системное имя ПользовательскиеПоля.Поле1 (следующим будет ПользовательскиеПоля.Поле2 и так далее) и записывает его в свойство ПутьКДанным (только для чтения).

Чтобы колонка появилась в результате компоновки:

• В режиме «1С:Предприятие» или Конфигураторе: перейдите на вкладку Поля (или Выбранные поля), разверните в левом дереве доступных полей ветку «Пользовательские поля» и перетащите созданное поле в правый список выбранных полей. Если в вашей группировке вместо Авто настроен собственный список выбранных полей, добавьте его и туда.
• В программном коде: прочитайте сгенерированное свойство Поле.ПутьКДанным, создайте Новый ПолеКомпоновкиДанных(Поле.ПутьКДанным) и добавьте его в Настройки.Выбор.Элементы (либо в ПоляГруппировки, если это измерение для группировки).

Программное создание пользовательского поля в 1С 8.3

Программное добавление пользовательских полей выручает, когда нужно динамически достроить колонку в типовом отчёте (например, в расширении или внешней печатной форме/обработке) без редактирования макета ОсновнаяСхемаКомпоновкиДанных.

Важно учитывать, что у объекта ПользовательскоеПолеВыражениеКомпоновкиДанных нет свойств ВыражениеДетальныхЗаписей и ВыражениеИтоговыхЗаписей (обращение через точку вызовет ошибку «Поле объекта не обнаружено») — формулы читаются и записываются только методами. Начиная с платформы 1С:Предприятие 8.3.10, для задания обеих формул используется единый метод УстановитьВыражения(ВыражениеДетальныхЗаписей, ВыражениеИтоговыхЗаписей), а для установки пользовательских текстовых представлений выражений — УстановитьПредставлениеВыражений(ПредставлениеДетальных, ПредставлениеИтоговых). Старые раздельные методы УстановитьВыражениеДетальныхЗаписей() и УстановитьВыражениеИтоговыхЗаписей() сохранены для обратной совместимости, но считаются устаревшими.

&НаСервере
Процедура ДобавитьПолеРентабельности(КомпоновщикНастроек)
    
    Настройки = КомпоновщикНастроек.Настройки;
    
    // 1. Создаём пользовательское поле-выражение в коллекции настроек
    ПолеРентабельность = Настройки.ПользовательскиеПоля.Элементы.Добавить(
        Тип("ПользовательскоеПолеВыражениеКомпоновкиДанных")
    );
    ПолеРентабельность.Заголовок = "Рентабельность, %";
    ПолеРентабельность.Использование = Истина;
    
    // 2. Задаём выражение детальных и итоговых записей одним вызовом
    ВыражениеДетальное = "ВЫБОР КОГДА ЕСТЬNULL(СуммаВыручки, 0) = 0 ТОГДА 0 "
        + "ИНАЧЕ (СуммаВыручки - ЕСТЬNULL(Себестоимость, 0)) / СуммаВыручки * 100 КОНЕЦ";
        
    ВыражениеИтоговое = "ВЫБОР КОГДА Сумма(ЕСТЬNULL(СуммаВыручки, 0)) = 0 ТОГДА 0 "
        + "ИНАЧЕ (Сумма(СуммаВыручки) - Сумма(ЕСТЬNULL(Себестоимость, 0))) "
        + "/ Сумма(СуммаВыручки) * 100 КОНЕЦ";
        
    ПолеРентабельность.УстановитьВыражения(ВыражениеДетальное, ВыражениеИтоговое);
    
    // 3. Выводим созданное поле в выбранные поля отчёта по авто-имени ПутьКДанным
    ВыбранноеПоле = Настройки.Выбор.Элементы.Добавить(
        Тип("ВыбранноеПолеКомпоновкиДанных")
    );
    ВыбранноеПоле.Поле = Новый ПолеКомпоновкиДанных(ПолеРентабельность.ПутьКДанным);
    ВыбранноеПоле.Использование = Истина;
    
КонецПроцедуры

Если вы добавляете поле внутри обработчика ПриКомпоновкеРезультата в модуле отчёта, добавляйте его в КомпоновщикНастроек.Настройки (чтобы компоновщик автоматически зарегистрировал поле в ДоступныеПоля), а затем формируйте итоговый снимок Настройки = КомпоновщикНастроек.ПолучитьНастройки() для передачи в КомпоновщикМакетаКомпоновкиДанных.Выполнить(Схема, Настройки, ДанныеРасшифровки).

Частые ошибки при работе с пользовательскими полями СКД

• Пустые ячейки в строках группировок и «Общем итоге». Причина: в поле-выражении заполнено только «Выражение детальных записей», а «Выражение итоговых записей» оставлено пустым либо записано без агрегатной функции Сумма(...). Для расчёта итогов обязательно укажите агрегатную формулу во втором выражении.
• Использование заголовков с пробелами вместо имён полей в коде 1С. В режиме «1С:Предприятие» формулы пишутся по заголовкам в квадратных скобках ([Сумма продажи]), но при вызове УстановитьВыражения() из встроенного языка или в Конфигураторе нужно указывать системный ПутьКДанным (СуммаПродажи), иначе возникнет ошибка «Поле не найдено».
• Попытка записать своё значение в ПутьКДанным. Свойство ПутьКДанным у пользовательских полей доступно только для чтения — платформа сама назначает идентификатор ПользовательскиеПоля.Поле1. Читайте это свойство после вызова Элементы.Добавить() и передавайте в Новый ПолеКомпоновкиДанных(Поле.ПутьКДанным).
• Обращение из одного пользовательского поля к другому пользовательскому полю. В выражениях пользовательских полей нельзя ссылаться на соседнее ПользовательскиеПоля.Поле1 — доступны только поля наборов данных и вычисляемые поля самой схемы компоновки.
• Вызов экспортных функций общих модулей в пользовательском поле. В отличие от Схема.ВычисляемыеПоля, в выражениях Настройки.ПользовательскиеПоля вызов функций общих модулей запрещён платформой. Если нужен вызов функции 1С, перенесите поле на вкладку «Вычисляемые поля» схемы.
• Ошибка деления на ноль при расчёте процентов и средних. Если в одной из строк или группировок знаменатель равен 0 или NULL, весь отчёт упадёт при компоновке. Всегда оборачивайте деление в конструкцию ВЫБОР КОГДА Сумма(ЕСТЬNULL(База, 0)) = 0 ТОГДА 0 ИНАЧЕ ... КОНЕЦ.
• Ошибка «Поле не найдено "ПользовательскиеПоля.Поле1"» после удаления поля. Если удалить пользовательское поле, но оставить ссылку на него в выбранных полях, отборе, сортировке или условном оформлении варианта, компоновщик макета выдаст ошибку. Перед удалением уберите поле из всех закладок настроек.

Частые вопросы по пользовательским полям в СКД