Vue-HTML
Полный справочник по серверным шаблонам модулей и меню: от подключения файла до циклов, компонентов, безопасного HTML и диагностики.

Содержание руководства
- Что такое Vue-HTML
- Где работает язык
- Как подключить шаблон
- Какие данные приходят
- Подстановки и экранирование
- Условия и директивы
- Выражения и операторы
- Атрибуты, классы и стили
- Встроенные функции
- Циклы и loop
- Серверные компоненты
- Пример 1. Единый шаблон
- Пример 2. Список и детальная страница
- Пример 3. Меню
- Vue 3 в браузере
- Чего в языке нет
- Проверка и диагностика
- Проверочный список
Что такое Vue-HTML
Vue-HTML — серверный язык шаблонов BuildNexus. Файлы выглядят как Vue, но их разбирает ядро: посетитель получает уже готовый HTML, а директивы на странице повторно не исполняются.
| Vue-HTML | Браузерный Vue 3 |
|---|---|
| Работает на сервере при создании HTML | Работает в браузере после загрузки страницы |
Файлы .tpl.html | Файлы .vue, TypeScript и собранный JS |
| Условия, циклы, подстановки и небольшой набор функций | Состояние, события, запросы и интерактивность |
| Не требует JavaScript у посетителя | Требует подключённого браузерного пакета |
Где работает язык
| Файл | Назначение | Возможности Vue-HTML |
|---|---|---|
modules/<модуль>/templates/*.tpl.html | Разметка блоков, карточек, списков и детальных страниц | Полный язык |
www/templates/menus/*.tpl.html | Разметка меню и его пунктов | Полный язык |
www/templates/pages/*.sehtml | Каркас всего HTML-документа | Токены композитора и ветвление v-if, но не полный язык |
www/templates/partials/*.sehtml | Шапка, подвал и части каркаса | Токены и ветвление, без циклов Vue-HTML |
Не ориентируйтесь только на похожий синтаксис. Цикл v-for в шаблоне модуля или меню работает, а в каркасе страницы .sehtml не является полноценным циклом.
Типичная папка модуля
modules/promo_banner/
├── contract.json
├── module.compose.json
└── templates/
└── promo_banner_template.tpl.htmlШаблон лежит внутри модуля, но начинает использоваться только после объявления его роли в module.compose.json.
Как подключить шаблон
Для простого блока укажите файл в modules/promo_banner/module.compose.json:
{
"version": "1.0.0",
"templates": {
"section_template": "promo_banner_template.tpl.html"
},
"assets": {
"css": ["style.scss"],
"js": []
},
"runtime": {
"mode": "app_native"
}
}Имя считается относительно папки templates/ этого модуля. Сам файл находится по адресу modules/promo_banner/templates/promo_banner_template.tpl.html.
Роли шаблонов
| Ключ | Что отрисовывает |
|---|---|
section_template | Весь простой блок или внешнюю обёртку list/detail-модуля |
record_template | Одну карточку записи |
list_template | Контейнер списка карточек |
show_template | Детальную страницу одной записи |
layout_template | Необязательную общую обёртку представления |
Если для роли предусмотрен *_fallback_template, ядро может использовать его как запасной вариант. Для блока без записей обычно достаточно одного section_template.
Какие данные приходят
Доступные имена зависят от роли шаблона и контракта модуля.
- В простом
section_templateполя раздела доступны напрямую:title,text,image,link_url. Также доступенsection_id. - В карточке записи доступны токены, которые контракт связал с
record.*. - В списке доступны значения раздела и собранные записи, предусмотренные моделью модуля.
- Значения серверного
computeдоступны как токеныcompute.*или подготовленные итоговые имена согласноcontract.render. - В шаблоне меню доступны
items, параметры меню и подготовленные поля каждогоitem.
Откуда берётся имя токена
Источником правды является contract.json. Поля редактора объявляют, что может заполнить владелец сайта, а contract.render связывает данные раздела, записи, результата вычисления и шаблонные токены.
<section data-section-id="{{ section_id }}">
<h2>{{ title }}</h2>
<div>{{ raw:text }}</div>
</section>Если токен пуст, сначала проверьте контракт и фактические данные раздела. Опечатку в имени поля статическая проверка определить не может: пустое необязательное поле выглядит так же.
Подстановки и экранирование
| Форма | Что делает |
|---|---|
{{ title }} | Выводит значение с HTML-экранированием |
{{ raw:text_html }} | Вставляет готовый HTML без экранирования |
{{ var:contact.phone }} | Подставляет переменную проекта |
{{ t('add_to_cart') }} | Выводит перевод активного языка |
<{{ title_tag }}> | Использует значение как имя HTML-тега |
Безопасный вывод по умолчанию
<h2>{{ title }}</h2>Если в title попадёт <script>, посетитель увидит текст, а не исполняемый тег.
Доверенный HTML
<div class="article">{{ raw:text }}</div>raw: и v-html применяйте только к данным редактора или ядра, происхождение которых известно. Не вставляйте так имя, комментарий, параметры адреса или другой ввод посетителя.
Условия и директивы
| Директива | Назначение |
|---|---|
v-if | Выводит элемент, если выражение истинно |
v-else-if, v-else | Продолжают цепочку соседних условий |
v-for | Повторяет элемент по массиву или объекту |
v-text | Задаёт безопасный текст элемента |
v-html | Вставляет доверенный HTML |
:атрибут | Вычисляет значение атрибута |
<article v-if="title" class="card">
<h2 v-text="title"></h2>
<p v-if="note">{{ note }}</p>
<p v-else>Описание ещё не добавлено</p>
</article>
<p v-else>Карточка не заполнена</p>v-else-if и v-else относятся к предыдущему условию и должны стоять на соседнем элементе. Если между ветвями вклинить другой тег, цепочка перестаёт быть однозначной.
Ложное значение в привязанном атрибуте убирает атрибут целиком. Это удобно для :aria-current, :target и условных классов.
Выражения и операторы
Выражения используются в v-if, привязанных атрибутах и подстановках.
| Возможность | Пример |
|---|---|
| Путь и индекс | item.title, items[1], rec.images.0.image |
| Литералы | true, false, null, 42, 'текст' |
| Сравнения | == != === !== > < >= <= |
| Логика | !flag, a && b, a || b |
| Арифметика | + - * / % |
| Тернарное условие | flag ? 'on' : 'off' |
| Длина | items.length, title.length |
| Скобки | (a || b) && c |
Особенности правдивости
Ложными считаются null, false, число 0 и пустая строка. Строка '0', пустой массив и пустой объект истинны. Флажок из данных проекта часто является строкой, поэтому проверяйте его явно:
<div v-if="is_active == '1'">Показать</div>Переменную с точкой в имени берите через скобки: var['social.vk']. Вокруг оператора вычитания оставляйте пробелы: a - b; запись has-icon считается одним именем.
Атрибуты, классы и стили
Обычный атрибут и привязка
<a href="{{ item.url }}">Обычная подстановка</a>
<a :href="item.url">Выражение</a>Внутри :атрибут пишется выражение без фигурных скобок. Запись :class="{{ kind }}" неверна и оставит элемент без класса.
Условные классы
<article :class="{
'card--active': is_active == '1',
'card--featured': featured == '1'
}">Список классов
<button :class="['btn', kind ? 'btn--' + kind : '']">Стили
<div :style="{ color: text_color, fontSize: size + 'px' }">В объекте стилей fontSize превращается в font-size. Объекты и массивы можно комбинировать. Для постоянных классов оставляйте обычный class, а в :class помещайте только вычисляемые модификаторы.
Если результат выражения ложный, привязанный атрибут не выводится. Так :target="item.target" не создаёт пустой target.
Встроенные функции
Функции вызываются только в функциональной форме: upper(title), а не title.toUpperCase().
| Функция | Назначение |
|---|---|
upper(s), lower(s), trim(s) | Регистр и удаление крайних пробелов |
truncate(s, n[, tail]) | Обрезка строки по символам |
number(n[, digits]) | Число с группами разрядов и дробной запятой |
round(n[, digits]) | Округление |
plural(n, one, few, many) | Русская форма слова; число отдельно |
join(list[, separator]) | Склейка непустых значений списка |
count(x) | Длина списка, объекта или строки |
t(key[, fallback]) | Перевод активного языка |
<h2>{{ upper(trim(title)) }}</h2>
<p>{{ truncate(text, 120) }}</p>
<strong>{{ number(price, 2) }} ₽</strong>
<span>
{{ count(records) }}
{{ plural(count(records), 'товар', 'товара', 'товаров') }}
</span>Функции можно вкладывать. Даты, регулярные выражения и сложные преобразования готовьте заранее в серверном JavaScript или источнике данных.
Циклы и loop
<article
v-for="(item, index) in items"
:class="{ 'card--first': loop.first }"
>
<span>{{ loop.number }}</span>
<h3>{{ item.title }}</h3>
</article>| Поле | Значение |
|---|---|
loop.number | Порядковый номер с единицы |
loop.index | Индекс с нуля |
loop.count | Всего элементов |
loop.first, loop.last | Первая и последняя итерация |
loop.even, loop.odd | Чётность по отображаемому номеру |
loop.key | Ключ объекта или индекс массива |
loop.parent | Счётчик внешнего цикла |
Поддерживаются формы item in items и (item, index) in items. Вложенный цикл создаёт собственный loop; к внешнему обращайтесь через loop.parent.
Серверные компоненты
Повторяющуюся серверную разметку можно вынести в компонент. Для модуля product_grid файл карточки располагается здесь:
modules/product_grid/templates/
└── _components/
└── product_grid/
└── card.tpl.htmlВызов использует пространство имён и имя файла:
<product_grid:Card
v-for="item in records"
:title="item.title"
:url="item.url"
:featured="item.featured == '1'"
read-more="Подробнее"
/><product_grid:Card>соответствует_components/product_grid/card.tpl.html.:titleпередаёт результат выражения.read-moreпередаёт постоянную строку.- Атрибут без значения означает логическое «да».
v-ifиv-forработают прямо на компоненте.
Компонент видит данные родительского шаблона, но явные параметры делают зависимость понятной и позволяют переиспользовать разметку. Компоненты записывайте самозакрывающимися тегами.
Пример 1. Единый шаблон
Модель A подходит блоку без отдельных записей: баннеру, текстовой секции, призыву к действию. Вся разметка находится в одном section_template.
module.compose.json
{
"templates": {
"section_template": "promo_banner_template.tpl.html"
},
"runtime": { "mode": "app_native" }
}templates/promo_banner_template.tpl.html
<section
class="promo-banner"
data-section-id="{{ section_id }}"
>
<div class="promo-banner__content">
<{{ title_tag }}
v-if="title"
class="promo-banner__title"
>{{ title }}</{{ title_tag }}>
<div v-if="text" class="promo-banner__text">
{{ raw:text }}
</div>
<a v-if="link_url && link_text"
class="button"
:href="link_url">
{{ link_text }}
</a>
</div>
</section>Поля title, title_tag, text, link_url и link_text должны быть объявлены контрактом модуля. Здесь нет скрытой промежуточной разметки: что написано в файле, то и становится секцией.
Пример 2. Список и детальная страница
Модель B нужна, когда есть карточки и отдельные страницы записей. Ядро по очереди создаёт карточки, список, при необходимости детальную страницу, а затем помещает результат во внешнюю оболочку.
module.compose.json
{
"templates": {
"section_template": "articles_template.tpl.html",
"record_template": "articles_card.tpl.html",
"list_template": "articles_list.tpl.html",
"show_template": "articles_show.tpl.html"
},
"runtime": { "mode": "app_native" }
}Внешняя оболочка
{{ raw:module_css }}
<section class="articles">
{{ raw:content }}
</section>
{{ raw:module_js }}Карточка одной записи
<article class="article-card">
<h3>{{ title }}</h3>
<p>{{ truncate(summary, 140) }}</p>
<a :href="detail_url">Читать</a>
</article>Контейнер списка
<div class="articles__grid">
{{ raw:records_html }}
</div>content и records_html уже содержат собранный HTML, поэтому выводятся через raw:. Чтобы изменить карточку, правьте record_template; section_template обычно остаётся тонкой оболочкой для CSS, JS и готового представления.
Пример 3. Меню
Шаблоны меню лежат в www/templates/menus/*.tpl.html и используют тот же полный движок Vue-HTML. Сами пункты находятся отдельно в www/menus/*.json.
<nav :aria-label="menu_title || 'Основное меню'">
<ul class="menu">
<li
v-for="item in items"
:class="['menu__item', item.is_active && 'is-active']"
>
<a
v-if="item.has_url"
class="menu__link"
:href="item.url"
:target="item.target"
:aria-current="item.aria_current"
>{{ item.title }}</a>
<span v-else class="menu__link">
{{ item.title }}
</span>
</li>
</ul>
</nav>Подготовленные поля item.item_class, item.link_class, item.children, item.target и item.aria_current позволяют сохранить навигационную семантику. Для вложенного меню повторите цикл по item.children.
В каркасе меню подключается токеном {{ menu:mainmenu }}. Вариант {{ menu:mainmenu|headermenu }} использует те же пункты с другим шаблоном.
Vue 3 в браузере
Vue-HTML заканчивает работу до отправки страницы. Если пользователь должен нажимать кнопки, менять состояние без перезагрузки, открывать панели или отправлять запросы, нужен браузерный Vue 3.
Разделите обязанности
- Vue-HTML выводит осмысленную серверную оболочку и запасное состояние.
- Серверный
computeподготавливает начальные данные и безопасный JSON. - Шаблон размещает точку монтирования и JSON-состояние.
- Компонент из
frontend/src/App.vueмонтируется в браузере. - Сборка модуля создаёт файлы в
assets/, которые объявляются вmodule.compose.json.
<div class="price-widget__mount"
data-price-widget
data-widget-key="{{ widget_key }}">
<p>{{ title }}</p>
<p>Загрузка интерактивного блока…</p>
</div>
<script type="application/json"
id="price-state-{{ widget_key }}">
{{ raw:state_json }}
</script>Так блок остаётся понятным без JavaScript и до монтирования. В поставке ядра и проекта ориентиром служит модуль bnx_vue_demo.
Чего в языке нет
Vue-HTML не является JavaScript и не поддерживает весь синтаксис Vue.
{{ title.toUpperCase() }} // нет методов
{{ items.map(x => x.name) }} // нет стрелок и map
{{ user?.name }} // нет optional chaining
{{ `Привет ${name}` }} // нет шаблонных строк
{{ now() }} // нет текущей даты
{{ /sale/i }} // нет регулярных выражений- Нет произвольных функций и методов объектов.
- Нет доступа к
window,documentи DOM. - Нет обработчиков
@clickкак исполняемой браузерной логики. - Нет запросов к сети и файловой системе.
- Нет
import,require, обещаний и асинхронного кода.
Для регистра используйте upper(title), для массива — v-for, для отсутствующего пути достаточно обычного обращения, а сложные вычисления вынесите в серверный compute. Интерактивность реализуйте отдельным Vue 3-компонентом.
Проверка и диагностика
В Studio включите «Проверку шаблонов». Ядро проверит дерево при старте и каждый сохранённый шаблон, а замечания появятся в панели открытой страницы.
| Диагностика | Что означает |
|---|---|
call | Неизвестная функция или вызов в стиле метода |
optional-chain | Использован неподдерживаемый ?. |
arrow | Обнаружена стрелочная функция |
backtick | Использована шаблонная строка JavaScript |
unbalanced | Не сходятся кавычки или скобки |
interp-in-bind | Внутри :атрибут ошибочно написаны фигурные скобки |
bad-v-for | Цикл не соответствует форме item in items |
Проверка всего проекта
bnxdev --lint --sites ./sites --modules ./modules/srcВывод имеет формат файл:строка: [код] сообщение и подходит для терминала, IDE и CI.
Что проверка не знает
Опечатку вроде item.is_activ невозможно отличить от необязательного пустого поля без реальных данных. Для таких случаев проверяйте вход раздела и итоговый HTML через инструменты рендера.
Проверочный список
- Определите среду: модуль или меню используют
.tpl.html, каркас страницы —.sehtml. - Объявите правильную роль файла в
module.compose.json. - Сверьте имена токенов с
contract.jsonи ролью шаблона. - Обычные данные выводите с экранированием;
raw:оставьте доверенному HTML. - В
:атрибутпишите выражение без фигурных скобок. - Для строковых флажков сравнивайте с
'1'или'0'. - Пустой список проверяйте через
count(items). - Сложную обработку вынесите в серверный JavaScript, интерактивность — в Vue 3.
- Включите диагностику и проверьте шаблоны линтером.
- Посмотрите итоговый HTML, мобильную ширину и страницу без браузерного JavaScript.
Куда дальше
Шаблоны сайта и каркасы · Устройство модулей · Серверный JavaScript · Данные и коллекции
В репозитории полезны живые образцы: about_block для единого шаблона, bnx_releases для разделения оболочки и карточки, www/templates/menus/menu.tpl.html для меню и bnx_vue_demo для браузерного острова.