docs(mxl): разделить справочник DSL и описать новые ключи

Справочник был одним файлом на 273 строки, а полная таблица свойств стиля его бы удвоила. Разделён по частоте обращения, как в meta-compile: в инструкции маршрутная таблица «что нужно → какой файл». reference/dsl-spec.md — верхний уровень, области, строки, ячейки reference/styles.md — шрифты, стили, цвет, рамка, колонки reference/format-properties.md — полный перечень свойств стиля Описаны columnStyles и новая запись стиля: ключ = имя свойства как в выгрузке, рамка пятью ключами, цвет в четырёх формах. Прежние align/valign/wrap работают и дальше, но в описании их нет — иначе у модели появляется развилка. Ограничения переписаны по факту: цвета, скрытие, отступ, посторонние рамки и стили линий больше не теряются; зато честно названо то, что теряется до сих пор — оформление строки помимо высоты. Пример из спеки скомпилирован и проверен валидатором. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-13 15:03:20 +03:00 · 2026-08-11 17:14:31 +03:00
parent 3c7f7345bb
commit 08503c72e9
9 changed files with 466 additions and 120 deletions
@@ -170,4 +170,6 @@
 | Form DSL | JSON-формат для компиляции форм | [form-dsl-spec.md](form-dsl-spec.md) |
 | SKD DSL | JSON-формат для компиляции СКД | [skd-dsl-spec.md](skd-dsl-spec.md) |
 | MXL DSL | JSON-формат для компиляции табличных документов | [mxl-dsl-spec.md](mxl-dsl-spec.md) |
+| MXL DSL: оформление | Шрифты, стили, цвета, рамки, колонки | [mxl-dsl-styles.md](mxl-dsl-styles.md) |
+| MXL DSL: свойства стиля | Полный перечень свойств формата | [mxl-dsl-format-properties.md](mxl-dsl-format-properties.md) |
 | Role DSL | JSON-формат для компиляции ролей | [role-dsl-spec.md](role-dsl-spec.md) |
