From 298d503c647526fcf69b8ecbefce410dbf4e5c3f Mon Sep 17 00:00:00 2001 From: Nick Shirokov Date: Sun, 8 Feb 2026 18:39:40 +0300 Subject: [PATCH] Extract MXL DSL spec to docs/mxl-dsl-spec.md Shared spec for mxl-compile and future mxl-decompile. Compiler SKILL.md now references the spec instead of inlining it. Co-Authored-By: Claude Opus 4.6 --- .claude/skills/mxl-compile/SKILL.md | 162 +++------------------------- README.md | 1 + docs/mxl-dsl-spec.md | 158 +++++++++++++++++++++++++++ 3 files changed, 174 insertions(+), 147 deletions(-) create mode 100644 docs/mxl-dsl-spec.md diff --git a/.claude/skills/mxl-compile/SKILL.md b/.claude/skills/mxl-compile/SKILL.md index d48f898a..af08a49b 100644 --- a/.claude/skills/mxl-compile/SKILL.md +++ b/.claude/skills/mxl-compile/SKILL.md @@ -39,156 +39,24 @@ powershell.exe -NoProfile -File .claude/skills/mxl-compile/scripts/mxl-compile.p 3. Claude вызывает `/mxl-validate` для проверки корректности 4. Claude вызывает `/mxl-info` для верификации структуры -## JSON-схема +## JSON-схема DSL -### Пример +Полная спецификация формата: **`docs/mxl-dsl-spec.md`** (прочитать через Read tool перед написанием JSON). -```json -{ - "columns": 10, - "defaultWidth": 30, - "columnWidths": { "1": 15, "2-8": 40, "9-10": 50 }, +Краткая структура: - "fonts": { - "default": { "face": "Arial", "size": 10 }, - "bold": { "face": "Arial", "size": 10, "bold": true }, - "header": { "face": "Arial", "size": 14, "bold": true } - }, - - "styles": { - "default": {}, - "header": { "font": "header", "align": "center" }, - "label": { "font": "bold" }, - "bordered": { "border": "all" }, - "bordered-right": { "border": "all", "align": "right" }, - "total-right": { "font": "bold", "border": "top", "align": "right" } - }, - - "areas": [ - { - "name": "Заголовок", - "rows": [ - { "height": 20, "cells": [ - { "col": 1, "span": 10, "style": "header", "param": "ТекстЗаголовка" } - ]} - ] - }, - { - "name": "ШапкаТаблицы", - "rows": [ - { "rowStyle": "bordered", "cells": [ - { "col": 1, "text": "№" }, - { "col": 2, "span": 6, "text": "Наименование" }, - { "col": 9, "text": "Кол-во" }, - { "col": 10, "text": "Сумма" } - ]} - ] - }, - { - "name": "Строка", - "rows": [ - { "rowStyle": "bordered", "cells": [ - { "col": 1, "param": "НомерСтроки" }, - { "col": 2, "span": 6, "param": "Товар", "detail": "Номенклатура" }, - { "col": 9, "style": "bordered-right", "param": "Количество" }, - { "col": 10, "style": "bordered-right", "param": "Сумма" } - ]} - ] - }, - { - "name": "Итого", - "rows": [ - { "cells": [ - { "col": 8, "span": 2, "style": "total-right", "text": "Итого:" }, - { "col": 10, "style": "total-right", "param": "Всего" } - ]} - ] - } - ] +``` +{ columns, defaultWidth, columnWidths, + fonts: { name: { face, size, bold, italic, underline, strikeout } }, + styles: { name: { font, align, valign, border, borderWidth, wrap, format } }, + areas: [{ name, rows: [{ height, rowStyle, cells: [ + { col, span, rowspan, style, param, detail, text, template } + ]}]}] } ``` -### Верхний уровень - -| Поле | Обяз. | По умолч. | Описание | -|------|:-----:|-----------|----------| -| `columns` | да | — | Количество колонок | -| `defaultWidth` | нет | 10 | Ширина колонок по умолчанию | -| `columnWidths` | нет | `{}` | Ширины колонок. Ключи 1-based: `"1"`, `"3-14"`, `"5,7,9"` | -| `fonts` | нет | — | Именованные шрифты (если не задано, создаётся Arial 10) | -| `styles` | нет | `{}` | Именованные стили | -| `areas` | да | — | Массив именованных областей (порядок = порядок в документе) | - -### Шрифты (`fonts.`) - -| Поле | По умолч. | Описание | -|------|-----------|----------| -| `face` | `"Arial"` | Имя шрифта | -| `size` | `10` | Размер | -| `bold` | `false` | Жирный | -| `italic` | `false` | Курсив | -| `underline` | `false` | Подчёркнутый | -| `strikeout` | `false` | Зачёркнутый | - -Шрифт `"default"` используется когда стиль не указывает шрифт явно. - -### Стили (`styles.`) - -| Поле | По умолч. | Описание | -|------|-----------|----------| -| `font` | `"default"` | Ссылка на имя шрифта | -| `align` | — | `left`, `center`, `right` | -| `valign` | — | `top`, `center` | -| `border` | — | Стороны рамки: `all`, `top`, `bottom`, `left`, `right`, `none`. Через запятую: `"top,bottom"` | -| `borderWidth` | `"thin"` | Толщина рамки: `thin` (1px) или `thick` (2px) | -| `wrap` | `false` | Перенос текста | -| `format` | — | Формат данных 1С: `"ЧЦ=15; ЧДЦ=2"`, `"ДФ=dd.MM.yyyy"` и т.д. | - -### Области (`areas[]`) - -| Поле | Обяз. | Описание | -|------|:-----:|----------| -| `name` | да | Имя области для `Макет.ПолучитьОбласть("Имя")` | -| `rows` | да | Массив строк | - -### Строки (`rows[]`) - -| Поле | По умолч. | Описание | -|------|-----------|----------| -| `height` | — | Высота строки (если не задана, используется авто) | -| `rowStyle` | — | Стиль для ВСЕХ колонок (заполняет пустоты рамками) | -| `cells` | `[]` | Массив ячеек | - -Строка без `cells` и `rowStyle` → пустая строка. - -### Ячейки (`cells[]`) - -| Поле | Обяз. | По умолч. | Описание | -|------|:-----:|-----------|----------| -| `col` | да | — | Позиция колонки (1-based) | -| `span` | нет | `1` | Объединение по горизонтали (количество колонок) | -| `rowspan` | нет | `1` | Объединение по вертикали (количество строк) | -| `style` | нет | rowStyle | Стиль ячейки (переопределяет rowStyle) | -| `param` | нет | — | Параметр заполнения | -| `detail` | нет | — | Параметр расшифровки (только с `param`) | -| `text` | нет | — | Статический текст | -| `template` | нет | — | Шаблонный текст с `[Параметр]` | - -Тип заполнения определяется автоматически: -- `param` → fillType=Parameter -- `template` → fillType=Template -- `text` → fillType=Text - -### `rowStyle` — автозаполнение - -Когда задан `rowStyle`, скрипт создаёт ячейки для ВСЕХ колонок строки. Позиции без явных ячеек заполняются пустыми ячейками с указанным стилем. Это обеспечивает сплошные рамки в табличных строках. - -## Ограничения MVP - -Текущая версия не поддерживает: -- Множественные наборы колонок -- Области типа Columns / Rectangle -- Рисунки (штрихкоды, картинки) -- Фон ячеек - -Эти возможности будут добавлены в будущих версиях без переделки основной архитектуры. +Ключевые правила: +- `col` — 1-based позиция колонки +- `rowStyle` — автозаполнение пустот стилем (рамки по всей ширине) +- Тип заполнения определяется автоматически: `param` → Parameter, `text` → Text, `template` → Template +- `rowspan` — объединение строк вниз (rowStyle учитывает занятые ячейки) diff --git a/README.md b/README.md index 769922d8..4988f20e 100644 --- a/README.md +++ b/README.md @@ -158,6 +158,7 @@ docs/ - [Встроенная справка](docs/1c-help-spec.md) — Help.xml, HTML-страницы, кнопка справки на форме - [Сборка и разборка EPF](docs/build-spec.md) — команды `1cv8.exe`, параметры, коды возврата - [Табличный документ (MXL)](docs/1c-spreadsheet-spec.md) — XML-формат SpreadsheetDocument, совместимость версий +- [MXL DSL](docs/mxl-dsl-spec.md) — JSON-формат описания макета для `/mxl-compile` и `/mxl-decompile` ## Технические детали diff --git a/docs/mxl-dsl-spec.md b/docs/mxl-dsl-spec.md new file mode 100644 index 00000000..d7d952b5 --- /dev/null +++ b/docs/mxl-dsl-spec.md @@ -0,0 +1,158 @@ +# Спецификация MXL DSL — JSON-формат описания табличного документа + +Компактный JSON-формат для описания макетов табличных документов 1С (SpreadsheetDocument). Используется навыками `/mxl-compile` (JSON → XML) и `/mxl-decompile` (XML → JSON). + +## Пример + +```json +{ + "columns": 10, + "defaultWidth": 30, + "columnWidths": { "1": 15, "2-8": 40, "9-10": 50 }, + + "fonts": { + "default": { "face": "Arial", "size": 10 }, + "bold": { "face": "Arial", "size": 10, "bold": true }, + "header": { "face": "Arial", "size": 14, "bold": true } + }, + + "styles": { + "default": {}, + "header": { "font": "header", "align": "center" }, + "label": { "font": "bold" }, + "bordered": { "border": "all" }, + "bordered-right": { "border": "all", "align": "right" }, + "total-right": { "font": "bold", "border": "top", "align": "right" } + }, + + "areas": [ + { + "name": "Заголовок", + "rows": [ + { "height": 20, "cells": [ + { "col": 1, "span": 10, "style": "header", "param": "ТекстЗаголовка" } + ]} + ] + }, + { + "name": "ШапкаТаблицы", + "rows": [ + { "rowStyle": "bordered", "cells": [ + { "col": 1, "text": "№" }, + { "col": 2, "span": 6, "text": "Наименование" }, + { "col": 9, "text": "Кол-во" }, + { "col": 10, "text": "Сумма" } + ]} + ] + }, + { + "name": "Строка", + "rows": [ + { "rowStyle": "bordered", "cells": [ + { "col": 1, "param": "НомерСтроки" }, + { "col": 2, "span": 6, "param": "Товар", "detail": "Номенклатура" }, + { "col": 9, "style": "bordered-right", "param": "Количество" }, + { "col": 10, "style": "bordered-right", "param": "Сумма" } + ]} + ] + }, + { + "name": "Итого", + "rows": [ + { "cells": [ + { "col": 8, "span": 2, "style": "total-right", "text": "Итого:" }, + { "col": 10, "style": "total-right", "param": "Всего" } + ]} + ] + } + ] +} +``` + +## Верхний уровень + +| Поле | Обяз. | По умолч. | Описание | +|------|:-----:|-----------|----------| +| `columns` | да | — | Количество колонок | +| `defaultWidth` | нет | 10 | Ширина колонок по умолчанию | +| `columnWidths` | нет | `{}` | Ширины колонок. Ключи 1-based: `"1"`, `"3-14"`, `"5,7,9"` | +| `fonts` | нет | — | Именованные шрифты (если не задано, создаётся Arial 10) | +| `styles` | нет | `{}` | Именованные стили | +| `areas` | да | — | Массив именованных областей (порядок = порядок в документе) | + +## Шрифты (`fonts.`) + +| Поле | По умолч. | Описание | +|------|-----------|----------| +| `face` | `"Arial"` | Имя шрифта | +| `size` | `10` | Размер | +| `bold` | `false` | Жирный | +| `italic` | `false` | Курсив | +| `underline` | `false` | Подчёркнутый | +| `strikeout` | `false` | Зачёркнутый | + +Шрифт `"default"` используется когда стиль не указывает шрифт явно. Если не определён, создаётся автоматически (Arial 10). + +## Стили (`styles.`) + +| Поле | По умолч. | Описание | +|------|-----------|----------| +| `font` | `"default"` | Ссылка на имя шрифта | +| `align` | — | `left`, `center`, `right` | +| `valign` | — | `top`, `center` | +| `border` | — | Стороны рамки: `all`, `top`, `bottom`, `left`, `right`, `none`. Через запятую: `"top,bottom"` | +| `borderWidth` | `"thin"` | Толщина рамки: `thin` (1px) или `thick` (2px) | +| `wrap` | `false` | Перенос текста | +| `format` | — | Формат данных 1С: `"ЧЦ=15; ЧДЦ=2"`, `"ДФ=dd.MM.yyyy"` и т.д. | + +## Области (`areas[]`) + +| Поле | Обяз. | Описание | +|------|:-----:|----------| +| `name` | да | Имя области для `Макет.ПолучитьОбласть("Имя")` | +| `rows` | да | Массив строк | + +## Строки (`rows[]`) + +| Поле | По умолч. | Описание | +|------|-----------|----------| +| `height` | — | Высота строки (если не задана, используется авто) | +| `rowStyle` | — | Стиль для ВСЕХ колонок (заполняет пустоты рамками) | +| `cells` | `[]` | Массив ячеек | + +Строка без `cells` и `rowStyle` → пустая строка. + +## Ячейки (`cells[]`) + +| Поле | Обяз. | По умолч. | Описание | +|------|:-----:|-----------|----------| +| `col` | да | — | Позиция колонки (1-based) | +| `span` | нет | `1` | Объединение по горизонтали (количество колонок) | +| `rowspan` | нет | `1` | Объединение по вертикали (количество строк) | +| `style` | нет | rowStyle | Стиль ячейки (переопределяет rowStyle) | +| `param` | нет | — | Параметр заполнения | +| `detail` | нет | — | Параметр расшифровки (только с `param`) | +| `text` | нет | — | Статический текст | +| `template` | нет | — | Шаблонный текст с `[Параметр]` | + +### Тип заполнения + +Определяется автоматически по содержимому ячейки: +- `param` → fillType=Parameter +- `template` → fillType=Template +- `text` → fillType=Text +- ничего → без fillType (пустая ячейка или рамка) + +## `rowStyle` — автозаполнение + +Когда задан `rowStyle`, компилятор создаёт ячейки для ВСЕХ колонок строки. Позиции без явных ячеек заполняются пустыми ячейками с указанным стилем. Это обеспечивает сплошные рамки в табличных строках. + +Если в предыдущих строках той же области есть ячейки с `rowspan`, их колонки при автозаполнении пропускаются. + +## Ограничения + +Текущая версия не поддерживает: +- Множественные наборы колонок (`columnsID`) +- Области типа Columns / Rectangle +- Рисунки (штрихкоды, картинки) +- Фон ячеек