СтрШаблон в 1С: что это такое и как работает подстановка в строки

СтрШаблон — это встроенная функция языка 1С:Предприятие, которая формирует строку по шаблону, подставляя вместо специальных маркеров переданные значения. Вместо длинной склейки строк оператором «+» разработчик пишет один шаблон вида «Товар %1, количество %2» и перечисляет значения параметрами — код становится короче, читаемее и безопаснее для локализации.

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

Ниже разобраны синтаксис функции, практические примеры, типичные ошибки при работе с маркерами и ситуации, когда СтрШаблон лучше заменить другими средствами платформы.

Что такое СтрШаблон и зачем она нужна

Во встроенном языке 1С строки традиционно соединялись оператором «+»: "Товар " + Наименование + " отсутствует на складе " + Склад. При трёх-четырёх подстановках такая конструкция превращается в трудночитаемую цепочку, где легко потерять пробел или кавычку. СтрШаблон решает эту задачу: текст пишется целиком, а переменные места помечаются маркерами.

Маркер выглядит как знак процента с номером: %1, %2, %3 и так далее до %10. Номер соответствует порядковому номеру параметра, переданного после шаблона. При выполнении функция заменяет каждый маркер строковым представлением соответствующего значения.

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

Синтаксис и параметры функции

Формат вызова: СтрШаблон(Шаблон, Значение1, Значение2, ..., Значение10). Первый параметр — строка-шаблон с маркерами, остальные — значения для подстановки. Все значения автоматически приводятся к строковому типу так же, как при обычном преобразовании функцией Строка().

Пример базового вызова:

ТекстСообщения = СтрШаблон("В документе %1 указано %2 позиций на сумму %3 руб.",
НомерДокумента,
КоличествоСтрок,
СуммаДокумента);

Если в шаблоне нужен сам символ процента, его удваивают: «%%» выведет один знак «%». Это важно, например, при формировании строк с процентными ставками или скидками.

Ограничение — максимум десять параметров подстановки. На практике этого достаточно для сообщений и надписей; если значений больше, строку собирают частями или используют другие механизмы, например форматированный документ или текстовый макет.

Как использовать СтрШаблон в типовых сценариях

Сообщения пользователю и предупреждения

Самый частый сценарий — информативные сообщения об ошибках проведения или заполнения. Вместо набора склеек пишется один понятный текст:

Сообщить(СтрШаблон("Недостаточно товара ""%1"": требуется %2, доступно %3.",
Товар,
ТребуемоеКоличество,
Остаток));

Формирование текстов запросов

СтрШаблон удобен, когда текст запроса собирается динамически, например имя таблицы или поле выбирается по условию:

ТекстЗапроса = СтрШаблон("ВЫБРАТЬ Ссылка ИЗ Справочник.%1 ГДЕ %2 = &Значение",
ИмяСправочника,
ИмяПоля);

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

Записи в журнал регистрации и служебные строки

При записи событий, формировании наименований и комментариев шаблон делает код единообразным:

ЗаписьЖурналаРегистрации("Обмен данными",
УровеньЖурналаРегистрации.Ошибка, , ,
СтрШаблон("Не удалось выгрузить узел %1: %2", Узел, ОписаниеОшибки()));

1. 1
   Сформулируйте итоговый текст сообщения целиком, как его должен увидеть пользователь.
2. 2
   Замените переменные фрагменты маркерами %1, %2 и так далее по порядку.
3. 3
   Передайте значения параметрами функции в том же порядке, что и номера маркеров.
4. 4
   Если в тексте нужен знак %, запишите его как %%.
5. 5
   Запустите код и проверьте, что все маркеры заменены и текст читается корректно.

Типичные ошибки при работе со СтрШаблон

Чаще всего встречается несовпадение номеров маркеров и параметров: в шаблоне есть %3, а передано только два значения. В этом случае маркер останется в строке как есть — пользователь увидит «%3» в сообщении, что выглядит как дефект программы. Обратная ситуация (лишние параметры) не вызывает ошибки, но сигнализирует о том, что шаблон недописан.

