Конструктор представлений подсистемы «Зарплата и кадры»

Внешняя обработка для конфигураций на базе подсистемы «Зарплата и кадры» (1С:ЗУП 3.1, ЗУП КОРП, ЗКГУ и др.). Интерактивно собирает представления запросов — текстовые описания наборов данных, которые типовой механизм конфигурации на лету заменяет на реальные запросы к базе, — и показывает, какие представления, поля и параметры доступны в конкретной базе.

Этот файл — основная документация и по механизму представлений, и по обработке. Справка внутри обработки (Help/ru.html объекта и форм) собирается из него и из файлов docs/*.md скриптом scripts/build_help.py, поэтому редактировать документацию нужно только здесь.

Содержание

• Зачем нужна обработка
• Механизм представлений запросов
  • Идея
  • Как устроена замена
  • Синтаксис представления в тексте запроса
  • Поля
  • Параметры
  • Отборы
  • Таблица фильтра
  • Источник данных и уточнение
  • Как применить представление
• Возможности обработки
• Требования и установка
• Быстрый старт
• Форма «Конструктор представлений»
• Форма «Текст запроса»
• Код программного интерфейса
• Импорт представления из текста запроса
• Интеграция с внешними инструментами
• Кэш описаний представлений
• Пакетный режим: выгрузка описаний в JSON
• Как обработка формирует описания
• Программный интерфейс модуля объекта
• Ограничения и особенности
• Репозиторий
• Лицензия

Зачем нужна обработка

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

Обработка решает это так:

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

Механизм представлений запросов

Идея

Представление — это описание набора данных, которое пишется прямо в тексте запроса в виде запроса помещения во временную таблицу с именем Представления_<Имя>. Разработчик перечисляет нужные поля и параметры, а получение данных происходит «под капотом»: перед выполнением типовая процедура ЗарплатаКадрыОбщиеНаборыДанных.ЗаменитьЗапросыКПредставлениямВиртуальныхТаблиц находит такие описания и заменяет их на реальные запросы к регистрам и справочникам, используя типовые алгоритмы подсистемы (получение кадровых данных, срезов регистров, штатного расписания, учёта времени и т. д.).

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

Как устроена замена

Единого реестра представлений в конфигурации нет — это диспетчеризация по имени в цепочке общих модулей. Головная функция ЗарплатаКадрыОбщиеНаборыДанных.ПолучитьЗапросПоПредставлению(ТекстЗапроса, СоответствиеПараметров) передаёт описание в ЗарплатаКадрыОбщиеНаборыДанныхРасширенный, который сам строит часть представлений (штатное расписание, кадровая расстановка, отпуска, плановые начисления и удержания, стажи, статьи финансирования, бухучёт зарплаты) и далее по цепочке делегирует: УчетРабочегоВремениРасширенный.ЗапросПоПредставлению (данные учёта времени, плановое время) → модули прикладных подсистем (аттестации, медицина, бюджетные учреждения, охрана труда, кадровое планирование, подбор персонала, кадровый резерв, медосмотры, организационная структура; каждый вызывается только при наличии подсистемы) → в конце ЗарплатаКадрыОбщиеНаборыДанныхБазовый (периоды, регистры, кадровые данные, рабочие места, сотрудники организации, отработанное время, НДФЛ). Модуль, распознавший имя, возвращает готовый объект Запрос; если имя никто не распознал или представление недоступно по функциональной опции, результат — Неопределено.

Процедура ЗаменитьЗапросыКПредставлениямВиртуальныхТаблиц(ТекстЗапроса, Приемник) работает так:

1. Разбивает пакет по ; на отдельные запросы и в каждом ищет ПОМЕСТИТЬ, за которым (через пробелы) следует Представления_ — это и есть описание представления.
2. Разбирает описание: имя и источник данных — из имени временной таблицы, таблица фильтра — из секции ИЗ, поля — имена после КАК в секции ВЫБРАТЬ, параметры — пары "Имя" = Значение из секции ГДЕ (кавычки снимаются с обеих частей). Значение параметра — просто строка из текста; как её понимать (ИСТИНА, "МЕСЯЦ", &НачалоПериода, НАЧАЛОПЕРИОДА(&Дата, МЕСЯЦ)), решает построитель конкретного представления. Построитель забирает только нужные ему параметры по имени, остальные игнорируются.
3. Подставляет полученный текст вместо описания. Имя создаваемой временной таблицы при этом переписывается без подчёркивания: Представления_КадровыеДанныеСотрудников → ПредставленияКадровыеДанныеСотрудников, и в конце во всём тексте пакета Представления_ заменяется на Представления — обращения к таблице из других запросов пакета тоже переименовываются. Замена выполняется рекурсивно, поэтому построенный текст может сам содержать представления.
4. Переносит параметры запроса, которые создал построитель (например, &Период внутри реального текста), в приёмник: в объект Запрос, в динамический список или в схему компоновки данных — в зависимости от типа второго аргумента. Параметры с префиксом Представления_ при переносе переименовываются.

Если построитель вернул Неопределено, описание остаётся в тексте как есть (с тем же переименованием Представления_ → Представления). Ошибки при этом не возникает: запрос выполнится, но временная таблица будет содержать пустые значения из выражений-заглушек, а не реальные данные. Обработка использует это свойство, чтобы определять доступность представления в базе.

Синтаксис представления в тексте запроса

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

ВЫБРАТЬ
	ДАТАВРЕМЯ(1, 1, 1) КАК Период,
	ЗНАЧЕНИЕ(Справочник.Сотрудники.ПустаяСсылка) КАК Сотрудник,
	"" КАК ИОФамилия,
	0 КАК ОбщийСтажЛет
ПОМЕСТИТЬ Представления_КадровыеДанныеСотрудников
ИЗ
	ВТФильтр КАК ВТФильтр
ГДЕ
	"ТолькоРазрешенные" = ЛОЖЬ
	И "ФормироватьСПериодичностьДень" = ИСТИНА

Части описания:

Часть	Назначение
ВЫБРАТЬ … КАК <Имя>	Список полей, которые должны попасть в результат. Выражение слева от КАК — типизированное пустое значение (см. Поля).
ПОМЕСТИТЬ Представления_<Имя>[_<ИсточникДанных>][_<Уточнение>]	Имя представления и, при необходимости, имя регистра-источника и постфикс (см. Источник данных и уточнение). Результат помещается во временную таблицу с этим именем, и дальше в пакете к ней обращаются как к обычной временной таблице. В исполняемом тексте подчёркивание после Представления исчезает (ПредставленияКадровыеДанныеСотрудников) — механизм переименовывает и саму таблицу, и обращения к ней.
ИЗ <ТаблицаФильтра> КАК <ТаблицаФильтра>	Необязательная таблица фильтра — временная таблица того же пакета, ограничивающая выборку (см. Таблица фильтра).
ГДЕ "<Параметр>" = <Значение> И …	Параметры представления и отборы. Имя параметра записывается строковым литералом в кавычках (см. Параметры и Отборы).

Для запроса, который никогда не выполняется «как есть», такая запись выглядит непривычно, но она синтаксически корректна: конструктор запроса и схема компоновки данных её принимают, а типовой механизм подменяет её реальным текстом до выполнения.

Поля

В секции ВЫБРАТЬ перечисляются поля представления, которые нужны в результате. Слева от КАК пишется не реальное выражение, а пустое значение нужного типа:

Тип поля	Выражение
Ссылка	ЗНАЧЕНИЕ(Справочник.Сотрудники.ПустаяСсылка)
Дата	ДАТАВРЕМЯ(1, 1, 1)
Число	0 или ВЫРАЗИТЬ(0 КАК ЧИСЛО(15, 2))
Строка	"" или ВЫРАЗИТЬ("" КАК СТРОКА(150))
Булево	ЛОЖЬ
Прочее	НЕОПРЕДЕЛЕНО

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

Обработка знает состав полей каждого представления и подставляет выражения сама — вручную их писать не требуется. Имя поля после КАК должно совпадать с именем поля представления; для представлений на основе регистров (см. Источник данных) состав полей определяется измерениями, ресурсами и реквизитами выбранного регистра.

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

Параметры

Параметры представления перечисляются в секции ГДЕ в виде условий "<ИмяПараметра>" = <Значение>, соединённых через И. Значение может быть:

• литералом — строкой в кавычках ("МЕСЯЦ"), числом (10), булевым (ИСТИНА / ЛОЖЬ), датой (ДАТАВРЕМЯ(2025, 1, 1, 0, 0, 0));
• выражением языка запросов — чаще всего параметром запроса &НачалоПериода или функцией вида НАЧАЛОПЕРИОДА(&ДатаНачала, МЕСЯЦ). Значения параметров запроса устанавливаются обычным образом в объекте Запрос или в настройках СКД.

В обработке для каждого параметра есть признак «Значение — выражение» (колонка В): без него любое строковое значение будет заключено в кавычки, с ним — подставлено как есть. Механизм представлений не различает строковые и, например, числовые параметры, поэтому признак нужен, чтобы получить синтаксически и логически верный текст.

У большинства представлений есть общие параметры:

• ТолькоРазрешенные — получать данные с учётом ограничений доступа на уровне записей. Построители формируют реальные запросы с ВЫБРАТЬ РАЗРЕШЕННЫЕ, и только если параметр не равен строго ИСТИНА, слово РАЗРЕШЕННЫЕ из текста убирается. По умолчанию ЛОЖЬ.
• Параметры периода — у каждого представления свои: НачалоПериода/ОкончаниеПериода (сотрудники организации, отработанное время), НачалоИнтервала/ОкончаниеИнтервала (периоды), ДатаНачала/ДатаОкончания (учёт времени), ДатаАктуальности (штатное расписание), Дата (кадровая расстановка). Обязательные параметры в обработке по умолчанию заполнены одноимёнными параметрами запроса (&НачалоПериода и т. д.).
• Параметры с префиксом ПараметрыПостроения_ — передаются в структуру параметров построения типовой функции. Это фиксированный набор имён, а не произвольные свойства структуры: ПараметрыПостроения_ФормироватьСПериодичностьДень (плановые начисления сотрудников, представления на основе регистров) и ПараметрыПостроения_ВключатьЗаписиНаНачалоПериода (только ТаблицаРегистра).
• ПсевдонимыПолейСКД — строка вида "Поле1 КАК Псевдоним1, Поле2 КАК Псевдоним2", переименование полей результата. Читается только представлениями на основе регистров (СрезПоследних, СрезПервых, ТаблицаРегистра); для остальных игнорируется.

Обязательные параметры в обработке отмечены жирным шрифтом и включены в запрос по умолчанию. Необязательные параметры, не включённые в запрос, получают значения по умолчанию внутри построителя (например, у Периоды это Периодичность = МЕСЯЦ и ИспользоватьКонецПериода = Ложь). Параметры, которых построитель не знает, молча игнорируются.

Отборы

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

ГДЕ
	"ЛевоеЗначение1" = "Подразделение"
	И "ВидСравнения1" = "="
	И "ПравоеЗначение1" = &Подразделение
	И "ЛевоеЗначение2" = "ВидЗанятости"
	И "ВидСравнения2" = "<>"
	И "ПравоеЗначение2" = ЗНАЧЕНИЕ(Перечисление.ВидыЗанятости.ВнутреннееСовместительство)

• ЛевоеЗначениеN — имя поля представления;
• ВидСравненияN — условие языка запросов. Механизм не проверяет его по списку — подставляется любое условие, применимое в тексте запроса; обработка предлагает =, <>, >, >=, <, <=, В, В ИЕРАРХИИ;
• ПравоеЗначениеN — значение или выражение. Значение вида ВЫЧИСЛИТЬ(…) вычисляется построителем в безопасном режиме, остальные подставляются как есть.

Номер N нужен, чтобы различать тройки: типовой разбор собирает параметры по префиксам ЛевоеЗначение/ВидСравнения/ПравоеЗначение, и без разных суффиксов несколько отборов перезаписали бы друг друга. Порядок отборов значения не имеет. В обработке отбор добавляется как обычная строка таблицы параметров с признаком О (отбор): имя поля выбирается из списка доступных полей представления, вид сравнения — из списка, значение — литерал или выражение. Тройки параметров и их нумерацию обработка формирует сама.

Отборы учитывают ровно пять представлений — те, чьи построители вызывают КоллекцияОтборПоПараметрам: КадровыеДанныеСотрудников, КадровыеДанныеФизическихЛиц, СрезПоследних, СрезПервых, ТаблицаРегистра. У остальных признак отбора в обработке недоступен.

Таблица фильтра

Многие представления получают данные не по всей базе, а по списку объектов и периодов, который передаётся временной таблицей. Её имя указывается в секции ИЗ:

ИЗ
	ВТФильтр КАК ВТФильтр

Таблица фильтра должна быть создана раньше в том же пакете запросов (или в менеджере временных таблиц). Механизм берёт первую таблицу из секции ИЗ и отбирает по ней записи, а по её полям периода определяет даты, на которые нужны данные. Требования к составу полей зависят от представления:

• Кадровые данные (КадровыеДанныеСотрудников, КадровыеДанныеФизическихЛиц, СотрудникиОрганизации и др.): поле сотрудника (Сотрудник или ФизическоеЛицо) и Период.
• Представления на основе регистров (СрезПоследних, СрезПервых, ТаблицаРегистра): поля периода — Период либо ДатаНачала и ДатаОкончания (для ТаблицаРегистра — ДатаНачала/ДатаОкончания); все остальные колонки считаются измерениями и должны называться так же, как измерения регистра, — по ним накладывается отбор.

Если нужных полей в таблице нет, внятной ошибки не будет: отбор по отсутствующему измерению просто не сформируется или соединение окажется неверным, и результат будет неполным. Состав таблицы фильтра стоит проверять на закладке «Исполняемый запрос».

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

Источник данных и уточнение

Три базовых представления — СрезПоследних, СрезПервых и ТаблицаРегистра — универсальны: они получают данные любого периодического регистра сведений, имя которого указывается в имени временной таблицы через подчёркивание:

ПОМЕСТИТЬ Представления_СрезПоследних_ГрафикРаботыСотрудников

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

Уточнение — произвольный постфикс после имени представления и источника данных:

ПОМЕСТИТЬ Представления_КадровыеДанныеСотрудников_НаНачалоПериода
ПОМЕСТИТЬ Представления_КадровыеДанныеСотрудников_НаКонецПериода

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

Как применить представление

Представление можно вставить в любой текст запроса — объекта Запрос или набора данных схемы компоновки данных.

Произвольный запрос. Перед выполнением текст нужно передать в ЗарплатаКадрыОбщиеНаборыДанных.ЗаменитьЗапросыКПредставлениямВиртуальныхТаблиц. Первый параметр — текст пакета, он изменяется на месте (передаётся по ссылке); второй — приёмник параметров запроса, которые создают построители: объект Запрос, динамический список или схема компоновки данных. Условия:

• у запроса должен быть МенеджерВременныхТаблиц — представление помещается во временную таблицу;
• описание представления должно стоять в пакете раньше запросов, которые обращаются к Представления_…;
• таблица фильтра, если она используется, — раньше описания представления.

Запрос = Новый Запрос;
Запрос.МенеджерВременныхТаблиц = Новый МенеджерВременныхТаблиц;
Запрос.Текст =
	"ВЫБРАТЬ РАЗРЕШЕННЫЕ
	|	ДАТАВРЕМЯ(2025, 1, 1) КАК Период,
	|	Сотрудники.Ссылка КАК Сотрудник
	|ПОМЕСТИТЬ ВТФильтр
	|ИЗ
	|	Справочник.Сотрудники КАК Сотрудники
	|;
	|
	|////////////////////////////////////////////////////////////////////////////////
	|ВЫБРАТЬ
	|	ДАТАВРЕМЯ(1, 1, 1) КАК Период,
	|	ЗНАЧЕНИЕ(Справочник.Сотрудники.ПустаяСсылка) КАК Сотрудник,
	|	"""" КАК ИОФамилия,
	|	0 КАК ОбщийСтажЛет
	|ПОМЕСТИТЬ Представления_КадровыеДанныеСотрудников
	|ИЗ
	|	ВТФильтр КАК ВТФильтр
	|ГДЕ
	|	""ТолькоРазрешенные"" = ИСТИНА";

ЗарплатаКадрыОбщиеНаборыДанных.ЗаменитьЗапросыКПредставлениямВиртуальныхТаблиц(Запрос.Текст, Запрос);
Запрос.Выполнить();

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

Возможности обработки

• Каталог представлений базы. Список всех представлений, доступных в текущей конфигурации, с учётом подключённых подсистем и функциональных опций; для каждого — поля, параметры, текстовые описания.
• Формирование текста представления. Отметка нужных полей и параметров, отборы, фильтр, источник данных, уточнение — и готовый текст запроса.
• Исполняемый запрос. Просмотр текста, в который представление превращается после замены типовым механизмом, — удобно для отладки и изучения того, что именно делает представление.
• Код программного интерфейса. Для части представлений — фрагмент кода на встроенном языке, получающий те же данные через типовые экспортные функции (КадровыйУчет.СоздатьВТКадровыеДанныеСотрудников, ЗарплатаКадрыОбщиеНаборыДанных.СоздатьВТИмяРегистраСрезПоследних и др.).
• Преобразование для вставки в код. Текст запроса в виде строкового литерала ("…" | …) и обратно.
• Импорт из текста запроса. Разбор существующего представления: поля, параметры, отборы, фильтр подставляются в форму для изменения.
• Интеграция с внешними инструментами. Форму можно открыть из другой обработки с параметрами: получить текст представления в результате закрытия или отредактировать переданный текст.
• Кэш описаний. Сбор описаний по конфигурации выполняется один раз и сохраняется в хранилище настроек пользователя.
• Пакетный режим. Запуск из командной строки с выгрузкой всех описаний в JSON.

Требования и установка

• Конфигурация на базе подсистемы «Зарплата и кадры» с общим модулем ЗарплатаКадрыОбщиеНаборыДанных: 1С:ЗУП 3.1 (базовая, ПРОФ, КОРП), ЗКГУ 3.1 и производные. Механизм представлений есть во всех редакциях; отдельные представления (кадровый резерв госслужащих, бюджетные учреждения, медосмотры, подбор персонала) доступны только при наличии соответствующих подсистем — как правило, в КОРП. Работа проверена на ЗУП 3.1.30.116 и 3.1.38.92; более ранние версии не проверялись, минимальной считается 3.1.30.116.
• Библиотека стандартных подсистем (используются ОбщегоНазначения, ОбщегоНазначенияКлиентСервер, СтандартныеПодсистемыСервер).
• Платформа 1С:Предприятие 8.3 той версии, которую требует конфигурация; проект EDT собран для версии 8.3.27.
• Права на использование внешних обработок.

Установка: скачать файл .epf со страницы релизов репозитория (или собрать из исходников в EDT) и открыть в режиме «1С:Предприятие» через «Файл → Открыть». При необходимости обработку можно подключить как дополнительную через подсистему «Дополнительные отчёты и обработки» БСП.

Быстрый старт

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

Форма «Конструктор представлений»

Главная форма обработки. Подробное описание элементов — в справке формы (клавиша F1 в форме), исходный текст — docs/КонструкторПредставлений.md.

Слева — список Представления с именами представлений. По умолчанию в нём только основные (часто используемые) представления; кнопка Показывать все над списком выводит все доступные в базе. Справа — две страницы для выбранного представления:

• Поля — таблица доступных полей: флажок И (включить в запрос), имя, выражение пустого значения. Кнопки командной панели: установить/снять все флажки, «Только используемые».
• Параметры — поле «Источник данных» (только для представлений на основе регистров), поле «Фильтр» (только для представлений с фильтром), таблица параметров с колонками И (включить), О (отбор), «Имя», «Вид сравнения», В (значение — выражение), «Значение», а также поле «Уточнение».

Командная панель формы:

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

Форма «Текст запроса»

Открывается командой «Показать запрос». Три закладки, подробнее — в справке формы (F1), исходный текст — docs/ТекстЗапроса.md:

• Представление — текст представления в том виде, в котором его нужно вставить в запрос. Текст можно править прямо в форме.
• Исполняемый запрос — результат замены представления типовым механизмом: реальный текст запроса к регистрам и справочникам. Формируется при переходе на закладку по текущему тексту представления; если текст содержит ошибку, вместо запроса выводится описание ошибки.
• Код программного интерфейса — фрагмент кода на встроенном языке, получающий те же данные через типовые функции (см. следующий раздел). Закладка недоступна, если для представления код не предусмотрен.

На каждой закладке есть кнопка Скопировать в буфер обмена; на первых двух — Текст запроса для вставки в код, которая превращает текст в строковый литерал встроенного языка (кавычки удваиваются, строки начинаются с |) и обратно.

Код программного интерфейса

Для ряда представлений типовая конфигурация предоставляет экспортные функции, которые создают ту же временную таблицу напрямую, без текста представления: ЗарплатаКадрыОбщиеНаборыДанных.СоздатьВТПериоды, …СоздатьВТИмяРегистраСрезПоследних, КадровыйУчет.СоздатьВТКадровыеДанныеСотрудников, КадровыйУчет.СоздатьВТСотрудникиОрганизации, УправлениеШтатнымРасписанием.СоздатьВТШтатноеРасписание и другие. Такой способ удобен, когда данные получаются в коде, а не в СКД.

Обработка хранит для этих представлений шаблон кода и подставляет в него выбранные поля, параметры, отборы, фильтр и источник данных:

• выбранные поля передаются строкой "Поле1,Поле2" или, если полей много, массивом, объявление которого добавляется перед вызовом;
• отборы превращаются в вызовы ЗарплатаКадрыОбщиеНаборыДанных.ДобавитьВКоллекциюОтбор(ПараметрыПостроения.Отборы, "Поле", "=", Значение);
• псевдонимы полей СКД — в ПараметрыПостроения.СоответствиеПсевдонимовПолейСКД.Вставить("Поле", "Псевдоним");
• необязательные параметры, не включённые в запрос, из кода убираются: строка шаблона удаляется, а позиция аргумента в вызове сохраняется (Метод(Первый, , Третий)).

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

Представления с кодом программного интерфейса: Периоды, СрезПоследних, СрезПервых, ТаблицаРегистра, КадровыеДанныеСотрудников, КадровыеДанныеФизическихЛиц, РабочиеМестаСотрудников, СотрудникиОрганизации, СтажиСотрудников, ТекущаяКадроваяРасстановка, ФактическиеОтпускаСотрудников, ШтатноеРасписание.

Импорт представления из текста запроса

Команда Вставить из текста запроса принимает текст представления — как обычный текст запроса, так и скопированный из кода строковый литерал с кавычками и | — и разбирает его типовыми функциями подсистемы:

• имя представления, источник данных и уточнение — из имени временной таблицы после ПОМЕСТИТЬ;
• таблица фильтра — из секции ИЗ;
• поля — из секции ВЫБРАТЬ;
• параметры и отборы — из секции ГДЕ (тройки ЛевоеЗначениеN/ВидСравненияN/ПравоеЗначениеN собираются обратно в строки-отборы).

Если представление с таким именем есть в списке, оно дополняется: у существующих полей и параметров снимаются флажки, затем отмечаются и заполняются те, что найдены в тексте; поля и параметры, которых нет в описании, добавляются новыми строками. Если представления с таким именем нет (например, оно добавлено расширением), создаётся новая строка списка. Для значений параметров признак «выражение» выставляется по наличию & в значении.

Интеграция с внешними инструментами

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

• ТекстЗапроса — текст представления для изменения. При открытии он разбирается (см. Импорт), соответствующее представление становится текущим.
• При открытии с владельцем форма переходит в режим вставки: появляется кнопка по умолчанию Вставить, которая закрывает форму и возвращает владельцу текст представления как результат закрытия. Если при этом передан ТекстЗапроса, кнопка называется Изменить, а в заголовок формы добавляется имя представления.

Служебные параметры РежимВставки и РежимИзменения форма устанавливает сама.

Пример открытия из другого модуля (обработка предварительно подключена через ВнешниеОбработки.Подключить, ИмяОбработки — имя, возвращённое при подключении):

ПараметрыФормы = Новый Структура("ТекстЗапроса", ТекстПредставления);
ОписаниеОповещения = Новый ОписаниеОповещения("ПослеИзмененияПредставления", ЭтотОбъект);
ОткрытьФорму("ВнешняяОбработка." + ИмяОбработки + ".Форма.КонструкторПредставлений",
	ПараметрыФормы, ЭтотОбъект, , , , ОписаниеОповещения);

В обработчике ПослеИзмененияПредставления первым параметром придёт текст представления (или Неопределено, если форма закрыта без нажатия кнопки).

Ради совместимости с такими инструментами в клиентском коде формы не используются асинхронные конструкции (Асинх/Ждать), а копирование выполняется через устаревший вариант ОбщегоНазначенияКлиентСервер.СкопироватьРекурсивно.

Кэш описаний представлений

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

При следующем открытии описания берутся из кэша, если обе версии совпадают с текущими. Изменение версии конфигурации (обновление) или версии обработки (поле «Комментарий» в свойствах внешней обработки) делает кэш недействительным, и описания собираются заново.

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

Команда Сбросить текущие настройки кэш не трогает: она заново заполняет форму из кэша, отменяя все сделанные в сеансе отметки и значения.

Пакетный режим: выгрузка описаний в JSON

Обработку можно запустить из командной строки и получить описания всех представлений в виде JSON-файлов, не открывая форму:

1cv8 ENTERPRISE /F"C:\bases\zup" /N"Администратор" /Execute"C:\tools\КонструкторПредставленийЗарплатаКадры.epf" /C"mode=batch;out=C:\temp\Представления"

Параметр запуска /C разбирается как строка ключ=значение;…:

• mode=batch — включает пакетный режим;
• out=<каталог> — каталог выгрузки; создаётся, если не существует.

В пакетном режиме форма не открывается: обработка собирает описания по конфигурации (кэш не используется), записывает файлы и завершает работу. На каждое представление создаётся файл <Подсистема>/<Имя>.json (пробелы в имени подсистемы заменяются на _, общие представления попадают в каталог Общие). Файлы в кодировке UTF-8 без BOM, переводы строк LF, отступ 2 пробела.

Структура файла:

{
  "Подсистема": "КадровыйУчет",
  "Имя": "КадровыеДанныеСотрудников",
  "ЕстьИсточникДанных": false,
  "ЕстьФильтр": true,
  "Фильтр": "",
  "ФильтрОбязателен": true,
  "ДоступныОтборы": true,
  "Основное": true,
  "Описание": "Текстовое описание представления",
  "ЕстьПрограммныйИнтерфейс": true,
  "Шаблон": "Шаблон кода программного интерфейса с плейсхолдерами <Имя>",
  "ДоступныеПараметры": [
    {
      "Имя": "ТолькоРазрешенные",
      "Тип": ["Булево", "Строка"],
      "Значение": false,
      "Обязательный": false,
      "Описание": "",
      "ДоступныеЗначения": [],
      "ЗначениеЭтоВыражение": false
    }
  ],
  "ДоступныеПоля": [
    {
      "Имя": "Сотрудник",
      "Выражение": "ЗНАЧЕНИЕ(Справочник.Сотрудники.ПустаяСсылка)",
      "Описание": "Текстовое описание поля"
    }
  ]
}

Поле	Тип	Описание
Подсистема	строка	Имя подсистемы, к которой отнесено представление; Общие для базовых.
Имя	строка	Имя представления (часть имени временной таблицы после Представления_).
ЕстьИсточникДанных	булево	Представление требует указания регистра-источника.
ЕстьФильтр, ФильтрОбязателен, Фильтр	булево, булево, строка	Возможность, обязательность и имя по умолчанию таблицы фильтра.
ДоступныОтборы	булево	Поддержка отборов по полям.
Основное	булево	Основное (часто используемое) представление; в форме конструктора по умолчанию выводятся только основные.
Описание	строка	Текстовое описание представления.
ЕстьПрограммныйИнтерфейс, Шаблон	булево, строка	Наличие и шаблон кода программного интерфейса; параметры шаблона не выгружаются.
ДоступныеПараметры[]	массив	Параметры: имя, список имён типов, значение по умолчанию (null, если не задано), обязательность, описание, список доступных значений (Значение/Представление), признак «значение — выражение».
ДоступныеПоля[]	массив	Поля: имя, выражение пустого значения, описание.

Как обработка формирует описания

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

1. Проверяет наличие подсистемы (ОбщегоНазначения.ПодсистемаСуществует) и функциональной опции.
2. Создаёт описание представления (НовоеОписаниеПредставления) и добавляет параметры с типами, значениями по умолчанию и признаками обязательности.
3. Определяет состав полей одним из способов:
   • через типовой механизм замены: формирует запрос-заглушку ВЫБРАТЬ … ПОМЕСТИТЬ Представления_<Имя> …, передаёт его в ЗаменитьЗапросыКПредставлениямВиртуальныхТаблиц и разбирает полученный реальный запрос объектом СхемаЗапроса — колонки последнего запроса выбора и есть доступные поля, а по их типам вычисляются выражения пустых значений;
   • через типовые функции описания полей, если состав полей не определяется запросом (кадровые данные: КадровыйУчет.ПоляПредставленийКадровыхДанныхСотрудников, …ФизическихЛиц);
   • через типовые функции построения запросов (КадровыйУчет.ЗапросВТРабочиеМестаСотрудниковПоВременнойТаблице, УправлениеШтатнымРасписанием.ЗапросВТШтатноеРасписание, ЗарплатаКадрыОбщиеНаборыДанных.ЗапросВТПредставленияОтработанноеВремя).
   • для представлений на основе регистров поля определяются в момент выбора регистра по запросам ЗапросВТИмяРегистра / ЗапросВТИмяРегистраСрез.
4. Для представлений с программным интерфейсом задаёт шаблон кода и связи его плейсхолдеров с параметрами.
5. Заполняет текстовые описания представления и полей из макетов обработки ТекстовоеОписание<Имя> (формат — JSON с ключами ОписаниеПредставления и Поля).

Если типовой механизм не заменил запрос-заглушку (представление недоступно по функциональным опциям или отсутствует в версии конфигурации), список полей остаётся пустым.

Программный интерфейс модуля объекта

Экспортные функции модуля объекта можно использовать из другого кода, получив объект обработки (ВнешниеОбработки.Создать(...) или РеквизитФормыВЗначение("Объект")):

Функция	Назначение
ОписанияПредставленийПоКонфигурации()	Соответствие «имя представления → описание» по текущей базе.
НовоеОписаниеПредставления()	Пустая структура описания представления (документирована в модуле).
СформироватьТекстЗапросаПредставления(Свойства, Поля, Параметры)	Текст представления по свойствам, коллекции полей и параметров.
РазобратьТекстЗапросаПредставления(ТекстЗапроса)	Разбор текста представления на имя, источник, уточнение, фильтр, поля, параметры, отборы.
ТекстЗапросаИзСтрокКода(ТекстЗапроса)	Преобразование строкового литерала кода в текст запроса.
КодПрограммногоИнтерфейса(Шаблон, Параметры)	Подстановка значений параметров в шаблон кода.
ВидыПараметровПрограммногоИнтерфейса()	Идентификаторы видов параметров шаблона.
ДоступныеВидыСравненияОтбора()	Соответствие видов сравнения СКД и их записи в тексте запроса.
ЗначениеПараметраВВыражениеЯзыкаЗапроса(Значение)	Литерал языка запросов для значения (дата, число, булево, строка, вид сравнения).
ПоляЗапросаВДоступныеПоляПредставления(ТекстЗапроса, Описание, ИмяВТ, КонтрольУникальности)	Заполнение доступных полей описания по тексту запроса.
ВыгрузитьПредставленияВJSON(ОписанияПредставлений, КаталогВыгрузки)	Выгрузка описаний в JSON-файлы.
МодульОбщегоНазначения(), МодульОбщегоНазначенияКлиентСервер()	Доступ к модулям БСП без прямой ссылки из формы.

Ограничения и особенности

• Список представлений собран вручную в модуле объекта по типовой конфигурации; представления, добавленные расширениями, появившиеся в новых версиях ЗУП или ещё не описанные в обработке, в списке не отображаются, но их можно импортировать из текста запроса — они появятся в списке без описаний полей.
• Механизм не сообщает об ошибках в описании представления: неизвестное представление остаётся в тексте с пустыми значениями полей, неизвестные параметры игнорируются, неполная таблица фильтра даёт неполный результат. Проверяйте исполняемый запрос.
• Обработка не проверяет совместимость выбранных полей и параметров с логикой представления — это делает типовой механизм при замене; ошибки видны на закладке «Исполняемый запрос».
• Текст представления должен содержать хотя бы одно поле, иначе запрос синтаксически некорректен.
• Код программного интерфейса — заготовка: параметры вида &Параметр и плейсхолдеры, которые нельзя вычислить из формы, требуют ручной правки.
• Кэш описаний привязан к версиям конфигурации и обработки и не отслеживает функциональные опции (см. Кэш).
• Пакетный режим требует запуска в режиме «1С:Предприятие» с параметром /Execute и не поддерживает веб-клиент.

Репозиторий

SharedQueryDesignerHRM/
├── README.md                       # эта документация; источник справки обработки
├── docs/
│   ├── КонструкторПредставлений.md # справка формы «Конструктор представлений»
│   └── ТекстЗапроса.md             # справка формы «Текст запроса»
├── scripts/
│   └── build_help.py               # сборка Help/ru.html обработки и форм из Markdown
├── src/ExternalDataProcessors/КонструкторПредставленийЗарплатаКадры/
│   ├── ObjectModule.bsl            # описания представлений, формирование и разбор текста, генерация кода, JSON
│   ├── Forms/КонструкторПредставлений/
│   ├── Forms/ТекстЗапроса/
│   ├── Templates/ТекстовоеОписание*/  # текстовые описания представлений и полей (JSON)
│   └── Help/ru.html                # справка обработки (генерируется)
└── DT-INF/                         # проект 1C:EDT