@@ -0,0 +1,77 @@
+# Полный список свойств стиля
+
+Имя ключа совпадает с именем свойства в выгрузке — исключений нет. Частые свойства
+с примерами — в `mxl-dsl-styles.md`, здесь полный перечень.
+
+Тип значения:
+
+- **число** — целое;
+- **да/нет** — `true` / `false`;
+- **перечисление** — одно из указанных, регистр не важен;
+- **цвет** — `#RRGGBB`, `style:Имя`, `web:Имя`, `win:Имя`;
+- **линия** — `"Solid"` либо `{ style, width }`;
+- **текст** — строка (разворачивается на языки макета).
+
+## Текст и выравнивание
+
+| Ключ | Тип | Значение |
+|------|-----|----------|
+| `font` | имя | Ссылка на имя из `fonts` |
+| `horizontalAlignment` | перечисление | `Left`, `Center`, `Right`, `Justify`, `Auto` |
+| `verticalAlignment` | перечисление | `Top`, `Center`, `Bottom` |
+| `textPlacement` | перечисление | `Wrap`, `Cut`, `Block`, `Auto` |
+| `textOrientation` | число | Поворот в десятых долях градуса: `900` = 90° |
+| `textColor` | цвет | Цвет текста |
+| `indent` | число | Отступ текста |
+| `autoIndent` | число | Автоматический отступ |
+| `format` | текст | Формат данных: `"ЧЦ=15; ЧДЦ=2"` |
+| `editFormat` | текст | Формат редактирования |
+| `mask` | текст | Маска ввода |
+| `markNegatives` | да/нет | Выделять отрицательные |
+
+## Фон и рамка
+
+| Ключ | Тип | Значение |
+|------|-----|----------|
+| `backColor` | цвет | Цвет фона |
+| `pattern` | перечисление | `Solid`, `WithoutPattern`, `Pattern7`, `Pattern10`, `Pattern12`, `Pattern13`, `Pattern14`, `Pattern16` |
+| `patternColor` | цвет | Цвет узора |
+| `border` | линия | Все четыре стороны |
+| `leftBorder`, `topBorder`, `rightBorder`, `bottomBorder` | линия | Отдельная сторона |
+| `borderColor` | цвет | Цвет рамки |
+
+## Поведение
+
+| Ключ | Тип | Значение |
+|------|-----|----------|
+| `hidden` | да/нет | Скрыть |
+| `protection` | да/нет | Защита от редактирования |
+| `print` | да/нет | Выводить на печать |
+| `hyperLink` | да/нет | Гиперссылка |
+| `detailsUse` | перечисление | Использование расшифровки: `Cell`, `Row`, `WithoutProcessing` |
+| `autoMarkIncomplete` | да/нет | Автоотметка незаполненного |
+| `bySelectedColumns` | да/нет | По выделенным колонкам |
+| `columnSizeChange` | перечисление | `Normal`, `QuickChange` |
+| `autoWidthCalculation` | да/нет | Автоматический расчёт ширины |
+| `widthWeightFactor` | число | Весовой коэффициент ширины |
+
+## Картинка в ячейке
+
+| Ключ | Тип | Значение |
+|------|-----|----------|
+| `picIndex` | число | Номер картинки |
+| `pictureSizeMode` | перечисление | `AutoSize`, `Proportionally`, `RealSize` |
+| `picHorizontalAlignment` | перечисление | `Auto`, `Center`, `Left`, `Right` |
+| `picVerticalAlignment` | перечисление | `Top`, `Center`, `Bottom` |
+| `textPosition` | перечисление | Положение текста относительно картинки: `Auto`, `Top`, `Right`, `Bottom` |
+| `drawingBorder` | число | Рамка рисунка |
+| `drawingHaveLeftBorder`, `drawingHaveTopBorder`, `drawingHaveRightBorder`, `drawingHaveBottomBorder` | да/нет | Наличие стороны рамки рисунка |
+
+## Чего в стиле нет
+
+- `width` — свойство колонки, задаётся через `columnWidths`;
+- `height` — свойство строки, задаётся ключом `height` у строки;
+- `fillType` — выводится из того, каким ключом задано содержимое ячейки
+  (`text` / `param` / `template`);
+- `containsValue`, `valueType`, `controlType` — свойства конкретной ячейки, а не общего
+  оформления; сейчас не поддерживаются.
@@ -2,6 +2,9 @@

 Компактный JSON-формат для описания макетов табличных документов 1С (SpreadsheetDocument). Используется навыками `/mxl-compile` (JSON → XML) и `/mxl-decompile` (XML → JSON).

