Как правильно получить текущие начисления сотрудника в 1С:ЗУП 3.1?

← На главную

При разработке и кастомизации конфигурации 1С:Зарплата и управление персоналом 3.1 (ЗУП) программисты часто сталкиваются с необходимостью вывода действующих начислений сотрудников в печатные формы приказов, справок или отчетов. Типичный пример — вывод размера районного коэффициента, северной надбавки или надбавки за вредные условия труда на дату кадрового перевода.

В этой статье мы подробно разберем, как правильно использовать механизмы программного интерфейса ЗУП 3.1 для получения этих сведений, детально изучим структуру возвращаемых данных конфигурации, разберем типичные ошибки разработчиков-новичков и рассмотрим наиболее эффективные способы отладки кода.

Разбираем метод КадровыйУчетРасширенный.ТекущиеНачисленияСотрудника

Для получения актуальных плановых начислений в системе предусмотрен специализированный программный интерфейс. Чаще всего разработчики используют экспортную функцию ТекущиеНачисленияСотрудника из общего модуля КадровыйУчетРасширенный.

Давайте проанализируем, какие параметры принимает эта функция:


ТекущиеНачисления = КадровыйУчетРасширенный.ТекущиеНачисленияСотрудника(
    Сотрудник, 
    ДатаСведений, 
    Показатели, 
    ДокументыОснования
);

Где передаваемые параметры означают следующее:

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

В чем главная ошибка при обработке результата?

Наиболее распространенная ошибка начинающих разработчиков заключается в попытке обратиться к результату функции напрямую как к таблице значений или структуре. Например, код вида ТекущиеНачисления.РайонныйКоэффициент или ТекущиеНачисления[0].Размер гарантированно вызовет ошибку выполнения системы: «Поле объекта не обнаружено» или «Значение не является значением объектного типа».

Выясним причину такого поведения платформы. Данная функция возвращает коллекцию типа Соответствие (Map), а не таблицу значений напрямую. Структура возвращаемого соответствия выглядит следующим образом:

Ключ соответствия: Ссылка на вид расчета из плана видов расчета начислений (ПланВидовРасчетаСсылка.Начисления).
Значение соответствия: Коллекция (обычно массив структур или таблица значений), содержащая детальные параметры этого начисления на указанную дату (размер, показатели, документы-основания).

Исправляем ошибку передачи параметров: Один сотрудник vs Список сотрудников

Еще одна неочевидная проблема возникает при передаче в функцию массива вместо одиночной ссылки. Давайте разберемся, почему передача массива сотрудников в функцию ТекущиеНачисленияСотрудника приводит к фатальному сбою программы.

В общем модуле КадровыйУчетРасширенный сосуществуют две схожие функции:

ТекущиеНачисленияСотрудника(...) — предназначена для работы строго с одним сотрудником.
ТекущиеНачисленияСотрудников(...) — спроектирована для работы с массивом/списком сотрудников (оптимизирована под пакетные запросы).

Рассмотрим, как устроена одиночная функция изнутри «под капотом» системы:


Функция ТекущиеНачисленияСотрудника(Сотрудник, ДатаСведений, ...) Экспорт
    Возврат ТекущиеНачисленияСотрудников(
        ОбщегоНазначенияКлиентСервер.ЗначениеВМассиве(Сотрудник), 
        ДатаСведений, ...
    ).Получить(Сотрудник);
КонецФункции

Если мы передадим в эту функцию готовый массив в качестве первого параметра, система принудительно обернет его в еще один массив. В результате функция для работы со списком вернет соответствие, где ключами будут являться элементы исходного массива (конкретные ссылки на сотрудников). Однако одиночная функция попытается получить значение из этого соответствия, используя в качестве ключа весь переданный массив целиком. Разумеется, такого ключа в соответствии не окажется, метод возвратит значение Неопределено, а последующая попытка вызвать метод Получить() для извлечения вида расчета вызовет ошибку «Значение не является значением объектного типа (Получить)».

Правило простое: если у нас есть массив сотрудников, мы должны использовать функцию ТекущиеНачисленияСотрудников, а если у нас есть конкретная ссылка на сотрудника — используем ТекущиеНачисленияСотрудника.

Реализуем безопасный алгоритм получения начислений

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

Посмотрим на пример правильной реализации в модуле объекта печатной формы:


