steelmorgan/mxl-dsl

MXL DSL

Компактный JSON-формат для описания табличных документов 1С (SpreadsheetDocument). Claude описывает что (области, ячейки, стили, параметры), CLI обеспечивает корректность XML (палитры, индексы, объединения, namespace).

Канон взят из спецификации Широкова (cc-1c-skills) и расширен флагом --format designer|edt для двух форматов вывода.

Когда применять

| Триггер | Действие | |---------|----------| | Создать печатную форму с нуля | mxl compile + JSON DSL → references/dsl-spec.md | | Доработать существующий макет | mxl decompile → редактирование JSON → mxl compile | | Понять структуру чужого макета (области, параметры, расшифровки) | mxl info → references/info-modes.md | | Проверить корректность собранного Template.xml | xml-gen validate --type mxl → references/validate-classes.md | | Реверс-инжиниринг печати по образцу (скрин/скан) | mxl decompile или собрать с нуля по сетке — задать page + "Nx" ширины |

Намеренно вне DSL — делать кодом

DSL покрывает статическое оформление ячеек — font/align/valign/border/wrap/format через карту styles. Намеренно НЕ генерирует рантайм-условное оформление: раскраску/стилизацию ячейки в зависимости от выводимого значения. Это делается программно при заполнении таб. документа — Область.ТекстЦвет = …, Область.ЦветФона = … на заполненной области. Отсутствие — дизайн, а не дефект инструмента, см. правило no-manual-xml-edit.md § «Что делается кодом, а НЕ через xml-gen».

Команды

# Компиляция JSON → Template.xml
xml-gen mxl compile [--format designer|edt] <input.json> <output.xml>

# Декомпиляция Template.xml → JSON DSL
xml-gen mxl decompile <Template.xml> <output.json>

# Анализ структуры (области, параметры, расшифровки, текст)
xml-gen mxl info <Template.xml> [--with-text] [--limit N] [--offset N] [--format text|json]

# Валидация
xml-gen validate --type mxl <Template.xml> [--detailed] [--max-errors N]

output.xml для compile — путь к макету в EPF/ERF: .../Templates/<Name>/Ext/Template.xml.

--format (только compile):

• designer — формат конфигуратора (Template.xml в Ext/)
• edt — формат EDT (XML внутри .mxl-папки EDT-проекта)

Минимальный DSL

{
  "columns": 4,
  "areas": [
    {
      "name": "Заголовок",
      "rows": [
        { "cells": [
          { "col": 1, "span": 4, "text": "Накладная" }
        ]}
      ]
    }
  ]
}

Ключевые отличия от старого инлайн-формата

| Было (старо) | Стало (канон) | |--------------|---------------| | {"text": "[Параметр]"} — параметр через скобки в тексте | {"param": "Параметр"} — отдельный тип ячейки | | {"text": "Инв № [Номер]"} — параметр в шаблоне через скобки | {"template": "Инв № [Номер]"} — отдельный тип | | span без col (последовательное заполнение) | col 1-based + span (явное позиционирование) | | Ширины колонок не задавались | columns + columnWidths + page + "Nx" | | Сплошные рамки строки — каждая ячейка явно | rowStyle — автозаполнение пустот | | Только горизонтальное объединение | rowspan (вертикальное) + rowStyle учитывает занятые ячейки | | Расшифровка не описывалась | detail — параметр расшифровки рядом с param | | Высота строки не задавалась | height на строке | | N пустых строк — N объектов {} | { "empty": N } |

Полная спецификация полей (верхний уровень, fonts, styles, areas, rows, cells, fillType-детекция, rowStyle с rowspan, "Nx"-пропорции, форматы 1С ЧДЦ=/ДФ=) — references/dsl-spec.md.

Использование областей в BSL

Имена областей из DSL (name) и имена параметров (param) — то, чем BSL обращается к макету:

ТД = ЭтотОбъект.ПолучитьМакет("ПечатнаяФорма");
ТабДок = Новый ТабличныйДокумент;

ОбластьШапка = ТД.ПолучитьОбласть("Заголовок");
ОбластьШапка.Параметры.ТекстЗаголовка = "Накладная № 1";
ТабДок.Вывести(ОбластьШапка);

Для Каждого Стр Из ТЧ Цикл
    Строка = ТД.ПолучитьОбласть("Строка");
    Строка.Параметры.Товар       = Стр.Товар;        // detail = Номенклатура подставит ссылку для расшифровки
    Строка.Параметры.Количество  = Стр.Количество;
    Строка.Параметры.Сумма       = Стр.Сумма;
    ТабДок.Вывести(Строка);
КонецЦикла;

Для пересечений (область Rows + область Columns, например этикетки/ценники) обращение через |:

Область = ТД.ПолучитьОбласть("ВысотаЭтикетки|ШиринаЭтикетки");

Decompile — что важно знать

• Шрифты и стили получают автоматические осмысленные имена (default, bold, header, bordered, bordered-right, bold-right, border-top и т.п.) по комбинации свойств — не обязаны совпадать с исходными.
• Если в строке все пустые ячейки имеют одинаковый стиль — он сворачивается в rowStyle, а пустые ячейки убираются из вывода.
• Шаблонные параметры ([Имя] в text) выделяются в отдельные ячейки template.

Workflow (типовой)

1. (опционально) Если макет создаётся по изображению — наложить сетку, определить пропорции колонок → задать page: "A4-landscape" + "Nx" ширины.
2. Написать JSON (Write).
3. mxl compile → Template.xml.
4. xml-gen validate --type mxl → если есть ошибки, см. references/validate-classes.md.
5. mxl info → проверить структуру областей и параметров глазами агента.
6. (для доработки чужого макета) mxl decompile → редактировать → compile.

Правильно / Неправильно

// ❌ статический текст и параметр свалены в одну ячейку через скобки
{ "col": 2, "text": "Инв № [Номер]" }

// ✅ это шаблон с подстановкой → template
{ "col": 2, "template": "Инв № [Номер]" }

// ❌ сплошные рамки строки — каждая пустая ячейка прописана вручную
{ "cells": [
  { "col": 1, "style": "bordered", "param": "А" },
  { "col": 2, "style": "bordered" },
  { "col": 3, "style": "bordered" },
  { "col": 4, "style": "bordered", "param": "Б" }
]}

// ✅ rowStyle автозаполняет пустоты
{ "rowStyle": "bordered", "cells": [
  { "col": 1, "param": "А" },
  { "col": 4, "param": "Б" }
]}

Ссылки

• references/dsl-spec.md — полная спецификация полей DSL
• references/info-modes.md — как читать вывод mxl info (типы областей, пересечения, [tpl]-параметры, detail)
• references/validate-classes.md — классы ошибок валидатора
• Соседние DSL: ../role-dsl/, ../form-dsl/

---

depends_on: [] metadata: category: 1c-development version: "2.0"