Сборка справки

Справка объекта и форм генерируется из Markdown:

pip install -r requirements.txt
python scripts/build_help.py          # пересобрать Help/ru.html
python scripts/build_help.py --check  # проверить, что справка актуальна (для CI)

Скрипт преобразует README.md → Help/ru.html обработки, docs/КонструкторПредставлений.md и docs/ТекстЗапроса.md → Help/ru.html соответствующих форм, оборачивает результат в HTML-каркас справки 1С (стиль v8help://service_book/service_style), убирает блоки между HTML-комментариями help:skip-begin … help:skip-end (разделы, имеющие смысл только в репозитории), остальные HTML-комментарии и внешние изображения, а также регистрирует справку в файле .mdo, если она ещё не зарегистрирована.

Смотрите также

• QueryConsole1C — расширение конфигурации с полноценной консолью запросов для ЗУП, ЗГУ и ERP. Решает похожую задачу — получение данных подсистемы «Зарплата и кадры» без ручного вызова методов программного интерфейса, — но другим способом: добавляет в язык запросов собственный синтаксис (ИсполняемоеПредставление.Имя(...)), который распознаётся только внутри самого расширения (свой лексер, парсер и исполнитель), а не встроенным типовым механизмом Представления_..., который используют отчёты и печатные формы конфигурации «как есть».

Лицензия

MIT, © 2025 Ilya Fedorov.