Вторая группа ошибок — форматирование чисел и дат. СтрШаблон приводит значения к строке стандартным образом, поэтому число 1234.5 может вывестись с нежелательным разделителем, а дата — в формате по умолчанию. Для контроля вида значения предварительно обрабатывают функцией Формат() и передают уже готовую строку.

Третья ошибка — попытка использовать СтрШаблон там, где нужна локализация через НСтр, но шаблон собирается из кусочков конкатенацией. Тогда перевести такое сообщение корректно невозможно: в другом языке порядок слов иной. Шаблон должен быть единой строкой.

Как проверить результат и отладить шаблон

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

При отладке сложных шаблонов удобно временно вывести шаблон и значения параметров по отдельности. Это позволяет быстро увидеть, какое именно значение пришло пустым или в неожиданном виде — например, пустая ссылка выведется как строка вида «00000000-0000-0000-0000-000000000000» или пустое представление, что сразу бросается в глаза.

Контрольные точки

Как проверить результат

Итоговая строка сообщения

Норма

Все маркеры заменены осмысленными значениями, текст читается естественно

Тревожный признак

В тексте видны %1, %2 или пустые места между словами

Числа и даты

Норма

Разделители и формат соответствуют ожиданиям пользователя

Тревожный признак

Число выведено с лишними знаками, дата — в техническом виде

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

Норма

Запрос выполняется без синтаксической ошибки

Тревожный признак

Ошибка «Синтаксическая ошибка» при выполнении запроса

Альтернативы СтрШаблон и когда их выбирать

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

Для формирования XML, JSON и HTML строковые шаблоны в принципе не рекомендуются: платформа предоставляет объекты ЗаписьXML, ЗаписьJSON, которые корректно экранируют спецсимволы. Ручная сборка таких форматов через СтрШаблон — частый источник невалидных файлов.

Чем собирать строку

Конкатенация (+)

Подходит для 1–2 подстановок в простых случаях; при большем числе значений код быстро теряет читаемость.

СтрШаблон

Оптимален для сообщений, надписей, служебных строк с 2–10 значениями; единый шаблон удобен для локализации.

Текстовый макет с параметрами

Подходит для многострочных текстов, писем и печатных форм; требует создания макета в конфигураторе.

ЗаписьXML / ЗаписьJSON

Обязательны для машинных форматов: гарантируют корректное экранирование, чего СтрШаблон не делает.

Ограничения и безопасные границы применения

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

Ещё одно ограничение — десять параметров и отсутствие именованных маркеров. В длинных шаблонах легко перепутать порядок %5 и %6, поэтому шаблоны с большим числом подстановок стоит разбивать на несколько сообщений или выносить в макет.

Удобный приём: выносить все шаблоны сообщений в общий модуль в виде функций, возвращающих готовый текст. Тогда тексты сообщений собраны в одном месте, их легко править и переводить без поиска по всему коду конфигурации.

Частые вопросы о СтрШаблон

Чем СтрШаблон отличается от функции Строка()?

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

Сколько параметров можно передать в СтрШаблон?

До десяти значений: маркеры нумеруются от %1 до %10. Если нужно подставить больше данных, строку собирают несколькими вызовами или используют текстовый макет с именованными параметрами.

Как вывести в строке сам символ процента?

Знак процента удваивается: запись «%%» в шаблоне превратится в одиночный «%» в результате. Например, шаблон «Скидка %1%%» с параметром 15 даст строку «Скидка 15%».

Почему в сообщении остался виден маркер %2?

Значит, в шаблоне указан маркер, для которого не передан параметр, либо в номере маркера опечатка (например, %12 вместо %1 и %2). Проверьте, что количество параметров после шаблона не меньше максимального номера маркера.

Работает ли СтрШаблон на тонком и веб-клиенте?

Да, функция входит во встроенный язык платформы и доступна на сервере, толстом, тонком и веб-клиенте без ограничений. Её можно использовать и в клиентских процедурах формирования сообщений.

Можно ли использовать СтрШаблон для сборки XML или JSON?

Технически можно, но делать этого не стоит: функция не экранирует спецсимволы, и любое значение с кавычкой или угловой скобкой сломает структуру файла. Для этих форматов предназначены объекты ЗаписьXML и ЗаписьJSON.