При создании пользовательских инструкций, встроенных справок по подсистемам, интерактивных дашбордов и отчетов в среде 1С:Предприятие 8.3 разработчики часто используют готовые HTML-страницы. В конфигурации создается общий макет или макет объекта, куда помещается HTML-разметка с текстовым описанием и иллюстрациями, а на управляемой форме размещается элемент управления «Поле HTML-документа». Однако первая же попытка получить макет на сервере и напрямую отправить его на клиентскую сторону завершается аварийной остановкой работы интерфейса.
Платформа генерирует диагностическое сообщение следующего содержания:
Ошибка передачи данных между клиентом и сервером. Значение недопустимого типа.
по причине:
Ошибка преобразования данных XDTO:
Запись значения свойства 'ret':
форма: Элемент
по причине:
Ошибка отображения типов:
Отсутствует отображение для типа 'ОболочкаHTMLДокумента'
В дополнение к этой ошибке разработчики нередко сталкиваются со второй проблемой: даже после успешной передачи текста страницы в форму изображения в документе не отображаются и выводятся в виде пустых рамок («битых ссылок»). Ниже разобран механизм возникновения этих неполадок, диагностические шаги и надежные варианты решения.
В клиент-серверной архитектуре управляемого приложения 1С взаимодействие между клиентским приложением (тонким или веб-клиентом) и сервером осуществляется через контекстные и неконтекстные вызовы процедур и функций. Любые данные, передаваемые через границы этих уровней — будь то параметры процедур или возвращаемые значения функций — должны быть преобразованы во внутренний формат передачи данных (механизм сериализации XDTO).
Платформа умеет сериализовать примитивные типы (число, строка, дата, булево), ссылки, структуры, массивы, таблицы значений и некоторые специализированные прикладные объекты. Однако объекты, предназначенные для манипуляции документами в памяти сервера или клиента (например, ОболочкаHTMLДокумента, COMОбъект, внутренние интерфейсные указатели), не обладают типом отображения XDTO. Возврат подобного объекта из серверной функции в клиентскую процедуру невозможен: платформа не может преобразовать внутренний C++ указатель или DOM-оболочку в сетевой пакет и прерывает операцию ошибкой соответствия типов.
Если в процессе разработки возникла данная ошибка, рекомендуется выполнить следующие проверочные действия:
&НаСервере или &НаСервереБезКонтекста, из которой возвращается результат. Убедитесь, что оператор Возврат не возвращает сам объект макета или интерфейсный элемент формы.Строка (с неограниченной длиной) либо ФорматированныйДокумент.<img>. Если атрибут src содержит локальный дисковый путь сервера или относительный путь, на стороне клиента эта картинка не загрузится.Наиболее простое и быстрое решение проблемы передачи данных — извлечь строковое представление HTML-документа непосредственно в серверном контексте и работать исключительно со строкой. Строковый тип данных безупречно сериализуется платформой.
Существует два варианта реализации этого подхода в зависимости от структуры модуля формы.
Вариант А: Контекстная серверная процедура
Если макет принадлежит объекту текущей обработки или отчета, доступ к нему получают через преобразование реквизита формы в прикладной объект, считывают текст и сразу записывают его в строковый реквизит формы:
&НаСервере
Процедура ЗагрузитьСправкуНаСервере()
ОбработкаОбъект = РеквизитФормыВЗначение("Объект");
Макет = ОбработкаОбъект.ПолучитьМакет("СправкаПоЭДО");
// Получаем сырой текст HTML и помещаем в реквизит формы типа Строка
Объект.ДляСправки = Макет.ПолучитьТекст();
КонецПроцедуры
&НаКлиенте
Процедура ПриОткрытии(Отказ)
ЗагрузитьСправкуНаСервере();
КонецПроцедуры
Вариант Б: Неконтекстная функция и прямое управление элементом
Если макет является общим или не требует обращения к полному контексту формы, оптимально использовать неконтекстный вызов. Это снижает нагрузку на сеть, так как на сервер не передается состояние всех элементов формы:
&НаСервереБезКонтекста
Функция ПолучитьТекстHTMLМакета()
Макет = ПолучитьОбщийМакет("ОбщаяИнструкцияHTML");
Возврат Макет.ПолучитьТекст();
КонецФункции
&НаКлиенте
Процедура ПоказатьИнструкцию(Команда)
ТекстHTML = ПолучитьТекстHTMLМакета();
// Установка текста напрямую в элемент управления формы
Элементы.ПолеHTMLИнструкция.УстановитьТекст(ТекстHTML);
КонецПроцедуры
Метод УстановитьТекст() применяется к элементу формы на клиенте, когда реквизит формы не привязан к данным или когда требуется динамически изменить содержимое без модификации реквизитов объекта.
Когда в макете содержатся графические иллюстрации, схема с простой передачей текста решает проблему ошибки XDTO, но приводит к отсутствию картинок на форме. Элемент «Поле HTML-документа» представляет собой встроенный браузерный движок. Если в тексте макета указан тег вида <img src="image1.png"> или ссылка на локальный файл, браузер клиента пытается найти файл в своей локальной временной директории и не находит его.
Для корректного вывода изображений применяются три базовых механизма:
1. Встраивание изображений через Data URI (Base64)
Это самый универсальный и изолированный метод, рекомендованный стандартами разработки 1С. Картинка переводится в формат Base64-строки и подставляется прямо в атрибут src тега <img>:
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...">
Такой документ становится полностью автономным: ему не требуются внешние сетевые подключения, доступ к файловой системе клиента или сохранение промежуточных файлов на диск.
Ограничения: объем исходного HTML-документа увеличивается примерно на треть по сравнению с чистым весом картинок. Если общий объем графики превышает несколько десятков мегабайт, передача такой строки с сервера на клиент может замедлить отклик интерфейса.
2. Использование навигационных ссылок временного хранилища
Платформа 1С поддерживает внутренний протокол e1cib/tempstorage/ для встроенного браузера. Разработчик может поместить двоичные данные картинок во временное хранилище на сервере, получить уникальный адрес и подставить его в разметку страницы:
&НаСервере
Функция ПодготовитьHTMLСКартинкамиВХ(ТекстHTML, ДвоичныеДанныеКартинки)
АдресКартинки = ПоместитьВоВременноеХранилище(ДвоичныеДанныеКартинки, УникальныйИдентификатор);
// Заменяем имя файла в разметке на навигационную ссылку 1С
ТекстHTML = СтрЗаменить(ТекстHTML, "image1.png", АдресКартинки);
Возврат ТекстHTML;
КонецФункции
Ограничения: адрес временного хранилища действителен только в рамках текущего сеанса и привязан к жизненному циклу формы. При закрытии формы или истечении сеанса ссылки становятся недействительными.
3. Использование внешнего веб-сервера
Если справочные материалы регулярно обновляются, графика может размещаться на корпоративном веб-узле с указанием абсолютных путей, например https://example.com/assets/images/manual-banner.png. В этом случае HTML-страница остается легковесной.
Ограничения: требуется бесперебойный доступ к сети Интернет или корпоративной сети с рабочих мест пользователей. Метод неприменим в изолированных контурах безопасности.
Альтернативный путь визуализации HTML-макетов — использование специализированного типа данных платформы ФорматированныйДокумент. Этот объект умеет принимать на вход сырой HTML-текст и отдельно обрабатывать связанные графические ресурсы через структуру вложений.
Алгоритм настройки:
ФорматированныйДокумент.
&НаСервере
Процедура ЗагрузитьВФорматированныйДокумент()
ОбработкаОбъект = РеквизитФормыВЗначение("Объект");
Макет = ОбработкаОбъект.ПолучитьМакет("СправкаПоЭДО");
СтруктураВложений = Новый Структура;
// Если картинка получена в виде двоичных данных или объекта Картинка:
// СтруктураВложений.Вставить("pic1.png", ДвоичныеДанныеИзображения);
Объект.ПолеФорматированногоДокумента.УстановитьHTML(Макет.ПолучитьТекст(), СтруктураВложений);
КонецПроцедуры
Условия применения и ограничения: объект ФорматированныйДокумент ориентирован на базовую текстовую разметку (выделение шрифтов, простые таблицы, списки). Он поддерживает лишь ограниченное подмножество стандартов HTML и CSS. Сложная блочная верстка, flexbox, CSS-сетки, адаптивные стили и исполняемый JavaScript будут вырезаны либо отобразятся некорректно. Если требуется отобразить современную веб-страницу со сложным дизайном, следует использовать только «Поле HTML-документа» со строковым источником данных.
На практике многие разработчики сталкиваются с неочевидной особенностью платформы при создании самого макета в дереве метаданных. При выборе типа «HTML-документ» среда разработки 1С открывает встроенный WYSIWYG-редактор. Этот редактор обладает следующими особенностями:
<meta>, переопределять стили по умолчанию и оборачивать текст в собственные контейнеры.Макет.ПолучитьТекст() для макета типа «HTML-документ» возвращает форматированный текст так, что при помещении в строковый реквизит формы встроенный браузер отображает исходный код тегов (<html><body>...) вместо их визуальной отрисовки.Для надежного вывода рекомендуется создавать макет с типом «Текстовый документ» в кодировке UTF-8. В такой макет помещается исходный HTML-код страницы. Платформа не вмешивается в синтаксис текстового документа, сохраняя структуру тегов, встроенные скрипты и Base64-строки в первозданном виде.
В типовых конфигурациях на базе Библиотеки Стандартных Подсистем (БСП) реализован универсальный механизм подготовки HTML-документов к печати и отображению. Он заключается в программном поиске локальных файлов изображений, переводе их в Base64 и замене путей в разметке. Ниже приведена готовая функция, реализующая данный алгоритм:
&НаСервереБезКонтекста
Функция ВстроитьИзображенияВHTML(Знач ТекстHTML, КаталогКартинок)
НайденныеФайлы = НайтиФайлы(КаталогКартинок, "*.*");
Для Каждого ФайлКартинки Из НайденныеФайлы Цикл
Расширение = НРег(ФайлКартинки.Расширение);
// Определение корректного MIME-типа изображения
Если Расширение = ".png" Тогда
MIME = "image/png";
ИначеЕсли Расширение = ".jpg" Или Расширение = ".jpeg" Тогда
MIME = "image/jpeg";
ИначеЕсли Расширение = ".gif" Тогда
MIME = "image/gif";
ИначеЕсли Расширение = ".svg" Тогда
MIME = "image/svg+xml";
Иначе
Продолжить;
КонецЕсли;
// Чтение двоичных данных файла и конвертация в Base64
ДвоичныеДанные = Новый ДвоичныеДанные(ФайлКартинки.ПолноеИмя);
СтрокаКартинки = "data:" + MIME + ";base64," + Base64Строка(ДвоичныеДанные);
// Замена относительного пути на встроенный ресурс
ТекстHTML = СтрЗаменить(ТекстHTML, ФайлКартинки.Имя, СтрокаКартинки);
КонецЦикла;
Возврат ТекстHTML;
КонецФункции
Если макет хранится в конфигурации неделимым блоком, изображения можно предварительно упаковать в архив .zip в виде двоичного макета либо сохранить в один файл HTML уже с внедренными Base64-строками перед добавлением в конфигурацию.
Для гарантированно стабильной работы форм придерживайтесь следующих правил:
ФорматированныйДокумент, если пользователю требуется изменять текст прямо на форме и форматировать его стандартными средствами платформы.