+Оформление — шрифты, стили, цвета, рамки, колоночные раскладки — в `mxl-dsl-styles.md`;
+полный перечень свойств стиля — в `mxl-dsl-format-properties.md`.
+
 ## Пример

 ```json
@@ -18,11 +21,11 @@

  "styles": {
    "default": {},
-    "header": { "font": "header", "align": "center" },
+    "header": { "font": "header", "horizontalAlignment": "Center" },
    "label": { "font": "bold" },
-    "bordered": { "border": "all" },
-    "bordered-right": { "border": "all", "align": "right" },
-    "total-right": { "font": "bold", "border": "top", "align": "right" }
+    "bordered": { "border": "Solid" },
+    "bordered-right": { "border": "Solid", "horizontalAlignment": "Right" },
+    "total-right": { "font": "bold", "topBorder": "Solid", "horizontalAlignment": "Right" }
  },

  "areas": [
@@ -77,43 +80,20 @@
 | `page` | нет | — | Формат страницы: `"A4-landscape"` (780), `"A4-portrait"` (540) или число. Автоматически вычисляет `defaultWidth` из суммы пропорций `"Nx"` |
 | `defaultWidth` | нет | 10 | Ширина колонок по умолчанию. Игнорируется если задан `page` и все колонки используют `"Nx"` |
 | `columnWidths` | нет | `{}` | Ширины колонок. Ключи 1-based: `"1"`, `"3-14"`, `"5,7,9"`. Значения: число (абсолют) или `"Nx"` (множитель от defaultWidth, напр. `"2x"`, `"0.5x"`) |
+| `columnStyles` | нет | — | Оформление колонок: те же ключи, значение — имя стиля (см. `mxl-dsl-styles.md`) |
 | `textLanguages` | нет | `["ru"]` | Языки, на которых пишется текст, заданный строкой (см. ниже) |
 | `fonts` | нет | — | Именованные шрифты (если не задано, создаётся Arial 10) |
-| `styles` | нет | `{}` | Именованные стили |
+| `styles` | нет | `{}` | Именованные стили (см. `mxl-dsl-styles.md`) |
 | `areas` | да | — | Массив областей — диапазонов подряд идущих строк (порядок = порядок в документе); имя необязательно |
 | `namedAreas` | нет | — | Именованные области, заданные координатами (см. ниже) |
-| `columnSets` | нет | — | Дополнительные колоночные раскладки: своя ширина колонок у группы строк (см. ниже) |
-
-## Шрифты (`fonts.<name>`)
-
-| Поле | По умолч. | Описание |
-|------|-----------|----------|
-| `face` | `"Arial"` | Имя шрифта |
-| `size` | `10` | Размер |
-| `bold` | `false` | Жирный |
-| `italic` | `false` | Курсив |
-| `underline` | `false` | Подчёркнутый |
-| `strikeout` | `false` | Зачёркнутый |
-
-Шрифт `"default"` используется когда стиль не указывает шрифт явно. Если не определён, создаётся автоматически (Arial 10).
-
-## Стили (`styles.<name>`)
-
-| Поле | По умолч. | Описание |
-|------|-----------|----------|
-| `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"` и т.д. |
+| `columnSets` | нет | — | Дополнительные колоночные раскладки (см. `mxl-dsl-styles.md`) |

 ## Области (`areas[]`)

 | Поле | Обяз. | Описание |
 |------|:-----:|----------|
 | `name` | нет | Имя области для `Макет.ПолучитьОбласть("Имя")` |
+| `columnSet` | нет | Ссылка на раскладку из `columnSets` |
 | `rows` | да | Массив строк |

 Макет собирается из областей — диапазонов подряд идущих строк. Имя делает область именованной: она доступна в коде как `Макет.ПолучитьОбласть("Имя")` и занимает строки своего диапазона. **Область без имени** — просто кусок сетки: так описываются строки, не принадлежащие ни одной именованной области.
@@ -142,30 +122,6 @@

 Диапазон — та же грамматика, что у `columnWidths`, но **только** число или `"N-M"`: список через запятую запрещён, область непрерывна. Имя обязательно, и хотя бы одна ось должна быть задана; нарушение любого из этих правил → ненулевой код выхода и сообщение в stderr.

-## Колоночные раскладки (`columnSets`)
-
-Группа строк может иметь собственные ширины колонок — в 1С это «индивидуальная ширина колонок». Документные `columns` и `columnWidths` описывают раскладку по умолчанию; дополнительные объявляются в `columnSets`, а область ссылается на нужную ключом `columnSet` — так же, как ячейка ссылается на `styles` через `style`.
-
-```json
-{
-  "columns": 52,
-  "columnWidths": { "1": 8 },
-  "columnSets": {
-    "таблица": { "columns": 52, "columnWidths": { "1": 7, "2-52": 24 } }
-  },
-  "areas": [
-    { "name": "Шапка", "rows": [ ... ] },
-    { "name": "ТабличнаяЧасть", "columnSet": "таблица", "rows": [ ... ] }
-  ]
-}
-```
-
-Раскладка описывается той же парой полей, что и документная: `columns` — количество колонок (у раскладок оно обычно разное), `columnWidths` — ширины. Ключ словаря — имя раскладки; в макетах, полученных через `/mxl-decompile`, это идентификатор из исходного файла, при описании с нуля — любая строка.
-
-Все строки области получают раскладку области, поэтому одна область не может смешивать раскладки. Позиции колонок (`col`, `span`) проверяются по ширине раскладки СВОЕЙ области, а не документной.
-
-Ссылка на необъявленную раскладку → ненулевой код выхода и сообщение в stderr.
-
 ## Строки (`rows[]`)

 | Поле | По умолч. | Описание |