// 1. Получаем соответствие начислений сотрудника на дату
НачисленияСотрудника = КадровыйУчетРасширенный.ТекущиеНачисленияСотрудника(
    СсылкаНаДокумент.Сотрудник, 
    ДатаНачалаПеревода, 
    Неопределено, 
    Истина
);

РазмерРК = 1; // Дефолтное значение районного коэффициента
ПроцентВредности = 0;

Если НачисленияСотрудника <> Неопределено Тогда

    // 2. Извлекаем данные районного коэффициента
    // Рекомендуется использовать предопределенные ссылки, если они есть в ПВР
    ВидРасчетаРК = ПланыВидовРасчета.Начисления.РайонныйКоэффициент;
    ДанныеРК = НачисленияСотрудника.Получить(ВидРасчетаРК);
    
    Если ДанныеРК <> Неопределено И ДанныеРК.Количество() > 0 Тогда
        // Извлекаем значение из первой строки коллекции показателей
        РазмерРК = ДанныеРК[0].Размер;
    КонецЕсли;

    // 3. Извлекаем данные надбавки за вредность (поиск по уникальному коду)
    ВидРасчетаВредность = ПланыВидовРасчета.Начисления.НайтиПоКоду("Вредность");
    Если ЗначениеЗаполнено(ВидРасчетаВредность) Тогда
        ДанныеВредности = НачисленияСотрудника.Получить(ВидРасчетаВредность);
        Если ДанныеВредности <> Неопределено И ДанныеВредности.Количество() > 0 Тогда
            ПроцентВредности = ДанныеВредности[0].Размер;
        КонецЕсли;
    КонецЕсли;

КонецЕсли;

// 4. Передаем полученные значения в параметры макета печатной формы
ОбластьРаботник.Параметры.РайонныйКоэффициент = РазмерРК;
ОбластьРаботник.Параметры.НадбавкаЗаВредность = ПроцентВредности;

Альтернативные специализированные функции ЗУП 3.1

Разработчикам прикладных решений полезно знать, что для некоторых стандартных показателей в ЗУП 3.1 существуют готовые «облегченные» функции, которые возвращают результат напрямую без необходимости обхода сложных коллекций соответствий.

Проанализируем две такие полезные возможности:

А. Получение процента северной надбавки

Если нам требуется оперативно получить процент действующей северной надбавки сотрудника на определенную дату, мы можем задействовать следующую функцию:


ПроцентСН = КадровыйУчетРасширенный.ПроцентСевернойНадбавки(Сотрудник, ДатаПолученияДанных);

Данная функция возвращает числовое значение процента напрямую (например, 30 или 50), что существенно упрощает разработку.

Б. Получение районного коэффициента через кадровые данные

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


СписокПолей = "РайонныйКоэффициент";
КадровыеДанные = КадровыйУчет.КадровыеДанныеСотрудника(Сотрудник, СписокПолей, Дата);
РазмерРК = ?(КадровыеДанные <> Неопределено, КадровыеДанные.РайонныйКоэффициент, 1);

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

Как эффективно отлаживать внешние печатные формы (ВПФ)?

Часто у начинающих специалистов возникает сложность с отладкой кода внешних печатных форм, так как код выполняется в модуле объекта ВПФ, который загружается платформой динамически из справочника «Дополнительные отчеты и обработки» во временное хранилище. Точки останова в модуле объекта при этом просто «не цепляются» конфигуратором.

Рассмотрим два проверенных способа решения этой проблемы:

Переключение ВПФ в режим отладки через БСП. В современных версиях ЗУП 3.1, построенных на базе Библиотеки Стандартных Подсистем (БСП), при регистрации внешней печатной формы в справочнике дополнительных обработок можно перевести ее в режим выполнения «Отладка». При этом система предложит указать локальный путь к файлу обработки .epf на вашем жестком диске. При запуске печати из документа система будет выполнять код именно локального файла, что позволит конфигуратору без труда перехватывать выполнение на установленных точках останова.
Использование внешней обработки-отладчика. Мы можем создать простейшую внешнюю обработку со следующей структурой: на форме размещаем реквизит типа ДокументСсылка (например, «Кадровый перевод») и кнопку «Выполнить отладку». По нажатию кнопки программно создаем экземпляр нашей печатной формы, загружая ее непосредственно с диска, заполняем параметры и вызываем процедуру печати. В таком режиме отладка в модуле объекта обработки будет работать без каких-либо ограничений.

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