Разработка и Конфигурация · 12 мин
Как открыть форму выбора документа в 1С
Как программно открыть форму выбора документа в 1С: ОткрытьФорму, параметры отбора, обработка выбора, отбор по организации и периоду. Примеры кода и FAQ.
Форма выбора документа в 1С нужна всякий раз, когда пользователь должен указать конкретный документ: заполнить реквизит «Основание», подобрать заказ в накладную, выбрать счёт для оплаты. В управляемом приложении для этого есть два пути — стандартный механизм поля ввода с типом «ДокументСсылка» и программный вызов формы выбора через метод ОткрытьФорму() или ПоказатьВыборИзСписка(). Первый вариант работает «из коробки», второй даёт полный контроль над отбором, периодом и обработкой результата.
Ключевой объект здесь — параметры формы. Через структуру параметров передаются отбор по организации, контрагенту, периоду, режим выбора, запрет изменения списка. Правильно настроенные параметры избавляют пользователя от поиска нужного документа в тысячах записей журнала и снижают риск ошибочного выбора чужого документа.
Типичная задача разработчика — открыть форму выбора с предустановленным отбором и получить результат в обработчик оповещения. Ниже разобраны оба сценария: для управляемых форм (тонкий клиент, веб-клиент) и кратко для обычных форм, а также частые ошибки, из-за которых форма открывается без отбора или выбор не возвращается в вызывающий код.
Стандартный выбор документа без программирования
Если реквизит формы имеет тип ДокументСсылка.ИмяДокумента, платформа сама обеспечивает выбор: кнопка выбора в поле ввода открывает стандартную форму выбора, работает ввод по строке (по номеру документа), история выбора. В типовых конфигурациях этого достаточно для большинства полей «Документ основание», «Заказ», «Счёт на оплату».
Стандартный механизм уже включает быстрый отбор по периоду и кнопки создания нового документа. Пользователь может открыть форму выбора, установить период «За текущий месяц» и найти нужный документ по номеру. Проблемы начинаются, когда нужен жёсткий отбор: например, показывать только проведённые документы конкретной организации, или когда документ выбирается не в поле ввода, а по кнопке «Подобрать».
В поле ввода есть свойство «Параметры выбора» и «Связи параметров выбора» — через них можно ограничить список без единой строки кода в модуле. Например, связать поле «Заказ» с полем «Контрагент», чтобы в форме выбора показывались только заказы выбранного контрагента. Это делается в конфигураторе, в палитре свойств элемента формы.
Программное открытие формы выбора через ОткрытьФорму
Базовый вызов выглядит так: ОткрытьФорму("Документ.РеализацияТоваровУслуг.ФормаВыбора", ПараметрыФормы, Элемент, , , , ОписаниеОповещения). Первый параметр — полное имя формы, далее структура параметров, владелец (обычно элемент формы или сама форма), ключ уникальности, окно, описание оповещения о закрытии, режим открытия окна.
&НаКлиенте
Процедура ПодобратьДокумент(Команда)
ПараметрыФормы = Новый Структура;
ПараметрыФормы.Вставить("РежимВыбора", Истина);
ПараметрыФормы.Вставить("МножественныйВыбор", Ложь);
Оповещение = Новый ОписаниеОповещения("ПослеВыбораДокумента", ЭтотОбъект);
ОткрытьФорму("Документ.РеализацияТоваровУслуг.ФормаВыбора",
ПараметрыФормы, ЭтотОбъект, , , , Оповещение,
РежимОткрытияОкнаФормы.БлокироватьОкноВладельца);
КонецПроцедуры
&НаКлиенте
Процедура ПослеВыбораДокумента(Результат, ДопПараметры) Экспорт
Если Результат <> Неопределено Тогда
Объект.ДокументОснование = Результат;
КонецЕсли;
КонецПроцедурыПараметр РежимВыбора = Истина переводит форму списка в режим выбора: появляется кнопка «Выбрать», двойной щелчок возвращает ссылку. Без этого параметра откроется обычный список документов, и закрытие формы не вернёт результат. Параметр МножественныйВыбор позволяет выбрать несколько документов — тогда в оповещение придёт массив ссылок, а не одна ссылка.
Режим открытия окна стоит указывать явно. БлокироватьОкноВладельца — стандарт для выбора: пользователь не сможет переключиться в родительскую форму, пока не завершит выбор или не закроет форму. Независимое окно для выбора почти никогда не нужно и приводит к ситуациям, когда открыто несколько форм выбора одновременно.
Передача отбора: организация, контрагент, период
Отбор передаётся через параметр «Отбор» — структуру, где ключ — имя поля списка, а значение — значение отбора или массив значений. Пример: показать только реализации выбранной организации и контрагента.
ПараметрыФормы = Новый Структура;
Отбор = Новый Структура;
Отбор.Вставить("Организация", Объект.Организация);
Отбор.Вставить("Контрагент", Объект.Контрагент);
Отбор.Вставить("Проведен", Истина);
ПараметрыФормы.Вставить("Отбор", Отбор);
ПараметрыФормы.Вставить("РежимВыбора", Истина);Есть важное ограничение: отбор по полю работает только если это поле доступно для отбора в динамическом списке формы выбора. В типовых формах выбора основная таблица — сама таблица документа, поэтому отбор по реквизитам шапки (Организация, Контрагент, Склад) работает. Отбор по табличной части (например, по номенклатуре в товарах) так не сделать — потребуется переопределение запроса динамического списка в модуле формы выбора или произвольная форма.
Отбор по периоду задаётся иначе: у динамического списка документов есть стандартный параметр периода. Проще всего передать отбор по дате через два элемента структуры отбора — «Дата» с видом сравнения «БольшеИлиРавно» и «МеньшеИлиРавно», но структура «Отбор» поддерживает только равенство. Для неравенств нужно либо настраивать отбор динамического списка программно в обработчике ПриСозданииНаСервере формы выбора (через расширение или доработку), либо передавать собственный параметр и обрабатывать его в модуле формы.
Отбор по ссылочному полю принимает массив: Отбор.Вставить("Склад", МассивСкладов) покажет документы по любому из складов. Это удобно, когда пользователь работает с несколькими складами одновременно.
Получение и проверка результата выбора
Результат выбора приходит в обработчик, указанный в ОписаниеОповещения. Если пользователь выбрал документ — в параметре обработчика будет ссылка (или массив ссылок при множественном выборе). Если закрыл форму крестиком или клавишей Esc — придёт Неопределено. Проверка на Неопределено обязательна, иначе реквизит затрётся пустым значением.
После получения ссылки имеет смысл проверить сам документ: проведён ли он, не помечен ли на удаление, той ли он организации. Форма выбора с отбором снижает риск, но не исключает его — например, документ мог быть открыт и изменён другим пользователем в момент выбора. Проверку выполняйте на сервере, если нужны данные реквизитов: на клиенте доступна только ссылка.
Как проверить результат
Ссылка на документ или массив ссылок
Неопределено — пользователь отменил выбор, не затирайте реквизит
Проведён, не помечен на удаление
Пометка удаления или отмена проведения — документ нельзя использовать как основание
Организация и контрагент совпадают с шапкой
Документ другой организации — проверьте, не потерян ли отбор при открытии
Выбор документа в обычных формах и толстом клиенте
В обычном приложении (конфигурации на 8.2 без управляемого интерфейса, а также некоторые старые решения) используется другой API: ПолучитьФорму("Документ.Имя.ФормаВыбора", Владелец) и метод ОткрытьМодально(). Результат возвращается как значение, возвращённое методом Закрыть(Результат) внутри формы выбора, либо через событие ОбработкаВыбора у владельца.
Модальное открытие в управляемом приложении запрещено настройками по умолчанию (режим использования модальности), поэтому код с ОткрытьМодально() в управляемых формах вызовет ошибку. Если вы сопровождаете старую конфигурацию и переводите её на управляемые формы — все места выбора документов нужно переписать на асинхронный шаблон с ОписаниеОповещения.
Сравнение подходов
Подходит для полей ввода с отбором по реквизитам шапки. Не требует кода, но не работает для кнопок и сложных условий.
Универсальный способ для управляемых форм: любые отборы, кнопки подбора, множественный выбор. Требует обработчика оповещения.
Когда нужен отбор по табличной части, поиск по остаткам или нестандартная компоновка. Максимум гибкости, но форму нужно создавать и сопровождать.
Типичные ошибки при открытии формы выбора
Самая частая ошибка — забыть параметр РежимВыбора = Истина. Форма открывается как обычный список, двойной щелчок открывает документ на редактирование вместо выбора, обработчик оповещения получает Неопределено. Второе место — передача отбора с именем поля, которого нет в динамическом списке: платформа молча игнорирует такой отбор или выдаёт ошибку «Поле не найдено» в зависимости от версии.
Третья группа ошибок связана с контекстом: вызов ОткрытьФорму в серверной процедуре (метод доступен только на клиенте и в толстом клиенте), использование модального вызова там, где он запрещён, отсутствие директивы Экспорт у обработчика оповещения. Ещё одна тонкость: если форма выбора переопределена в конфигурации (своя форма выбора у документа), откроется именно она — и она может не поддерживать стандартный параметр «Отбор», если разработчик её не реализовал.
Альтернативы: подбор, быстрый выбор и своя форма
Если нужно выбрать много документов с накоплением (например, подобрать несколько заказов в одну реализацию), лучше работает схема «подбор»: форма выбора открывается с МножественныйВыбор = Истина и ЗакрыватьПриВыборе = Ложь, каждый выбор приходит отдельным оповещением, форма остаётся открытой, пока пользователь не нажмёт «Перенести» или не закроет её.
Для выбора из короткого фиксированного списка (например, непроведённые документы текущего дня) иногда проще не открывать форму выбора, а сформировать список значений запросом и вызвать ПоказатьВыборИзСписка() — это лёгкое выпадающее меню вместо полноценной формы. А когда требования выходят за рамки стандарта (отбор по остаткам, по табличной части, поиск по штрихкоду документа), создают собственную форму выбора с произвольным запросом динамического списка и назначают её в свойствах объекта метаданных.
Что важно запомнить
Форму выбора документа открывают через ОткрытьФорму с параметром РежимВыбора, отбор передают структурой «Отбор», результат получают в обработчике ОписаниеОповещения с обязательной проверкой на Неопределено. Простые случаи решаются параметрами выбора поля ввода без кода, сложные — собственной формой выбора через расширение.
Частые вопросы
Как открыть форму выбора документа только с проведёнными документами?
Передайте в параметрах формы структуру отбора: Отбор.Вставить("Проведен", Истина). Поле «Проведен» доступно для отбора в стандартном динамическом списке документов. Если форма выбора переопределена в конфигурации, убедитесь, что в её динамическом списке это поле не отключено от отбора.
Почему отбор через параметр «Отбор» не срабатывает?
Чаще всего поле с таким именем отсутствует в основной таблице динамического списка формы выбора или запрещено для отбора в настройках списка. Проверьте точное имя реквизита (с учётом регистра), откройте настройку динамического списка формы в конфигураторе и убедитесь, что поле доступно. Также проверьте, не используется ли в конфигурации собственная форма выбора, игнорирующая стандартный параметр.
Как получить несколько выбранных документов?
Передайте параметр МножественныйВыбор = Истина. В обработчик оповещения тогда придёт массив ссылок, а не одна ссылка. Если нужно, чтобы форма не закрывалась после каждого выбора (режим подбора), добавьте параметр ЗакрыватьПриВыборе = Ложь и обрабатывайте каждое оповещение как добавление строки в табличную часть.
Можно ли открыть форму выбора из серверной процедуры?
Нет. ОткрытьФорму — клиентский метод, он доступен только в контексте клиента (директивы &НаКлиенте). Правильный шаблон: клиентская процедура открывает форму, получает ссылку в оповещении, а затем при необходимости вызывает серверную процедуру для чтения реквизитов выбранного документа или заполнения объекта.
Как ограничить список документов текущим месяцем?
Стандартный параметр «Отбор» поддерживает только равенство, поэтому диапазон дат через него не задать. Варианты: передать отбор по полю «Дата» с конкретным днём, если достаточно одного дня; настроить отбор динамического списка программно в расширении формы выбора; либо пользователь сам установит период кнопкой «Установить период» в открытой форме — в типовых формах она доступна.
Чем выбор документа отличается от ввода по строке?
Ввод по строке работает прямо в поле ввода: пользователь набирает номер, платформа ищет подходящие документы и показывает выпадающий список без открытия формы. Это быстрее, когда номер известен. Форма выбора нужна, когда документ ищут по отборам, периоду или содержимому. Оба механизма дополняют друг друга и работают одновременно для одного поля.