@@ -260,10 +216,10 @@ round-trip** (`/mxl-decompile` → `/mxl-compile`): в JSON оно не попа
 XML не возвращается.

 - ячейки-поля ввода (`containsValue` / `valueType` / `controlType`);
+- оформление СТРОКИ помимо высоты: у строки задаётся только `height`, а скрытие,
+  шрифт и прочее платформа хранит и у неё тоже;
 - объединения, не привязанные к ячейке (по всей высоте или ширине документа);
- рисунки и картинки, в том числе штрихкоды;
- цвет текста, цвет фона ячейки, скрытые строки и колонки, отступ;
- рамка с разным стилем у разных сторон; стили линий кроме сплошной;
+- рисунки и картинки, в том числе штрихкоды, и примечания к ячейкам;
 - группировки строк и колонок;
 - колонтитулы, параметры печати, область печати;
 - объявление языков макета: список языков и текущий язык всегда описываются как русский —
@@ -0,0 +1,133 @@
+# Оформление: шрифты, стили, колонки
+
+Оформление в табличном документе — одна сущность на всех: ячейка, строка и колонка ссылаются
+на один и тот же именованный стиль. Ячейка — ключом `style`, строка — `rowStyle`, колонка —
+через `columnStyles`.
+
+## Шрифты (`fonts.<name>`)
+
+| Поле | По умолч. | Описание |
+|------|-----------|----------|
+| `face` | `"Arial"` | Имя шрифта |
+| `size` | `10` | Размер (бывает дробным: `8.3`) |
+| `bold` | `false` | Жирный |
+| `italic` | `false` | Курсив |
+| `underline` | `false` | Подчёркнутый |
+| `strikeout` | `false` | Зачёркнутый |
+
+Шрифт `"default"` используется, когда стиль не указывает шрифт явно. Если не определён,
+создаётся автоматически (Arial 10).
+
+## Стили (`styles.<name>`)
+
+Ключ стиля — имя свойства так, как оно называется в выгрузке. Ниже частые; полный список
+из 44 свойств — в `mxl-dsl-format-properties.md`.
+
+| Поле | Описание |
+|------|----------|
+| `font` | Ссылка на имя из `fonts` |
+| `horizontalAlignment` | `Left`, `Center`, `Right`, `Justify`, `Auto` |
+| `verticalAlignment` | `Top`, `Center`, `Bottom` |
+| `textPlacement` | Что делать с длинным текстом: `Wrap` (перенос), `Cut` (обрезать), `Block`, `Auto` |
+| `backColor` | Цвет фона (см. «Цвет») |
+| `textColor` | Цвет текста |
+| `border`, `leftBorder`, `topBorder`, `rightBorder`, `bottomBorder` | Рамка (см. «Рамка») |
+| `borderColor` | Цвет рамки |
+| `format` | Формат данных 1С: `"ЧЦ=15; ЧДЦ=2"`, `"ДФ=dd.MM.yyyy"` |
+| `hidden` | Скрыть |
+| `protection` | Защита от редактирования |
+| `indent` | Отступ |
+| `textOrientation` | Поворот текста, в десятых долях градуса (`900` = 90°) |
+
+Значения перечислений регистр не различают: `"center"` и `"Center"` равнозначны.
+
+```json
+"styles": {
+  "шапка": {
+    "font": "жирный",
+    "horizontalAlignment": "Center",
+    "verticalAlignment": "Center",
+    "textPlacement": "Wrap",
+    "backColor": "#EBEBEB"
+  },
+  "итог": { "font": "жирный", "topBorder": "Solid", "horizontalAlignment": "Right" }
+}
+```
+
+## Цвет
+
+Строка в одной из четырёх форм — это нотация самой платформы:
+
+| Форма | Значение |
+|-------|----------|
+| `#RRGGBB` | RGB-hex, напр. `#FFFFC0` |
+| `style:ИмяСтиля` | Элемент стиля конфигурации или платформы, напр. `style:FormBackColor` |
+| `web:Имя` | Цвет из web-палитры, напр. `web:Gainsboro`, `web:FireBrick` |
+| `win:Имя` | Системный цвет Windows, напр. `win:ButtonText` |
+
+Имя должно существовать в своей палитре — несуществующее платформа отвергнет при загрузке.
+
+## Рамка
+
+Пять ключей: `border` — все четыре стороны сразу, `leftBorder` / `topBorder` / `rightBorder` /
+`bottomBorder` — по отдельности. Значение одинаковое у всех:
+
+| Запись | Значение |
+|--------|----------|
+| `"Solid"` | Стиль линии, ширина 1 |
+| `{ "style": "Solid", "width": 2 }` | Стиль и ширина |
+
+Стили линии: `Solid`, `None`, `Dotted`, `ThinDashed`, `LargeDashed`, `ThickDashed`, `Double`.
+
+Задавать стороны по отдельности можно всегда: если все четыре совпали, компилятор сам свернёт
+их в один `border` — так это хранит платформа.
+
+```json
+"рамка-снизу":  { "bottomBorder": "Dotted" },
+"рамка-вокруг": { "border": { "style": "Solid", "width": 2 } }
+```
+
+## Колоночные раскладки (`columnSets`)
+
+Группа строк может иметь собственные ширины колонок — в 1С это «индивидуальная ширина колонок».
+Документные `columns` и `columnWidths` описывают раскладку по умолчанию; дополнительные
+объявляются в `columnSets`, а область ссылается на нужную ключом `columnSet` — так же, как
+ячейка ссылается на `styles` через `style`.
+
+```json
+{
+  "columns": 52,
+  "columnWidths": { "1": 8 },
+  "columnSets": {
+    "таблица": { "columns": 52, "columnWidths": { "1": 7, "2-52": 24 } }
+  },
+  "areas": [
+    { "name": "Шапка", "rows": [ ] },
+    { "name": "ТабличнаяЧасть", "columnSet": "таблица", "rows": [ ] }
+  ]
+}
+```
+
+Раскладка описывается той же парой полей, что и документная: `columns` — количество колонок
+(у раскладок оно обычно разное), `columnWidths` — ширины. Ключ словаря — имя раскладки;
+в макетах, полученных декомпиляцией, это идентификатор из исходного файла, при описании
+с нуля — любая строка.
+
+Все строки области получают раскладку области, поэтому одна область не может смешивать
+раскладки. Позиции колонок (`col`, `span`) проверяются по ширине раскладки СВОЕЙ области,
+а не документной.
+
+Ссылка на необъявленную раскладку → ненулевой код выхода и сообщение в stderr.
+
+## Стиль колонки (`columnStyles`)
+
+Колонка несёт то же оформление, что ячейка и строка. Ключи — та же грамматика диапазонов,
+что у `columnWidths`; значение — имя стиля.
+
+```json
+"columnWidths": { "1": 30, "2-3": 15 },
+"columnStyles": { "1": "по-центру", "4": "скрытая" }
+```
+
+Внутри `columnSets` работает тот же ключ. Ширина и стиль независимы: колонка может иметь
+только ширину, только стиль или и то, и другое.