diff --git a/.claude/skills/mxl-compile/SKILL.md b/.claude/skills/mxl-compile/SKILL.md index c3654b9f..b8fd7c37 100644 --- a/.claude/skills/mxl-compile/SKILL.md +++ b/.claude/skills/mxl-compile/SKILL.md @@ -43,19 +43,26 @@ powershell.exe -NoProfile -File "${CLAUDE_SKILL_DIR}/scripts/mxl-compile.ps1" -J ## JSON-схема DSL -Ниже — компактная структура и ключевые правила, достаточные для типового макета. Полные таблицы полей (все свойства шрифтов, стилей, ячеек), развёрнутый пример и ограничения формата — в **`reference/dsl-spec.md`**; нужны не всегда, читать по необходимости. +Ниже — компактная структура и ключевые правила, достаточные для типового макета. Подробности читать по необходимости: + +| Что нужно | Файл | +|---|---| +| Полные таблицы полей, развёрнутый пример, ограничения формата | `reference/dsl-spec.md` | +| Шрифты, стили, цвета, рамки, колоночные раскладки и стили колонок | `reference/styles.md` | +| Полный перечень свойств стиля — все 44 | `reference/format-properties.md` | Краткая структура: ``` -{ columns, page, defaultWidth, columnWidths, +{ columns, page, defaultWidth, columnWidths, columnStyles, fonts: { name: { face, size, bold, italic, underline, strikeout } }, - styles: { name: { font, align, valign, border, borderWidth, wrap, format } }, + styles: { name: { font, horizontalAlignment, verticalAlignment, textPlacement, + backColor, textColor, border, borderColor, format, hidden } }, areas: [{ name, columnSet, rows: [{ height, rowStyle, cells: [ { col, span, rowspan, style, param, detail, text, template } ]}]}], namedAreas: [{ name, rows, cols }], - columnSets: { name: { columns, columnWidths } } + columnSets: { name: { columns, columnWidths, columnStyles } } } ``` @@ -64,6 +71,8 @@ powershell.exe -NoProfile -File "${CLAUDE_SKILL_DIR}/scripts/mxl-compile.ps1" -J - `name` у области в `areas` необязателен: область без имени — просто кусок сетки, именованной она не станет - `namedAreas` — области, которые не описываются диапазоном подряд идущих строк: полоса колонок, прямоугольник, ячейка. Тип не указывается, он следует из того, какие оси заданы - `columnSet` у области — ссылка на раскладку из `columnSets`, когда группе строк нужны свои ширины колонок; без него действует документная раскладка +- Ключ стиля — имя свойства как в выгрузке; `columnStyles` вешает стиль на колонку так же, как `style` на ячейку +- Рамка — `border` (все стороны) или `leftBorder`/`topBorder`/`rightBorder`/`bottomBorder`; значение `"Solid"` либо `{ style, width }` - `rowStyle` — автозаполнение пустот стилем (рамки по всей ширине) - `empty` в строке — шорткат для N подряд пустых строк (`{ "empty": 3 }` = три `{}`) - Строку можно писать массивом ячеек — позиция из порядка, `col` не нужен: `"текст"`, `"{Имя}"` — параметр, `">"` — продолжить ячейку слева, `"|"` — сверху, `null` — пропуск колонки diff --git a/.claude/skills/mxl-compile/reference/dsl-spec.md b/.claude/skills/mxl-compile/reference/dsl-spec.md index 6539ca1b..e4f13e31 100644 --- a/.claude/skills/mxl-compile/reference/dsl-spec.md +++ b/.claude/skills/mxl-compile/reference/dsl-spec.md @@ -2,6 +2,9 @@ Компактный JSON-формат для описания макетов табличных документов 1С (SpreadsheetDocument). Используется навыком `/mxl-compile` (JSON → XML). +Оформление — шрифты, стили, цвета, рамки, колоночные раскладки — в `styles.md`; +полный перечень свойств стиля — в `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` | нет | — | Оформление колонок: те же ключи, значение — имя стиля (см. `styles.md`) | | `textLanguages` | нет | `["ru"]` | Языки, на которых пишется текст, заданный строкой (см. ниже) | | `fonts` | нет | — | Именованные шрифты (если не задано, создаётся Arial 10) | -| `styles` | нет | `{}` | Именованные стили | +| `styles` | нет | `{}` | Именованные стили (см. `styles.md`) | | `areas` | да | — | Массив областей — диапазонов подряд идущих строк (порядок = порядок в документе); имя необязательно | | `namedAreas` | нет | — | Именованные области, заданные координатами (см. ниже) | -| `columnSets` | нет | — | Дополнительные колоночные раскладки: своя ширина колонок у группы строк (см. ниже) | - -## Шрифты (`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"` и т.д. | +| `columnSets` | нет | — | Дополнительные колоночные раскладки (см. `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`, а скрытие, + шрифт и прочее платформа хранит и у неё тоже; - объединения, не привязанные к ячейке (по всей высоте или ширине документа); -- рисунки и картинки, в том числе штрихкоды; -- цвет текста, цвет фона ячейки, скрытые строки и колонки, отступ; -- рамка с разным стилем у разных сторон; стили линий кроме сплошной; +- рисунки и картинки, в том числе штрихкоды, и примечания к ячейкам; - группировки строк и колонок; - колонтитулы, параметры печати, область печати; - объявление языков макета: список языков и текущий язык всегда описываются как русский — diff --git a/.claude/skills/mxl-compile/reference/format-properties.md b/.claude/skills/mxl-compile/reference/format-properties.md new file mode 100644 index 00000000..cfab577e --- /dev/null +++ b/.claude/skills/mxl-compile/reference/format-properties.md @@ -0,0 +1,77 @@ +# Полный список свойств стиля + +Имя ключа совпадает с именем свойства в выгрузке — исключений нет. Частые свойства +с примерами — в `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` — свойства конкретной ячейки, а не общего + оформления; сейчас не поддерживаются. diff --git a/.claude/skills/mxl-compile/reference/styles.md b/.claude/skills/mxl-compile/reference/styles.md new file mode 100644 index 00000000..93e24cca --- /dev/null +++ b/.claude/skills/mxl-compile/reference/styles.md @@ -0,0 +1,133 @@ +# Оформление: шрифты, стили, колонки + +Оформление в табличном документе — одна сущность на всех: ячейка, строка и колонка ссылаются +на один и тот же именованный стиль. Ячейка — ключом `style`, строка — `rowStyle`, колонка — +через `columnStyles`. + +## Шрифты (`fonts.`) + +| Поле | По умолч. | Описание | +|------|-----------|----------| +| `face` | `"Arial"` | Имя шрифта | +| `size` | `10` | Размер (бывает дробным: `8.3`) | +| `bold` | `false` | Жирный | +| `italic` | `false` | Курсив | +| `underline` | `false` | Подчёркнутый | +| `strikeout` | `false` | Зачёркнутый | + +Шрифт `"default"` используется, когда стиль не указывает шрифт явно. Если не определён, +создаётся автоматически (Arial 10). + +## Стили (`styles.`) + +Ключ стиля — имя свойства так, как оно называется в выгрузке. Ниже частые; полный список +из 44 свойств — в `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` работает тот же ключ. Ширина и стиль независимы: колонка может иметь +только ширину, только стиль или и то, и другое. diff --git a/README.md b/README.md index 7ed82b36..974ed867 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,7 @@ python scripts/switch.py --runtime powershell # вернуть на PowerShell - [Пакетный режим конфигуратора 1С](docs/build-spec.md) — команды `1cv8.exe`, DESIGNER, ENTERPRISE, CREATEINFOBASE - [Табличный документ (MXL)](docs/1c-spreadsheet-spec.md) — XML-формат SpreadsheetDocument, совместимость версий - [MXL DSL](docs/mxl-dsl-spec.md) — JSON-формат описания макета для `/mxl-compile` и `/mxl-decompile` +- [MXL DSL: оформление](docs/mxl-dsl-styles.md) — шрифты, стили, цвета, рамки, колоночные раскладки - [Form DSL](docs/form-dsl-spec.md) — JSON-формат описания формы для `/form-compile` - [Роли (Rights.xml)](docs/1c-role-spec.md) — XML-формат прав роли, типы объектов, RLS - [Role DSL](docs/role-dsl-spec.md) — JSON-формат описания ролей для `/role-compile` @@ -268,6 +269,8 @@ docs/ ├── build-spec.md # Пакетный режим конфигуратора 1С ├── 1c-spreadsheet-spec.md # Спецификация табличного документа ├── mxl-dsl-spec.md # Спецификация MXL DSL +├── mxl-dsl-styles.md # MXL DSL: оформление +├── mxl-dsl-format-properties.md # MXL DSL: полный перечень свойств стиля ├── form-dsl-spec.md # Спецификация Form DSL ├── meta-dsl-spec.md # Спецификация Meta DSL ├── 1c-role-spec.md # Спецификация ролей (Rights.xml) diff --git a/docs/1c-specs-index.md b/docs/1c-specs-index.md index 0c22007d..9278e086 100644 --- a/docs/1c-specs-index.md +++ b/docs/1c-specs-index.md @@ -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) | diff --git a/docs/mxl-dsl-format-properties.md b/docs/mxl-dsl-format-properties.md new file mode 100644 index 00000000..82868b3f --- /dev/null +++ b/docs/mxl-dsl-format-properties.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` — свойства конкретной ячейки, а не общего + оформления; сейчас не поддерживаются. diff --git a/docs/mxl-dsl-spec.md b/docs/mxl-dsl-spec.md index b5b49352..bbb64a76 100644 --- a/docs/mxl-dsl-spec.md +++ b/docs/mxl-dsl-spec.md @@ -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.`) - -| Поле | По умолч. | Описание | -|------|-----------|----------| -| `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"` и т.д. | +| `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`, а скрытие, + шрифт и прочее платформа хранит и у неё тоже; - объединения, не привязанные к ячейке (по всей высоте или ширине документа); -- рисунки и картинки, в том числе штрихкоды; -- цвет текста, цвет фона ячейки, скрытые строки и колонки, отступ; -- рамка с разным стилем у разных сторон; стили линий кроме сплошной; +- рисунки и картинки, в том числе штрихкоды, и примечания к ячейкам; - группировки строк и колонок; - колонтитулы, параметры печати, область печати; - объявление языков макета: список языков и текущий язык всегда описываются как русский — diff --git a/docs/mxl-dsl-styles.md b/docs/mxl-dsl-styles.md new file mode 100644 index 00000000..e423a486 --- /dev/null +++ b/docs/mxl-dsl-styles.md @@ -0,0 +1,133 @@ +# Оформление: шрифты, стили, колонки + +Оформление в табличном документе — одна сущность на всех: ячейка, строка и колонка ссылаются +на один и тот же именованный стиль. Ячейка — ключом `style`, строка — `rowStyle`, колонка — +через `columnStyles`. + +## Шрифты (`fonts.`) + +| Поле | По умолч. | Описание | +|------|-----------|----------| +| `face` | `"Arial"` | Имя шрифта | +| `size` | `10` | Размер (бывает дробным: `8.3`) | +| `bold` | `false` | Жирный | +| `italic` | `false` | Курсив | +| `underline` | `false` | Подчёркнутый | +| `strikeout` | `false` | Зачёркнутый | + +Шрифт `"default"` используется, когда стиль не указывает шрифт явно. Если не определён, +создаётся автоматически (Arial 10). + +## Стили (`styles.`) + +Ключ стиля — имя свойства так, как оно называется в выгрузке. Ниже частые; полный список +из 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` работает тот же ключ. Ширина и стиль независимы: колонка может иметь +только ширину, только стиль или и то, и другое.